code-outline-graph 0.2.41

Symbol-level code indexer MCP server — token-efficient AI editing with confirm-before-read flow

code-outline-graph

Symbol-level code indexer and MCP server. Parses your codebase with tree-sitter, stores symbols in SQLite + vector DB, and exposes a confirm-before-read protocol so AI assistants read only the symbols they need — not whole files.

10x–50x fewer tokens compared to reading files directly.

Install

pip install code-outline-graph

Quick Start

cd your-project
code-outline-graph build .

build runs once and configures everything — index, MCP configs, hooks, skill. Output:

╔══════════════════════════════════════════════════════════╗
║         code-outline-graph  •  Building Index            ║
╚══════════════════════════════════════════════════════════╝

[1/7] Indexing /home/user/myproject ...

      SKIP   .env                        (secret file)
      WARN   src/broken.py               parse error line 42
      OK     src/auth/views.py           23 symbols   0.04s
      OK     src/api/routes.py           45 symbols   0.11s

      src/auth/      →   3 files    67 symbols
      src/api/       →   8 files   203 symbols

      [████████████████████] 100%  186 files · 1789 symbols  →  Done!
      Skipped: 1  •  Errors: 1  •  Time: 3.2s

[2/7] Writing MCP configs (Claude/Cursor/Antigravity) ...
      Written: /home/user/myproject/.mcp.json  ✓
      Written: /home/user/myproject/.cursor/mcp.json  ✓
      Written: /home/user/.gemini/antigravity/mcp_config.json  ✓
[3/7] Writing Codex CLI config + hooks ...
      Written: .codex/config.toml  ✓
      Written: .codex/hooks.json   ✓
[4/7] Writing Gemini CLI config + hooks ...
      Written: .gemini/settings.json  ✓
[5/7] Writing Claude Code SessionStart + PostToolUse hooks ...
      Written: .claude/settings.json  ✓
[6/7] Writing AI instruction blocks ...
      Updated: AGENTS.md  ✓
      Updated: GEMINI.md  ✓
[7/7] Installing Claude Code skill ...
      Installed: SKILL.md     ✓
      Installed: examples.md  ✓

══════════════════════════════════════════════════════════
  Build complete in 5.1s
  186 files  •  1789 symbols  •  1 skipped  •  1 error
══════════════════════════════════════════════════════════

CLI Commands

Command	Description
code-outline-graph build [path]	Index project + write MCP configs for all clients
code-outline-graph build --embeddings [path]	Also build semantic vector embeddings
code-outline-graph update [path]	Reindex changed files only
code-outline-graph update --embeddings [path]	Reindex changed files and refresh embeddings
code-outline-graph search <query>	Search symbols by keyword
code-outline-graph outline <file>	List all symbols in a file
code-outline-graph status [path]	Show index stats
code-outline-graph prune [path]	Remove stale rows for deleted or ignored files
code-outline-graph doctor [path]	Check DB, parser, embeddings, and MCP config health
code-outline-graph serve [path]	Start MCP server (stdio), watcher off by default
code-outline-graph serve --watch [path]	Start MCP server with file watching
code-outline-graph install-skill	Install Claude Code skill to ~/.claude/skills/

MCP Tools

The server exposes 11 tools to AI assistants:

Tool	Description
resolve_edit_target	NL description → top-5 symbol candidates (signatures only, no body)
read_symbol_body	Read source lines for one symbol only
list_outline	All symbols in a file with line ranges
get_outline_summary	Compressed signatures-only outline
get_file_header	Imports + top-level constants only
get_symbol	Exact symbol metadata by name
find_by_keyword	Keyword search across all symbol names
get_line_range	Read arbitrary line slice from a file
index_project	Index a directory; pass watch: true to start file watcher
update_project	Reindex only changed files (faster than index_project)
prune_project	Remove stale index rows for deleted or ignored files

Confirm-Before-Read Protocol

1. resolve_edit_target({"description": "user login handler"})
   → [{name: "login", file: "views/auth.py", start: 45, end: 89, signature: "def login(...)"}]

2. AI picks correct candidate from signatures (no body read yet)

3. read_symbol_body({"name": "login", "file": "views/auth.py"})
   → 44 lines instead of 300-line file

Supported Languages

50+ languages and formats — symbols extracted where applicable, files tracked for all others.

Systems & Backend Python, JavaScript/JSX, TypeScript/TSX, Go, Rust, Java, C, C++, C#, Kotlin, Swift, Dart, Scala, Groovy, Zig, Lua

Web & Frontend HTML, CSS, SCSS, Sass, Less, Vue, Svelte

Shell & Scripting Bash/Zsh (.sh/.bash/.zsh), Fish, PowerShell, Batch/CMD, Perl, R

Functional Elixir, Erlang, Haskell, OCaml, Clojure/ClojureScript, Nix

Data & Config JSON, YAML, TOML, INI/CFG, XML, PLIST, SQL, SQLite (.db — tables/views), CSV

Infrastructure & Build Terraform/HCL, Protobuf, GraphQL, Makefile, Dockerfile

Mac / Windows system files (.DS_Store, .exe, .dll, .lnk, etc.) are binary and are skipped automatically.

Architecture

cli.py          CLI entry point — build/update/search/outline/status/serve
server.py       MCP server — tools, optional file watcher lifecycle
indexer.py      Orchestrates parse → checksum → DB upsert → embeddings
parser.py       tree-sitter parsing → Symbol extraction per language
db.py           SQLite + sqlite-vec — symbols table + FTS5 + vector index
search.py       FTS search, keyword search, vector search, resolve_edit_target
watcher.py      watchdog file watcher — debounced file-level reindex
embeddings.py   fastembed vector embeddings for semantic search
paths.py        Per-project DB path resolution (.code-outline-graph/index.db)

Each project gets its own SQLite DB at .code-outline-graph/index.db inside the project. The watcher is opt-in and only reindexes changed files on save or removes symbols for deleted files. Git branch switches no longer trigger a full project reindex automatically.

Large Codebases

The default runtime is conservative so AI-assisted sessions do not saturate the machine:

• Parser workers default to min(4, cpu_count); override with CODE_OUTLINE_INDEX_WORKERS=2 or build --workers 2.
• Embeddings are disabled by default; enable with --embeddings or CODE_OUTLINE_ENABLE_EMBEDDINGS=1.
• Files >=512KB are skipped by default; enable background indexing with --background-large-files or CODE_OUTLINE_BACKGROUND_LARGE_FILES=1.
• File watching is disabled by default; enable with serve --watch or CODE_OUTLINE_WATCH=1 for MCP index_project.

MCP Configuration

build auto-configures all supported clients in one shot:

Client	MCP config	SessionStart hook
Claude Code	.mcp.json	.claude/settings.json
Cursor	.cursor/mcp.json	none
Antigravity	~/.gemini/antigravity/mcp_config.json	none
Codex CLI	.codex/config.toml	.codex/hooks.json
Gemini CLI	.gemini/settings.json	.gemini/settings.json

It also appends usage instructions (sentinel-bounded, safe to re-run) to AGENTS.md and GEMINI.md so clients that read those files know to use the MCP tools.

The SessionStart hook runs code-outline-graph update . at the start of every AI session, keeping the index fresh without manual intervention.

Claude Code Skill

build automatically installs the Claude Code skill to ~/.claude/skills/code-outline-graph/ (SKILL.md + examples.md). The skill teaches Claude the confirm-before-read protocol and tool reference.

To install manually or update after upgrading:

code-outline-graph install-skill

Development

pip install -e ".[dev]"
pytest                        # run all tests
pytest tests/test_parser.py   # run single test file

License

MIT