AgentFabric

ACTIVE DEVELOPMENT: This project is currently in active development and may change rapidly.

CLI Agent Multiplexer & Orchestration Substrate

AgentFabric is a terminal multiplexing layer designed to orchestrate a workforce of autonomous CLI agents (like Claude Code, Gemini CLI, or Aider). It provides visible terminal session management, transport multiplexing, and coordination primitives for running multiple interactive agents while maintaining human-in-the-loop oversight.

---

Docs

• OPERATOR_RUNBOOK.md — production checklist, MCP examples, troubleshooting, and recovery steps.
• AI_OPERATOR_GUIDE.md — canonical workflow, gate, and policy rules for AI operators in this repo.
• CLAUDE.md — detailed orchestration logic and tier definitions.

---

How It Works

AgentFabric operates as a "terminal substrate" that sits between your orchestrator (Gemini CLI, Claude Code, or a custom script) and the actual agent processes.

1. The Terminal Substrate (Tmux + node-pty + Alacritty)

Instead of running agents in raw terminal emulators, AgentFabric spawns the actual CLI process inside node-pty, bridges it into a dedicated Tmux session, and opens an Alacritty window attached to that tmux session.

• Visible By Design: Every spawned terminal is intended to be user-viewable and interactive.
• Shared I/O Paths: The same session can be driven by the user, MCP tools, gRPC clients, WebSocket clients, and Redis-backed automation.
• Visible Terminal Preflight: Visible sessions are preflight-checked for tmux, a supported terminal binary, and display availability before spawn so broken GUI prerequisites fail early instead of leaving half-attached sessions.
• Cleaner Interactive Panes: Tmux windows are renamed to human-meaningful titles, pane resets happen on relaunch, and repeated Gemini startup banner noise is suppressed in the visible pane.

2. The Multi-Transport API

The daemon.js serves as the central hub, exposing multiple interfaces:

• MCP (Model Context Protocol): Native integration with Claude Desktop and Gemini CLI tools.
• gRPC: High-performance, language-agnostic protocol for Python/Go/Rust orchestrators.
• WebSocket/JSON-RPC: Real-time event streaming for web UIs or lightweight CLI clients.

MCP socket mode is the recommended production path for long-lived control. The proxy now probes the MCP socket directly before attempting daemon spawn, and reconnect state includes a resume payload plus recent board events.

3. Safety & Governance Layers

AgentFabric includes layered governance around session creation and automation:

• OperationGate: A hard write-gate on managed terminal_write paths plus per-session output monitoring. It can elevate incidents and globally lock managed writes until a human overrides it.
• TrustPolicy (bwrap): If configured, agents run inside a Bubblewrap sandbox, restricting their filesystem and network access to only what is strictly necessary.
• AutoResponder: Automatically approves known-safe Y/n prompts from agents, while escalating dangerous or ambiguous prompts to the central Blackboard for review.
• Protected Session Lifecycles: Sessions are classified as operator, worker, or managed. Destructive controls such as terminal_kill, terminal_interrupt, and terminal_release refuse to touch protected operator sessions unless force: true is explicitly supplied.
• Verified Inter-Agent Messages: Structured inbox messages carry a runtime-signed provenance envelope. Reads expose verification state, invalid replies are excluded from the ACK path, and message status can be inspected through MCP.

4. Context Lifecycle Management

AgentFabric tracks the "Context Window" of each agent. The ContextManager uses two stages:

• Checkpoint (soft): Request and persist a structured summary while the session keeps running.
• Wipe (hard): Restart the session with recent summaries injected when a tracked session exceeds its hard threshold and a restart spec exists.

This gives long-lived sessions bounded context growth while preserving accumulated task state.

5. Shared Memory and Orchestration

AgentFabric includes a shared blackboard plus synthesis helpers so multiple agents can collaborate without losing state:

• Semantic Knowledge Search: Knowledge lookup supports exact topic fetches and ranked fuzzy matches.
• Memory Synthesis: knowledge_synthesize builds an operational brief from knowledge entries, context summaries, task results, and recent events.
• Automatic Task Consolidation: When a task is marked done through MCP, AgentFabric can auto-synthesize and store a task:<taskId> knowledge entry.
• Template Dry Runs: Templates can be previewed before task creation.
• Conductor-Style Panel Review: Template execution can prepend a panel-review and synthesis gate so intake is expanded into a production-ready brief before downstream phases execute.

---

Quick Start

Installation

npm install
# Ensure tmux and alacritty are installed for visible mode
sudo apt install tmux alacritty 

Start the Daemon

# Standard mode (WebSocket + gRPC)
node daemon.js

# MCP stdio mode (single host, exits when the host disconnects unless --mcp-keep-alive is used)
node daemon.js --mcp

# Persistent MCP socket mode (recommended for multi-host / long-lived control)
node daemon.js --mcp-socket

