Index Your First Repo

import { Aside, Steps } from ‘@astrojs/starlight/components’;

Once Forge is installed, indexing a repo takes one command.

Basic indexing

cd ~/path/to/your/repo
forge index .

Expected output:

forge: indexing /path/to/your/repo (incremental)
forge: AST index done — 2,104 files indexed, 0 skipped, 0 errors (2,631 ms)
forge: tip — run with --with-search to also build the full-text search index

The first run is the slow one. Subsequent runs process only changed files and finish in a fraction of the time.

Full index with search and git history

For the best agent experience, also build the full-text search index and ingest git history:

forge index . --full --with-search --with-git

What each flag adds:

Flag	Enables	Tools unlocked
(none)	AST graph, imports, exports, dependency edges	forge_trace_imports, forge_trace_dependents, forge_check_wiring, forge_find_cycles
--with-search	Tantivy keyword search index	forge_search
--with-git	Commit history, blame data	forge_git_history, forge_git_blame
--full	Wipes previous index, re-scans everything	—

Run `--full --with-search --with-git` for the first index on any new repo. After that, `forge index .` (no flags) handles incremental updates fast enough to run on every save if you use `forge serve --watch`.

Checking the index

forge status

Example output:

forge status — /path/to/your/repo
  Index age:    2 minutes ago
  Files:        2,104 indexed, 0 stale
  Symbols:      18,432
  Import edges: 6,211
  Search:       ready (Tantivy)
  Git history:  ready (847 commits)
  Health:       not run — use `forge health`

If any layer shows not ready, re-run the corresponding flag.

Run a health check

forge health

This runs the four built-in checks across your indexed codebase:

• broken_imports — import paths that resolve to no indexed file
• dead_exports — named exports with no known consumers
• circular_deps — import cycles in the dependency graph
• secret_scan — hard-coded API keys, tokens, and credentials

Example output:

forge health — /path/to/your/repo
  P0 critical:  0
  P1 errors:    2
    dead_exports: src/utils/legacy.ts — export `oldHelper` has 0 consumers
    broken_imports: src/api/client.ts — cannot resolve './helpers/retry'
  P2 warnings:  5
  Info:         12

No findings is ideal. A few P1s in a real codebase is normal. P0s (circular deps that break module loading, or secrets) deserve immediate attention.

Where does the index live?

Forge stores its index in ~/.forge/<repo-id>/ — a SHA-1-keyed directory per repo.

~/.forge/
└── 3a7f9bc2.../          # SHA-1 of the repo root path
    ├── forge.db           # SQLite: AST graph, symbols, imports, health findings
    ├── search/            # Tantivy full-text index (present if --with-search)
    ├── heartbeat.json     # License heartbeat cache
    └── community_usage.json  # Rate limit counters (Community Mode only)

To reset the index for a repo:

forge index . --full
# or delete the directory manually:
rm -rf ~/.forge/<repo-id>/

Supported languages

Forge uses tree-sitter grammars for structural parsing. Supported in v1.4.0:

Language	AST parsing	Import/export edges	Symbol extraction
TypeScript	Yes	Yes	Yes
JavaScript	Yes	Yes	Yes
Python	Yes	Yes	Yes
Rust	Yes	Yes	Yes
Go	Yes	Yes	Yes

Other file types (YAML, JSON, Markdown, etc.) are indexed for full-text search but not AST-parsed. See Concepts: AST Parsing for the tradeoffs.

Next

Connect to Claude Code — add Forge to your agent’s MCP config.