Aer

 █████╗ ███████╗██████╗ 
██╔══██╗██╔════╝██╔══██╗
███████║█████╗  ██████╔╝
██╔══██║██╔══╝  ██╔══██╗
██║  ██║███████╗██║  ██║
╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝

A coding agent for your terminal — powered by your Codex ChatGPT subscription.

Raw-mode TUI with Claude Code / Codex–style mechanics: live tool cards, token paint, approvals, checkpoints, sessions, slash OS.

No API keys. No JSON spew.

---

Quick start

# 1. ChatGPT subscription login (not Platform API)
codex login

# 2. Install
bun install

# 3. Open Aer (interactive — needs a real TTY)
bun run aer

Offline / local stub (no Codex):

bun run aer --stub

One-shot:

bun run aer "Summarize what this repository does"
bun run aer auth
bun run aer task fixtures/hello-world/task.json

Doc	What
docs/architecture/cli-design.md	Altitude UI design
docs/architecture/cli-parity.md	Claude Code / Codex parity tracker
docs/architecture/cli-honest-gap.md	What shipped vs what’s platform-owned
Visual preview	bun run apps/cli/src/ui/preview.ts

---

Why it felt like “helix”

Early scaffold followed the AGENTS.md binary name helix. That was wrong for the product. The CLI is aer. Runtime state lives in .aer/.

---

What you get

Mode	Command	Feel
Interactive	aer	Alt-screen TUI · live stream · slash OS · sessions
One-shot	aer "…"	Stream cards + progressive reveal
Resume	aer continue / aer resume	Pick up .aer/sessions
Task file	aer task <file>	Harness run with tool lines · metrics
Full Codex UI	/codex inside Aer	Hand off to interactive Codex CLI

Auth is always Codex ChatGPT subscription. API-key login is rejected.

Interactive highlights

• Live codex exec --json stream with tool cards (commands, file changes)
• Stub token deltas + progressive reveal for whole messages
• Shift+Tab permission modes · sticky footer · / and @ popups
• Shell ! and write approvals (y / n / a always) → .aer/approvals.json
• File checkpoints · Esc Esc / /rewind · /checkpoints picker
• Image attach: ctrl+v or /image → next turn codex -i
• Alt-screen + mouse: on by default · ctrl+f to toggle
• Ctrl+O transcript · Ctrl+R history · Ctrl+C cancel in-flight turn

---

Commands

aer                         Interactive coding session
aer "fix the flaky test"   One-shot
aer --stub                  Offline stub stream
aer auth                    Check subscription login
aer resume [id]             Resume a prior session
aer continue                Resume last session
aer doctor                  Environment checkup
aer init                    Write AER.md
aer diff                    Working tree diff
aer task <task.json>        Run a task file
aer replay <run-id>         Inspect a prior run
aer calibrate               Build Codex genome profile
aer completion zsh          Shell completions
aer bench smoke             Internal smoke suite
aer help

Inside interactive mode:

/help /status /usage /context /model /mode /plan /permissions
/clear /compact /rename /resume /fork /export /copy
/diff /review /rewind /checkpoints /init /memory /btw /goal
/image /fullscreen /theme /approve /deny /background /tasks
/doctor /mcp /auth /fast /effort /codex /editor /exit

!git status     shell mode (approval-gated)
@src/file.ts    attach file
ctrl+v          paste clipboard image
ctrl+f          toggle alt-screen
shift+tab       cycle permission mode
esc esc         rewind files + turn
\ + enter       multiline

---

Architecture

you
 ↓
aer CLI  (altitude TUI · raw mode)
 ↓
Codex adapter  ←── ChatGPT subscription  (codex exec --json)
 ↓
Policy · MVCC · Tools · Verifier
 ↓
.aer/sessions · .aer/checkpoints · .aer/runs/<id>

---

Develop

bun install
bun run typecheck
bun test packages/codex-adapter apps/cli/src/tui apps/cli/src/checkpoint.test.ts apps/cli/src/approvals.test.ts
bun run aer --stub "hello"

---

Status

Phases 0–16 scaffolded + CLI TUI parity pass. See docs/decisions/STATUS.md.
No “outperforms” claims until held-out gates pass.

License

MIT

Architecture Atlas v5

These editable Mermaid diagrams mirror the Notion architecture dossier.

