cezar ⚡

Parallel coding agents orchestrator — a local cockpit for running and tracking AI coding-agent tasks in your repo.

Type a task, pick a workflow and an agent — Claude Code, Codex or OpenCode, or a mix of them per step — and watch it work live: steps, tool calls, tokens, diffs, in a browser cockpit that runs entirely on your machine. Your CLI logins, your gh, your files. No accounts, no database, no cloud.

A look inside · What it solves · Who it's for · Quick start · How it works · Core concepts · Cockpit tour · Agent backends

cd your-repo
npx cezar-cli        # → cockpit at http://localhost:4321

That's the whole setup. If your claude CLI is logged in (Pro/Max) and gh is authenticated, there is nothing else to configure. State lives in .ai/cezar/ inside your repo — plain JSON, NDJSON and Markdown you can cat and fix by hand.

A look inside

Click any thumbnail for the full-size screenshot.

| Watch a run live | The review gate | Parallel variants | |:--:|:--:|:--:| | | | | | Every step, tool call, token and screenshot — streamed as it happens. | Nothing auto-merges: inspect the diff, send notes into the same session, or push a draft PR. | Run a task ×2/×3 in isolated worktrees, compare the diffs, keep one. | | Plan before you run | Workflow builder | GitHub, one click away | | | | | | Press Plan first and review the proposed chain — trim, reorder, then start. | Stitch skills and shell checks into a reusable YAML chain, no code. | Open issues and PRs via your gh — run the agent straight on an issue. |

What it solves

Most "AI coding agent" tooling makes you choose between a terminal you can't see into once it's running, and a cloud product that wants your API key, your code on their servers, and an account. cezar is the third option: the agent runs locally under your subscription, and a cockpit shows you exactly what it's doing.

• No visibility into a running agent. A headless claude run is a black box until it finishes. cezar streams every step — agent text, each tool call and its result, tokens and cost per step — live, and keeps the full replay.
• One agent, one working tree, one thing at a time. Kick off a second task and it fights the first over your files. cezar runs each task in its own git worktree, so two (or three) agents work in parallel without stepping on each other — or on the branch you're editing.
• The agent finishes and you have to trust it. cezar ends non-trivial runs at a review gate: inspect the diff, send notes back into the same session, or push a draft PR — never an auto-merge.
• Losing a session when it fails. Every run records its claude session id. Take it over interactively in one click (claude --resume <id>), or continue it in-process from the cockpit.
• Locked into one agent vendor. Most tools wed you to a single CLI. cezar drives Claude Code, Codex and OpenCode through one runner seam — set a default, pick a backend per task, or mix them inside one workflow (implement with one agent, review with another). See Agent backends.
• Setup tax. No wizard, no env vars, no schema. Skills are Markdown, workflows are short YAML, and everything degrades: no gh → works without PRs, no network → local skills still load, no .ai/skills → the bare prompt still runs.

Who it's for

• Solo devs and small teams who want the leverage of coding agents without handing their code and keys to a SaaS — the agent runs on your subscription, on your machine.
• claude CLI power users who love headless runs but want to see them, compare a few attempts side by side, and review a diff before it lands.
• Anyone with a backlog who'd rather queue three tasks into isolated worktrees and pick the winners than babysit one terminal.
• Teams with shared conventions who want their playbooks (skills) pulled from a git repo, applied consistently, with zero per-project setup.

Quick start

Prerequisites: Node 20+, at least one logged-in agent CLI — the claude CLI (Pro/Max subscription), the codex CLI, or OpenCode — and, optionally, git and the gh CLI.

cd your-repo
npx cezar-cli              # start the cockpit for the current repo
#   or: npx @pat-lewczuk/cezar

The cockpit opens at http://localhost:4321 (auto-picks the next free port if busy). Type a task, pick a workflow, hit Start. That's it.

npx cezar-cli run "add a --json flag to the export command"   # headless, CI-friendly
npx cezar-cli init                                            # scaffold .ai/cezar/

Both the cezar and cez commands are installed, so once it's on your PATH you can run either. No API key is ever used — cezar shells out to whichever agent CLIs you are already logged into, claude by default.

Just kicking the tires? Set CEZ_DRY_RUN=1 to run against a bundled mock instead of the real CLI — the whole cockpit works with no claude login, so you can explore runs, diffs, variants and the review gate offline.

How it works

