ii-agent-harness

Slack-driven agent sessions backed by persistent tmux workspaces. Say it in a thread, run it in a shell.

ii-agent-harness turns Slack threads into persistent, tmux-backed agent sessions running Claude Code, Codex, or plain operator shells. Each thread maps to a durable workspace with heartbeat supervision, audit logging, sandboxed execution, and streaming terminal output posted back to Slack.

Everything is session-first — your Slack threads become live workspaces, not throwaway command invocations. The tmux session is the source of truth for the runtime, with a full audit trail of every Slack-to-tmux handoff visible to operators.

Quick Start | Commands | Architecture | Community | Contributing

What You Get

• Persistent agent sessions — each Slack thread maps to a durable tmux workspace
• Multi-runtime support — Claude Code, Codex, and operator shell adapters behind a common interface
• Streaming output — terminal output is normalized, chunked, and posted back to Slack threads
• Heartbeat supervision — near-real-time liveness monitoring with degraded-state detection and auto-recovery
• Audit trail — every Slack input, tmux dispatch, and transport action is recorded with timestamps
• Sandboxed execution — repo allowlists, profile-based policies, and environment scrubbing
• Operator dashboard — browser-accessible host pages showing session state, transcripts, and audit logs
• Scheduled supervision hooks — launchd/cron-friendly supervisor passes for liveness checks and recovery loops

Quick Start

npm install

# Standalone/package-local setup:
cp .env.example .env
# Edit .env with your Slack app credentials and repo allowlist

# Monorepo operators should instead configure the sibling
# implementation/ii-agent-harness-implementation wrapper.

# Set up Slack app manifest
npm run setup

# Start the server
npm start

Prerequisites

• Node.js 22+
• tmux installed and on PATH
• A Slack app with Socket Mode enabled (see setup guide)

Slack Commands

Command	Description
/hero start <runtime> <repo>	Start a new agent session
/hero status	Show session health and state
/hero sessions	List all active sessions
/hero pause	Pause the current session
/hero resume	Resume a paused session
/hero stop	Gracefully stop the session
/hero end	End the session; archival happens later via retention/supervisor
/hero inspect	View detailed session diagnostics
/hero doctor	Run health checks across all sessions

Thread replies in a managed session are injected directly into the live tmux pane as agent input.

Architecture

Slack Thread ──▶ Slack Bridge ──▶ Session Manager ──▶ tmux session
     ▲                                                      │
     └────────── Output Normalizer ◀── Transcript Capture ◀─┘

Core Components

• Slack Bridge — routes thread messages to sessions, handles commands, posts output
• Session Manager — creates/destroys tmux sessions, manages lifecycle states
• Runtime Adapters — pluggable backends for Claude Code, Codex, and operator shells
• Transcript Store — captures raw and normalized terminal output
• Supervisor — heartbeat loop and scheduled repair jobs
• Sandbox Policy Engine — enforces repo allowlists, profiles, and resource limits

Session Lifecycle

creating → ready → running → idle → paused → closing → closed → archived

With recovery paths: degraded → recovering → running or error

How It Works

1. A Slack user runs /hero start codex my-repo in a channel
2. The bridge authorizes the user and repo against the sandbox policy
3. A tmux session is created with the agent shell booted inside it
4. Thread replies are serialized and injected into the tmux pane
5. A capture loop reads terminal output and streams it back to Slack
6. Heartbeats monitor liveness; the supervisor auto-recovers degraded sessions
7. All dispatches are audit-logged for operator review

Development

# Typecheck
npm run check

# Run tests
npm test

# Run proof harness
npm run prove

# Browser tests
npm run test:browser

Documentation

• SYSTEM_PLAN.md — full system design
• SECURITY_MODEL.md — sandboxing and access control
• STATE_MODEL.md — session state machine
• RUNBOOK.md — operational guide
• REQUIREMENTS.md — feature requirements

Community

• Discord: discord.gg/G7Qnnhy
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: SECURITY.md

Open Source

• License: Apache 2.0
• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md