• GIF

  The init process of repogrammar for a repo

RepoGrammar

Save tokens when coding with AI agents.

Inspiration

Coding agents repeatedly waste tokens rediscovering conventions that already exist in a repository: how routes, tests, models, fixtures, or data-access methods are implemented.

Humans rarely read an entire codebase before making a change. They inspect a few representative examples and follow the repository's established patterns.

RepoGrammar applies the same principle:

Read only what is necessary, and trust only what the repository evidence supports.

What It Does

RepoGrammar gives coding agents a compact and auditable map of repeated implementation patterns before they begin broad source-code exploration.

It returns:

• Family: a repeated implementation pattern with sufficient compatible support.
• Variation and exception: observed differences, accepted variations, and intentionally unsupported cases.
• Evidence: repository-relative paths, content hashes, byte ranges, and support counts, without source snippets by default.
• Read plan: a prioritized set of hash-checked source spans to inspect before editing.
• UNKNOWN: a typed abstention for stale, ambiguous, dynamic, unsupported, or out-of-scope cases. This prevents uncertain evidence from being presented to coding agents as fact.

RepoGrammar provides a pattern-family-first CLI and a read-only MCP tool named repogrammar_context, integrated with Codex and Claude Code.

How We Built It

RepoGrammar uses a Rust core with a layered, dependency-inverted architecture:

core → ports → application → adapters → interfaces

Key design decisions include:

• Tree-sitter generates candidates but does not prove semantics. A family requires at least three compatible implementations backed by exact framework anchors.
• Target-repository application code is never executed. The Python worker may parse files such as setup.py, but never runs them. The TypeScript worker does not load the repository's own typescript package by default.
• Local-first indexing. Repository metadata is stored in a mutable SQLite database under .repogrammar/, with explicit init, sync, and autosync workflows.
• One-command setup. repogrammar setup combines agent detection, MCP integration, repository indexing, autosync configuration, and an MCP self-test behind one confirmation.

Challenges We Ran Into

The hardest problem was not finding patterns. It was deciding when a pattern claim was unsafe.

This led to several safeguards:

• Typed uncertainty: unresolved evidence is classified explicitly rather than hidden.
• Lookalike rejection: similar syntax is insufficient without framework-specific imports, fully qualified names, or other exact anchors.
• Untrusted-input handling: parsers, workers, installers, archives, and file reads operate under strict safety and resource limits.
• Mutable-index correctness: stale records, dependency changes, dirty markers, incremental updates, and re-indexing are handled transactionally.

Accomplishments That We Are Proud Of

RepoGrammar demonstrates that repository-aware context reduction does not require another LLM, vector database, embedding service, or cloud model.

Key accomplishments include:

• Evidence-backed repository pattern families.
• Metadata-first output with optional and bounded source spans.
• Hash-checked and prioritized read plans.
• First-class typed abstention instead of fabricated certainty.
• Fully local operation with no LLM or cloud-model dependency at runtime.
• A transparent support matrix distinguishing official support, structural previews, and discovery-only languages.

What We Learned

Useful context matters more than more context.

Coding agents benefit most from a small amount of trustworthy evidence, representative implementations, and an explicit plan describing what still needs to be read.

Abstention should not be treated as failure. In repository analysis, knowing when the available evidence is insufficient is part of producing a reliable answer.

What's Next

RepoGrammar will expand its query and language coverage without weakening its evidence model.

The next priorities are:

• Add analyzer-backed semantic evidence to reduce avoidable UNKNOWN results.
• Improve target resolution for files, symbols, directories, modules, and scoped pattern queries.
• Advance Go, PHP, Ruby, and Swift beyond discovery-only support.
• Integrate with more coding agents, including Cursor, OpenCode, and Gemini-based workflows.

Built With

• codex
• python
• rust
• tree-sitter