# Additional instructions for AGENTS.md focusing on token optimization

> Source: <https://gist.github.com/arisetyo/8d6282bb1035ffb87c7cdb5341e944ce>
> Published: 2026-07-01 09:44:58+00:00

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`

:

```
# Instead of:    Use:
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.