Tolvi

Capture engineering decisions where they happen. Query them later in plain English.

Status: Pre-1.0 - v0.3.1 released. The CLI (Homebrew, go install and release binaries), agent integrations, and the docs site are shipped. See ROADMAP.md.

What Tolvi is

A per-repo engineering knowledge vault - decisions, sessions, and patterns stored as Markdown with YAML frontmatter under <repo>/vault/. A CLI lets you write and read it from the terminal, and agent integrations (Claude Code, Codex, Cursor, Gemini CLI, OpenHands, Aider) teach AI tools to use the vault first-class.

The CLI uses CAG: the whole vault goes into Anthropic context via prompt caching, with zero infrastructure beyond an API key. The vault format (tolvi-format-v2) is the only thing agents need to learn.

Quickstart

The "drop into a repo" wedge:

# 1. Install the CLI with Homebrew, Go, or a release binary
brew install --cask tolvi-labs/tap/tolvi
# or: go install github.com/tolvi-labs/tolvi/cli/cmd/tolvi@latest

# 2. Set your Anthropic API key (or write ~/.config/tolvi/config.yaml)
export ANTHROPIC_API_KEY=sk-ant-...

# 3. In any repo:
tolvi init
tolvi sync decision "Why we chose Postgres" --body "pgvector + JSON support tipped it"
tolvi ask "what did we decide about Postgres"
tolvi recall                    # what was I doing? recent sessions + active decisions, no API call

# 4. Check the setup, and see where docs are routed:
tolvi doctor
tolvi doctor --json             # same checks, machine-readable, for scripts and tools
tolvi roots

# 5. See every repo on this machine that has a vault:
tolvi repos list
tolvi repos scan ~/src          # register ones that were never registered

Role packs give a new vault templates tuned to a kind of work. tolvi init uses the engineer pack unless --pack <name> names another (or --pack none for no templates), and tolvi packs list shows the six the binary carries. See Packs.

For Claude Code users, the skill at skills/tolvi/ lets you do the same thing in natural language inside a Claude Code session (/tolvi slash command). From a checkout, bash skills/tolvi/install.sh --with-hooks installs it. With no checkout, which is what brew install gives you, the binary carries the same files:

tolvi integrations install --with-hooks

It writes the skill and the three slash commands, wires the session hooks, and allowlists reads only: tolvi sync and tolvi commit stay a conscious per-call approval. Nothing is overwritten without --force, and running it twice changes nothing.

tolvi repos keeps a machine-local index at ~/.config/tolvi/repos.json, beside roots.json and never committed. tolvi init registers a repo as it provisions it, and tolvi repos scan <dir> picks up ones that predate the index. The index is a cache over each repo's own .vault-meta.json, so entries are verified when they are read: a repo you moved is listed as stale rather than trusted, and tolvi repos forget <path> drops it when you say so. Losing the file costs nothing, because a scan rebuilds it.

tolvi roots is worth knowing early if you use more than one repo. Roots are declared once per machine in ~/.config/tolvi/roots.json and never committed, so a repo commits only who it is and the machine decides where its docs live. With no roots.json everything stays in the repo's own vault/, which is the default and what a contributor wants.

For optional pre-commit nudges that flag commits touching decision-likely files (deps, infra, tooling, large diffs):

tolvi precommit install

Solo quickstart

Solo is the single-builder setup: a vault in your repo, Claude Code wired to read it, and nothing else to run. The tolvi binary is the whole installer.

brew install --cask tolvi-labs/tap/tolvi      # or go install, as above
cd /path/to/your-repo
tolvi init                                    # vault/ with the engineer pack's templates
tolvi integrations install --with-hooks       # skill, slash commands and hooks in ~/.claude

The recall hook surfaces recent sessions and active decisions when a session starts, and before every git commit the commit hook stages vault/ and checks for today's session note. Two options change where and how:

• --scope project writes into <git root>/.claude instead of ~/.claude, with hook paths written through "$CLAUDE_PROJECT_DIR", so you can commit .claude/ and the hooks work on every teammate's checkout.
• --strict makes the commit hook deny a commit until today's session note exists. Without it the hook only warns and the commit proceeds.

tolvi integrations install --with-hooks --scope project --strict

Re-running with different options needs --force, since the skill is already in place. The settings merge replaces its own hook entries rather than adding a second set, including the tolvi-solo-recall and tolvi-solo-sync entries the retired tolvi-solo installer wrote.

The stack

Every Tolvi tool installs from one marketplace:

/plugin marketplace add tolvi-labs/tolvi
/plugin install tolvi-guild        # plan against your codebase
/plugin install tolvi-bastion      # harden the plan before code
/plugin install tolvi-magellan     # compile it into an executable task DAG

tolvi itself installs the same way, with the /tolvi-recall, /tolvi-sync and /tolvi-commit slash commands. Each plugin also ships manifests for Codex, Cursor, Gemini, Devin and Hermes, so the skills work outside Claude Code too.

Forge, which runs the plan on a local model, installs separately from PyPI: pipx install tolvi-forge, then forge detect-hardware. Magellan's tasks.json reaches it through forge plan load <tasks.json> --path <repo> and forge agents run --apply --path <repo>, which commits each approved task on a forge/<feature> branch.

Tolvi Desktop is a macOS menu bar app that shows your vaults, setup checks and Forge's runtime at a glance; it is proprietary, and you can download it at tolvilabs.com/desktop.

Packs

Each shipped pack lives in cli/internal/packs/files/<name>/, inside the CLI module so the binary can embed it: a README, the templates tolvi init copies into vault/templates/, and a pack.json declaring its status, what it covers, and every template with what to use it for. The manifest is the machine-readable source of truth, so tools read it instead of parsing this table, and .github/scripts/pack-manifest-check.sh fails the build when a manifest, its templates and this table disagree.

Two ways to capture

Tolvi captures at two altitudes, on purpose. They are complementary, not redundant:

• Mechanical (CLI): tolvi sync writes a single note you already have in mind; tolvi commit stages vault/ and runs git commit, gated on a session note existing for today. Deterministic, no LLM, scriptable: what you commit is exactly what is there. Use it in CI, in hooks, or when you want control and no surprises.
• Synthesized (skill): inside a Claude Code or Cursor session, /tolvi-sync reconstructs the whole working session into decisions, patterns, and a session log, and /tolvi-commit does that and then commits. Comprehensive and near-zero effort, but it needs an agent in the loop and is non-deterministic.

Rule of thumb: mechanical for known, controlled capture; the skill for synthesizing the messy reality of a working session. The skill captures what a qualified actor tried or considered (including reasoned rejections), the high-signal record a Slack thread or ticket can't give you.

What's shipped

What's coming

See ROADMAP.md.

Repository layout

tolvi-labs/tolvi/
├── spec/                # Format spec + JSON Schemas
├── cli/                 # Go CLI (single static binary)
├── integrations/        # Per-agent integration files
├── examples/sample-vault/  # Synthetic vault for demos + CI validation
├── docs/                # Architecture, conventions, ADRs, design specs
└── .github/             # CI workflows + scripts

Each subdirectory has its own README with detailed install and usage notes.

Architecture

See docs/ARCHITECTURE.md (note: some sections describe the original v1 plan, including a server that has since moved to a private repo).

License

Apache 2.0. See NOTICE for attribution.

Contributing

See CONTRIBUTING.md. External contributors should read the Brand isolation section before opening a PR.