Additional instructions for AGENTS.md focusing on token optimization

Always retrieve the smallest amount of information necessary. Escalate only when necessary. Stop escalating as soon as sufficient information has been obtained.

Preferred order:

• Need code structure? graph.json

. - Need symbols? ast-grep

. - Need repository metadata? rtk

. - Need implementation? Source files.

• Use repository-wide search as last resort

Avoid reading entire directories or the whole repository unless explicitly requested.

rtk is a CLI proxy that filters and compresses command outputs, saving 60-90% tokens. Use rtk

whenever possible because it preserves the relevant information while reducing LLM token consumption.

Always prefix shell commands with rtk

:

ls -la           rtk ls -la
git status       rtk git status
git log -10      rtk git log -10
docker ps        rtk docker ps

Other examples where you can use rtk

: Other examples where you can use rtk

:

rtk tree
rtk read
rtk cat
rtk git diff
rtk diff
rtk npm run test
rtk curl <url>
rtk pytest
rtk jest
rtk vitest
rtk playwright test
rtk lint
rtk prettier --check .

A pre-computed AST knowledge graph (graph.json

) is available at: graphify-out/graph.json

Use graph.json

before searching or reading multiple source files.

Workflow:

• Read graph.json

. - Identify the relevant symbols, files, and dependency paths.

• Read only the source files required for the task.
• Avoid scanning unrelated files.

Use the graph for:

• dependency tracing
• call-path discovery
• identifying high-centrality modules
• impact analysis before refactoring
• locating symbol definitions

Never read an entire directory simply to locate a symbol. Use graph.json

to locate the symbol first, then read only the relevant files.

The graph is generated from AST extraction and represents extracted structural relationships only. Treat graph edges as authoritative for structural relationships. Do not infer dependencies that are absent from the graph.

Prefer ast-grep

over grep

whenever searching source code.

Use ast-grep

for:

• locating function definitions
• locating class definitions
• locating method implementations
• finding imports
• matching AST patterns
• performing structural search

Use grep

only for:

• Markdown
• JSON
• YAML
• log files
• generated text
• plain-text configuration

Avoid using grep

to search programming language source code when ast-grep

can answer the query.