# argot

> A local guardrail that flags AI-written code foreign to a repo's own patterns — a dependency you've never used, a function you already wrote, logic in the wrong place, an import that breaks the layering — all learned from the repo's git history. One statically-linked Rust binary. The base voice model is model-free (statistical, no neural net); a small local code-embedding model powers the semantic layer — an embedding model, not an LLM: no generation, no cloud, 100% local. argot answers "is this how we write things here?", not "is this valid?".

argot is a **probabilistic** guardrail — verify before acting on a hit. Every docs page below has a plain-markdown twin at the same path with a `.md` suffix (e.g. `/docs/configure.md`) — fetch that to read the source without scraping HTML.

## Lifecycle

Argot learns locally; it is not a service that retrains on every pull request. Run `argot init` on the accepted branch, review and commit `argot.toml` plus the repository-specific `.argot/` snapshot, then let local tools and CI read that same baseline. CI reads the pull request base snapshot and never fits, so a PR cannot teach or certify itself. After material accepted source/function/layout drift, `refresh.next_action` explains whether maintenance is useful; invoke `argot-refresh` locally to review scope and mutes before fitting and recommitting. Commit count and age are not default triggers.

## Agent and MCP use

`argot mcp` is a passive, read-only server with six distinct tools: `argot.get_fit_status` for readiness and refresh advice; `argot.get_voice_context` for pre-write vocabulary; `argot.check_hunk` for a fast voice-only snippet signal; `argot.explain_hunk` for deeper evidence about that snippet; `argot.check_changeset` for the complete configured detector pipeline; and `argot.list_conventions` for repository discovery. The server does not fit or mutate the reviewed baseline. Setup and refresh remain explicit local workflows whose resulting `.argot/` snapshot is reviewed and committed.

## What it catches

A voice pass plus semantic, architecture, integrity, and optional custom-rule checks. History supplies the fitted model and artifacts; custom rules are authored by the repo. Every finding belongs to a named rule with a configurable severity (`error` fails the check, `warn` reports without failing, `off` disables) — set in `argot.toml [rules]` or per run with `--rule <name|group>=<severity>`; `argot rules` lists them.

**1 · Foreign — the base voice model (statistical, no neural net; ~98% when the foreign symbol is visible in the change):** a foreign dependency (an import the repo has never used), a foreign API (a call into a library it standardises away from), or a whole foreign paradigm (a Django-style view in a FastAPI repo, hand-rolled validation, a different HTTP client). This is the class the published benchmark numbers gate on. Rules (group `voice`): `foreign-import`, `rare-tokens`, `unfamiliar-callee`, `convention`.

**2 · Superseded — the migration miner (group `voice`):** new code written the way the repo is migrating away from. At fit, argot replays up to 1,000 accepted commits and mines replacement pairs (an import or callee systematically removed while its replacement is added); the replacement stops reading as foreign, and new code on the old pattern raises `superseded` (ships `warn`) citing the migrating commits. Migrations can also be declared in `argot.toml` (`[[migration]]` — from/to/reason, effective without a refit), and `argot conventions` lists each migration's remaining files.

**3 · Redundant — the semantic layer:** a new function that reinvents one the repo already has. A per-repo code-embedding index finds the nearest existing function and shows where it lives. Rule: `redundant` (group `semantic`).

**4 · Misplaced — the semantic layer:** the right code filed in the wrong package — its nearest semantic neighbours concentrate somewhere else. Rule: `misplaced` (group `semantic`).

**5 · Layering — the architecture graph:** an internal import that reverses the repo's established layer direction or crosses a boundary it never crosses. Canonical result: 264/272 (97.1%) — detector-specific real recall; control result is separate. Rule: `layering` (group `architecture`).

**6 · Test integrity — the test-inventory diff:** a test weakened, disabled, or deleted alongside the production change it covers — the shape of an agent gaming a failing suite. Canonical fixture result: 154/164 (93.9%) — detector-specific fixture catch; controls and accepted-history results are separate; accepted-history result: 45/3602 (1.2%) — replay false-fire rate at gating severity only. Rules (group `integrity`): `test-deleted`, `test-disabled`, `test-weakened` (ships `warn`).

