RepoGrammar

Repository conventions for coding agents.

Documentation · Quickstart · Changelog · Contributing

RepoGrammar indexes repeated implementations in your repository and gives coding agents a source-backed read plan: examples of how this codebase implements a route, fixture, model, or data-access role, with the evidence behind each match. When the evidence is insufficient, it returns UNKNOWN with a recovery action.

It runs locally and exposes a pattern-first CLI and one read-only MCP tool. There are no LLM calls, API keys, embeddings, or cloud services in the analysis path. Python 3.10+ is required for the bundled Python analyzer.

The current GitHub stable release is 0.5.0, published through GitHub only. The older npm release is a separate channel; see the publication evidence.

Recorded from a real CLI run on a fixture repository; playback is slowed for readability.

Quick start

Requires Python 3.10+, Bash, curl, tar, and gzip. macOS and glibc Linux are supported. Rust, Cargo, Node.js, Docker, and API keys are not required.

1. Install — copy and run

This single block downloads the pinned installer, verifies its checksum, and installs the CLI. It does not alter coding-agent settings or index a repository.

(
set -eu
install_tmp="$(mktemp -d)"
trap 'rm -rf "$install_tmp"' EXIT
cd "$install_tmp"
curl -fsSLO https://github.com/SioYooo/RepoGrammar/releases/download/v0.5.0/install.sh
curl -fsSLO https://github.com/SioYooo/RepoGrammar/releases/download/v0.5.0/install.sh.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c install.sh.sha256
else
  shasum -a 256 -c install.sh.sha256
fi
bash install.sh --version v0.5.0 --install-cli-only --yes
) &&
export PATH="$HOME/.local/bin:$PATH"
repogrammar version

Add the export PATH line to ~/.zshrc or ~/.bashrc once to keep the command available in new terminals. Expected version: 0.5.0.

2. Index your project

From your project's directory:

repogrammar init

That is all: init builds the current project's index and starts background updates. There is no global repository scanner. Run init once in each project. The explicit form repogrammar init --project "$PWD" --yes does the same thing; use --no-autosync for CI or a one-shot index.

3. Connect your coding agent (optional)

repogrammar install --target auto --scope global --yes --no-telemetry

Current source builds also add a short conditional guide for Codex/Claude Code at their effective global profile path. Review it with install --dry-run; --no-instructions skips that write. Published 0.5.0 artifacts retain their shipped override-only instruction wiring. This is configuration behavior, not evidence of agent adoption or token savings.

Restart the coding-agent session after connecting. Choose a specific client with --target codex, --target claude-code, or --target opencode.

Related MCP server: TokenLighten

When should I index again?

index remains available for compatibility. Use init to start, sync for ordinary changes, and resync to rebuild. Do not repeatedly run init after normal edits.

Usage

Find examples for an exact repository location:

repogrammar find "path/to/routes.py:7" --project "$PWD" --mode compact
repogrammar families --project "$PWD"
repogrammar sync --project "$PWD"

Start with an exact path or symbol when available. Framework-qualified queries such as FastAPI route are also supported. See the CLI reference for the complete commands and the MCP contract for coding-agent integration.

Background updates

init starts a daemon for that repository. On macOS and Linux, native file notifications coalesce edits before a sync. Idle native operation reconciles metadata periodically instead of rescanning the tree every second. Git-ignored untracked directories are pruned before fingerprint traversal, while tracked files and ignore exceptions remain visible.

If native watching fails, autosync logs the fallback and polls with bounded idle backoff. Failed syncs retry with bounded backoff even without another edit. File notifications are hints; explicit sync and query-time hashes remain the freshness authority. These changes reduce background work; no battery-life percentage is claimed.

repogrammar autosync status --project "$PWD"
repogrammar autosync stop --project "$PWD"
repogrammar autosync start --project "$PWD"

For CI or one-shot analysis, initialize with --no-autosync. See the autosync contract for intervals and recovery.

How it works

repository → local index → pattern families → examples + bounded read plan
                                └──────────→ UNKNOWN + recovery action

• Repository conventions: find compatible implementations and their exceptions.

• Verifiable context: every result carries provenance and freshness checks.

• Incremental updates: native filesystem events wake autosync; changes use the existing incremental indexer. Periodic reconciliation and polling fallback handle unavailable watchers.

• Agent integration: connect Codex, Claude Code, or opencode through MCP.

How does it differ from other code tools?

These are mechanism comparisons, not benchmark or superiority claims. Static alignment is not proof of runtime equivalence. The FastAPI/pytest fixture walkthrough shows a read plan, optional source spans, and negative cases you can reproduce.

What do UNKNOWN and a bounded read plan mean?

UNKNOWN means the requested claim lacks sufficient qualifying evidence. Its typed reason and recovery action tell the agent what remains unresolved; it does not mean the repository is incorrect. PARTIAL_CONTEXT can provide local metadata without selecting a proven family. A bounded read plan names a limited set of source locations and remaining reading obligations. Read the required source before editing; the plan does not replace that obligation. See the MCP contract and UNKNOWN policy.

Does repository code leave my machine?

RepoGrammar's analysis runs locally and makes no LLM, embedding, or cloud calls. MCP responses contain metadata by default; source spans require explicit opt-in. The coding agent receiving that response has its own data-handling policy and may send metadata or requested source to its provider. Local analysis is not a privacy guarantee for the entire agent session. Anonymous telemetry is off by default and excludes source and paths; explicit upload is separate. See the telemetry contract for local diagnostics and consent boundaries.

Scope and limitations

The official language focus is Python: FastAPI, pytest, Pydantic, and SQLAlchemy. Other languages have bounded structural or dependency-inventory capabilities; these are not full language support. The strict Top-20 qualification program remains 0/20 complete. Read the language audit for the evidence and unresolved gates.

RepoGrammar is pre-1.0. It is not a sound whole-program analyzer, and neither a syntax match nor a dependency declaration proves behavior. Dynamic dispatch, unsupported frameworks, stale indexes, and incomplete semantics can result in abstention. Read known limitations before relying on a result.

Public binary targets are macOS arm64/x86_64 and glibc Linux arm64/x86_64. Windows and musl Linux are not supported installation targets.

Use ordinary source inspection when a repository has few repeated patterns, your framework is outside the bounded scope, or an answer remains UNKNOWN. Use runtime tests or a suitable semantic analyzer when the question requires behavioral correctness, security assurance, or whole-program proof.

Development

cargo build --locked
cargo test --workspace --all-features

Read CONTRIBUTING.md and the testing policy for the full checks. Architecture and specifications live in docs/. Report bugs through GitHub Issues; report security issues according to SECURITY.md.

License

MIT.