ft — FrankenTerm

</div>

A swarm-native terminal platform that replaces legacy terminal workflows for massive AI agent orchestration. 54 workspace crates. 483 core modules. 45,000+ tests. Purpose-built for fleets of 200+ concurrent AI coding agents.

Summary counts last verified against the current checkout on April 6, 2026: 54 workspace crates, 47 vendored workspace crates under frankenterm/, 483 crates/frankenterm-core/src Rust modules, and 790k+ core-library Rust lines.

<div align="center"> <h3>Quick Install</h3>

cargo install --git https://github.com/Dicklesworthstone/frankenterm.git --bin ft frankenterm

ft --version should work immediately after install. ft doctor / ft doctor --json also run immediately, but current builds will report diagnostic errors on a fresh machine until the active compatibility backend bridge is available: WezTerm CLI installed in PATH and a reachable WezTerm GUI/mux for wezterm cli list.

</div>

TL;DR

The Problem: Running large AI coding swarms across ad-hoc terminal panes is chaos. You can't reliably observe state, detect rate limits or auth failures, coordinate handoffs, or automate safe recovery without brittle glue code. When you're running 50+ Claude Code / Codex / Gemini agents simultaneously, a single undetected rate limit wastes hours of compute. A stuck agent silently burns tokens. An auth failure goes unnoticed for 30 minutes. You have no search across agent output, no audit trail, no way for one AI to safely control another.

The Solution: ft is a full terminal platform for agent swarms with deep observability, deterministic eventing, policy-gated automation, and machine-native control surfaces (Robot Mode + MCP). It captures every byte of terminal output across every pane, detects state transitions via multi-pattern matching, triggers automated workflows in response, and exposes all of it through a JSON API built for AI-to-AI orchestration. The closest analogy is Kubernetes for terminal-based AI agents: observe, detect, react, audit.

Platform Direction

ft is developed as a replacement-class terminal runtime for multi-agent systems, not a thin wrapper around another terminal. The architecture is actively expanding with:

Concepts learned from Ghostty and Zellij (session model, ergonomics, and runtime resilience)
Ground-up ft subsystems purpose-built for agent swarms (tiered scrollback, fleet memory, mission orchestration)
Targeted integrations and code adaptation from /dp/asupersync, /dp/frankensqlite, and /frankentui

Why Use ft?

| Feature | What It Does | |---------|--------------| | Perfect Observability | Captures all terminal output across all panes with delta extraction (<50ms lag) | | Intelligent Detection | Multi-agent pattern engine detects rate limits, errors, prompts, completions across Codex, Claude Code, and Gemini | | Event-Driven Automation | Workflows trigger on patterns, not sleep loops or polling heuristics | | Robot Mode API | JSON/TOON interface optimized for AI agents to control other AI agents | | Lexical + Hybrid Search | FTS5 lexical search plus semantic/hybrid retrieval modes across captured output | | Policy Engine | 21-subsystem policy framework with capability gates, rate limiting, audit trails, and approval tokens | | Mission Orchestration | Transactional multi-pane execution with prepare/commit/compensate lifecycle, idempotency guards, and deterministic replay | | Tiered Scrollback | Three-tier memory management (hot/warm/cold) keeps 200+ panes under 1GB vs 4GB+ in stock terminals | | Replay & Forensics | Capture, replay, and diff decision graphs for post-incident analysis and regression testing | | Fleet Memory Controller | Coordinated backpressure across queue depth, system memory, and per-pane budgets with hysteresis | | Distributed Mode | Optional agent-to-aggregator streaming with per-agent dedup, wire protocol versioning, and stale-session pruning |

Quick Example

# Start the ft watcher/runtime
$ ft watch

# See all active panes as JSON
$ ft robot state
{
  "ok": true,
  "data": {
    "panes": [
      {"pane_id": 0, "title": "claude-code", "domain": "local", "cwd": "/project"},
      {"pane_id": 1, "title": "codex", "domain": "local", "cwd": "/project"}
    ]
  }
}

# Compact TOON output (40-60% fewer tokens for AI-to-AI comms)
$ ft robot --format toon state

# Get recent output from a specific pane
$ ft robot get-text 0 --tail 50

# Batch output from multiple panes in one call
$ ft robot get-text --panes 0,1,2 --tail 20

