astrograph

name	astrograph
description	Use Astrograph's local code graph before grep/read loops for JS/TS architecture, call flow, dependency, impact, symbol lookup, and task-context questions. Trigger when an indexed project has Astrograph MCP tools or the astrograph CLI available, especially when the user asks how code works, who calls what, what depends on a symbol, or where a change may reach.

Astrograph

Astrograph is a pre-built local code graph for JavaScript and TypeScript projects. Use it to answer structural code questions with fewer broad searches and fewer file reads.

First Check

If Astrograph MCP tools are available, prefer them over shelling out to the CLI. If only the CLI is available, use the matching astrograph <command>.

Before relying on the graph in a project, check freshness:

• MCP: call astrograph_status.
• CLI: run astrograph status.
• If there is no .astrograph/ index, offer to run astrograph init.
• If the daemon is running, trust it as the freshness owner.
• Always read the coverage/staleness banner before deciding whether to inspect files directly.

Tool Choice

Pick by intent:

Intent	Use
"How does this feature/module work?"	astrograph_context
"How does X reach Y?"	astrograph_trace
"Find the symbol named X"	astrograph_search
"Who calls X?"	astrograph_callers
"What does X call?"	astrograph_callees
"What breaks if I change X?"	astrograph_impact
"Show this one symbol and maybe its code"	astrograph_node
"Show related code for these names/terms"	astrograph_explore
"Which files are indexed?"	astrograph_files
"Is the graph healthy/fresh?"	astrograph_status

CLI equivalents:

astrograph context "how does auth refresh work?"
astrograph trace LoginScreen refreshToken
astrograph search useAccount
astrograph callers useAccount
astrograph callees AccountScreen
astrograph impact updateSession
astrograph node useAccount --code
astrograph explore session refresh token
astrograph files
astrograph status

Prefer Astrograph Before Grep

Use Astrograph first for:

• cross-file control flow
• callers/callees
• imports and dependencies
• impact analysis before editing
• symbol lookup when the name is approximate
• architecture questions
• task context for an implementation or bug

Use rg, glob, or direct file reads when:

• the graph is missing and the user does not want to initialize it
• the coverage banner says a specific file is pending or partial
• you need raw text not modeled by the graph, such as comments, copy, env var names, config keys, or test snapshots
• the user explicitly asks for literal text search
• Astrograph gives no useful result after one focused retry

Query Style

Make graph queries precise:

• Prefer symbol names when known: useAccount, CheckoutScreen, AuthService.login.
• For context, use a natural task phrase: "how does checkout submit an order".
• For trace, provide endpoints, not prose.
• For explore, pass a compact bag of related symbols or terms.
• If results are noisy, narrow by symbol name, file area, or node kind instead of immediately falling back to broad grep.

Source Blocks Are Already Read

When astrograph_context, astrograph_trace, astrograph_node, or astrograph_explore returns code blocks, treat those blocks as already read. Do not re-open the same files just to verify them unless the banner says the file is pending/partial or the answer still lacks necessary detail.

External Symbols

Project symbols are the default. External node_modules and .d.ts symbols can be useful, but they often drown out project results.

Use external results only when needed:

astrograph callers someSymbol --include-external
astrograph callees someSymbol --include-external

After Editing

If the daemon is running, it should sync changes in the background.

If not using the daemon:

astrograph sync

After edits that affect a question, check astrograph_status or the next tool's coverage banner before trusting old graph results.

Answering Users

When Astrograph answers the question, cite the symbols and files it returned and avoid narrating a separate grep/read expedition. If the graph is partial, say what may be missing and inspect only the pending or relevant files directly.