About TIMMY
Overview
TIMMY is a local-first flight recorder and control plane for AI agent work, published as the timmy-tui repository under the MIT license. Every agent run produces a signed, hash-chained receipt that records what ran, where it ran, how long it took, what it cost, and which artifacts it produced.
The project states its position plainly: trust the receipt, not the model. Because each receipt binds OS, architecture, and tool build hashes to the run, a replay refuses to proceed on a drifted machine instead of reporting a result the original environment never produced. TIMMY runs from the terminal and ships with zero telemetry, so receipts stay on the operator's machine unless that operator shares them.
Key Benefits
- Signed run records: each receipt is sha256 hash-chained and ed25519-signed, carrying prompt and response hashes, usage, cost, latency, and error class.
- Honest replay: environment locks bind OS, architecture, and tool build hashes, so a replay on a drifted machine fails rather than faking a pass.
- Portable proof bundles: .agentrun bundles ship the EDL, manifest, sources, hashes, and receipts, with OTIO interchange through timmy export.
- Operator-gated dispatch: DispatchPlans are CUE-validated, and single-use expiring tokens bind to the complete immutable plan hash.
- Zero telemetry: no call-home and no analytics, and receipts never leave the machine unless the operator shares them.
- Cost-free local models: local Ollama models answer at $0 when OpenRouter is unreachable, and the run is flagged as a FALLBACK.
How It Works
Clone the repository, run npm install, copy .env.example to .env, and optionally add an OPENROUTER_API_KEY for frontier models. npm start opens the TUI, where Tab switches tabs, ? shows the key grammar, Ctrl+L opens the live log monitor, and Ctrl+K opens the command palette. Running timmy demo seals a receipt at .timmy/receipts/demo-receipt.json, and timmy proof "create a hello world worker" produces a proof run folder plus replay.md.
Use Cases
- Agent developers audit a full run trail, since failed and denied runs seal receipts too and release epochs keep older streams queryable.
- Platform engineers replay a run on another machine to confirm the environment matches, because drifted machines are refused outright.
- Model evaluators run judge loops that fan out across local models and escalate to frontier models only when confidence is low, with child and parent receipts per loop.
- 3D and game pipeline teams dispatch work through the blender, godot, defold, cocos, unity, unreal-mcp, and houdini-mcp lanes, with tmux, zellij, or rmux multiplexing.
- Any MCP-speaking agent calls the 37 receipt, dispatch, lane, geo voxel bench, and vision tools through timmy mcp serve.
- Vision and inspection teams open Roboflow Vision Studio for image inspection with archived evidence and operator review.
Why Choose This Product
TIMMY suits teams that need to prove what an agent did rather than trust a transcript. The honesty clause makes the tool report unavailable capabilities as not_configured or blocked and seal a receipt saying so, which rules out fabricated passes. Two limits are documented: the npm package still serves an early 0.1.0 build, so install from source for now, and prompts are stored in plaintext in receipts, so credentials never belong in task strings.
TIMMY Pros & Cons
- Open source under the MIT license and installable from source
- Every run, including failed and denied ones, seals a signed receipt
- Replay refuses drifted environments instead of reporting a guess
- 37 MCP tools available to any MCP-speaking agent
- Local-first with zero telemetry, call-home, or analytics
- npm package still serves an early 0.1.0 build; install from source for now
- Six editable tldraw templates are not in the public checkout yet
- Prompts are stored in plaintext in receipts, so task strings must never hold credentials
Key Features
Signed Receipts
Every run seals a sha256 hash-chained, ed25519-signed record with prompt and response hashes, usage, cost, latency, and error class, and failed or denied runs seal as well.
Environment Lock
OS, architecture, and tool build hashes bind to every receipt, so replay refuses to run on a drifted machine.
Receipt Replay
EDL cut-lists replay clips from the manifest alone, and timmy export writes portable .agentrun bundles or OTIO interchange files.
Command Post
A typed, CUE-validated DispatchPlan drives six delegation tools, and operator tokens bind to the complete immutable plan hash, single-use and expiring.
Harness Lanes
TIMMY dispatches to OpenHands with disposable sandboxing, OpenCode, Pi, jcode, minds, key-gated API lanes, and 3D lanes for blender, godot, defold, cocos, unity, unreal-mcp, and houdini-mcp.
Judge Loops
Multi-model fan-out runs local first and escalates to frontier models only when confidence is low, sealing a child and parent receipt per loop.
MCP Server
timmy mcp serve exposes 37 tools to any MCP-speaking agent, covering receipt verification, environment lock, dispatch plan and arm, lane listing, the geo voxel bench, and vision inspection.
Operator Approvals
Dispatch stays default-deny on paid routes without a spend bound, and timmy approve arms a plan before dispatch, tail, pause, cancel, or collect.
Browser Companions
A browser companion on port 3001 mirrors chat, a receipt browser and dispatch survey run on 4310, and the Mission Map serves on 4336.
Vision Studio
timmy vision inspects images through a configured Roboflow model or saved Workflow with archived evidence, and timmy vision doctor checks a machine without running inference.
Frequently asked questions about TIMMY
Is TIMMY free to use?
TIMMY ships under the MIT license from the public timmy-tui repository, and local Ollama models answer at $0 when OpenRouter is unreachable. The example receipt shows a cost_usd field, which tracks the cost of the model call rather than a TIMMY subscription.
What is a receipt in TIMMY?
A receipt is a sha256 hash-chained, ed25519-signed run record holding the prompt and response hashes, requested and resolved model, transport, latency in milliseconds, token count, cost in USD, status, and error class. Each receipt also links to the previous hash, and failed and denied runs seal receipts too.
How do I install TIMMY?
Clone https://github.com/woodman33/timmy-tui.git, run npm install, copy .env.example to .env, and optionally add an OPENROUTER_API_KEY for frontier models. Then run npm start to open the TUI. The npm package still serves an early 0.1.0 build, so the project recommends installing from source for now.
Does TIMMY send my data anywhere?
No. TIMMY is local-first with zero telemetry: it makes no call-home and runs no analytics, and receipts never leave your machine unless you choose to share them.
What happens if I replay a run on a different machine?
Every receipt carries an environment lock binding the OS, architecture, and tool build hashes to the run. If the replaying machine has drifted from that environment, the replay refuses rather than producing a result that the original environment never produced.
Can receipts contain secrets?
Prompts are stored in plaintext inside receipts, so never put credentials in task strings. API keys stay in environment variables or the keychain and are redacted on the way out.