You describe a task. cezar runs it as a workflow — an ordered list of agent steps and shell checks — shelling out to your locally installed agent CLI (Claude Code by default; Codex and OpenCode are drop-in alternatives, per task or per step). Each task gets its own git worktree; the cockpit streams every event live and parks the run at a review gate when there's a diff to inspect.

   you type a task
        │
        ▼
   ┌─────────────┐   optional: Plan → AI drafts a chain of steps you approve
   │  workflow   │   (agent steps + shell checks, with bounded onFail retries)
   └─────────────┘
        │
        ▼
   ┌──────────────────────────────┐     ┌───────────────────────────────┐
   │  git worktree per task       │     │  agent CLI  (your login)      │
   │  (isolated branch, parallel) │◄───►│  claude · codex · opencode    │
   └──────────────────────────────┘     │  default-deny · acceptEdits   │
        │                                 └───────────────────────────────┘
        │  agent text · tool calls · tool results · tokens · cost
        ▼
   ┌─────────────┐   SSE (replay + live)   ┌──────────────────────────┐
   │ .ai/cezar/  │ ──────────────────────► │  cockpit  localhost:4321 │
   │ JSON·NDJSON │                         │  Tasks · Git · GitHub ·  │
   │ ·Markdown   │                         │  Skills · Workflows      │
   └─────────────┘                         └──────────────────────────┘
                                                  │
                                          review gate: read the diff →
                                          send notes back · draft PR · finish

When a check fails, the workflow can loop back to an earlier step (bounded by max) with the failing output appended to the retried agent's prompt. Nothing auto-merges: a run with changes rests in review until you act on it.

Core concepts

Three words, no jargon — task, skill, chain:

• Tasks are the unit of work. Every task is a run: queued → running → review / done / failed / cancelled, with a live event log, per-step token and cost usage, cancel/delete, and — for anything with a diff — a review gate. Paste screenshots into the task, or send follow-up messages into the live session while it works.
• Skills are Markdown playbooks. Drop them in .ai/skills/ or .ai/cezar/skills/, or pull them from a shared team skills repo (a bare git clone cached globally in ~/.cache/cez/). A workflow step references one by skill: <name> and its body becomes the agent's extra system prompt — so you shape how the agent reasons without touching code.
• Chains (workflows) stitch steps into a pipeline: agent steps plus shell checks, with bounded onFail retry loops. Write the YAML yourself, build one by drag-ordering skills in the Workflows tab, or press Plan first and let the AI draft a chain for your task that you review, trim and start. The built-in quick-task (one agent step) works with zero setup.

Two moves that make the cockpit worth the browser tab:

• Parallel variants (×2 / ×3). Run the same task as competing agents in separate worktrees, then compare their diffs side by side and pick one — the losers are archived and their worktrees cleaned up.
• Review gate. A finished run with changes waits in review. Read the diff, type notes that go straight back into the agent's session, or push a gh pr create --draft. You stay the merge button.

Cockpit tour

Seven views, one browser window, all live over Server-Sent Events:

| View | What's in it | |---|---| | Tasks | Every task with its status, live event stream (agent text · tool calls · tool results · pasted/generated screenshots), tokens and cost. Continue, cancel, open in terminal (claude --resume), review the diff, or push a draft PR. | | Inbox | Follow-ups an agent left behind (todos.json) — one click turns a suggestion into the next task, pre-wired to its suggested skill. | | Git | Branch, working-tree status, diff vs HEAD, recent commits (click one for its inline patch + GitHub link), and the configurable base branch that worktrees fork from and PRs target. | | GitHub | Open issues and PRs of the repo's origin, read through your logged-in gh. Hand an issue straight to the agent — pick a workflow and skills, one click runs it. | | Skills | Local skills plus the team skills repo, with a rendered body + prompt preview. Refresh pulls the latest from the remote. | | Workflows | Build a chain by drag-ordering skills, save it as portable YAML, import/export, or delete. Built-ins always come back. | | Settings | Appearance (dark/light theme, accent, density), agent backends, notifications, and the skills catalog. |

The cockpit is a React app served pre-built from the package — npx cezar-cli still means no build step and no dev server on your machine — with a dark/light theme, a ⌘K command palette, and bookmarklets that launch a task straight from a GitHub page.

Workflow format

A workflow is a small YAML file in .ai/cezar/workflows/:

name: fix-and-verify
description: Implement the task, then verify; retry with failing output on red.
steps:
  - id: implement
    name: Implement
    prompt: "{{task}}"
    skill: project-conventions   # optional — from .ai/skills or .ai/cezar/skills
    # model: opus                # optional per-step model override
    # runner: codex              # optional per-step backend: claude · codex · opencode
    # allowedTools: [Read, Edit, Write, Grep, Glob, Bash]
  - id: verify
    name: Verify
    command: "npm test"          # a check step: exit 0 passes
    onFail:
      retry: implement           # loop back to an earlier step…
      max: 2                     # …at most twice

{{task}} is replaced with the task text you typed. When a check fails and loops back, its failing output is appended to the retried agent's prompt so the next attempt can see what broke.