# Parent-process stdio control mode
node daemon.js --control

# Dev Mode (secure default policy)
node daemon.js --dev

# Dev Mode with explicit OPEN auth policy override
node daemon.js --dev --allow-insecure-dev-mode

# Explicit hyperscale opt-in for built-in adapters
node daemon.js --adapter conflux --hyperscale-opt-in

Configuration

AgentFabric can be configured via environment variables or CLI flags:

• REDIS_URL: Enable Redis-backed shared state. This is the recommended production mode for shared memory, multi-client coordination, and persistent board state.
• --token <secret>: Set the shared secret for WebSocket clients. WebSocket clients must present Authorization: Bearer <secret>.
• --grpc-token <secret>: Set the shared secret for gRPC TCP clients.
• --redis-mode <required|optional|disabled>: Controls Redis dependency behavior. Defaults to required in --mcp-socket mode and optional elsewhere.
• --allow-insecure-dev-mode: With --dev, explicitly switches AuthPolicy to OPEN. Without this flag, --dev keeps secure ISOLATED auth.
• --adapter-trust <strict|permissive>: External adapter trust policy. Defaults to strict outside dev mode.
• --adapter-allowlist <abs1,abs2,...>: Comma-separated absolute paths allowed for --adapter-path when --adapter-trust strict.
• --hyperscale-opt-in: Explicitly enables hyperscale behavior for built-in adapters that support it.
• --mcp-tool-profile <full|readonly>: MCP tool exposure profile. readonly disables mutating/admin tools.
• --mcp-tool-allowlist <tool1,tool2,...>: Explicit per-tool allowlist.
• --mcp-tool-denylist <tool1,tool2,...>: Explicit per-tool denylist (applied after allowlist).
• --ws-max-connections, --ws-per-ip-max, --ws-req-per-min, --ws-idle-timeout-ms, --ws-origin-allowlist: WebSocket abuse-control policy.
• --audit-log-dir <path>: Enable dedicated structured audit event stream (audit.ndjson).
• --env-file .env: Load additional environment variables into the daemon process.
• AGENTFABRIC_GRAPH_BACKEND: Graph backend (kuzu, off). Default is kuzu with graceful fallback if unavailable.
• AGENTFABRIC_GRAPH_MIRROR: Optional mirror backend (cayley, none). Recommended topology is Kuzu writer + optional Cayley mirror.
• AGENTFABRIC_CAYLEY_URL: Cayley mirror ingest endpoint URL used by graph_sync.

Useful MCP Runtime Behaviors

• session_resume returns a reconnect payload including active tasks, pending approvals/auth actions, gate state, and recent board events.
• template_run supports dryRun: true to preview a template and panelReview: true to prepend a conductor-style panel review.
• knowledge_query supports semantic fallback, knowledge_list supports search, and knowledge_synthesize produces a cross-agent memory brief.
• auth_resolve { action: "complete" } is the intended path for Gemini browser-auth completion before relaunch.
• agent_negotiate accepts pollMs and retryAttempts for overloaded recipients, and timeout errors include structured diagnostics.
• graph_status, graph_index, graph_query expose lightweight knowledge-graph indexing and lookup.
• graph_sync and graph_drift_check support mirror sync and checksum-based drift monitoring.
• npm run symbols:generate refreshes project_symbols.json for validate_code and graph indexing workflows.
• For operational procedures, examples, production checks, and troubleshooting, see OPERATOR_RUNBOOK.md.

---

Security Posture

AgentFabric is conservative by default:

• AuthPolicy: ACP clients default to ISOLATED mode (clients can only see/touch their own ACP-managed sessions).
• Dev Mode Policy: --dev is still secure by default (ISOLATED) unless --allow-insecure-dev-mode is explicitly supplied.
• Network: gRPC TCP binds are restricted to loopback unless --allow-insecure-grpc is set.
• WebSocket Auth: When --token is configured, only Authorization: Bearer <token> is accepted.
• Adapter Trust: External adapter loading is blocked by default in strict trust mode unless a path is explicitly allowlisted.
• Adapter Capabilities: Adapter manifests can declare capabilities; SessionManager methods outside declared capabilities are denied at runtime.
• MCP Tool Scoping: MCP tools are policy-gated at both list and call time using profile + allow/deny lists.
• WebSocket Abuse Controls: Connection caps, per-IP limits, request-rate windows, origin allowlisting, and idle eviction are enforced server-side.
• Access Control: Session mutation is mediated by transport- and tool-level ownership/claim checks, with additional governance available through OperationGate.

---

Monitoring

• Health: GET http://localhost:7779/health
• Readiness: GET http://localhost:7779/ready
• Metrics: GET http://localhost:7779/metrics (Prometheus-compatible)

---

For detailed orchestration logic and tier definitions, see CLAUDE.md.