termdock-ast

@termdock/termdock-ast

3 forks

Updated 1/18/2026

Use the Termdock AST API to locate symbols, dependencies, callers/callees, or impact before exploring unknown code. Skip when the user gives an exact file path or only needs a literal string search.

Installation

$skills install @termdock/termdock-ast

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorytermdock/termdock-issues

Path.codex/skills/termdock-ast/SKILL.md

Branchmain

Scoped Name@termdock/termdock-ast

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: termdock-ast description: "Use the Termdock AST API to locate symbols, dependencies, callers/callees, or impact before exploring unknown code. Skip when the user gives an exact file path or only needs a literal string search."

Termdock AST API

When to Use This Skill

Use AST API first when:

The user asks "where is X", "who calls X", "what does X call", or "what depends on X"
You need a file path or symbol ownership before editing
You expect a change to touch multiple files or affect behavior
You are about to run broad search without a known target

Skip AST API when:

The user provides an exact file path or a snippet to edit
The task is doc-only or config-only (SKILL.md, README, settings)
You only need a literal-string search

Default rule: Use AST for discovery and impact; skip it for known-file edits.

If API is unavailable: Fall back to rg/rg --files and note the limitation.

Quick Start

Step 1: Get Workspace ID (Required First)

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

Save this ID for all subsequent calls.

Step 2: Choose Your Query Type

Goal	API	Example
Find symbol by name	`/api/search`	"Where is UserService?"
See file imports/exports	`/api/graph/deps`	"What does this file import?"
Find callers	`/api/graph/callers`	"Who calls this function?"
Find callees	`/api/graph/calls`	"What does this function call?"
Impact analysis	`/api/impact`	"What breaks if I change this?"

API Reference

1. Search Symbols

curl 'http://localhost:3033/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

curl 'http://localhost:3033/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?

curl 'http://localhost:3033/api/graph/callers?to=<symbolId>&workspace=<wsId>'

4. What Does This Call?

curl 'http://localhost:3033/api/graph/calls?from=<symbolId>&workspace=<wsId>'

5. Impact Analysis

curl 'http://localhost:3033/api/impact?symbolId=<id>&depth=2&workspace=<wsId>'

Returns all symbols and files affected by changing this symbol.

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

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: symbolId, file

# 2. See dependencies
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

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

Rebuild index after code changes:

curl -X POST 'http://localhost:3033/api/index/update' -H 'Content-Type: application/json' -d '{"workspace":"<wsId>"}'

Response Format

All APIs return:

{
  "success": true|false,
  "data": {...},
  "error": {"code": "...", "message": "..."}
}

Always check success before using data.

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)

More by termdock

View all

recall-termdock-issues-dc11

recall: Retrieves cross-session memories about past decisions, lessons, and patterns. Use when user asks about prior work, past decisions, or mentions a feature. Triggers include check memory, what did we decide, how did we solve.

termdock-ast

Use the Termdock AST API to locate symbols, dependencies, callers/callees, or impact before exploring unknown code. Skip when the user gives an exact file path or only needs a literal string search.

recall-termdock-issues-dc11