CodeSurf

0.7.0

1. A note for humans and AI agents

CodeSurf is a local tool your AI agent installs and calls to show you how Ruby, Python, TypeScript, or JavaScript code works in an interactive graph. Agents: follow the installation steps below, then pass a repository path and the human’s question to open a separate window they can explore.

2. How to Install

Agent: run these commands on the human’s computer, in their desktop session.

node --version  # Requires Node.js 22.12+ (Node 24 LTS recommended)
npm install -g https://codesurf.io/downloads/codesurf-cli-latest.tgz
codesurf --version

For natural-language tracing and chat, CodeSurf uses a signed-in Codex CLI. If it is not already installed:

npm install -g @openai/codex
codex login

The human completes sign-in once; reuse their existing login. No separate CodeSurf account or private GitHub access is needed.

Ruby projects need an installed Ruby interpreter with Ripper that supports their syntax; set CODESURF_RUBY to select it. Methods, lexical namespaces and explicit class-method calls are indexed; Rails DSL routes, metaprogramming and unknown instance receivers are not inferred.
Python projects need Python 3.10+ with support for the project’s syntax; set CODESURF_PYTHON to choose an interpreter.
The viewer requires a graphical desktop. Run locally for a visible window; an agent running on a remote server should use --html-only and transfer the report to the human.
macOS is tested. Windows and desktop Linux use the same npm package but have not yet been verified; Linux needs Electron’s system libraries.
If global npm installation is denied, configure a user-owned npm prefix and add its executable directory to PATH; avoid installing as root.

Check installation without AI or a repository:

codesurf --demo

Current release: 0.7.0 package · SHA-256 · release metadata · plain-text agent instructions

3. How to Update

Agent: quit the open CodeSurf application, then reinstall from the latest URL and check the installed version. This preserves saved reports and chat histories.

npm install -g https://codesurf.io/downloads/codesurf-cli-latest.tgz --prefer-online
codesurf --version

Use the versioned package URL above to pin a release. npm update codesurf-cli is not the update method for this direct-download package.

4. How to use

Human: tell your agent what you want to understand. Agent: call CodeSurf with the repository path and a specific question, including relevant inputs or assumptions.

codesurf /path/to/repo \
  "Trace a request with an expired access token. Assume refresh succeeds."

By default, the command opens the Electron desktop app with a left-to-right graph; further runs become tabs in the same window. The example below traces a request, a rejected access token, a token refresh, and a retry using the bundled example source.

Actual CodeSurf report with focused source snippets, per-file undo and redo, a beginner explanation chat, and folder groups. — Actual report view from the bundled token-refresh example. Click to enlarge.

Scroll to zoom; drag empty canvas to pan. Use Fit to see the whole trace.
Expand hidden sections as needed; use per-file undo and redo to restore line visibility. Click ⓘ for a function’s explanation, inputs, and return type.
Hover a line to follow its call path. Click a line or token to open a chat and type your question; its definition preview has an eye button to reveal that source.
Ask any chat to open a different flow or view to generate a new visualization tab.
Ask broader follow-ups in the introductory chat. Each source line has one chat.
Collapse folders and resize code cards horizontally; card height follows the visible code.

Actual CodeSurf view with a symbol chat and a three-line definition preview. — Open a symbol chat to inspect its definition preview and reveal it explicitly.

For humans: add this to AGENTS.md

Add this instruction to your repository’s AGENTS.md if you want your agent to use CodeSurf when explaining code. For use across repositories, add it to your agent’s global instructions instead.

When helping me understand unfamiliar code or explaining an execution flow,
use CodeSurf to open an interactive visualization alongside your explanation.

Read https://codesurf.io for installation and update instructions.
If CodeSurf is missing, install it with my permission; reuse my existing
Codex login. Run it on my local desktop so I can see the window:

codesurf /path/to/repo "The specific flow, inputs, and assumptions to trace"

Use --html-only when no graphical desktop is available and tell me where
the generated report was saved. Do not upload source reports without asking.

