{"id":46250393,"url":"https://github.com/mmnto-ai/totem","last_synced_at":"2026-08-27T15:57:36.120Z","repository":{"id":341159017,"uuid":"1168851303","full_name":"mmnto-ai/totem","owner":"mmnto-ai","description":"Rules you can enforce, state you can derive, context you can query: plain files in your repo, under whichever coding agent you use.","archived":false,"fork":false,"pushed_at":"2026-08-22T04:08:51.000Z","size":16918,"stargazers_count":16,"open_issues_count":433,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-08-22T04:17:16.640Z","etag":null,"topics":["agents-md","ai-agents","ast-grep","claude-code","cli","code-review","codebase-governance","deterministic","developer-tools","git-hooks","human-in-the-loop","linting","mcp-server","monorepo","pnpm","rule-engine","static-analysis","typescript","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmnto-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","claude":"CLAUDE.md","gemini":"GEMINI.md","cursor":null,"copilot":".github/copilot-instructions.md","dco":null,"cla":".github/CLA.md","disclosure":null}},"created_at":"2026-02-27T21:46:24.000Z","updated_at":"2026-08-22T02:27:49.000Z","dependencies_parsed_at":"2026-08-22T04:22:31.273Z","dependency_job_id":null,"html_url":"https://github.com/mmnto-ai/totem","commit_stats":null,"previous_names":["mmnto-ai/totem"],"tags_count":1020,"template":false,"template_full_name":null,"purl":"pkg:github/mmnto-ai/totem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmnto-ai%2Ftotem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmnto-ai%2Ftotem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmnto-ai%2Ftotem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmnto-ai%2Ftotem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmnto-ai","download_url":"https://codeload.github.com/mmnto-ai/totem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmnto-ai%2Ftotem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36821662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-06T04:43:03.162Z","status":"online","status_checked_at":"2026-08-22T02:00:06.114Z","response_time":51,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai-agents","ast-grep","claude-code","cli","code-review","codebase-governance","deterministic","developer-tools","git-hooks","human-in-the-loop","linting","mcp-server","monorepo","pnpm","rule-engine","static-analysis","typescript","vector-database"],"created_at":"2026-03-03T22:05:43.814Z","updated_at":"2026-08-27T15:57:36.115Z","avatar_url":"https://github.com/mmnto-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Totem\n\n[![npm version](https://img.shields.io/npm/v/@mmnto/totem.svg)](https://www.npmjs.com/package/@mmnto/totem)\n[![CI](https://github.com/mmnto-ai/totem/actions/workflows/ci.yml/badge.svg)](https://github.com/mmnto-ai/totem/actions/workflows/ci.yml)\n[![MCP Server](https://img.shields.io/badge/MCP-Server-1f6feb)](https://github.com/mmnto-ai/totem/tree/main/packages/mcp)\n[![License: Apache-2.0](https://img.shields.io/github/license/mmnto-ai/totem)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D24-339933?logo=nodedotjs\u0026logoColor=white)](https://nodejs.org)\n[![pnpm](https://img.shields.io/badge/pnpm-managed-F69220?logo=pnpm\u0026logoColor=white)](https://pnpm.io)\n\n**Editor integrations:** [Claude Code](.claude/) · [Gemini CLI](.gemini/) · [GitHub Copilot](.github/copilot-instructions.md) · [JetBrains Junie](.junie/) · others in progress. See [`AGENTS.md`](AGENTS.md) for how integration works.\n\n_AI coding agents are brilliant goldfish. Totem keeps your project's lessons, rules, and context in the repository itself, underneath whichever agent you run, so what the team learned survives the session that learned it._\n\n\u003e `totem lint` is deterministic and offline. Zero LLM calls, no network, and the cost scales with the size of your diff, not the size of your history. Timing numbers live in [CI-recomputed receipts](docs/wiki/maturity.md), not in this README.\n\nWhen using LLMs on projects, I found that agents kept making the same architectural mistakes. They forgot context and reinvented helpers that already existed. The velocity was great, but the architectural integrity degraded quickly. Every PR became an exhausting back-and-forth with review bots over the same nits. They can make the wrong way look brilliant (until you realize what happened). They'll rarely ask: _\"doesn't a shared helper already exist for this?\"_\n\nThe cause is structural, not a prompt problem. Models are stateless. Every session starts from zero, and anything the last session learned is gone unless it lives somewhere durable. If project rules and lessons don't reside in the repository alongside the code, no amount of re-explaining fixes it for the next session.\n\nTotem is what I extracted to solve that friction. It's a file-based toolkit: plain markdown lessons, a queryable knowledge index derived from them, and compiled lint rules a zero-LLM linter enforces. The lint engine is deterministic; the index is local, derived, and rebuilt from your files at any time; the compiler and review commands are LLM-powered and opt-in. The structural pieces ship today; [Where the Loop Stands](#where-the-loop-stands) says exactly which half is which. The discipline and telemetry layers are in active development; the [maturity page](docs/wiki/maturity.md) carries the honest split, machine-derived from committed data.\n\n---\n\n- [Tripwires, Not Tracks](#tripwires-not-tracks)\n- [How Mistakes Become Rules](#how-mistakes-become-rules)\n- [Where the Loop Stands](#where-the-loop-stands)\n- [The Queryable Knowledge Index](#the-queryable-knowledge-index)\n- [What's in the Box](#whats-in-the-box)\n- [What Works and What Doesn't](#what-works-and-what-doesnt)\n- [Quickstart](#quickstart)\n- [Documentation \u0026 Workflows](#documentation--workflows)\n\n---\n\n## Tripwires, Not Tracks\n\nTo an agent, documentation is merely a suggestion. I tried the heavy orchestration approach that dictates every step of the agent's workflow, and found it rigid and disruptive to the human-in-the-loop dynamic. Totem is built on a different philosophy: you provide an open field surrounded by electric fences. The LLM is free to code however it wants, but when it attempts to alter the permanent state of the world (e.g., `git push`), it hits a deterministic tripwire.\n\nTotem turns a plain-English markdown lesson into a physical constraint that a local, zero-LLM linter enforces:\n\n**Input:** (`.totem/lessons/no-child-process.md`)\n\n```markdown\n## Lesson - Never use native child_process\n\nTags: architecture\nDirect use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead.\n```\n\n**Output:** (`git push` blocked on the agent's machine)\n\n```bash\n$ git push\n[Lint] Running compiled rules (zero LLM)...\n### Warnings\n- **packages/cli/src/git.ts:22** - Never use native child_process\n  Pattern: `import { execSync } from 'node:child_process'`\n  Lesson: \"Direct use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead.\"\n[Lint] Verdict: FAIL - Fix violations before pushing.\n```\n\nThe \"wrong\" way becomes the \"loud\" way. No LLM in the loop at runtime, no network, and the linter only reads your diff, which is why enforcement stays cheap no matter how large the project gets.\n\n## How Mistakes Become Rules\n\nThe core loop is simple. A mistake gets caught in a PR review, a bot nit, or a production bug. I write a plain-English lesson that explains what went wrong. `totem lesson compile` turns the lesson into an AST or regex rule, and `totem lint` enforces it on every push from that point forward. The same compiled pattern can't ship past the linter again once the pre-push hook or CI runs and the rule matches.\n\n```mermaid\ngraph LR\n    Catch[\"Catch a mistake\"] --\u003e|write a lesson| Compile[\"totem lesson compile (frozen)\"]\n    Compile --\u003e|generates rule| Enforce[\"totem lint\"]\n    Enforce --\u003e|catches next attempt| Catch\n\n    style Catch fill:#4b3a75,stroke:#9b72cf,color:#fff\n    style Compile fill:#5e3a24,stroke:#e67c3b,color:#fff\n    style Enforce fill:#1a4d2e,stroke:#34a853,color:#fff\n```\n\nThe compile step is frozen today; [Where the Loop Stands](#where-the-loop-stands), next, says why and what still runs.\n\nWhen a rule matches comments or string literals instead of actual code, `totem doctor` flags it as noisy, and `totem lesson compile --upgrade` re-runs the compiler with a precision-targeted prompt. I'd rather have 300 precise rules than 1,000 noisy ones.\n\nWant to watch the whole loop run on a committed fixture? [`examples/proof-kit/`](examples/proof-kit/) is a tiny repo where a real mistake, its lesson, and the compiled rule that blocks the recurrence are all committed. CI re-proves the block on every push and writes a [receipt](examples/proof-kit/receipt.json) with its parameters.\n\n## Where the Loop Stands\n\nThe loop above is the design. Here is where it stands today.\n\n**Enforcement is stable.** Compiled rules run on every diff: deterministic, offline, zero LLM.\n\n**Lessons are live.** They bank, index, and surface to agents today. They advise; they do not yet compile.\n\n**The compiler is frozen on purpose, since 2026-05-17.** We hit a soundness problem in the lesson-to-rule path and froze it fail-closed: a corrupt [freeze file](.totem/freeze.json) throws rather than bypassing itself. Fewer rules we trust beat more rules we do not.\n\n**The path back is gated, not dated.** The replacement compiler ships only after it passes held-out validation on real work; status lives on the [maturity page](docs/wiki/maturity.md).\n\nWhat this means today: existing rules keep enforcing, new lessons bank and advise, and new-rule compilation waits for the gate. If that trade is wrong for you, we would rather you know now.\n\n## The Queryable Knowledge Index\n\nYour lessons and ADRs live in your repo as plain markdown files: those files are the canonical source. `totem sync` derives a local semantic index from them (Tree-sitter + LanceDB) so they become queryable. The derived store stays on your machine and rebuilds from the files at any time, so there's no cloud dependency and no vendor lock-in.\n\nMCP-compatible agents query it through the bundled MCP server. Registering that server with your agent is a one-time, per-agent configuration step; `totem init` scaffolds it for the agents it detects, and for anything else, see [MCP Server Setup](docs/wiki/mcp-setup.md). Once registered, before your agent writes a line of code, it can ask \"what patterns are banned in this codebase?\" and get ranked candidates from your project's actual history. The agent still has to read them and synthesize: a queryable index returns candidates, not pre-synthesized answers. Whether an agent actually issues that query before deriving from scratch is an agent-discipline question; see [What Works and What Doesn't](#what-works-and-what-doesnt).\n\n## What's in the Box\n\nTotem is a set of CLI tools, not a framework. Building blocks you wire into whatever CI and workflow you already have. The table below highlights the commands you'll reach for most; several support `--json` for scripting, so check `totem \u003ccommand\u003e --help`.\n\n| Command                | What it does                                                                                                                     |\n| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `totem lint`           | Run all compiled rules against your diff. Zero LLM, offline.                                                                     |\n| `totem lesson compile` | Turn plain-English lessons into AST or regex rules.                                                                              |\n| `totem lesson extract` | Pull lessons from PR reviews and bot comments.                                                                                   |\n| `totem doctor`         | Verify the wiring end-to-end; flag noisy rules via Trap Ledger telemetry, suggest upgrades.                                      |\n| `totem spec`           | Generate an implementation spec from a GitHub issue before you touch any code (LLM-powered, requires a configured LLM provider). |\n| `totem review`         | LLM-powered review on an uncommitted diff, grounded in your project's lessons (requires a configured LLM provider).              |\n| `totem sync`           | Rebuild the semantic index from your lessons and docs.                                                                           |\n| `totem hook install`   | Install Git hooks (`pre-push` lint gate).                                                                                        |\n\nThe table above is a curated highlights reel, not the full surface. `totem help --all` lists every command the CLI ships (46 today), and the [CLI Reference](docs/wiki/cli-reference.md) documents each one with its flags.\n\nFor CI, `totem lint --format sarif` pipes into GitHub Code Scanning or any SARIF-compliant tool, so tripwires show up as inline PR annotations. The stream is scoped to error-severity findings; warnings stay local until a rule earns promotion. Recipes in [CI/CD Integration](docs/wiki/ci-integration.md); the same flag works on the standalone `totem-lite` binary for CI without Node.js.\n\n## What Works and What Doesn't\n\nTotem has three layers, and I want to be honest about where each one stands:\n\n1. **The enforcement layer works.** Compiled rules and Git hooks catch violations mechanically and offline. Nothing on that floor touches the network, so it runs natively in air-gapped environments. No source code leaves your machine. Because it lints the diff, not the history, it stays fast at any project size; the [maturity page](docs/wiki/maturity.md) renders the live lint receipt with its parameters, recomputed in CI.\n2. **The planning layer works too, to my surprise.** Before the agent writes any code, `totem spec` pulls the GitHub issue body and queries the knowledge base for relevant lessons and ADRs. It writes a structured implementation spec to `.totem/specs/\u003cissue\u003e.md`. None of this is a hard tripwire: the agent could write a vague spec and ignore the retrieved context. But in practice, in my own use of it, the structured prompt has repeatedly caught \"I'm about to reinvent a helper that already exists\" before the agent commits to an approach.\n3. **The knowledge index is real infrastructure.** The index exists, it's portable across repos, and any MCP agent can query it once registered. But whether an agent _consistently acts_ on the context it retrieves is an open question I'm actively working through. Availability is deterministic. The agent's discipline is not.\n\nI built the enforcement layer because the upstream layers aren't enough on their own. An agent can have a clean spec, relevant lessons in context, and still drift when it gets deep into a task. The tripwires catch what the planning layer and the knowledge index miss. That's the whole point of keeping them as three distinct layers: each catches a different class of failure, at a different stage of the workflow.\n\nThe [maturity page](docs/wiki/maturity.md) is this section in machine-derived form: shipped, partial, and goal rows built from committed data and drift-gated in CI, so the claims can't quietly outrun the code.\n\n## Quickstart\n\nInitialize Totem in any project (Node, Python, Go, Rust):\n\n```bash\npnpm dlx @mmnto/cli init\n```\n\nThis scaffolds `totem.config.ts`, wires up the `pre-push` git hook, and installs the baseline rule pack.\n\nRun the linter (offline):\n\n```bash\npnpm dlx @mmnto/cli lint\n```\n\nThen verify the wiring:\n\n```bash\npnpm dlx @mmnto/cli doctor --strict\n```\n\n`doctor --strict` reports config, hooks, rules, and index wiring, and exits non-zero on fail-class diagnostics. Read and resolve its warnings before treating setup as complete; if an agent is running this setup for you, that is its checklist too. For a machine-checkable all-wiring oracle in CI, `--strict=warn` also exits non-zero on warn-class diagnostics.\n\nThe npm packages declare `engines.node \u003e= 24` deliberately: Node 24 (LTS since 2025-10) is the runtime CI actually tests and the one the publishing pipeline (npm 11 / OIDC) runs on — a floor we exercise rather than one we claim. On CI images pinned to older Node, use the Lite binary below instead.\n\nNo Node.js? The **Totem Lite** standalone binary runs `init`, `lint`, and `hooks` fully offline: grab it from [Releases](https://github.com/mmnto-ai/totem/releases); platform commands in the [Installation Guide](docs/wiki/installation.md).\n\n## Documentation \u0026 Workflows\n\n- [**It Never Happens Again:**](docs/wiki/it-never-happens-again.md) How a PR mistake becomes a permanent project law: one lesson file, one command.\n- [**Governing AI Agents:**](docs/wiki/governing-ai-agents.md) How to use hooks and MCP tools to enforce project rules on Claude and Gemini from Turn 1.\n- [**It Stops Crying Wolf:**](docs/wiki/it-stops-crying-wolf.md) How override telemetry flags noisy rules for downgrade: proposed as a PR, merged by a human.\n- [**Maturity:**](docs/wiki/maturity.md) What's shipped, partial, and still a goal: machine-derived rows with receipts, drift-gated in CI.\n- [**Proof Kit:**](examples/proof-kit/) A committed, re-runnable exhibit: one real mistake, the rule compiled from its lesson, and CI re-proving on every pull request that the mistake stays blocked, with zero LLM calls.\n\n### Deep Dives\n\n- [CLI Reference](docs/wiki/cli-reference.md)\n- [Architecture \u0026 Workflows](docs/reference/architecture.md)\n- [MCP Server Setup](docs/wiki/mcp-setup.md)\n- [CI/CD Integration](docs/wiki/ci-integration.md)\n\n## Open Source Commitment\n\nThe core toolkit (enforcement engine, `totem lesson compile`, MCP server, and the rule-tuning loop) is Apache 2.0. If federation, hosted services, or centralized telemetry are introduced later, they are intended to be separate products, while the local toolkit remains Apache 2.0.\n\nSee [`COVENANT.md`](COVENANT.md) for details.\n\n## License\n\nApache 2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmnto-ai%2Ftotem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmnto-ai%2Ftotem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmnto-ai%2Ftotem/lists"}