feat: add absolute line numbers for improved AI agent communication

- Display line numbers from source Python file instead of relative cell numbers
- Add keyboard shortcut (Cmd+Shift+A) to toggle absolute line numbers
- Add UI toggle in Settings → Display → "Absolute line numbers"
- Add visual indicator ("A" badge) in cell corner when enabled
- Persist configuration in user config

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: lucharo

frontend/src/components/app-config/user-config-form.tsx

@@ -821,6 +821,34 @@ export const UserConfigForm: React.FC = () => {
                   </div>
                 )}
               />
+              <FormField
+                control={form.control}
+                name="display.absolute_line_numbers"
+                render={({ field }) => (
+                  <div className="flex flex-col space-y-1">
+                    <FormItem className={formItemClasses}>
+                      <FormLabel>Absolute line numbers</FormLabel>
+                      <FormControl>
+                        <Checkbox
+                          data-testid="absolute-line-numbers-checkbox"
+                          checked={field.value}
+                          onCheckedChange={field.onChange}
+                        />
+                      </FormControl>
+                      <FormMessage />
+                      <IsOverridden
+                        userConfig={config}
+                        name="display.absolute_line_numbers"
+                      />
+                    </FormItem>
+
+                    <FormDescription>
+                      Display line numbers relative to the Python script file
+                      instead of relative to each cell.
+                    </FormDescription>
+                  </div>
+                )}
+              />
             </SettingGroup>
             <SettingGroup title="Outputs">
               <FormField

frontend/src/components/editor/cell/code/cell-editor.tsx

@@ -45,7 +45,10 @@ import { LanguageToggles } from "./language-toggle";
 
 export interface CellEditorProps
   extends Pick<CellRuntimeState, "status">,
