athena-flow

Terminal companion UI for Claude Code — intercepts hook events via Unix Domain Sockets and renders a rich, interactive dashboard.

Built with Ink (React for CLIs) + React 19.

Install

npm install -g @lespaceman/athena-flow

Requires Node.js >= 20.

Usage

athena-flow                             # Start in current project directory
athena-flow --project-dir=/my/project   # Specify project directory
athena-flow --continue                  # Resume most recent session
athena-flow --sessions                  # Pick a session interactively
athena-flow setup                       # Re-run setup wizard

Options

| Flag | Description | | --------------- | ------------------------------------------------------------- | | --project-dir | Project directory for hook socket (default: cwd) | | --plugin | Path to a Claude Code plugin directory (repeatable) | | --isolation | Isolation preset: strict (default), minimal, permissive | | --theme | Color theme: dark (default), light, high-contrast | | --workflow | Workflow reference (e.g. name@rev) | | --continue | Resume most recent session, or specify a session ID | | --sessions | Launch interactive session picker | | --verbose | Show additional rendering detail |

Configuration

Config files are merged in order: global → project → CLI flags.

~/.config/athena/config.json          # Global config
{projectDir}/.athena/config.json      # Project config

{
	"plugins": ["/path/to/plugin"],
	"additionalDirectories": ["/path/to/allow"]
}

Development

npm install
npm run build       # Bundle with tsup
npm run typecheck   # Type-check with tsc (no emit)
npm run dev         # Watch mode (tsup --watch)
npm start           # Build & run
npm test            # Run vitest tests
npm run lint        # Prettier + ESLint
npm run format      # Auto-format

# Performance profiling (writes artifacts to .profiles/)
npm run perf:tui -- -- --sessions

See docs/performance-profiling.md for profiling modes and artifact analysis.

Architecture

Two entry points:

• athena-flow — Main Ink terminal UI. Parses args, renders React app, creates UDS server to receive hook events.
• athena-hook-forwarder — Lightweight script invoked by Claude Code hooks. Reads JSON from stdin, forwards to the UI via Unix Domain Socket, returns results via stdout.

Claude Code → hook-forwarder (stdin) → UDS → athena-flow → Dashboard UI

License

MIT