Quick Start

This walkthrough follows the loop AG.IDE is built for. Start inside your coding agent, index the whole repository, export the call graph, rank the highest-value targets, inspect the graph around each target, review the patch, then re-index to find the next improvement.

The examples use Redux as a real TypeScript repository. The same loop applies to your own codebase.

Install

macOS (Apple Silicon) — download AG.IDE from agide.dev. The app is signed and notarized, bundles the agide CLI, and installs it on first launch.

Linux (x86_64 / ARM64) — one line, no account:

curl -fsSL https://agide.dev/install.sh | bash

That installs the agide CLI to ~/.local/bin and the embedding model to ~/.agide/models (so semantic search works out of the box). Ensure ~/.local/bin is on your PATH. Everything runs offline — your code never leaves the machine.

To pin a version or change the location:

curl -fsSL https://agide.dev/install.sh | AGIDE_VERSION=0.1.0-preview.16 AGIDE_INSTALL_DIR=/usr/local/bin bash

Note

On minimal Linux containers without /etc/machine-id, set a stable 64-hex AGIDE_DB_KEY so the encrypted index can derive its key — e.g. export AGIDE_DB_KEY=$(head -c32 /dev/urandom | xxd -p -c32).

1. Start With the Agent

Open Codex, Claude Code, Cursor, or another coding agent at the repository root. Give the agent a direct AG.IDE-oriented task before it starts editing.

! agide --help

Use AG.IDE to index this repo, rank and fix the worst code-quality offender, re-index, and repeat five times.

2. Index the Repository

Indexing gives AG.IDE the system view that an agent does not get from a single file or prompt: symbols, calls, metrics, Git history, and search context.

Example

Index TypeScript

Builds the local structural map for Redux and records the files, symbols, calls, scores, and history signals.

terminal

$ agide index . --exclude website --exclude docs --exclude examples

indexed 31 package(s), 176 symbol(s), 196 call(s), 0 impl(s); 0 metric(s) computed; 0 dropped
recent churn: 40 commit(s) scanned, 477 file(s) signaled
historical quality: 202 snapshot(s) analyzed
scored 153 symbol(s)
prepared searchable code context

3. Export the Call Graph

Write the full call graph to a Mermaid Markdown file in the repository root. Then point AGENTS.md, CLAUDE.md, or your agent’s project instructions at AGIDE_CALLGRAPH.md so agents load the architecture map before broad changes.

Example

Export an agent call graph

Writes a Mermaid architecture map that coding agents can read before changing the codebase.

terminal

$ agide callgraph --format mermaid --limit 10000 > AGIDE_CALLGRAPH.md

wrote AGIDE_CALLGRAPH.md

Add a short note to your agent instructions:

Before changing architecture or refactoring across files, read AGIDE_CALLGRAPH.md.
Refresh it with:
agide callgraph --format mermaid --limit 10000 > AGIDE_CALLGRAPH.md

4. Rank the Worst Offenders

Ranking is the start of the improvement pass. It surfaces the functions most worth inspecting before you ask an agent to change anything.

Example

Rank quality hotspots

Shows the worst combined quality hotspots across complexity, coupling, churn, side effects, and ambiguity.

terminal

$ agide rank --limit 5

rank combined (5 rows)
comb   cplx   coup   churn  effects ambig  symbol                                 summary
1.000  1.000  1.000  0.000  1.000   1.000  src.createStore.createStore            300 lines, many decision branches; widely…
0.695  0.800  0.286  0.000  1.000   1.000  src.combineReducers.combineReducers    mutates external state heavily; many deci…
0.386  0.873  0.286  0.000  0.000   1.000  src.utils.kindOf.miniKindOf            many decision branches; no documentation
0.271  0.400  0.214  0.000  0.200   1.000  src.combineReducers.getUnexpectedStat… no documentation; branchy
0.199  0.182  0.214  0.000  0.200   1.000  src.utils.isPlainObject.isPlainObject  no documentation

5. Understand the Target

Before editing, inspect the blast radius. Impact and graph queries show callers, callees, tests, and surrounding structure so the agent can make a smaller, better-informed change.

Example

Estimate blast radius

Collects callers, tests, and warnings for a symbol before changing it.

terminal

$ agide query impact src.combineReducers.assertReducerShape

impact: src.combineReducers.assertReducerShape
direct callers (1)
function  src.combineReducers.combineReducers
    function combineReducers(reducers:
transitive callers (1)
function  src.combineReducers.combineReducers
    function combineReducers(reducers:
tests reaching (0)

Example

Show outbound dependencies

Asks what the selected ranked symbol calls, including a shallow transitive view.

terminal

$ agide query callees src.createStore.createStore --depth 2 --limit 5

callees (5 total)
method  test.typescript.store.test-d.next
    next(state: State)
function  src.utils.kindOf.kindOf
    function kindOf(val: any)
function  src.utils.isPlainObject.isPlainObject
    function isPlainObject(obj: any): obj is object
function  test.typescript.enhancers.test-d.enhancer
    enhancer: StoreEnhancer<
function  src.utils.kindOf.miniKindOf
    function miniKindOf(val: any): string

6. Improve with Focused Context

Give the agent one ranked target, the relevant file, and the graph context from the previous step. The goal is not to rewrite the world; it is to improve the highest-leverage offender without increasing coupling somewhere else.

7. Review the Patch

Diff review maps changed hunks back to indexed symbols and risk signals. Run it before accepting the agent’s change.

Example

Review a diff

Maps a real unified diff back to indexed symbols and risk context.

terminal

$ git diff -- src/combineReducers.ts | agide diff review

diff review: 1 changed file(s) matched to index data
  src/combineReducers.ts (1 symbol(s) touched)
    src.combineReducers.assertReducerShape (combined=0.197 complexity=3 cognitive=2 churn=0 lines changed=1)

8. Re-index and Repeat

After the patch lands locally, run the index again. AG.IDE re-scores the repository so the next pass starts from the new state, not stale assumptions.

Example

Index TypeScript

Builds the local structural map for Redux and records the files, symbols, calls, scores, and history signals.

terminal

$ agide index . --exclude website --exclude docs --exclude examples

indexed 31 package(s), 176 symbol(s), 196 call(s), 0 impl(s); 0 metric(s) computed; 0 dropped
recent churn: 40 commit(s) scanned, 477 file(s) signaled
historical quality: 202 snapshot(s) analyzed
scored 153 symbol(s)
prepared searchable code context