-    Pick<CellData, "id" | "code" | "serializedEditorState" | "config"> {
+    Pick<
+      CellData,
+      "id" | "code" | "serializedEditorState" | "config" | "lineno"
+    > {
   runCell: () => void;
   theme: Theme;
   showPlaceholder: boolean;
@@ -88,6 +91,7 @@ const CellEditorInternal = ({
   languageAdapter,
   setLanguageAdapter,
   showLanguageToggles = true,
+  lineno,
 }: CellEditorProps) => {
   const [aiCompletionCell, setAiCompletionCell] = useAtom(aiCompletionCellAtom);
   const deleteCell = useDeleteCellCallback();
@@ -188,6 +192,7 @@ const CellEditorInternal = ({
       diagnosticsConfig: userConfig.diagnostics,
       displayConfig: userConfig.display,
       inlineAiTooltip: userConfig.ai?.inline_tooltip ?? false,
+      cellLineno: lineno,
     });
 
     extensions.push(

frontend/src/components/editor/notebook-cell.tsx

@@ -622,6 +622,7 @@ const EditableCellComponent = ({
                 showHiddenCode={showHiddenCode}
                 languageAdapter={languageAdapter}
                 setLanguageAdapter={setLanguageAdapter}
+                lineno={cellData.lineno}
               />
               <CellRightSideActions
                 className={cn(
@@ -1099,6 +1100,7 @@ const SetupCellComponent = ({
               languageAdapter={"python"}
               setLanguageAdapter={Functions.NOOP}
               showLanguageToggles={false}
+              lineno={cellData.lineno}
             />
             <CellRightSideActions
               edited={cellData.edited}

frontend/src/core/cells/types.ts

@@ -20,6 +20,8 @@ export function createCell({
   edited = false,
   config,
   serializedEditorState = null,
+  lineno,
+  endLineno,
 }: Partial<CellData> & { id: CellId }): CellData {
   return {
     id: id,
@@ -34,6 +36,8 @@ export function createCell({
     lastCodeRun: lastCodeRun,
     lastExecutionTime: lastExecutionTime,
     serializedEditorState: serializedEditorState,
+    lineno: lineno,
+    endLineno: endLineno,
   };
 }
 
@@ -85,6 +89,10 @@ export interface CellData {
   config: CellConfig;
   /** serialized state of the underlying editor */
   serializedEditorState: SerializedEditorState | null;
+  /** starting line number in the Python script file */
+  lineno?: number;
+  /** ending line number in the Python script file */
+  endLineno?: number;
 }
 
 export interface CellRuntimeState {

frontend/src/core/codemirror/absolute-line-numbers/extension.ts

@@ -0,0 +1,29 @@
+/* Copyright 2024 Marimo. All rights reserved. */
+
+import type { Extension } from "@codemirror/state";
+import { lineNumbers } from "@codemirror/view";
+
+/**
+ * Creates a CodeMirror extension that displays absolute line numbers
+ * based on the cell's position in the Python script file.
+ *
+ * @param lineOffset - The starting line number of the cell in the Python file (0-indexed)
+ * @returns CodeMirror extension for absolute line numbers
+ */
+export function absoluteLineNumbers(lineOffset: number): Extension {
+  return lineNumbers({
+    formatNumber: (lineNo: number) => {
+      // lineNo is 1-indexed within the cell
+      // lineOffset is the absolute starting line (0-indexed)
+      // We want to display: lineOffset + lineNo
+      const absoluteLineNumber = lineOffset + lineNo;
+
+      // Add a visual indicator (*) on the first line to show absolute mode is active
+      if (lineNo === 1) {
+        return `${absoluteLineNumber}*`;
+      }
+
+      return String(absoluteLineNumber);
+    },
+  });
+}

frontend/src/core/codemirror/cm.ts

@@ -48,6 +48,7 @@ import type {
 } from "../config/config-schema";
 import type { HotkeyProvider } from "../hotkeys/hotkeys";
 import { store } from "../state/jotai";
+import { absoluteLineNumbers } from "./absolute-line-numbers/extension";
 import { requestEditCompletion } from "./ai/request";
 import { cellBundle } from "./cells/extensions";
 import type { CodemirrorCellActions } from "./cells/state";
@@ -81,8 +82,12 @@ export interface CodeMirrorSetupOpts {
   hotkeys: HotkeyProvider;
   lspConfig: LSPConfig;
   diagnosticsConfig: DiagnosticsConfig;
-  displayConfig: Pick<DisplayConfig, "reference_highlighting">;
+  displayConfig: Pick<
+    DisplayConfig,
+    "reference_highlighting" | "absolute_line_numbers"
+  >;
   inlineAiTooltip: boolean;
+  cellLineno?: number;
 }
 
 function getPlaceholderType(opts: CodeMirrorSetupOpts) {
@@ -180,9 +185,17 @@ export const basicBundle = (opts: CodeMirrorSetupOpts): Extension[] => {
     cellId,
     lspConfig,
     diagnosticsConfig,
+    displayConfig,
+    cellLineno,
   } = opts;
   const placeholderType = getPlaceholderType(opts);
 
+  // Use absolute line numbers if enabled and we have a valid line number
+  const useAbsoluteLineNumbers =
+    displayConfig.absolute_line_numbers &&
+    cellLineno !== undefined &&
+    cellLineno > 0;
+
   return [
     ///// View
     EditorView.lineWrapping,
@@ -191,7 +204,7 @@ export const basicBundle = (opts: CodeMirrorSetupOpts): Extension[] => {
     highlightActiveLine(),
     highlightActiveLineGutter(),
     highlightSpecialChars(),
-    lineNumbers(),
+    useAbsoluteLineNumbers ? absoluteLineNumbers(cellLineno) : lineNumbers(),
     rectangularSelection(),
     tooltips({
       // Having fixed position prevents tooltips from being repositioned

frontend/src/core/config/config-schema.ts

@@ -141,6 +141,7 @@ export const UserConfigSchema = z
           }),
         locale: z.string().nullable().optional(),
         reference_highlighting: z.boolean().prefault(false),
+        absolute_line_numbers: z.boolean().prefault(false),
       })
       .prefault({}),
     package_management: z

frontend/src/core/edit-app.tsx

@@ -26,6 +26,7 @@ import {
   useCellActions,
 } from "./cells/cells";
 import { CellEffects } from "./cells/effects";
+import { useResolvedMarimoConfig } from "./config/config";
 import type { AppConfig, UserConfig } from "./config/config-schema";
 import { RuntimeState } from "./kernel/RuntimeState";
 import { getSessionId } from "./kernel/session";
@@ -66,7 +67,9 @@ export const EditApp: React.FC<AppProps> = ({
   const hasCells = useAtomValue(hasCellsAtom);
   const filename = useFilename();
   const setLastSavedNotebook = useSetAtom(lastSavedNotebookAtom);
-  const { sendComponentValues, sendInterrupt } = useRequestClient();
+  const { sendComponentValues, sendInterrupt, saveUserConfig } =
+    useRequestClient();
+  const [config, setConfig] = useResolvedMarimoConfig();
 
   const isEditing = viewState.mode === "edit";
   const isPresenting = viewState.mode === "present";
@@ -132,6 +135,18 @@ export const EditApp: React.FC<AppProps> = ({
   useHotkey("global.expandAllSections", () => {
     expandAllCells();
   });
+  useHotkey("global.toggleAbsoluteLineNumbers", () => {
+    const newConfig = {
+      ...config,
+      display: {
+        ...config.display,
+        absolute_line_numbers: !config.display.absolute_line_numbers,
+      },
+    };
+    saveUserConfig({ config: newConfig }).then(() => {
+      setConfig(newConfig);
+    });
+  });
 
   const editableCellsArray = (
     <CellArray

frontend/src/core/hotkeys/hotkeys.ts

@@ -344,6 +344,11 @@ const DEFAULT_HOT_KEY = {
     group: "Editing",
     key: "Mod-Shift-\\",
   },
+  "global.toggleAbsoluteLineNumbers": {
+    name: "Toggle absolute line numbers",
+    group: "Other",
+    key: "Mod-Shift-A",
+  },
   "global.expandAllSections": {
     name: "Expand all sections",
     group: "Editing",

frontend/src/core/kernel/handlers.ts

@@ -54,6 +54,8 @@ export function handleKernelReady(
     last_execution_time = {},
     app_config,
     capabilities,
+    linenos = [],
+    end_linenos = [],
   } = data;
   const lastExecutedCode = last_executed_code || {};
   const lastExecutionTime = last_execution_time || {};
@@ -78,6 +80,8 @@ export function handleKernelReady(
       lastCodeRun: lastExecutedCode[cellId] ?? null,
       lastExecutionTime: lastExecutionTime[cellId] ?? null,
       config: configs[i],
+      lineno: linenos[i],
+      endLineno: end_linenos[i],
     });
   });