agent-source-repository 0.1.0

Agent Source Repository local context registry for coding agents
Documentation

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

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:

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:

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:

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:

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:

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:

cargo build --workspace --locked

Run the main verification gates:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked

See docs/installation.md and 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