Agent Loop

CLI-first Codex orchestration

Agent Loop

Run Codex through requirements, research, planning, implementation, verification, and review. Keep the terminal as the source of truth, then inspect the same run from a local desktop companion.

Watch the demo Start from source Source on GitHub

Demo

Start in the terminal. Continue in the desktop app.

Agent Loop CLI run demo
CLI output stays phase-centric: requirements, research, plan, implement, verify, review.
Agent Loop desktop companion demo
The desktop companion follows seeded runs, shows scrolling detail, opens diffs, and displays animated Miso PET state in the run list.

Workflow

A local loop from task to reviewed diff.

Task CLI run or desktop New Run
Requirements shape task and constraints
Research read code, docs, and history
Plan choose the path
Implement edit scoped worktrees
Verify run checks and retry
Review inspect the diff
Ready diff summary, patch, local commit
Verify fails or review requests changes → Implement
.agent-loop/runs/<run-id> state, events, artifacts, patches, summary

Architecture

One workflow engine, two local surfaces.

CLI surface run, resume, status, diff
Desktop surface New Run, Resume, Diff, PET mode
Workflow APIs runAgentLoop and resumeAgentLoop
Codex app-server phase turns and subagents
Worktrees .agent-loop/worktrees/<run-id>
Durable run directory state.json, events.jsonl, artifacts, patches, summary
CLI read side status, diff, commit, clean
Observation layer RunStore and FileRunObserver
Electron renderer Runs, detail, diff, actions, and PET sprites via typed IPC
GUI-started live events InProcessRunEventHub → Desktop

Quickstart

Run from this checkout.

CLI

corepack enable
pnpm install
pnpm build
pnpm agent-loop run --repo . --task "Fix the failing tests and review the diff."

Desktop

pnpm app:dev
pnpm app:build
pnpm app:package:mac