FrankenTerm

FrankenTerm (command-line tool ft) is a terminal hypervisor written in Rust, designed for coordinating fleets of AI coding agents.

Core Capabilities#

Observability#

• Perfect Observability: Cross-pane terminal output capture with <50ms delta extraction latency
• Delta Extraction: 4KB overlap matching for incremental content, avoiding full capture overhead
• FTS5 Full-Text Search: Lexical search + semantic/hybrid retrieval modes

Intelligent Detection#

• Multi-agent pattern engine detecting rate limits, errors, prompts, completions
• Built-in detection patterns: Codex, Claude Code, Gemini, Terminal Runtime
• User-configurable custom detection rules via TOML

Automation & Control#

• Event-Driven Automation: Pattern-triggered workflows without sleep loops or polling
• Policy Engine: Capability gates, rate limiting, audit trails
• Robot Mode API: JSON interface for AI agents controlling AI agents
• MCP Server: stdio transport MCP service support

Security & Compliance#

• Single-Writer Integrity: watcher lock ensures single writer, prevents concurrent corruption
• Approval mechanism: safe multi-agent control gate
• Secret redaction, local-first (no telemetry or cloud dependency)

Architecture Overview#

ft Swarm Runtime Core
├── Session Graph │ Pane Registry │ State Store │ Control Plane
├── Ingest + Normalization Pipeline
│   └── Discovery → Delta Extraction → Fingerprinting → Filter
├── Storage Layer (SQLite + FTS5)
│   └── output_segments │ events │ workflow_executions │ audit_actions
├── Pattern Engine │ Event Bus │ Workflow Engine
├── Policy Engine
│   └── Capability Gates │ Rate Limiting │ Audit Trail │ Approvals
└── Robot Mode API + MCP + Platform Interfaces

Design Philosophy#

1. Passive-First Architecture — Observation loop is read-only with no side effects; action loop is strictly separated with policy gates
2. Event-Driven, Not Time-Based — Condition-driven rather than time polling
3. Delta Extraction Over Full Capture — Incremental extraction optimizes storage and performance
4. Single-Writer Integrity — Prevents concurrent corruption
5. Agent-First Interface — Structured JSON, suitable for machine parsing

Performance Metrics#

Installation#

# Option 1: Cargo install
cargo install --git https://github.com/Dicklesworthstone/frankenterm.git ft

# Option 2: Build from source (recommended)
git clone https://github.com/Dicklesworthstone/frankenterm.git
cd frankenterm
cargo build --release
cp target/release/ft ~/.local/bin/

Quick Start#

ft setup              # Generate config and shell hooks
wezterm cli list      # Verify backend connection
ft watch              # Start watcher
ft status             # Check status
ft robot state        # JSON output all panes

Main CLI Commands#

# Watcher management
ft watch / ft watch --foreground / ft stop

# Pane inspection
ft status / ft get-text <pane_id>

# Search
ft search "error" / ft search "query" --pane 0

# Robot Mode (JSON API)
ft robot state
ft robot get-text <id> --tail 50
ft robot send <id> "text"
ft robot wait-for <id> <rule_id>

# MCP server
cargo build --release --features mcp
ft mcp serve

Configuration#

Path: ~/.config/ft/ft.toml

• [general]: log_level, log_format, data_dir
• [ingest]: poll_interval_ms, panes include/exclude, priorities, budgets
• [storage]: writer_queue_size, retention_days
• [patterns]: detection packs enable
• [workflows]: automatic workflow execution
• [safety]: approvals, secret redaction, rate limiting

Built-in Agent Pattern Detection#

Comparison with Other Tools#

Additional Notes#

• Requirements: Rust 1.85+ (nightly required for Rust 2024 edition), Linux/macOS
• Dependencies: WezTerm CLI (compatible backend bridge), SQLite (bundled via rusqlite)
• Feature flags: --features distributed (distributed mode), --features mcp (MCP server)
• Data retention: Default 30 days (configurable via storage.retention_days)
• Contribution policy: Author does not accept external code contributions, only issue and PR proposals