Prefer skills over steps? A workflow can also be written in the portable shorthand — an ordered list of skill names, each becoming one agent step:

name: triage-and-fix
skills: [reproduce, root-cause, implement, self-review]

How it runs agents

cezar shells out to your locally installed, logged-in agent CLI — your subscription, no API key. With the default Claude Code backend that means headless stream-json mode, tool access default-deny via --allowedTools, and edits auto-accepted (--permission-mode acceptEdits) inside the task's worktree. Codex and OpenCode are driven through their own native protocols — see Coding agent backends. Nothing runs on a server you don't own.

Useful environment variables:

| Var | Effect | |---|---| | CEZ_DRY_RUN=1 | Use the bundled mock instead of the real claude CLI — the entire cockpit works offline, for demos and development. | | CEZ_CLAUDE_BIN=/path/to/claude | Override which claude binary is used. | | CEZ_CODEX_BIN=/path/to/codex | Override which codex binary is used. | | CEZ_OPENCODE_BIN=/path/to/opencode | Override which opencode binary is used. | | GITHUB_TOKEN | Fallback for GitHub reads/PRs when gh isn't authenticated. |

Coding agent backends

cezar is not married to one vendor. Every agent step runs through a single AgentRunner seam with three built-in backends:

| Backend | CLI | How cezar drives it | |---|---|---| | Claude Code (default) | claude | Headless stream-json mode. | | Codex | codex | codex app-server — JSON-RPC over stdio, the same transport the Codex IDE extensions use. | | OpenCode | opencode | opencode serve — a local HTTP server with an SSE event stream. |

On startup cezar probes which CLIs are installed and the cockpit only offers the backends it found — install any one of the three and you're operational.

Pick a backend at three levels (most specific wins):

1. Config default — "defaultRunner": "codex" in .ai/cezar/config.json.
2. Per task — the backend picker next to the task box in the cockpit.
3. Per workflow step — runner: on any step in the YAML.

Per-step overrides are what make mixed-agent strategies a one-liner: implement with one agent, review with another, and let a shell check referee:

name: implement-and-cross-review
steps:
  - id: implement
    name: Implement
    prompt: "{{task}}"
    runner: codex                # one vendor writes the code…
  - id: review
    name: Cross-review
    prompt: "Review the diff produced for: {{task}}. Fix real issues only."
    runner: claude               # …another one reviews it
  - id: verify
    name: Verify
    command: "npm test"
    onFail: { retry: implement, max: 2 }

Parallel variants (×2/×3) of one task share that task's backend — mixing happens per task and per step, not inside a variant group.

The seam is deliberately small: a backend is one class implementing the AgentRunner interface (src/core/agent-runner.ts) that turns a prompt into a stream of normalized events. Other CLIs — pi, aider, whatever ships next — can slot in the same way.

Configuration (optional)

Zero config is the default — everything below is opt-in via .ai/cezar/config.json (a missing or invalid file simply uses the defaults, and never blocks startup):

{
  "skillsRepos": [{ "repo": "open-mercato/skills", "ref": "main" }], // team skills; [] disables
  "maxParallel": 2,          // how many tasks may run at once (non-git dirs always run 1)
  "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode"
  "plannerModel": "sonnet",  // model the "Plan first" button uses to draft chains
  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Git tab)
}

Run data (runs.json, NDJSON event logs, worktrees, todos.json) is git-ignored automatically; your workflows and skills stay committable.

Development

npm install
npm run dev          # server (API :4321) + Vite dev server, opens the cockpit in the browser
npm run dev:server   # tsx src/index.ts — the API server alone
npm run dev:web      # Vite dev server alone (proxies /api to :4321)
npm run build        # tsc → dist/, vite build → web/dist/, then the pack gate
npm run typecheck    # server + web (tsc --noEmit)
npm test             # vitest — server + cockpit unit suites
npm run test:unit    # node:test — fast core-module tests
npm run test:package # pack/install and exercise the built CLI
npm run test:e2e     # real-browser cockpit suite (agent-browser)

The stack is deliberately small: TypeScript (strict, ESM), Hono + SSE for the server, Zod at every boundary, YAML for workflows, and a React 19 + Vite + Tailwind v4 + shadcn/ui cockpit shipped pre-built in web/dist/ — the published package carries the built app, so npx users never run a bundler. Every module is meant to be read in one sitting.

Relationship to cezar (the SaaS)

cez is the radically-simple, single-user sibling of cezar — the team SaaS cockpit for running agents across the whole GitHub issue lifecycle (auto-triage, webhooks, Supabase, multi-repo). Same core ideas — agent runner, skills, declarative workflows, a live run cockpit — with none of the accounts, database or cloud. Start here; graduate to cezar when a team needs shared visibility.

License

MIT © Patryk Lewczuk