Totem
Editor integrations: Claude Code · Gemini CLI · GitHub Copilot · JetBrains Junie · others in progress. See AGENTS.md for how integration works.
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.
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, not in this README.
When 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?"
The 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.
Totem 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 says exactly which half is which. The discipline and telemetry layers are in active development; the maturity page carries the honest split, machine-derived from committed data.
---
- Tripwires, Not Tracks
- How Mistakes Become Rules
- Where the Loop Stands
- The Queryable Knowledge Index
- What's in the Box
- What Works and What Doesn't
- Quickstart
- Documentation & Workflows
---
Tripwires, Not Tracks
To 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.
Totem turns a plain-English markdown lesson into a physical constraint that a local, zero-LLM linter enforces:
Input: (.totem/lessons/no-child-process.md)
## Lesson - Never use native child_process
Tags: architecture
Direct use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead.Output: (git push blocked on the agent's machine)
$ git push
[Lint] Running compiled rules (zero LLM)...
### Warnings
- **packages/cli/src/git.ts:22** - Never use native child_process
Pattern: `import { execSync } from 'node:child_process'`
Lesson: "Direct use of `node:child_process` is forbidden outside `core/src/sys/`. Use the `safeExec` shared helper instead."
[Lint] Verdict: FAIL - Fix violations before pushing.