The semantic layer runs a code-embedding model compiled INTO the binary: a 15.6 MB static token-embedding table argot distilled from `jina-embeddings-v2-base-code` (Apache-2.0) with the model2vec technique. There is nothing to download, no cache to warm and no accelerator — a fit works on an air-gapped machine, on the first run. It turns a function into a vector — no cloud, no text generation, nothing leaves your machine. `ARGOT_OFFLINE=1` never touches the network and changes no rule result.

**Beyond the learned six — your own rules.** A repo can drop scripted rules under `.argot/rules/<name>/` (a TOML manifest + a sandboxed Rhai script, group `custom`): repo-specific conventions no generic linter ships, run on every diff across all 12 languages — and, via path globs, on files argot doesn't even score (`.env`, CI configs). A rule can be **locked** (`{ severity = "error", locked = true }` in the committed `argot.toml`): its severity freezes and every suppression surface is refused, so an agent can't mute or downgrade a check it can't satisfy. Weakening a lock — or editing a locked rule's script — is itself reported by `rule-tampered` (group `governance`, pinned `error`, unsuppressable). Twelve built-in rules in five groups (`voice`, `semantic`, `architecture`, `integrity`, `governance`) plus the dynamic `custom` group; `argot rules` lists them all.

**The line it won't cross:** an in-vocabulary break where every token is already in the repo and only the *choice* is wrong (a bare `ValueError` where the repo raises `HTTPException`; a manual status check instead of `raise_for_status()`). The semantic layer narrows this gap but does not close it — argot won't gate on a wrong choice among your own vocabulary, and says so. **A clean `argot check` means "no foreign pattern found," not "this matches every convention."**

## Docs

