AST API

Query your codebase structure via REST API or the Code Graph MCP server. Designed for Claude Code, Gemini CLI, and other AI coding assistants. Since v1.15, Code Analysis runs in a separate utility process and can be toggled per workspace.

Quick Start

Step 1: Get Workspace ID

Required for all API calls:

curl -s 'http://localhost:3033/api/workspaces' | jq '.data.workspaces[0].id'

Step 2: Search for a Symbol

curl 'http://localhost:3033/api/search?q=UserService&workspace=<wsId>&limit=10'

Step 3: Use the Symbol ID

Use the returned symbolId for callers, calls, and impact analysis.

When to Use AST API

Use AST API when:

• User asks "where is X?", "who calls X?"
• You need a file path before editing
• A change may affect multiple files
• Running broad search without a known target

Skip AST API when:

• User provides exact file path
• Task is doc-only or config-only
• Only need literal string search

API Reference

1. Search Symbols

GET /api/search?q=<name>&workspace=<wsId>&limit=10

Response fields:

• symbolId - Use for callers/calls queries
• file - Absolute path
• line - 0-indexed (add 1 for display)
• type - 5=Class, 6=Method, 11=Interface, 12=Function

2. File Dependencies

GET /api/graph/deps?file=src/path/to/file.ts&workspace=<wsId>

Returns: imports (what this file uses) and exports (what it provides)

3. Who Calls This? (Callers)

GET /api/graph/callers?to=<symbolId>&workspace=<wsId>

Find all locations that call or reference this symbol.

4. What Does This Call? (Callees)

GET /api/graph/calls?from=<symbolId>&workspace=<wsId>

Find all symbols that this function/method calls.

5. Impact Analysis

GET /api/impact?symbolId=<id>&depth=2&workspace=<wsId>

Returns all symbols and files affected by changing this symbol. Essential before refactoring.

6. Rebuild Index

POST /api/index/update
Content-Type: application/json
{"workspace":"<wsId>"}

Rebuild index after code changes. Use when search results seem stale.

Common Patterns

Pattern A: Find and Understand a Class

# 1. Find it
curl 'http://localhost:3033/api/search?q=TerminalService&workspace=ws_xxx&limit=1'
# Note the symbolId and file path

# 2. See what it imports/exports
curl 'http://localhost:3033/api/graph/deps?file=src/main/services/TerminalService.ts&workspace=ws_xxx'

# 3. Now read the file with context

Pattern B: Trace Usage

# 1. Find function
curl 'http://localhost:3033/api/search?q=createSession&workspace=ws_xxx&limit=5'
# Pick the right symbolId

# 2. Find all callers
curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=ws_xxx'

Pattern C: Safe Refactoring

# Before changing a function, check impact
curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=ws_xxx'
# Review impactedFiles before making changes

Decision Flowchart

User asks about code
        |
        v
Is it a "where is X?" question?
    |yes              |no
    v                 v
/api/search      Is it about dependencies?
    |                 |yes         |no
    v                 v            v
Got symbolId?    /api/graph/deps  Is it about call chain?
    |yes                              |yes         |no
    v                                 v            v
Need callers? -----> /api/graph/callers   Use other tools
Need callees? -----> /api/graph/calls
Need impact?  -----> /api/impact

Error Handling

Error	Cause	Action
No workspace found	API not running	Start Termdock app
Empty search results	Symbol not indexed	Try partial name or rebuild index
404 on symbolId	Stale ID after code change	Re-search to get new ID

Key Notes

• Line numbers are 0-indexed - Add 1 when showing to users
• Use relative paths for /api/graph/deps (e.g., src/main/...)
• Symbol IDs are stable until code changes
• API base: http://localhost:3033 (prod) or :3032 (dev)

Code Graph MCP Server

Since v1.13, Termdock also ships a local stdio MCP server so agents can query the code graph through the Model Context Protocol instead of raw HTTP. It is read-only — the index is built and maintained by the Termdock app, so open the project in Termdock first.

Start the server

node /path/to/Termdock/scripts/termdock-ast-mcp.js --path /path/to/project

Tool	Purpose
`termdock_context`	Budgeted code context pack from a natural-language query — preferred first tool
`termdock_search`	Search symbols by name (functions, classes, interfaces)
`termdock_callers` / `termdock_callees`	Caller / callee edges for a file
`termdock_impact`	Recursive caller collection for pre-refactor impact analysis
`termdock_node`	Single symbol detail; `includeCode: true` returns source
`termdock_status` / `termdock_files`	Index status and indexed file list

Claude Code setup

claude mcp add --scope project termdock-code-graph -- \
  node /path/to/Termdock/scripts/termdock-ast-mcp.js --path /path/to/project

Standalone limitation: termdock_callers, termdock_callees, and termdock_impact rely on the persisted call graph — with the Termdock app not running they return empty edges for most files. Search, context, status, and files work fully standalone.

Installing AST Skill for Claude Code

Open Settings → Skills tab in Termdock
Select Claude Code as target
Click Install on "termdock-ast" skill
Claude Code will now use AST API automatically when relevant