Multiple AI agents building software in parallel while you manage priorities and review what ships. Read this once — then you're set for every project.
~20 min setupRead onceYour role: product owner, not developer
What just happened
What npx ay-framework installed
Installed in your project
✓.claude/CLAUDE.md— guide every agent reads on boot ✓.claude/commands/— slash commands (/go, /plan, /verify-done…) ✓.claude/agents/janitor.md— agent that keeps docs honest ✓.ay/tracking/BOARD.md— kanban board (single source of truth) ✓.ay/tracking/AGENTS.md— live roster of who is working on what ✓.ay/tracking/HANDOFFS.md— async messages between agents ✓.ay/tracking/DECISIONS.md— architecture choices agents must respect ✓.git/hooks/— auto-syncs .ay/ into every git worktree
.ay/ is the nervous system. Never committed to git. Every agent — on any branch or worktree — reads the same BOARD.md and HANDOFFS.md. One source of truth, always local.
Your role
You are the product owner — not the developer
You stop writing code and start directing. Agents build, test, fix, and commit. You decide what matters and review what ships.
✓ You do
Say what to build (one sentence)
Answer plan-phase questions once
Provide credentials when asked
Make decisions agents can't make alone
Review PRs and approve what ships
✗ Agents handle
Writing and committing code
Running tests and debugging
Creating pull requests
Updating BOARD.md and logs
Coordinating between themselves
2
Approvals per feature set
~20
Minutes of your active time
3×
Faster than sequential dev
0
Lines of code you write
Before anything — one-time credentials
API keys: what you need and where to get them
Agents are real AI processes. They need API keys. Get these once, set them once — every future project inherits them automatically.
🤖
Anthropic API Key
Powers Claude Code — the engine behind every agent in this system.
2. Add to your shell (add to ~/.zshrc or ~/.bashrc):
$export ANTHROPIC_API_KEY=sk-ant-your-key-here
Or use OAuth — run claude and it walks you through browser login. No key file needed.
⚡
OpenAI API Key — for Codex CLI
Required if using OpenAI Codex CLI as an operator or worker agent. Codex CLI is an AI coding agent — like Claude Code but from OpenAI. It runs inside your session manager (cmux/tmux), it doesn't replace it.
Optional
What is Codex CLI? OpenAI's terminal AI agent. It reads files, runs bash commands, edits code — the same things Claude Code does. You run it in a terminal pane just like claude. The session manager (cmux, tmux) is still what gives the operator eyes and control over Codex sessions — Codex itself has no session-level API.
3. Run it in a pane:codex — same as running claude. The cmux or tmux operator can then read-screen / send-keys into that pane to babysit it just like any Claude worker.
The mental model: Claude Code and Codex CLI are the AI agents (the brains). cmux and tmux are the session layer (the eyes and hands). You need both. The operator uses the session layer's API to monitor and control whichever AI is running in each pane.
Model choice — performance vs cost
Which model for operator vs workers
The operator orchestrates and reasons about the whole project — use the most capable model. Workers execute scoped tasks — balance quality and cost based on complexity.
⚡ Operator (conductor)
claude-fable-5
Best reasoning for orchestration — plan decomposition, drift detection, PR creation, unblocking agents, long context.
Best for operator
codex-5.6-sol
OpenAI Codex CLI model. Fast operator with strong terminal session control. Good if you prefer OpenAI or want to drive Claude workers from Codex.
Codex alternative
🛠 Workers (agents)
claude-sonnet-4-6
Default sweet spot. Fast, capable, cost-effective for most tasks — UI components, API routes, standard features.
Default worker
claude-opus-4-8
Deep reasoning for complex tasks — tricky architecture, security, hard debugging. Slower and costs more; worth it for hard problems.
Complex tasks
codex-5.6-tera
OpenAI's most powerful Codex model. Strong at code generation and testing. Use as a Codex worker in mixed-AI swarms.
Codex worker
Set model per session
# Operator — Fable for orchestration $claude --model claude-fable-5
# Worker — Opus 4.8 for a hard task $claude --model claude-opus-4-8
# Codex worker in a mixed swarm $codex --model codex-5.6-tera
Step 1 of 3 — Critical choice
Session manager: view-only vs full control
This is the most important setup decision. For the operator to truly babysit agents — read their screen, send input, answer permission prompts, restart stuck ones — the terminal app must expose a native CLI or API. Without it, the operator is blind and you have to monitor manually.
Without a control API: The operator can coordinate through .ay/ files but cannot see what agents are doing, cannot answer their permission prompts, and cannot restart a stuck agent. You'd have to babysit manually.
Zero-config visibility (always available): Claude Code writes a live session file for every running agent at ~/.claude/sessions/<pid>.json — session ID, working directory, status, start time. The operator can read these with zero setup, even before you pick a session manager. ↓ See below
✓ Full control — operator can read screen, send input, answer prompts
📟
cmux
Native macOS terminal. Full CLI + Unix socket API. cmux read-screen, cmux send, cmux send-key — sees every pane, answers permission prompts, spawns splits, color-codes status in sidebar.
Best — richest API
🔮
Codex app
Native macOS coding session manager. Has native OS-level access to terminal sessions — reads output, sends input, sees all running processes and their details. Works alongside Claude Code agents.
Native session control
⬛
tmux
Built-in CLI for session control. tmux capture-pane reads any pane. tmux send-keys types into any pane. Works over SSH. The operator calls these via Bash tool.
Full control
🖥️
iTerm2
AppleScript + Python scripting API. Operator can send keystrokes and read content. More limited than cmux/tmux. Best paired with tmux running inside it.
Partial control
○ View only — you watch manually, no programmatic operator control
🔷
VS Code terminals
No external terminal control API. You can see agents but the operator cannot read their screens or send them keystrokes. Manual babysitting only.
View only
🌊
Warp
No external control API currently. Good-looking terminal but the operator cannot programmatically interact with agent sessions inside it.
View only
🪟
Separate windows
One window per agent. Use Mission Control to see them all. No control API at all — fully manual. Fine for getting started, but you'll outgrow it fast.
Manual only
cmux — full operator control
What the operator can do via cmux CLI
# Spawn a new agent split automatically $cmux new-split right --workspace workspace:1 $cmux send --workspace workspace:1 --surface surface:3 "claude --model claude-opus-4-8" $cmux send-key --workspace workspace:1 --surface surface:3 "enter"
# Read an agent's screen (operator checks if it's working or stuck) $cmux read-screen --workspace workspace:1 --surface surface:3 --lines 20
# Answer a permission prompt (agent is waiting for approval) $cmux send --surface surface:3 "1"# "1" = Yes
# Color-code agent status in the sidebar $cmux workspace-action --action set-color --color Red --workspace workspace:2
cmux also exposes a Unix socket API at /tmp/cmux.sock for raw JSON control — the same API used by the cmux-agent-manager skill that ships with ay-framework.
Codex app — native macOS session control
Codex app — native session access
# Codex app has native OS-level access to terminal sessions # It can see all running processes, read their output, and send input # This makes it usable as a session layer — similar to cmux
# The operator running inside Codex can inspect any agent session: # - See what every claude process is doing right now # - Read their screen output natively (no tmux needed) # - Send keystrokes to answer permission prompts
# Combine with .claude/sessions/ for full fleet visibility: $ls ~/.claude/sessions/ # list every running claude $cat ~/.claude/sessions/12345.json # read that agent's status + cwd
Codex app + .claude/sessions/ gives the operator both visual terminal control AND Claude-native session metadata for every running agent — no extra tooling needed.
tmux — scriptable session control
What the operator can do via tmux CLI
# Start a named session and split into panes $tmux new-session -s myproject -d $tmux split-window -h -t myproject # add worker pane
# Read any pane's output (operator checks what agent is doing) $tmux capture-pane -t myproject:0.1 -p -S -100
# Send a message to an agent (e.g. answer permission prompt) $tmux send-keys -t myproject:0.1 "1" Enter
# Detach and reattach later (agents keep running) $tmux detach # Ctrl+B D $tmux attach -t myproject
tmux works over SSH — run agents on a remote server, detach, come back later. The operator reads pane output using capture-pane via Bash tool.
iTerm2 — AppleScript control (limited)
# Send a keystroke to a specific iTerm2 session via osascript $osascript -e 'tell app "iTerm2" to tell current window to tell current session to write text "1"'
# Reading content requires the Python scripting API — more complex # Tip: use tmux INSIDE iTerm2 for full control via tmux CLI
iTerm2 scripting works but is complex to target specific panes. Running tmux inside iTerm2 gives you the best of both — iTerm2's visuals + tmux's CLI control API.
VS Code — view only
There is no external API to read VS Code terminal output or send keystrokes programmatically. You can watch agents work but the operator cannot babysit them. Run tmux inside VS Code's terminal to get full scripting control.
Warp — view only
Warp currently has no external terminal control API. Great for human use but the operator cannot read agent screens or send them input. Use tmux inside Warp for scripting control.
Separate windows — manual only
No control API. You manually check each window. Fine to get started and understand how the system works — but once you run 4+ agents, you'll want cmux or tmux so the operator can monitor and babysit autonomously.
Recommendation: Use cmux or Codex app on macOS — purpose-built for this. Use tmux on Linux/SSH. Both work out of the box with ay-framework's operator templates.
Always available — no setup required
Reading ~/.claude/sessions/
Claude Code writes a live JSON file for every running claude process on your machine. The operator reads these to know exactly which agents are active, what directory they're in, and their current status — without any terminal manager at all.
~/.claude/sessions/ — native Claude agent registry
# List every running claude process on this machine $ls ~/.claude/sessions/ 12345.json 12788.json 13001.json 13042.json
# See ALL agents — status + working directory in one shot $for f in ~/.claude/sessions/*.json; do jq -r '"PID \(.pid): \(.cwd) [\(.status)]"' "$f" done PID 12345: /Users/walid/project/frontend [active] PID 12788: /Users/walid/project/api [active] PID 13001: /Users/walid/project/auth [idle] PID 13042: /Users/walid/project/tests [ended]
The operator runs this as a fleet-scan — reads all session files, matches PIDs to their terminal panes (via cmux/tmux), and gets a full picture of the swarm without asking any agent. Stale files (no running process for that PID) signal a crashed or finished agent.
The full stack:.claude/sessions/ tells you who is running and where. cmux/tmux tells you what their screen shows right now and lets you send them input. Use both together.
Step 2 of 3 — One-time setup
MCPs so agents can test their own work
Without MCPs, agents write code and hand it to you to test. With MCPs they open a browser, fill forms, call APIs, and verify DB state — fully autonomous.
❌ Without MCPs
Agent: "I built the login page, please test it."
You: open browser → test → find bug → tell agent → wait → repeat.
Your time: involved in every iteration.
✓ With MCPs
Agent builds login → opens Playwright browser → fills form → confirms redirect → queries DB for session → marks done with test evidence.
Your time: review a one-page report.
Takes ~15 minutes. Do it once. Every agent in every future project gets browser control, API testing, and DB verification automatically. → MCP Setup Guide
Step 3 of 3
Your first conversation
Open Claude (or Codex) in your project folder. Two messages from you — then step away.
You
Build me a project management tool — tasks, assignments, due dates, Slack notifications.
Operator
Got it. Before spawning agents, I need your answers upfront. Answer now — nothing blocks later.
You
Next.js 14, Supabase, TypeScript, Supabase Auth. Vercel.
Operator
Written to DECISIONS.md — no agent will ever ask you these again.
Creating 19 tasks across 4 agents. Spawning now. One thing needs you: Supabase URL + anon key → drop in .env.local. Starting the 12 tasks that don't need credentials while you grab those.
That's the entire conversation. Two messages from you. The operator writes DECISIONS.md, spawns agents, unblocks on credential issues, monitors for drift — all without you.
Track your progress
Setup checklist — do this once per machine
Get your Anthropic API key — console.anthropic.com → API Keys, or log in via claude OAuth