- [Configure](https://argot.tmonier.com/docs/configure/): A committed argot.toml configures Argot, while a committed fit snapshot carries its learned voice — excludes, generated/data detection, rule severity, accepted hits, and local overrides. (markdown: https://argot.tmonier.com/docs/configure.md)
- [What it catches](https://argot.tmonier.com/docs/what-it-catches/): The six axes argot flags — a foreign dependency/API/paradigm the repo has never used, a pattern its own migrations left behind, a redundant function it already has, misplaced code, an import that breaks the repo's layering, and a test gamed to green a failing suite — plus an honest account of the in-vocabulary breaks it still won't gate on. (markdown: https://argot.tmonier.com/docs/what-it-catches.md)
- [The scoring model](https://argot.tmonier.com/docs/the-scoring-model/): The BPE log-ratio, the call-receiver penalty, file clustering, per-corpus auto-detect, the semantic layer, the architecture graph, and the integrity detector. (markdown: https://argot.tmonier.com/docs/the-scoring-model.md)
- [Languages](https://argot.tmonier.com/docs/languages/): Tree-sitter tokenization, supported languages, per-language calibration for monorepos, and test-integrity coverage per language. (markdown: https://argot.tmonier.com/docs/languages.md)
- [Performance](https://argot.tmonier.com/docs/performance/): Where the time goes, the machine-wide embedding cache, multi-core calibration — and the one rule behind all of it, results that never change with speed. (markdown: https://argot.tmonier.com/docs/performance.md)
- [Real-world scenarios](https://argot.tmonier.com/docs/real-world-scenarios/): argot dogfooded end-to-end on real repositories — setup, the day-one history audit, the local dev loop, muting, a gamed test, and the CI pull-request flow — with the actual transcripts, good and bad. (markdown: https://argot.tmonier.com/docs/real-world-scenarios.md)
- [Custom rules](https://argot.tmonier.com/docs/custom-rules/): Write your own rule — a rule.toml manifest plus a sandboxed Rhai script under .argot/rules/<name>/ — versioned with the repo, discovered fresh on every run, no recompiling argot. Same severities, suppressions, and output surfaces as every built-in. (markdown: https://argot.tmonier.com/docs/custom-rules.md)
- [Limitations](https://argot.tmonier.com/docs/limitations/): What argot deliberately does not prove: fit suitability, in-vocabulary choices, masked content, and changes outside the checked range. (markdown: https://argot.tmonier.com/docs/limitations.md)
- [Getting started](https://argot.tmonier.com/docs/): Install argot, audit accepted history, then fit a voice you can use in the daily review loop. (markdown: https://argot.tmonier.com/docs/getting-started.md)
- [Setup reference](https://argot.tmonier.com/docs/setup/): A compatibility route for repository setup; the canonical guide is Init and Fit. (markdown: https://argot.tmonier.com/docs/setup.md)
- [How it works](https://argot.tmonier.com/docs/how-it-works/): A local statistical voice model plus optional semantic, architecture, integrity, and custom-rule checks — with explicit limits on what a clean result means. (markdown: https://argot.tmonier.com/docs/how-it-works.md)
- [Set up with your agent](https://argot.tmonier.com/docs/setup-prompt/): One copy-pasteable prompt that walks any coding agent through setting argot up properly — audit, scope, fit, verify, tune, wire. (markdown: https://argot.tmonier.com/docs/setup-prompt.md)
- [Audit accepted history](https://argot.tmonier.com/docs/audit/): Review what Argot would have surfaced before changes were merged, without changing your working tree. (markdown: https://argot.tmonier.com/docs/audit.md)
- [Check a changeset](https://argot.tmonier.com/docs/check/): Select the changes to score, interpret severity and confidence separately, and keep the human decision explicit. (markdown: https://argot.tmonier.com/docs/check.md)
- [Init and Fit](https://argot.tmonier.com/docs/init-and-fit/): Set up portable configuration and a committed fit snapshot with init; refresh it locally with fit. (markdown: https://argot.tmonier.com/docs/init-and-fit.md)
- [Claude Code](https://argot.tmonier.com/docs/plugin/): The Claude Code plugin bundles on-demand skills, passive MCP tools, and an opt-in pre-write ask. (markdown: https://argot.tmonier.com/docs/plugin.md)
- [Other agents and MCP](https://argot.tmonier.com/docs/agents/): Use Argot skills and read-only MCP context with a compatible host, without assuming lifecycle automation. (markdown: https://argot.tmonier.com/docs/agents.md)
- [CI and pre-commit](https://argot.tmonier.com/docs/ci/): Wire Argot into a GitHub workflow or commit hook with the default advisory behavior made explicit. (markdown: https://argot.tmonier.com/docs/ci.md)
- [Snapshot health and refresh](https://argot.tmonier.com/docs/health-and-freshness/): Understand when Argot's committed repository memory needs maintenance, and refresh it locally without turning CI into a training system. (markdown: https://argot.tmonier.com/docs/health-and-freshness.md)
- [Command reference](https://argot.tmonier.com/docs/the-commands/): A compatibility route for the command overview; use the focused guides for the everyday workflow. (markdown: https://argot.tmonier.com/docs/the-commands.md)
- [Output reference](https://argot.tmonier.com/docs/reading-the-output/): A compatibility route for check output details; use Check a changeset for the canonical guide. (markdown: https://argot.tmonier.com/docs/reading-the-output.md)
- [Troubleshooting](https://argot.tmonier.com/docs/troubleshooting/): Diagnose shallow history, unsupported files, fit health, skipped rules, integrations, and removal safely. (markdown: https://argot.tmonier.com/docs/troubleshooting.md)

## Reference

- [AGENTS.md](https://github.com/get-tmonier/argot/blob/main/AGENTS.md): the canonical contract for using argot with a coding agent — the never-block rule, how to read `argot check` output, and muting false positives with a reason.
- [README](https://github.com/get-tmonier/argot/blob/main/README.md): install, quickstart, what it catches, and the honest benchmarks.
- [Skills](https://github.com/get-tmonier/argot/tree/main/skills): the `argot-setup`, `argot-refresh`, `argot-check`, `argot-review-pr`, `argot-setup-ci`, `argot-write-rule`, and `argot-suggest-rules` agent skills — `npx skills add get-tmonier/argot`.
- [Benchmarks](https://argot.tmonier.com/benchmarks): per-repo catch and false-alarm numbers, fed from CI.