Harness Support

A harness is the agent runtime that Athena wraps. The harness abstraction isolates Athena's workflow, plugin, and UI systems from the specifics of any one agent's event format or lifecycle API.

Current Harnesses

`claude-code` (Production)

The only production harness. Integrates via Claude Code's official hooks system.

Integration mechanism: Athena generates a temporary settings file that registers athena-hook-forwarder as the hook handler for all Claude Code hook event types. The forwarder streams events over a Unix Domain Socket to the Athena runtime.

Supported hook events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Notification, Stop, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit, PreCompact, Setup.

Activation: Default. Selected automatically unless overridden in config.

Detection: Athena detects whether Claude Code is installed via detectVersion() at setup and startup.

`openai-codex` (Planned)

Integration with OpenAI's Codex runtime via codex-app-server. When implemented, it will expose the same event stream interface to the Athena core — workflows, plugins, and the TUI work identically regardless of which harness is active.

Status: Not yet available in any release.

`opencode` (Planned)

Integration with the OpenCode agent runtime.

Status: Not yet available in any release.

The Harness Abstraction

Each harness implements the RuntimeConnector interface:

type Runtime = {
  start(): void;
  stop(): void;
  getStatus(): 'stopped' | 'running';
  onEvent(handler: RuntimeEventHandler): () => void;
  onDecision(handler: RuntimeDecisionHandler): () => void;
  sendDecision(eventId: string, decision: RuntimeDecision): void;
}

Events produced by any harness are typed as RuntimeEvent with a canonical RuntimeEventKind. Plugin authors and workflow authors work with these normalized types and do not interact with the harness interface directly.

Harness Configuration

Set the harness in your config:

{
  "harness": "claude-code"
}

The setup wizard also offers harness selection. Currently only claude-code is enabled — other harness options are shown as "coming soon" in the wizard.

Contributing a New Harness

A new harness requires:

Implementing the Runtime interface in src/harnesses/
A mechanism that produces NDJSON events matching Athena's RuntimeEvent schema
Registering the harness in src/harnesses/registry.ts
Unit tests covering event forwarding and lifecycle
Documentation update to this page

See PR & Code Conventions for contribution guidelines.