Local implementation-pattern context for coding agents.
Coding agents often search repositories as loose files, not as implementation families. RepoGrammar gives an agent local, source-backed context about how a repository usually implements a feature before the agent edits code. Instead of returning a long list of vaguely similar files, it summarizes recurring families, accepted variations, exceptions, and the evidence behind those claims.
RepoGrammar is pre-alpha. The current public preview is local-first and
conservative: when evidence is insufficient, stale, ambiguous, or outside the
supported scope, RepoGrammar returns UNKNOWN instead of guessing.
| Approach | What it is good at | What RepoGrammar adds |
|---|---|---|
grep / file search |
Fast exact text lookup. | Pattern-family summaries, support counts, variations, exceptions, typed UNKNOWNs, and a read plan for edits. |
| Embedding/RAG retrieval | Broad semantic recall over nearby text. | Repo-local family claims with freshness checks, metadata-only default output, and conservative abstention when support is weak. |
| LLM-only repo reasoning | Flexible interpretation after reading files. | A source-backed contract the agent can audit before spending tokens on source spans or making a claim. |
| Generic graph navigation | Precise symbol or call-path exploration. | Implementation-family context: canonical examples, legal variations, unsupported gaps, and claim-scoped uncertainty. |
There are no confirmed public release artifacts or published npm package in this checkout yet. Until a preview tag and npm publication are verified, use the source-checkout contributor dogfood path:
git clone https://github.com/SioYooo/RepoGrammar.git
cd RepoGrammar
cargo build --release
bash src/install/repogrammar-install.sh --install-cli-only --from-source --yes
repogrammar version
Then initialize a repository you want to analyze:
cd /path/to/your/repo
repogrammar init
repogrammar stats --json
repogrammar find --project . --token-budget 8000 <repo-relative-path-or-symbol>
Use repogrammar init --autosync when the repository should keep refreshing
after the first active index is built.
For coding-agent integration from a source checkout:
cd /path/to/RepoGrammar
bash src/install/repogrammar-install.sh --install-and-configure --from-source --yes --target all
See docs/quickstart.md, docs/quickstart-codex.md, and docs/quickstart-claude.md for copy-pasteable setup flows and caveats.
RepoGrammar output is designed to be small and auditable:
family: the local implementation family that has enough compatible support.variation: bounded differences among supported members, when evidence covers them.exception: intentionally unsupported or incompatible cases, when evidence covers them.evidence: repo-relative metadata, hashes, byte ranges, support counts, and covered claim labels; source snippets are not returned by default.read_plan: hash-checked spans an agent should inspect before editing.UNKNOWN: typed abstention for stale, ambiguous, dynamic, unsupported, low-support, or unresolved claims.
Explicit source output is opt-in only: --include-source-spans or
include_source_spans=true returns bounded line-numbered spans selected from
the read plan after content-hash validation.
The scoped v0.1 preview focuses on Python repositories using:
- FastAPI
- pytest
- Pydantic
- SQLAlchemy
Current Python claims are bounded framework-family claims, not full Python
semantic analysis. RepoGrammar requires compatible repeated evidence before it
emits a confident family claim. Low-support, dynamic, stale, or unresolved cases
remain UNKNOWN. The Python preview includes a static repo-local import and
pytest fixture graph for exact local modules, direct imported top-level symbols,
literal package re-exports, literal __all__ star imports, and unambiguous
same-file or conftest.py fixture bindings; it does not execute Python, pytest,
or project dependencies.
TypeScript and JavaScript are not official v0.1 support targets. A conservative
v0.2 token-saving foundation adds exact-anchor family support for Express
routes, Jest/Vitest suites/tests, and structural-preview Next.js, Fastify,
Prisma, and Drizzle adapters: a family is claimed solely when an exact local
anchor is promoted to application-layer DATAFLOW_DERIVED support. Lookalikes,
package-only evidence, reassigned or shadowed bindings, dynamic receivers or
methods, custom test wrappers, React components/hooks, Next middleware/server
actions/re-exports, Fastify dynamic or imported plugin registrations, Prisma
bulk/injected/raw clients, and Drizzle raw/dynamic builders stay UNKNOWN.
Exact local Fastify register(plugin, { prefix: "..." }) calls record
plugin/prefix context only and do not prove route support. Next dynamic
segments, route groups, and parallel routes are retained as bounded context on
exact local page/layout/route anchors rather than treated as membership proof
by themselves. TS/JS family claims require at least three compatible
exact-anchor support facts and use conservative complete-link clustering so
incompatible handler/test/component/query shapes do not single-link into one
family. Bounded package.json, tsconfig.json, jsconfig.json, and
Jest/Vitest config inventory is stored as structural context only. A bounded
repo-local static import resolver can record relative/path-alias imports as
structural context, while dynamic imports, conditional require, unresolved
aliases, and star re-exports remain typed UNKNOWN. When explicitly configured
through the semantic-worker environment variables, the checked-in TypeScript
worker can accept bounded module/export/package operations, use the TypeScript
compiler API for module resolution, and cross-check exact Next.js
file-convention export identity, relative repo-local Express/Fastify named
handler imports, relative repo-local Prisma shared-client bindings, or relative
repo-local Drizzle db/table bindings when a TypeScript module is available to
that worker. Only matching
TypeScript-provider resolve_export facts for exact Next.js anchors and
resolve_reexport facts for provider-required Express/Fastify handler imports
or relative repo-local Prisma/Drizzle bindings such as
import { prisma } from "./db" or Drizzle named db/users imports from
./db and ./schema may become
provider-resolved TS/JS-derived support; fallback
facts remain context only. Without that API it emits only structural fallback
facts or typed UNKNOWNs. This is not full TypeScript/JavaScript semantic
analysis.
For Jest/Vitest, package dependencies and JSON config files can provide ambient
runner context; script configs such as jest.config.ts or vitest.config.js
are recorded only as metadata/typed UNKNOWN and are not executed.
Rust is currently used only for RepoGrammar self-dogfooding. The v0.2 preview
can index .rs files with Tree-sitter Rust and form conservative internal
RepoGrammar implementation families such as indexing phases, family gates,
parser adapters, CLI/MCP handlers, installer actions, storage validation, and
product tests. This path is structural only: it does not run Cargo, rustc,
build scripts, or procedural macros. Cargo build scripts and target-specific
manifest sections are typed build-variant UNKNOWNs that block affected Rust
self-dogfood families until resolved; this is not general-purpose Rust semantic
analysis.
repogrammar stats --json keeps public readiness scoped: top-level readiness is
still Python v0.1-focused (official_family_scope: python_v0_1,
repo_shape_scope: python_family_eligible_units), while indexed_inventory
reports source-free active-index counts. A TS/JS repository can therefore be
indexed successfully while top-level Python eligible_code_units is 0.
by_language reports source-free indexed file/code-unit counts plus readiness
buckets for Python, bounded TS/JS and Java previews, and the internal Rust
self-dogfood preview. For TS/JS code with no supported family rows, stats points
users to repogrammar find or repogrammar check with exact repo-relative
paths for PARTIAL_CONTEXT read plans. React/RN family support remains
unsupported and stats must not turn React/RN components into family or
conformance claims. repogrammar unknowns --json and stats --unknowns --json
summarize typed UNKNOWNs by low-cardinality buckets only, without source text,
absolute paths, code-unit ids, fact ids, or free-text recovery guidance.
stats --json also reports a separate local-only query outcome rollup so
agents can distinguish successful family hits from PARTIAL_CONTEXT, typed
UNKNOWN, and fallback responses without recording targets, paths, symbols, or
source text.
repogrammar status --json and repogrammar doctor --json also report a
source-free readiness object for repository setup and local analysis state.
It distinguishes not-initialized repositories, state-only repositories with no
active index, ready active indexes, unhealthy or stale active indexes, and
autosync recommendations. The same object reports whether .repogrammar/ is
present, ignored, or accidentally tracked, and treats .codegraph/ as foreign
unmanaged provider state that RepoGrammar never creates, repairs, or deletes.
| Area | Public-preview status | Boundary |
|---|---|---|
| Python FastAPI | Supported | Bounded exact-anchor framework-family evidence plus static repo-local import context; literal include_router(..., prefix="...") records context only, while dynamic decorators/prefixes, unresolved imports, runtime DI, and stale evidence produce UNKNOWN. |
| Python pytest | Supported | Bounded test/fixture family evidence plus static fixture graph context; ambiguous fixture injection, nonliteral lookups, and dynamic plugin behavior produce UNKNOWN. |
| Python Pydantic | Supported | Bounded model/settings family evidence plus field and Field(...) metadata context; validator side effects, external bases, dynamic model factories, dynamic ConfigDict, and unresolved bases produce UNKNOWN. |
| Python SQLAlchemy | Supported | Bounded SQLAlchemy model/repository evidence plus DeclarativeBase/declarative_base() context and local literal relationship-target context; raw SQL, external bases, runtime-injected sessions, custom query wrappers, event listeners, dynamic model classes, dynamic declarative behavior, and dynamic relationship targets remain conservative. |
| JS/TS Express | v0.2 conservative preview | Exact import/require binding plus direct literal route calls and exact literal app.use("/prefix", router) mount context only; support requires at least three complete-link-compatible examples, and dynamic prefixes/middleware side effects remain unsupported. |
| JS/TS Jest/Vitest | v0.2 conservative preview | Imported runner, imported alias runner, or ambient test-file runner with safe project context only; custom wrappers and foreign runner imports stay UNKNOWN. |
| JS/TS Next.js | v0.2 compiler-cross-checked preview | next package context plus exact local App Router pages/layouts/routes and Pages Router pages/API routes; configured TypeScript workers can provider-cross-check exact route/page/layout/API export identity, while dynamic segments, route groups, parallel routes, middleware, server/client semantics, server actions, and re-exported routes remain context or UNKNOWN. |
| JS/TS Fastify | v0.2 structural preview | Exact local Fastify factory receiver plus shorthand or literal app.route declarations; exact local register(plugin, { prefix: "..." }) records plugin/prefix context only, while dynamic methods/options, imported plugins, plugin side effects, and dynamic prefixes remain UNKNOWN. |
| JS/TS Prisma | v0.2 compiler-cross-checked preview | Exact local new PrismaClient() bindings plus whitelisted model read/write operations and array $transaction; configured TypeScript workers can provider-cross-check relative repo-local named shared-client imports, while bulk operations, injected clients, external shared clients, extensions, callback transactions, dynamic model/op access, and raw SQL remain UNKNOWN. |
| JS/TS Drizzle | v0.2 compiler-cross-checked preview | Exact Drizzle table factories and local drizzle(...) db bindings remain structural; configured TypeScript workers can provider-cross-check relative repo-local named db/table imports for whitelisted select/insert/update/delete and db.query.<table>.findMany/findFirst; unresolved tables/dbs, external imports, dynamic builders, and raw SQL remain UNKNOWN. |
| JS/TS React | Not supported | Components/hooks may be detected as roles but cannot form public family claims. |
| Full JS/TS semantic analysis | Not supported | Only bounded optional TypeScript worker operations exist; no full Program/TypeChecker family support, dynamic wrapper support, package-script execution, or general JS/TS semantic claim. |
| Rust self-dogfood | Internal v0.2 preview | RepoGrammar-owned implementation families only, from Tree-sitter structural anchors; no Cargo/rustc/proc-macro execution and no general Rust semantic claims. |
| Java Spring MVC | v0.2 structural preview | Exact imported/FQN Spring MVC mapping annotations inside exact controllers; route constants and runtime dispatch remain UNKNOWN subclaims. |
| Java Spring/Spring Boot | v0.2 structural preview | Exact Spring stereotypes and @SpringBootApplication; component scan, DI, auto-configuration, and proxy behavior remain UNKNOWN. |
| Java Spring Data | v0.2 structural preview | Exact imported/FQN JpaRepository inheritance or @RepositoryDefinition; generated implementations, repository factories, and classpath resolution remain UNKNOWN. |
| Source text output | Explicit opt-in only | Default CLI/MCP output is metadata-only; --include-source-spans / include_source_spans=true returns bounded hash-checked line-numbered spans. |
| Token savings | Not claimed by default | Token-saving claims require paired baseline/treatment measurements. estimated_potential_token_savings is a local ESTIMATED potential-read-displacement diagnostic, not measured savings. |
| Project-local live install | Deferred | Public preview live writes are machine-level agent wiring only; per-repository .repogrammar/ lifecycle uses explicit init/resync/autosync commands. |
Publication caveat: this source checkout contains the release workflow and npm launcher, but that is not proof that public release artifacts or the npm package are already available. Use the source-checkout dogfood path above until a preview tag has produced release assets and npm publication has been verified. The three-phase rollout gate and per-phase verification steps live in docs/release/public-preview-release-checklist.md.
After a public-preview prerelease has been published, install the prebuilt CLI
binary first. During preview, use the exact prerelease tag rather than GitHub's
latest redirect:
curl -fsSLO https://github.com/SioYooo/RepoGrammar/releases/download/v0.2.0-preview.0/install.sh
bash install.sh --version v0.2.0-preview.0
After the npm package is published, users with Node/npm can use the wrapper to
download the same prebuilt binary and run it through npx:
npx @sioyooo/repogrammar install
After publication, you can also install the wrapper globally:
npm install -g @sioyooo/repogrammar
repogrammar install
The installer downloads the matching macOS/Linux release artifact, verifies its
checksum, installs repogrammar into a user-writable command directory, and
then can launch the agent setup wizard. Windows preview builds use the
PowerShell installer below. Neither path requires Rust, Cargo, Node.js, Docker,
a local LLM, an embedding model, or a cloud API key. The current Python preview
still requires a python3 interpreter at indexing time to run RepoGrammar's
bundled CPython AST worker; it does not require a Python virtualenv or project
dependency installation.
The npx / npm path requires Node/npm by definition, but still does not require
Rust or Cargo. On Windows preview builds, use PowerShell:
Invoke-WebRequest https://github.com/SioYooo/RepoGrammar/releases/download/v0.2.0-preview.0/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1 -Version v0.2.0-preview.0
Agent integration requires the native CLI for the agent you choose: codex for
Codex integration and claude for Claude Code integration. Missing agent CLIs
are non-fatal; you can configure the agents that are available and rerun
repogrammar install later.
The installer separates three steps: get the CLI, wire coding agents, then run
repogrammar init / repogrammar index inside each repository. Agent wiring
does not index code and does not create .repogrammar/.
From a source checkout, the same installer lives at:
bash src/install/repogrammar-install.sh
powershell -ExecutionPolicy Bypass -File src/install/install.ps1
Those scripts can install or repair the repogrammar command from a release,
configure Codex and Claude Code, uninstall connected agent integrations, remove
the local repogrammar command, or, for contributors, build from source. On
Windows, the PowerShell source-checkout menu defaults to the same contributor
source-build path. Until the first prerelease artifact exists, source-checkout
dogfood is the supported path:
cargo build --release
bash src/install/repogrammar-install.sh --install-cli-only --from-source --yes
repogrammar version
bash src/install/repogrammar-install.sh --install-and-configure --from-source --yes --target all
powershell -ExecutionPolicy Bypass -File src/install/install.ps1 -InstallCliOnly -FromSource -Yes
powershell -ExecutionPolicy Bypass -File src/install/install.ps1 -InstallAndConfigure -FromSource -Yes -Target all
The source path installs the built binary into RepoGrammar-managed user state
and refreshes the user-writable repogrammar command without requiring a
GitHub Release asset or published npm package. If that command path already
contains an older unmanaged repogrammar, the installer backs it up before
replacing it with the managed command. After install/update, the scripts compare
other repogrammar copies on PATH by SHA256 and remove stale copies when
--yes / -Yes is used; on Windows, install.ps1 -Verify reports the same
state and install.ps1 -Prune -Yes runs the cleanup explicitly. If a stale
copy cannot be removed because a process or permissions blocks deletion, the
installer exits nonzero and leaves the stale copy listed for manual cleanup.
Before the npm package is published, local npm dogfood can bypass release downloads with an already built binary:
REPOGRAMMAR_BINARY=/absolute/path/to/target/release/repogrammar node src/npm/repogrammar.js version
npm pack
npm install -g ./sioyooo-repogrammar-0.2.0-preview.0.tgz
The published npm path still expects release artifacts by default.
Contributor release-readiness smoke should also cover the source checkout and a fresh checkout before a preview tag is cut:
npm_config_cache=/tmp/repogrammar-npm-cache npm pack --dry-run
REPOGRAMMAR_BINARY=/absolute/path/to/target/debug/repogrammar node src/npm/repogrammar.js version
repogrammar init --project /tmp/repogrammar-smoke --yes --resync --json --progress never
repogrammar status --project /tmp/repogrammar-smoke --json
repogrammar doctor --project /tmp/repogrammar-smoke --json
repogrammar unknowns --project /tmp/repogrammar-smoke --json
repogrammar stats --project /tmp/repogrammar-smoke --unknowns --json
repogrammar install --target all --scope global --dry-run
repogrammar uninstall --target all --scope global --dry-run
The dry-run install and uninstall commands currently produce human-readable plans, not JSON. The full contributor smoke matrix, including MCP serving and optional source-tree secret scans, is documented in docs/development/testing.md.
You can also review the plan without writing anything:
repogrammar install --target all --scope global --dry-run --no-telemetry
The installer configures machine-level coding-agent MCP integration. It does not
index the current repository and does not create or modify .repogrammar/.
Supported public-preview binary targets are macOS arm64/x86_64, Linux arm64/x86_64, and Windows x86_64 preview. Release artifacts include the RepoGrammar binary and the Python worker asset used by the current Python frontend. The npm wrapper is a thin launcher for those same release artifacts; it is not the implementation of RepoGrammar.
After repogrammar is installed from source or from a verified release, run
the repository-local analysis step from a repository you want to analyze:
repogrammar init --autosync
repogrammar status
repogrammar autosync status
repogrammar prune --dry-run
repogrammar compact --dry-run --json
repogrammar storage clean --dry-run
repogrammar logs --component daemon --tail 20
repogrammar families
repogrammar find --project . --token-budget 8000 <target>
repogrammar family --project . --mode compact <family-id>
repogrammar explain --project . --token-budget 8000 <target>
repogrammar check --project . --token-budget 8000 <target>
Before a repository is initialized or before enough evidence exists, query
commands return explicit fallback or UNKNOWN results rather than pretending an
index or family claim exists.
repogrammar install wires machine-level agent MCP integration only and can be
run separately when agent setup is desired. Repository analysis is always an
explicit per-repository step:
repogrammar init creates safe repo-local state and builds or refreshes the
active static-analysis generation by default. Add --autosync to start
repository-local auto-sync after that first index succeeds; automation may add
--yes for noninteractive confirmation. Use --state-only only for low-level
lifecycle repair when indexing must be skipped. resync shows progress
automatically in an interactive terminal. Use
repogrammar resync --progress always to force progress output, or
repogrammar resync --progress never for quiet scripts.
If repogrammar status reports storage_layout: mutable_with_legacy, the
mutable SQLite database is authoritative and the old generation-directory
layout is diagnostic state. Inspect reclaimed space with
repogrammar storage clean --dry-run, then run
repogrammar storage clean --yes to remove the legacy layout, prune inactive
mutable generations, and compact the repo-local SQLite database.
repogrammar autosync start is optional but recommended for dogfooding. It
enables repository-local auto-sync and starts a background worker that tracks a
lightweight supported-file metadata fingerprint, debounces saves, and runs
sync so added, modified, removed, and unchanged paths are reconciled into the
next active generation. sync uses path-level incremental copy-forward when
safe and reports a full-rebuild fallback when project context or worker
preconditions require it. It does not run from install, does not initialize
other repositories, and can be inspected or managed with:
repogrammar autosync status
repogrammar logs --component daemon --tail 20
repogrammar autosync stop
repogrammar autosync disable
RepoGrammar exposes a read-only MCP tool named repogrammar_context.
For find_analogues, explain_deviation, and check_conformance, agents
should pass the repo-relative path, symbol/member id, framework role, or pattern
question they already have; RepoGrammar discovers candidate families internally
and returns exact family ids as follow-up handles. show_family remains
exact-family-id only.
Global MCP integration is supported for Codex and Claude Code. Running
repogrammar install with no flags opens a simple text wizard that lets you
select Codex, Claude Code, or both in one run. Re-running the wizard later lets
you add a missing supported agent or repair the repogrammar command without
reinstalling already managed agents. Anonymous telemetry remains opt-in and
default-no in the wizard; after you review the install plan, pressing Enter at
the final confirmation proceeds.
Noninteractive dry-runs remain available:
repogrammar install --target all --scope global --dry-run --no-telemetry
After reviewing the plan, use --yes for explicit noninteractive installs:
repogrammar install --target codex --scope global --yes --no-telemetry
repogrammar install --target claude-code --scope global --yes --no-telemetry
repogrammar install --target all --scope global --yes --no-telemetry
Multi-agent install is all-or-rollback: if one selected agent fails, changes from the same run are rolled back. Project-local live writes are deferred.
For planning and manual configuration, the CLI also understands CodeGraph-style
target ids such as cursor, opencode, hermes, gemini, antigravity, and
kiro in dry-run and --print-config modes:
repogrammar install --print-config cursor --location local
repogrammar install --target cursor,gemini --location local --dry-run --no-telemetry
Those preview targets are not live-written by the public preview installer yet.
RepoGrammar is local-first. Repository-derived indexes live under
.repogrammar/ in the analyzed project.
Anonymous telemetry is off by default. install --yes does not imply telemetry
consent. Telemetry, when explicitly enabled, is designed to use coarse
allowlisted product metrics and must not include source code, prompts, query
text, repository names, paths, symbols, credentials, or raw errors.
Useful commands:
repogrammar telemetry status --json
repogrammar telemetry on
repogrammar telemetry off
repogrammar telemetry export --json
repogrammar telemetry purge --yes
Local paired token experiments can record already-redacted host usage counts without manual token flags:
repogrammar telemetry experiment-record --name <id> --usage-json usage.json
The usage file must contain only token counts plus optional success/test outcome metadata; raw prompts, source, paths, symbols, messages, patches, and query text are rejected.
RepoGrammar is not production-ready and should not be treated as a sound static analyzer. In this preview:
- Python support is limited to bounded framework-family evidence.
- Dynamic Python behavior often produces typed
UNKNOWN. - JS/TS preview support is limited to exact-anchor Express, Jest/Vitest, Next.js, Fastify, Prisma, and Drizzle families. Full JS/TS semantics, React, dynamic wrappers, executable Jest/Vitest/Next config semantics, Fastify dynamic prefix and plugin-effect resolution, Prisma/Drizzle runtime extensions, and complete alias/re-export resolution are deferred.
- Source snippets are not returned by default.
- Full Python semantic providers, runtime observation, and broader language support are deferred.
- Telemetry upload remains experimental and opt-in.
See docs/limitations.md for the public-preview boundary checklist and examples of claims to avoid.
- Documentation map
- Quickstart
- Codex quickstart
- Claude Code quickstart
- Limitations
- Python FastAPI/pytest example
- CLI specification
- Product specification
- Python analysis specification
- MCP API specification
- Telemetry specification
- Roadmap
Contributors building from source need Rust/Cargo. Node.js is needed only for TypeScript worker tests; Python 3 is needed for Python indexing and Python worker tests. For contributor setup, architecture, and validation commands, start with docs/README.md and docs/development/testing.md.
MIT