1. Harness anatomy

flowchart LR
  USER["Developer"] --> MODE["CLI mode router<br>interactive / one-shot / resume / task / replay"]
  MODE --> TUI["Raw-mode altitude TUI<br>input editor, slash OS, @file popup, tool cards, transcript"]
  TUI --> TURN["Turn and session controller"]
  TURN --> CONTEXT["Context assembler<br>AER.md, files, image, history, task spec"]
  CONTEXT --> CODEX["Codex adapter<br>codex exec --json via ChatGPT subscription"]
  CODEX --> PARSER["JSON stream parser"] --> BUS["Internal event bus"]
  BUS --> TUI
  BUS --> POLICY["Permission mode + exact approval engine"]
  POLICY --> APPROVAL[(".aer/approvals.json")]
  POLICY --> CHECK["Checkpoint / MVCC manager"]
  CHECK --> SNAP[(".aer/checkpoints")]
  CHECK --> SHELL["Shell executor"]
  CHECK --> FILE["File-mutation adapter"]
  SHELL --> VERIFY["Diff, tests, typecheck, review, task gates"]
  FILE --> VERIFY
  VERIFY --> RUN[(".aer/runs/<id> + metrics")]
  TURN --> SESSION[(".aer/sessions")]
  SESSION --> REPLAY["Resume, replay, export and rewind"]

Loading

2. Approval, checkpoint, and rewind wiring

flowchart TB
  PROPOSE["Codex proposes command or file change"] --> EVENT["Separate proposal event"] --> SCOPE["Normalize exact operation, paths, arguments and permission mode"]
  SCOPE --> KNOWN{"Existing durable approval matches exact scope?"}
  KNOWN -->|yes| PRE["Create pre-mutation checkpoint"]
  KNOWN -->|no| ASK["Render approval card: yes / no / always"]
  ASK -->|deny| DENY["Return structured denial to model"]
  ASK -->|yes| PRE
  ASK -->|always| SAVE["Persist scoped approval"] --> PRE
  PRE --> EXEC["Execute cancellable subprocess or patch"] --> COMPLETE["Separate completion event"] --> GATES["Verification pipeline"]
  GATES -->|pass| COMMIT["Persist transcript, result, metrics and checkpoint link"]
  GATES -->|fail| FAILED["Mark failed; do not claim task completion"]
  REWIND["Esc Esc or /rewind"] --> PICK["Select turn and checkpoint"] --> RESTORE["Restore files and session cursor"] --> TUI["Re-render coherent transcript state"]

Loading

3. Coding-turn narrative

sequenceDiagram
  actor Dev
  participant UI as Raw TUI
  participant C as Turn Controller
  participant X as Codex JSON Adapter
  participant P as Policy / Checkpoint / Tools
  participant V as Verifier / Local State
  Dev->>UI: prompt, @files, image, shell or task.json
  UI->>C: normalized turn input
  C->>X: codex exec --json with assembled context
  X-->>C: tokens, reasoning, command and file-change proposals
  C-->>UI: progressive paint and live tool cards
  X->>P: proposed mutation
  P-->>Dev: exact approval request when required
  Dev->>P: deny, allow once, or scoped always
  alt approved
    P->>P: pre-mutation checkpoint
    P->>P: cancellable execution
    P->>V: diff, tests, typecheck, review and task gates
    V-->>C: verified result or failed evidence
  else denied
    P-->>C: structured denial event
  end
  C->>V: persist transcript, metrics, approvals, checkpoints and run artifacts

Loading

4. Harness reliability model

stateDiagram-v2
  [*] --> IDLE
  IDLE --> ASSEMBLING_CONTEXT --> STREAMING
  STREAMING --> AWAITING_APPROVAL: mutation proposed
  AWAITING_APPROVAL --> CHECKPOINTING: approved
  AWAITING_APPROVAL --> STREAMING: denied
  CHECKPOINTING --> EXECUTING --> VERIFYING
  VERIFYING --> COMPLETED: gates pass
  VERIFYING --> FAILED: gates fail
  STREAMING --> CANCELLED: Ctrl+C
  EXECUTING --> CANCELLED: cancellation
  FAILED --> REWINDING
  CANCELLED --> REWINDING
  REWINDING --> IDLE
  IDLE --> RESUMING --> STREAMING

Loading