Skip to main content

​
Architecture Overview

Genie v4 is an agent orchestration system that turns wishes (structured plans) into pull requests through autonomous AI agents. The architecture is built around five subsystems that work together.

​
High-Level Component Map

┌─────────────────────────────────────────────────────────┐
│                     genie CLI                           │
│  (commander.js entry point → src/genie.ts)              │
├─────────────┬──────────────┬────────────────────────────┤
│  Skills     │  Commands    │  Hooks                     │
│  /brainstorm│  team create │  PreToolUse → identity     │
│  /wish      │  spawn       │  PreToolUse → auto-spawn   │
│  /work      │  send        │  PostToolUse → nats-emit   │
│  /review    │  status      │  Stop → nats-emit          │
└──────┬──────┴──────┬───────┴──────────┬─────────────────┘
       │             │                  │
       ▼             ▼                  ▼
┌─────────────┐ ┌──────────┐  ┌──────────────────┐
│  Wish State │ │  Agent   │  │  NATS Pub/Sub    │
│  (PG tasks) │ │ Registry │  │  (observability) │
└──────┬──────┘ │ (~/.genie│  └────────┬─────────┘
       │        │ /workers │           │
       │        │  .json)  │           │
       │        └────┬─────┘           │
       │             │                 │
       ▼             ▼                 ▼
┌──────────────────────────────────────────────────┐
│                   pgserve                        │
│  Embedded PostgreSQL (port 19642)                │
│  schedules · triggers · runs · tasks · messages  │
└──────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────┐
│                tmux Transport                    │
│  Sessions → Windows → Panes (one per agent)     │
│  send-keys injection · pane capture · state      │
└──────────────────────────────────────────────────┘

​
Subsystems

SubsystemModulePurpose
Statewish-state.ts, agent-registry.ts, mailbox.ts, team-manager.tsTrack wish execution groups, worker lifecycle, message delivery, team configs
Postgresdb.ts, db-migrations.ts, task-service.tsEmbedded pgserve database — 10 migrations, tasks, boards, projects, agents, sessions, app registry
Messagingnats-client.ts, protocol-router.ts, claude-native-teams.tsReal-time pub/sub, provider-agnostic routing, Claude Code native IPC bridge
Schedulerscheduler-daemon.ts, cron.tsCron-based trigger firing, lease-based claiming, heartbeat collection
Transcriptstranscript.ts, claude-logs.ts, codex-logs.tsProvider-agnostic log reading from Claude Code and Codex sessions
Observabilityaudit_events, sessions, session_contentOTel-structured event logging — costs, tokens, tool usage, errors. Session replay and search.
Boardsboards, board_templatesKanban-style pipelines with configurable columns, gates, and action skills

​
Data Flow: Wish to PR

1

Plan

/brainstorm → /wish creates a WISH.md with execution groups and acceptance criteria.
2

Decompose

/work reads WISH.md, creates PG tasks (parent = wish, children = groups), and resolves dependencies.
3

Dispatch

The team-lead spawns agents into tmux panes via genie spawn. Each agent gets a worktree clone and a group assignment.
4

Execute

Agents work autonomously. Hooks inject identity into messages, auto-spawn offline agents, and emit events to NATS.
5

Converge

As groups complete (genie done), the wish state machine recalculates dependent groups. Blocked groups become ready.
6

Review

/review validates all criteria. If issues are found, /fix loops until the reviewer returns SHIP.

​
State Fragmentation

Genie state is intentionally distributed across four scopes:
ScopeLocationWhat Lives Here
Global~/.genie/Worker registry, team configs, sessions, pgserve data
Per-repo<repo>/.genie/Wish state, mailbox, team chat
Per-worktree<worktree>/.genie/Team chat (worktree-specific)
Claude native~/.claude/teams/Native team configs, inbox messages
Worktrees share the main repo’s .genie/ via git rev-parse --git-common-dir. The worker registry is global, not per-worktree.

​
Environment Variables

VariableEffect
GENIE_HOMERelocates all global state from ~/.genie
GENIE_AGENT_NAMEAgent identity for hook dispatch (must be set for auto-spawn)
GENIE_TEAMDefault team when --team not provided
GENIE_NATS_URLNATS server URL (default: nats://localhost:4222)
GENIE_PG_PORTpgserve port (default: 19642)
GENIE_MAX_CONCURRENTMax concurrent scheduler runs (default: 5)
GENIE_IDLE_TIMEOUT_MSAuto-suspend idle workers after N ms
CLAUDECODE=1Enables Claude Code features in team-lead