Agent reference

# Save a report without a window
codesurf /path/to/repo "Trace checkout" --html-only --out ./checkout.html

# Add another repository
codesurf /path/to/frontend "Trace login" --repo /path/to/backend

# Offline analysis with a known entry point
codesurf /path/to/repo "Trace login" --static --entry src/auth.ts#login

codesurf --help

Electron is the default viewer. Only --html-only exports a self-contained HTML report with a JSON snapshot alongside it. Zero exit status means report generation succeeded. Chat requires the CodeSurf desktop viewer and Codex sign-in.

Analysis reads source without executing the target application and can miss dynamic runtime behavior. AI investigation may send source to the configured model provider; reports contain source, so review them before sharing.

Changelog

0.7.0 Current

Explore code through focused flows, source-backed arrows, and a map conversation.

Compact sticky notes introduce each flow and point to its entry. Shared files appear once across flows.
Ask questions and refine the same map in the connected, collapsible chat. Assumptions and omitted scenarios have expandable callouts.
Relevant source stays readable; unrelated context is muted. Gaps of five lines or fewer stay visible, and code cards grow vertically.
Opening a definition adds its file when needed and links the exact call to the function.
Updated navigation and Lucide icons, with a single sidebar expand control.

0.6.1

Definition previews now show source line numbers and a “Defined in file:line” label. Refreshed both screenshots.

0.6.0

Focused source snippets, reversible line expansion, and chats connected to the code.

Initial views show question-relevant lines rather than entire functions, with subtle gray expandable gaps.
Per-file undo and redo restore line visibility; wider cards keep Wrap alongside those controls. Removed Show full functions.
Symbol chats show a three-line definition preview; an eye button explicitly reveals it in the graph. Hover never expands code.
Symbol and chat highlighting work both ways. Chats scale and pan with the canvas, hide with collapsed sources, and show directional hints when offscreen.
Chat replies render Markdown links, lists and code. Execution paths use light blue.
Added a centered loading message, readable startup errors, a README-style empty state, path-only card titles, and a Graphs sidebar label.
Fixed a stale-process Markdown startup failure, trimmed report snapshots, and indexed symbol references for faster rendering.
The Editor button opens the repository and selected file in VS Code; requires its code command on PATH.

0.5.0

Electron is the default experience. Use --html-only to explicitly export HTML; --out requires that flag. Replaces --no-open.

0.4.0

Ask any chat to open another flow or a different view: CodeSurf recognizes the request, carries over the relevant context, and opens a new visualization tab while preserving the current run.

0.3.1

Fixed chat failures caused by an unsupported configured Codex model: chats now select Codex’s advertised default model and a supported reasoning setting.

0.3.0

Added Ruby support and separated language indexing into independent adapters.

Ruby methods, namespaces, class-method calls, parameter shapes, and source locations are indexed with the built-in Ripper parser.
Choose the Ruby interpreter with CODESURF_RUBY, or select enabled adapters with --languages typescript,python,ruby.
Parser and runtime failures are isolated so one language does not prevent the others from being indexed.
Added regression coverage for Ruby, mixed-language repositories, Unicode, and missing runtimes.

0.2.0

Updated the desktop viewer and added public installation and update instructions.

Runs share one window with closable tabs and a full-width title and navigation card.
Functions start collapsed; expanding shows the full body. Info tooltips explain each function and show input and return shapes.
Added a flow-level chat and one chat per source line, with follow-ups and streamed answers.
Improved folder layout, line-number alignment, accurate expansion counts, and mouse-wheel zoom over code.
Cards resize horizontally and automatically fit their visible code; removed green line highlights and redundant card labels.
Added --version, the offline --demo, a latest-release download URL, checksums, and agent instructions.

0.1.0

Initial public CodeSurf release: natural-language code tracing for Python, TypeScript, and JavaScript/Node.js, with a local desktop graph and downloadable HTML reports.