# ASR
Agent Source Repository, or ASR, is a local source-context registry for coding
agents. It lets an agent search, narrow, and read only the relevant file ranges
before editing code.
The supported product surface is the `asr` CLI and its Rust library crate.
## Core Contract
```txt
Forgejo stores the canonical Git repository.
ASR owns the registered repository and the checkout used for agent work.
The agent reads and edits only the checkout that ASR indexed.
```
For read-only discovery, ASR can register and index a normal Git checkout or a
bare Git repository. For editing, the source of truth must be a checkout that
both ASR and the agent use. If ASR indexes one path while the agent edits
another path, the work must stop because search results and file contents may no
longer match.
## Agent Workflow
Run ASR before broad source reads:
```bash
asr repo status <repo> --json
asr repo index <repo> --json
asr context "<task>" --repo <repo> --budget 4000 --json
```
Then read only the returned bounded ranges:
```bash
asr read <repo> src/example.rs --lines 10:80 --json
```
`search`, `context`, `read`, `deps`, and `impact` are snapshot-bound by
default: ASR verifies that the current registered source still matches the ready
index state before returning agent-facing source evidence. `read`, `deps`, and
`impact` accept `--live` only as an explicit escape hatch for current-source
inspection; JSON output marks those results with `source_policy.live=true`.
Use these commands only when more evidence is needed:
```bash
asr search "RetryPolicy" --repo <repo> --top-k 8 --json
asr deps <repo> src/example.rs --json
asr impact <repo> src/example.rs --json
asr diff <repo> --base HEAD~1 --head HEAD --json
asr verify <repo> --json
```
After source changes, re-run:
```bash
asr repo index <repo> --json
```
## Forgejo Relationship
Forgejo is the code vault. ASR is the map and freshness guard. The agent is the
worker.
The intended Forgejo flow is:
```txt
Forgejo bare repository
-> ASR-managed checkout for the task
-> ASR indexes that checkout
-> agent reads and edits that same checkout
-> tests and verification run there
-> commit, merge, and push back to Forgejo
-> ASR re-indexes after the source changes
```
The detailed operating contract is in the Forgejo workflow doc listed below.
## Install And Verify
Build locally:
```bash
cargo build --workspace --locked
```
Run the main verification gates:
```bash
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
```
See [docs/installation.md](docs/installation.md) and
[docs/verification.md](docs/verification.md) for operator details.
## State Boundary
ASR writes metadata under `ASR_HOME`, defaulting to `~/.asr`.
ASR must not write `.asr`, indexes, or generated state into source repositories.
Registered source repositories must not live inside `ASR_HOME`, and `ASR_HOME`
must not be inside a Git worktree.
`ASR_HOME/index/exact/<repo>` is a persistent exact-match cache. SQLite chunk
snapshots remain the source of truth, and ASR validates or rebuilds the exact
shard from SQLite before using it.
## Supported Inputs
ASR indexes source files through its local source indexer. Tree-sitter chunking is
available for Rust, Python, JavaScript, JSX, TypeScript, TSX, Go, Java, C, and
C++. Other text-like languages may be indexed with line fallback depending on the
search path.
## Documentation
- [docs/README.md](docs/README.md): documentation index
- [docs/agent-usage.md](docs/agent-usage.md): ASR-first agent rules
- [docs/forgejo-workflow.md](docs/forgejo-workflow.md): Forgejo, ASR, and agent ownership contract
- [AGENTS.md](AGENTS.md): local agent instructions for this repository