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 drag away
Press Plan 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 │                         │  Runs · Repo · 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 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

Six tabs, one browser window, all live over Server-Sent Events:

The whole GUI is dependency-free vanilla JS with no build step, a dark/light
theme toggle, 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:

Coding agent backends

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

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 button uses to draft chains
  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Repo 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          # tsx src/index.ts — the cockpit, live-reloaded
npm run build        # tsc → dist/
npm run typecheck    # tsc --noEmit

The stack is deliberately small: TypeScript (strict, ESM), Hono + SSE for
the server, Zod at every boundary, YAML for workflows, and vanilla JS
for the GUI (no framework, no 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