Quickstart
Loomtracer records the decisions you make with your agents: what was decided, the options that lost and why, and who decided, you or the agent. It is not only for engineering; any decision a person makes with an agent fits. Running it today takes a developer’s setup: a binary you run from the terminal, or a server in Docker, and an agent that connects over MCP. Your instance, your data, nothing phones home.
-
Install the command-line tool,
loomtracerLinux (x86_64, ARM64) and Apple Silicon Macs. The script downloads the latest release, checks its SHA-256 and puts
loomtracerin~/.local/bin:Terminal window curl -fsSL https://raw.githubusercontent.com/alexknips/loomtracer/master/scripts/install.sh | shloomtracer --version -
Connect your agent
In your project, for Claude Code:
Terminal window claude mcp add loomtracer -- loomtracer mcp --agent-tool claudeDecisions go to
./loomtracer/, a SQLite ledger in your project.--agent-tool claudefiles your agent’s captures under Claude Code; without it they are filed under Codex. For Codex, Cursor, Claude Desktop or a shared.mcp.json, see MCP Setup. -
Record a decision
Start
claudein the project and say: “Record a decision: we use SQLite for the ledger. We considered Postgres and rejected it: more than we need for now. It rests on the assumption that one machine is enough.”Your agent records the decision with its options, the reason, what it rests on and who decided. Every decision must say what it rests on: an earlier decision, something observed, an assumption, or a bet with a date to check. Loomtracer refuses one that names nothing, so that it can tell you later whether the decision still holds.
-
Ask why
In a fresh session: “Why did we pick SQLite, and what did we rule out?” Your agent answers from the record: the reason, the option that lost, who decided, and whether the decision still holds.
If loomtracer is not found
Section titled “If loomtracer is not found”If loomtracer --version says loomtracer: not found, your shell does not have ~/.local/bin on its PATH
yet. Add it, for this shell and in your shell’s startup file (~/.bashrc or ~/.zshrc):
export PATH="$HOME/.local/bin:$PATH"Without it, claude mcp add still succeeds, but Claude Code cannot start loomtracer.
On other platforms, build it from source:
cargo install --git https://github.com/alexknips/loomtracer --locked loomtracerWithout an agent: the CLI
Section titled “Without an agent: the CLI”Try it in a temporary ledger first. This records a sample decision, asks for it back and leaves no files behind:
loomtracer --actor human:alice quickstartThen, in your project, the same decision as in step 3, and the question from step 4:
export LOOMTRACER_ACTOR=human:aliceloomtracer emit decision.capture --source human \ --title "Use SQLite for the ledger" \ --rationale "One file next to the app is all we need; Postgres is a server to run and back up" \ --topic-keys storage --options sqlite,postgres --chose sqlite \ --rests-on-assumption "One machine is enough" \ --binds "Every later write goes to one SQLite file" --cheap-to-undoloomtracer query why "sqlite for the ledger" --summaryA capture also says what the decision binds (--binds or --binds-nothing) and what undoing it would
cost (--undo-cost or --cheap-to-undo); one that leaves either out is refused. The ledger is
./loomtracer/ledger.sqlite, created on the first write. query recent --since 24h --summary
lists what was decided today, one line each. The CLI Reference has every command.
Setting the actor
Section titled “Setting the actor”Every write says who made it, and Loomtracer refuses an anonymous one. An actor is human:<name>
(human:alice, human:alice@example.com), agent:<tool>:<name> or system:<name>.
- In the terminal, set
LOOMTRACER_ACTOR=human:<you>once, as above, or pass--actor human:<you>before the command (loomtracer --actor human:alice disagree …). Without either,loomtraceruseshuman:<your git email>, thenhuman:<your user name>. - Over MCP, the server records your agent as
agent:<tool>:<id>, with the tool from--agent-tool. When the agent records a call you made, it can record you as the one who decided.
Run a cell with Docker
Section titled “Run a cell with Docker”To share one decision record across several machines, run a self-hosted cell: the loomtracer server with Postgres in
Docker Compose, on any machine with Docker, in about five minutes.
Prerequisites: Docker 24+ with Compose v2 (docker compose version). Port 8080 must be available.
# 1. Fetch the compose cellgit clone https://github.com/alexknips/loomtracer && cd loomtracer
# 2. Create your config and set strong secretscp .env.example .env# Linux:sed -i "s/change-me-before-production/$(openssl rand -hex 32)/g" .env# macOS: sed -i '' "s/change-me-before-production/$(openssl rand -hex 32)/g" .env
# 3. Start (builds the image on first run, ~5 minutes)docker compose up --build -dConfirm the cell is healthy:
docker compose psNAME STATUS PORTShivemind Up (healthy) 127.0.0.1:8080->8080/tcppostgres Up (healthy)The compose service keeps its old name, hivemind, so an existing cell keeps its data.
The port is published on 127.0.0.1, so only this machine can reach the cell; to expose it deliberately, set LOOMTRACER_PUBLISH_ADDR in .env to the interface address to publish on, or put a TLS reverse proxy in front (see Exposing the cell deliberately).
Connect your agent to the cell
Section titled “Connect your agent to the cell”Provision a tenant to get your bearer token (shown once — save it):
ADMIN_KEY=$(grep LOOMTRACER_ADMIN_KEY .env | cut -d= -f2)curl -s -X POST http://localhost:8080/v1/tenants \ -H "Authorization: Bearer $ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{"tenant_id": "me", "display_name": "My Team"}'The response includes token_secret — a value starting with lt_tk_.... Copy it now.
Add the cell to Claude Code by pasting this into .mcp.json in your project root:
{ "mcpServers": { "loomtracer": { "url": "http://localhost:8080/mcp", "headers": { "Authorization": "Bearer lt_tk_..." } } }}Reload Claude Code. The loomtracer tools appear in your agent’s tool list. The other clients are in
MCP Setup.
Without Docker, LOOMTRACER_DIR=./loomtracer loomtracer serve --port 8080 serves the same HTTP API and /mcp;
set LOOMTRACER_API_KEY to require a bearer token. The
self-hosting runbook covers
production settings, TLS, upgrades and troubleshooting.
Next steps
Section titled “Next steps”- MCP Setup — Codex, Cursor, Claude Desktop, and the cell over HTTP
- Agent Capture — the capture plugin, and what your agent should record
- Human Review — look over what your agents decided
- How it works — the record, its status, and where your data lives