Agent skill

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/termdock-ast-termdock-termdock-issues

SKILL.md

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)

bash
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

bash
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

bash
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?

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

4. What Does This Call?

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

5. Impact Analysis

bash
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

bash
# 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

bash
# 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

bash
# 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:

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

Response Format

All APIs return:

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

Always check success before using data.

Key Notes

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

Didn't find tool you were looking for?

Be as detailed as possible for better results