convez.ai
MCP ServerDevOps & InfraestruturaAvançado
woodman33

TIMMY-TUI: Console de Agentes com Recibos Locais

woodman33/openrouter-tui-agent

Recibos e auditoria local para agentes de IA com trust console TUI

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que funciona como camada de auditoria local para agentes de IA, gerando recibos verificáveis e evidências de execução. Integra OpenRouter models, converte chamadas MCP em bundles CLI inspecionáveis, e espelha estado em cliente web com isolamento de workspace via cmux.

Instalação

$npx convez-ai woodman33/openrouter-tui-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 semanas
Versão
—
Issues abertas
22
Contribuidores
1

Casos de uso

  • Auditar e rastrear operações de agentes de IA em produção
  • Gerar provas verificáveis de execução de tarefas com hash determinístico
  • Inspecionar e validar chamadas MCP antes de executar com permissões de file system

Veredito

Ferramenta especializada para quem precisa auditoria e accountability em sistemas com agentes IA. Implementação robusta com recibos criptograficamente vinculados, mas exige familiaridade técnica com MCP e operações CLI para aproveitar plenamente.

README

A tradução para o português deste README ainda está na fila.

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 & Setup

You can run TIMMY TUI by either cloning the source repository directly, installing it globally, or running it via npx.

Option A: Clone and Run from Source (Recommended)

git clone https://github.com/woodman33/openrouter-tui-agent.git
cd openrouter-tui-agent
npm install
cp .env.example .env
# (Optional) Add your OPENROUTER_API_KEY to the .env file
npm start

Option B: Install Globally

npm install -g timmy-tui

Option C: Run via 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. Clone the repository and navigate into it
git clone https://github.com/woodman33/openrouter-tui-agent.git
cd openrouter-tui-agent

# 2. Install dependencies
npm install

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

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

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

# 6. 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.
Ver o original no GitHub

Bom para

Relacionados