Repository Structure

athena-flow/
├── src/                        # All runtime source code
│   ├── app/                    # CLI entry, shell, commands, providers, process management
│   │   ├── bootstrap/          # bootstrapConfig.ts — config/plugin/workflow resolution
│   │   ├── commands/           # Command registry, parser, executor, built-in commands
│   │   │   └── builtins/       # help, clear, quit, stats, context, sessions, tasks, setup
│   │   ├── entry/              # cli.tsx — main entry point (athena / athena-flow binary)
│   │   ├── history/            # historyStore.ts — input history
│   │   ├── process/            # useHarnessProcess.ts — harness lifecycle
│   │   ├── providers/          # RuntimeProvider.tsx, useFeed.ts
│   │   ├── runtime/            # createRuntime.ts
│   │   └── shell/              # AppShell.tsx — root application component
│   │
│   ├── core/                   # Harness-agnostic core runtime logic
│   │   ├── controller/         # runtimeController.ts, permission.ts, rules.ts
│   │   ├── feed/               # mapper.ts, timeline.ts, todoPanel.ts, types.ts, cellFormatters.ts
│   │   ├── runtime/            # connector.ts, events.ts, process.ts, types.ts
│   │   └── workflows/          # applyWorkflow.ts, installer.ts, loopManager.ts, registry.ts, types.ts
│   │
│   ├── harnesses/              # Harness adapters
│   │   ├── claude/             # Claude Code integration
│   │   │   ├── config/         # flagRegistry.ts, isolation.ts, modelResolver.ts
│   │   │   ├── hooks/          # generateHookSettings.ts — temp settings file generation
│   │   │   ├── process/        # spawn.ts, useProcess.ts, tokenAccumulator.ts
│   │   │   ├── protocol/       # envelope.ts, events.ts, result.ts
│   │   │   ├── runtime/        # server.ts (UDS server), mapper.ts, decisionMapper.ts
│   │   │   └── system/         # detectVersion.ts
│   │   ├── mock/               # Mock harness for testing
│   │   ├── configProfiles.ts
│   │   ├── processProfiles.ts
│   │   └── registry.ts         # Harness capability registry
│   │
│   ├── infra/                  # Infrastructure layer
│   │   ├── plugins/            # config.ts, loader.ts, marketplace.ts, frontmatter.ts, types.ts
│   │   └── sessions/           # store.ts, registry.ts, schema.ts, sessionIndex.ts, types.ts
│   │
│   ├── setup/                  # Setup wizard and first-run flow
│   │
│   ├── shared/                 # Types and utilities — no layer imports
│   │   ├── types/              # common.ts, session.ts, transcript.ts, toolOutput.ts
│   │   └── utils/              # format.ts, formatters.ts, fileTree.ts, hyperlink.ts, perf.ts, id.ts
│   │
│   ├── ui/                     # Terminal UI (React 19 + Ink 6)
│   │   ├── components/         # FeedGrid, FeedList, Header, PermissionDialog, SessionPicker, etc.
│   │   ├── glyphs/             # registry.ts — unicode/ascii glyph pairs
│   │   ├── header/             # contextBar.ts, model.ts, renderLines.ts
│   │   ├── hooks/              # useFeedKeyboard.ts, useFeedNavigation.ts, useLayout.ts, useSpinner.ts, etc.
│   │   ├── layout/             # buildBodyLines.ts, buildFrameLines.ts, renderDetailLines.ts
│   │   ├── theme/              # ThemeContext.tsx, themes.ts, types.ts
│   │   └── tooling/            # toolExtractors.ts
│   │
│   └── __sentinels__/          # Boundary discipline enforcement tests
│
├── docs/                       # Documentation source (performance-profiling.md, etc.)
├── .github/workflows/          # CI/CD pipelines
├── package.json                # @athenaflow/cli — bins: athena, athena-flow, athena-hook-forwarder
├── tsconfig.json
├── tsup.config.ts              # Build config (tsup bundler, ESM output)
├── vitest.config.ts
└── CLAUDE.md                   # Instructions for AI coding assistants

Key Source Modules

src/app/entry/cli.tsx

The entry point for athena and athena-flow. Parses CLI args with meow, merges configs, resolves the bootstrap config, and mounts the React/Ink application.

src/app/shell/AppShell.tsx

The root application component. Manages all major UI state: focus mode (feed/input/todo), permission dialogs, session picker, setup wizard, keyboard handlers, and the harness process lifecycle.

src/harnesses/claude/runtime/server.ts

The Unix Domain Socket server. Listens at <projectDir>/.claude/run/ink-<PID>.sock, receives NDJSON hook events, maps them to RuntimeEvent objects, and sends decision responses back for blocking events.

src/harnesses/claude/hooks/generateHookSettings.ts

Generates the temporary Claude Code settings file at startup that registers athena-hook-forwarder as the handler for all hook event types. Registers cleanup on exit, SIGINT, SIGTERM, and uncaughtException.

src/core/feed/

The feed layer: mapper transforms runtime events to feed events, timeline sequences and filters them, cellFormatters renders individual cells in the grid.

src/infra/sessions/

SQLite session persistence. store.ts handles per-session databases; registry.ts enumerates all session databases for the session picker; schema.ts defines the five-table schema.

src/infra/plugins/

Plugin loading: loader.ts reads a plugin directory, finds skills/*/SKILL.md files, parses frontmatter via frontmatter.ts, and returns PromptCommand objects. marketplace.ts resolves marketplace refs by cloning/updating GitHub repos.

src/ui/

Built with React 19 + Ink 6. Uses use-context-selector for performance-optimized context access. Every glyph has both Unicode and ASCII variants (src/ui/glyphs/). The three themes (dark, light, high-contrast) are defined in src/ui/theme/themes.ts.

Architectural Boundaries

The codebase enforces strict layer boundaries via ESLint no-restricted-imports:

• core/ must not import from app/, ui/, or harnesses/
• harnesses/ must not import from app/ or ui/
• ui/ must not import from harnesses/
• shared/ must not import from any layer

src/__sentinels__/ contains tests that verify these boundaries are maintained.

Build System

Athena uses tsup to bundle TypeScript into ESM output. Node.js 20+ is required. The output is ESM-only.

npm run build    # production bundle → dist/
npm run dev      # watch mode, rebuilds on change