Skip to content

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.

  1. Install the command-line tool, loomtracer

    Linux (x86_64, ARM64) and Apple Silicon Macs. The script downloads the latest release, checks its SHA-256 and puts loomtracer in ~/.local/bin:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/alexknips/loomtracer/master/scripts/install.sh | sh
    loomtracer --version
  2. Connect your agent

    In your project, for Claude Code:

    Terminal window
    claude mcp add loomtracer -- loomtracer mcp --agent-tool claude

    Decisions go to ./loomtracer/, a SQLite ledger in your project. --agent-tool claude files 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.

  3. Record a decision

    Start claude in 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.

  4. 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 --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):

Terminal window
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:

Terminal window
cargo install --git https://github.com/alexknips/loomtracer --locked loomtracer

Try it in a temporary ledger first. This records a sample decision, asks for it back and leaves no files behind:

Terminal window
loomtracer --actor human:alice quickstart

Then, in your project, the same decision as in step 3, and the question from step 4:

Terminal window
export LOOMTRACER_ACTOR=human:alice
loomtracer 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-undo
loomtracer query why "sqlite for the ledger" --summary

A 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.

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, loomtracer uses human:<your git email>, then human:<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.

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.

Terminal window
# 1. Fetch the compose cell
git clone https://github.com/alexknips/loomtracer && cd loomtracer
# 2. Create your config and set strong secrets
cp .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 -d

Confirm the cell is healthy:

Terminal window
docker compose ps
NAME STATUS PORTS
hivemind Up (healthy) 127.0.0.1:8080->8080/tcp
postgres 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).

Provision a tenant to get your bearer token (shown once — save it):

Terminal window
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.


  • 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