Cezar

Nightly builds — help us shape cezar 🌙

Every night we publish the trunk to npm, so the features landing in the next release are one command away:

npx cezar-cli@nightly      # everything merged as of last night

Come build this with us. cezar is shaped by the people who run it on real repos: if you try a nightly and something feels wrong — a workflow that stalls, a diff that reads badly, a runner that should exist — open an issue and tell us. That feedback, early, is worth more than a bug report six weeks after a release, and it is how most of the features here got their final shape.

Know what you're installing. A nightly is verified (typecheck, unit suites, packaged-CLI e2e — the same gate a release runs) but it is not a release: it can be rough, a flag or a screen may change under you, and something occasionally breaks in a way no test caught. Nothing is at risk beyond your patience — every task runs in its own git worktree and cezar never auto-merges — but if you need a boring day, stay on the stable release. Pin a nightly you liked with its exact version (npx cezar-cli@0.9.2-nightly.20260813.126 — the cockpit prints the version it booted, and the date in it tells you how old the build is), and drop back to stable any time with a plain npx cezar-cli.

Preview builds

Every green CI run also publishes an installable npm snapshot (how it works), so you can try code that has not even merged yet:

npx cezar-cli@develop      # current develop head

Every pull request gets its own preview too — the CI bot posts a sticky comment on the PR with the exact pinned version to copy-paste (npx cezar-cli@<version>-pr<N>.<run>). Nightlies and previews are all prerelease versions under their own dist-tags; a plain npx cezar-cli always resolves to the latest stable release.

---

or: npm run install-as-command:global # self-contained snapshot copy

Now `cd` into any other repo and run it:

**5. The change loop**

- **Link mode** (default): edit source → `npm run build` → the global command
  reflects it immediately. No relink needed. (It is a live symlink into this
  checkout — don't move or delete the checkout while it's linked.)
- **Snapshot mode** (`:global`): re-run `npm run install-as-command:global` to
  refresh the installed copy. It survives moving/deleting the checkout.

**6. Uninstall**

7. Troubleshooting

- cezar: command not found after install → your npm global bin dir isn't on PATH. The script prints the exact dir; add it to your shell profile (export PATH="$(npm prefix -g)/bin:$PATH"). - EACCES / permission denied → your global prefix is root-owned. Point npm at a user-writable one and retry — never sudo: npm config set prefix ~/.npm-global. - Already installed the published @open-mercato/cezar globally? The link/snapshot install replaces it; uninstall-as-command removes ours, and npm i -g @open-mercato/cezar brings the published one back.

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.

```bash cd your-repo npx cezar-cli # start the cockpit for the current repo

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
  // Team-skill repos are code-trusted: a skill body becomes an agent system prompt.
  // Only owner/name, https/ssh URLs, or local paths (`/abs`, `./rel`, `~/dir`,
  // `C:\dir`) are accepted — no ext::/fd:: transport helpers. Write a relative
  // path as `./name`, not a bare `name`. Pin `ref` to a full commit SHA to freeze
  // the source against a moving branch head — cezar verifies it resolves to
  // exactly that commit, and reports it as `team.commit`.
  "worktreeRetention": 10,   // keep the last N finished worktrees on disk; 0 = unlimited (branch always kept)
  "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode" · "pi"
  "modelsLocked": true,      // optional: native per-runner model is fixed/read-only; runner stays selectable
  "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)
}

Put the same "modelsLocked": true key in ~/.cezar/config.json to apply it to every registered project. When the key is absent or false in both config files (and CEZ_AGENT_MODELS_LOCKED is not 1), each runner's normal model selector uses that runner's discovered model list. While locked, the model is shown read-only and follows the selected runner's native settings; the runner itself remains selectable.

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

Settings that belong to you rather than to a repo — the parallel cap (maxParallel, default 2), the per-task memory ceiling and the checkout root — live once in ~/.cezar/config.json, alongside the project registry, and are edited from Settings → Resources and Settings → Projects. A maxParallel left over in a repo's .ai/cezar/config.json is imported into the workspace file the first time cezar boots there, and ignored afterwards.

Editing the agents' own config (Settings → Agent config)

cezar picks which agent runs; Settings → Agent config lets you edit how it behaves — the raw config files Claude, Codex and OpenCode read for settings, MCP, and memory. In the multi-project cockpit the section is project-scoped: repo-relative files resolve from the selected project's root, while user-scope files continue to resolve from the agent's home.

Each file keeps its native format and vendor-documented precedence. Tracked files reach task worktrees after commit; Claude's gitignored personal layer is seeded into each run's worktree. Editing is a local-machine capability, so a hosted cockpit (CEZ_REMOTE=1) is read-only and never serves home-file contents.

---

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 · pi
    # 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]

---

Troubleshooting: the agent's shell returns nothing

Symptom. A task on the Claude backend keeps working, but every shell command comes back with no output and a spurious non-zero exit status — echo hello included. Redirecting into a file inside the worktree still produces the right content, so the commands genuinely run; only the capture is lost. Codex tasks on the same machine are unaffected, because that backend streams over stdio pipes instead of round-tripping a command's output through a temp file.

Diagnosis. The temp directory the agent was given is out of space or out of quota. One line tells you:

echo probe > "${TMPDIR:-/tmp}/probe"   # "Disk quota exceeded" / "No space left on device"
df -i "${TMPDIR:-/tmp}"                # a tmpfs can exhaust inodes long before bytes

Under quota the file is created and the write then fails, so the backend reads back a zero-byte capture file and hands the agent an empty result.

Fix. Since #785 cezar gives each task its own TMPDIR under .ai/cezar/tmp/<task-id> and write-probes it before spawning, so a broken temp directory fails the task with agent temp directory is not writable: … on the task thread instead of corrupting its work. If you see that error, free space on the disk holding the repo. CEZ_AGENT_TMPDIR=0 turns the whole mechanism off — per-task directory and pre-spawn check alike — and hands agents the host TMPDIR again, which is the way out if the check itself is wrong on your platform.

---