# Wait for a specific pattern (e.g., agent hitting rate limit)
$ ft robot wait-for 0 "codex.usage.reached" --timeout-secs 3600

# Search all captured output
$ ft robot search "error: compilation failed"

# Semantic/hybrid search mode
$ ft robot search "error: compilation failed" --mode hybrid

# Send input to a pane (with policy checks)
$ ft robot send 1 "/compact"

# View recent detection events
$ ft robot events --limit 10

# Run a transactional multi-pane operation
$ ft tx run --contract mission.json

# Inspect the full tx lifecycle
$ ft tx show --include-contract

Read/query interfaces (ft get-text, ft search, ft robot get-text, ft robot search, and MCP wa.get_text / wa.search) are policy-evaluated and redact secret material in returned text/snippets.

Design Philosophy

1. Passive-First Architecture

The observation loop (discovery, capture, pattern detection) has no side effects. It only reads and stores. The action loop (sending input, running workflows) is strictly separated with explicit policy gates. In practice, ft watch can never accidentally send input to a pane or modify agent state; it is a pure observer.

2. Event-Driven, Not Time-Based

No sleep(5) loops hoping the agent is ready. Every wait is condition-based: wait for a pattern match, wait for pane idle, wait for an external signal. Deterministic, not probabilistic. The ft robot wait-for command blocks until a specific rule fires, not until a timer expires.

3. Delta Extraction Over Full Capture

Instead of repeatedly capturing entire scrollback buffers, ft uses 4KB overlap matching to extract only new content. This produces efficient storage, minimal latency, and explicit gap markers for discontinuities. When the overlap match fails (terminal reset, scrollback clear), the gap is recorded as an explicit event rather than silently dropped.

4. Single-Writer Integrity

A file-system lock (via fs2) ensures only one watcher can write to the database. No corruption from concurrent mutations. Graceful fallback for read-only introspection. The lock metadata records PID and start time for diagnostics.

5. Agent-First Interface

Robot Mode returns structured JSON with consistent schemas. Every response includes ok, data, error, elapsed_ms, and version. TOON (Token-Optimized Object Notation) output reduces token consumption by 40-60% for AI-to-AI communication. Built for machines to parse, not humans to read.

6. Transactional Safety

Multi-pane operations use a prepare/commit/compensate lifecycle borrowed from distributed transaction protocols. If a commit step fails, compensation rolls back the committed steps. Kill switches and pause controls provide emergency intervention. Every transition emits an observability event with a reason code and decision path.

7. Defense in Depth for Memory

The fleet memory controller synthesizes pressure signals from three independent subsystems: pipeline backpressure (queue depths), system memory utilization, and per-pane memory budgets. These feed a unified 4-tier pressure model (Normal, Elevated, Critical, Emergency) with asymmetric hysteresis that escalates fast and de-escalates slow. Actions range from throttling poll intervals to emergency warm-scrollback eviction.

Safety Guarantees

Observe vs act split: ft watch is read-only; mutating actions must pass the Policy Engine.
No silent gaps: capture gaps are recorded explicitly and surfaced in events/diagnostics.
Policy-gated sending: ft send and workflows enforce prompt/alt-screen checks, rate limits, and approvals.
Policy-gated reads: get-text/search surfaces enforce policy checks and return redacted text payloads.
Transactional operations: ft tx run uses prepare/commit/compensate phases with idempotency guards and deterministic replay.
Approval tokens: Allow-once approval codes scoped to specific action + pane + fingerprint combinations.
Secret redaction: Captured output is redacted before being returned through any API surface, with configurable sensitivity tiers (T1/T2/T3) and retention policies.

Secure Distributed Mode

Secure distributed mode is available as an optional feature-gated build and is off by default.

# Build ft with distributed mode support
cargo build -p frankenterm --release --features distributed

The distributed wire protocol provides:

Versioned message envelopes with sender identity validation
Per-agent sequence-number dedup (no duplicate processing)
1 MiB maximum message size enforcement
Stale-session pruning with configurable idle thresholds
Local receipt-clock decisions (untrusted remote clocks not used for liveness)

Operational topology:

Run ft watch on the aggregator host with [distributed].enabled = true

Frankenterm

Install / Use

README