Introduction

Introduction

Athena Flow is a workflow runtime built around Claude Code. It runs alongside Claude Code as a persistent process that receives the agent's runtime events, enforces isolation policies, orchestrates plugins and workflows, and renders everything live in your terminal.

Think of it as the control plane for your Claude Code sessions — giving you visibility into every tool call, permission decision, and agent action as it happens, with the ability to steer what happens next.

The Problem It Solves

Running Claude Code on real codebases surfaces a set of practical challenges that the agent itself doesn't solve:

  • Observability: What exactly did the agent do, in what order, and why? Tool calls, subprocesses, and file writes happen fast and are hard to audit after the fact.
  • Control: You want to allow broad capabilities during exploration but lock things down when running against production systems.
  • Repeatability: Running the same kind of task repeatedly (e2e test generation, PR reviews, dependency audits) requires reusable prompt templates and agent configurations, not ad-hoc prompts each time.
  • Extensibility: Different projects need different tools — custom commands, MCP servers, team-specific agents — that Claude Code alone cannot provide.

Athena Flow addresses all four.

What It Provides

Live event feed — A structured terminal view of every event emitted by Claude Code: tool invocations, permission prompts, outputs, errors, and timing. Organized into columns so you can scan at a glance.

Session persistence — Every session is stored in SQLite locally. You can resume any previous session, inspect its history, and pick up where you left off.

Plugin system — Extend Athena with plugins that add slash commands and MCP servers. Plugins are plain directories containing skill definitions that Athena loads at startup.

Workflow orchestration — Define reusable workflows as JSON files that bundle prompt templates, plugin references, loop configurations, and isolation settings.

Isolation presets — Control what the agent is allowed to do with three built-in presets: strict, minimal, and permissive. Applied per-session, with full isolation from Claude Code's own settings file.

How It Works

Athena sits between Claude Code and your terminal:

Claude Code ──► hook-forwarder (stdin) ──► Unix Domain Socket ──► Athena Flow runtime
  1. Athena generates a temporary Claude Code settings file that registers athena-hook-forwarder as the handler for all Claude Code hook events.
  2. Claude Code calls the forwarder binary at each lifecycle point (tool use, permission request, session start/end, etc.).
  3. The forwarder streams NDJSON events over a Unix Domain Socket to the Athena runtime.
  4. Athena receives and processes the stream: applying workflow logic, plugin resolution, isolation policy, persisting to SQLite, and updating the terminal UI.

The agent never slows down — hook processing is fast and non-blocking. Athena observes and influences the session without being in the critical path of the agent's execution.

Harness Model

Athena uses the concept of a harness — the agent runtime it wraps. Today the only production harness is claude-code. Support for openai-codex (via codex-app-server) and opencode are planned. The harness abstraction means Athena's workflow, plugin, and UI systems remain the same regardless of which underlying agent is running.