TIMMY AgentOps

Open-source local receipt and replay layer for AI agent work.

AI agents can edit files, run commands, call models, and change infrastructure. TIMMY creates local receipts so developers can see what happened, when it happened, and what artifacts were produced.

Installation

Install globally:

npm install -g timmy-tui

Or run directly using npx:

npx timmy-tui demo

CLI Usage

A. Run Demo

timmy demo

Generates a verifiable local receipt file at .timmy/receipts/demo-receipt.json.

B. Record a Task Proof Stub

timmy proof "create a hello world Cloudflare Worker"

Generates a proof run folder under .timmy/runs/run_<timestamp>/ containing manifest.json, receipt.json, and replay.md.

🎬 1. Demo

Launch the TUI and follow the guided demo flow described in §6 below.

🛠️ 2. What Works Today

• Local Verifiable Receipts: Generates run manifestations using a tamper-evident, hash-bound .agentrun format.
• Deterministic Key-Sorted Hashing: Manifests are hashed recursively by sorting JSON keys.
• Main Chat with OpenRouter Model Rail: Real-time streaming conversation, hotkey swapping, and dynamic model fetching.
• MCP → CLI Evidence Bundle Generation: Converts MCP tool calls into local inspectable bash scripts and environment setups.
• cmux Workspace Launch: Seamless workspace isolation with multiplexer controls (cmux window layout).
• Browser Companion Chat Mirror: Live state mirroring on local WebSocket web client (localhost:3001).
• Bounded Logs: Strict console append logs verifying state changes without bloating directory index files.
• Setup/Help/Doctor Commands: Pre-flight CLI checkups and environment verifiers.

🚀 3. Quickstart

To run the console locally:

# 1. Install dependencies
npm install

# 2. Setup your local configuration
cp .env.example .env

# 3. Add your OPENROUTER_API_KEY to the .env file
# OPENROUTER_API_KEY=sk-or-v1-...

# 4. Run system diagnostic check
npm run timmy -- doctor

# 5. Start the TUI
npm start

🧬 4. First Proof

Generate your first verifiable session validation proof manifest:

npm run timmy -- agent-proof "Validate workspace integrity"

This runs the core telemetry auditor and writes a local sealed TIMMY receipt in the active session database containing a manifest hash and session timestamp.

📂 5. First MCP → CLI Scan

Inspect and scan an external MCP server to compile an evidence bundle:

1. Navigate to the MCP → CLI panel (Tab to "MCP → CLI" in the left nav).
2. Paste an MCP server URL into the scanner prompt.
3. Press Scan MCP Server to generate a local evidence bundle under mcp-cli/<slug>/.
4. Review the generated CLI plan, Visa scope, and receipt fields before giving the agent file system permissions.

🏆 6. Demo Flow

Follow this end-to-end path to exercise TIMMYTUI's full trust loop:

Main Chat ──► MCP → CLI Scan ──► Workspace / cmux
                                        │
Sealed Receipt ◄── Browser Companion ◄──┘

🧾 7. Why Receipts Matter for AI Agents

AI agents are capable of mutating files, executing terminal commands, and calling API endpoints. Without a structured log of actions, debugging becomes difficult and security boundaries become opaque.

TIMMY solves this by acting as a flight recorder for agent execution. Every step, tool-use outcome, and generated artifact is registered into a local, key-sorted manifest receipt sealed with a deterministic SHA-256 hash. If any file or log is tampered with, the receipt validation seal breaks.

📄 8. Example Receipt Output

Here is a typical receipt.json generated by TIMMY:

{
  "schema_version": "0.1.0",
  "run_id": "run_proof_1717750800000",
  "type": "proof",
  "task": "create a hello world Cloudflare Worker",
  "created_at": "2026-06-07T09:49:22.000Z",
  "cwd": "/path/to/openrouter-tui-agent",
  "platform": "darwin",
  "node_version": "v20.10.0",
  "package": {
    "name": "timmy-tui",
    "version": "0.1.0"
  },
  "status": "completed",
  "artifacts": [
    {
      "path": ".timmy/runs/run_proof_1717750800000/replay.md",
      "sha256": "5c9b83b63297a7a2bc4175bded918cd928c388a212b47bbbc28acb82f039a4c"
    }
  ],
  "receipt_sha256": "4adaec82308cc7e5bded918cd928c388a212b47bbbc28acb82f039a4cae4fb8a"
}

🗺️ 9. Roadmap

Refer to ROADMAP.md for full development milestones.

🤝 10. Contributing

We welcome early open-source contributors! Refer to CONTRIBUTING.md for local environment setup, style policies, and PR review gates.

🛡️ 11. Security Note

• Do not pass secret credentials inside raw task strings, as prompts are stored in plaintext.
• Dangerous command mutations are not run in the local proof stubs of version v0.1.
• Refer to SECURITY.md for reporting guidelines.

🔒 12. OpenSSF / Trust Notes

• Provenanced Releases: Published directly from GitHub Actions with npm trusted publishing provenance.
• Zero Telemetry: TIMMY does not call home or track developer behavior. All receipts remain strictly local-first.
• Local Authorities: No secret collection or analytics tracking is coded into any execution loop.