AGENTS.md — working in this repository

cezar is a parallel coding-agents orchestrator: a local cockpit (CLI + browser GUI) for running and tracking AI coding-agent tasks in a repo. You type a task, pick a workflow and a backend — Claude Code, Codex or OpenCode (experimental), or a mix per step — and watch it work live: steps, tool calls, tokens, diffs. Each task runs in its own git worktree, ends at a review gate (never auto-merges), and can be pushed as a draft PR through gh. Everything is local: no accounts, no database, no cloud — state is plain JSON, NDJSON and Markdown under .ai/cezar/. The server stack stays deliberately small: strict TypeScript (ESM, Node 20+), Hono + SSE, Zod at every boundary, and YAML workflows. The cockpit is React 19 + Vite + Tailwind v4 + shadcn/ui, compiled to static assets (the legacy vanilla UI was retired in R7). Every module is meant to be read in one sitting.

Zero config

cezar ships no config file the user must create and no setting they must set before it works. Every capability is discovered from what is already there — the repo, the environment, gh, the running processes — or it degrades quietly to a smaller cezar. .ai/cezar/config.json is optional and every key has a working default; A repository .env is never auto-loaded. Tracker credentials use managed encrypted per-project records in cezarHomeDir()/tracker-connections/, written by Settings and decrypted only into the project connection object, never into process.env or agent environments.

New state may be written, never required: .ai/cezar/, ~/.cache/cez/, ~/.cezar/. Delete any of them and cezar rebuilds what it needs on the next run. State that a user must author, migrate, or repair is not state — it is configuration, and it needs a reason. One deliberate exception inside that rule: the project registry keeps a ~/.cezar/config.json.bak snapshot, so deleting config.json alone restores instead of resetting — delete the ~/.cezar directory for a true reset.

Practical rules:

• When a feature seems to need configuration, the design is wrong. Discover it, or default it.
• Features that widen exposure or cost (network, other processes) are opt-in behind a CEZ_* flag, off by default — the zero-config default is also the safe default.
• Owner-approved exception (2026-09-12): task dispatch (cez task create, spec .ai/specs/2026-09-10-dispatch.md) is default-on; CEZ_DISPATCH=0 turns it off. Its brakes live in the engine — four children in flight, a child's budget carved out of its parent's — and with dispatch off the agent fanned out through its own sub-agents instead, unbudgeted and invisible (live run 3f7eaf02, 4.3M tokens).
• Owner-approved exception (2026-09-14): automations (spec .ai/specs/2026-09-14-automations-redesign.md) are default-on; CEZ_AUTOMATIONS=0 turns them off. The default does nothing on its own — the timer arms only for an automation the user ENABLED, and a poll left enabled from the #801 opt-in days is re-baselined at boot when it has been idle longer than its own lookback, so the flip can never launch a backlog.
• Owner-approved exception: Open Mercato skill updates are default-on. They start only after the server listens, run at most once per six-hour cache window, use explicit lock-authorized names and fixed bounded npx argument arrays under a cross-process lock, and never block boot. CEZ_SKILLS_AUTO_UPDATE=0 or the global Settings override disables automatic application (background detection remains read-only).
• Telemetry is opt-in (docs/telemetry.md): nothing — not even a ping — leaves the machine until the user answers yes in the cockpit's consent bar, Settings → Privacy or cezar telemetry enable; the answer lives in ~/.cezar/config.json (telemetry), and bumping TELEMETRY_POLICY_VERSION asks again. CEZ_TELEMETRY=0/DO_NOT_TRACK=1 block it even after a yes; no env var can grant it. Never make it default-on, and never send before consent. It never sends prompts, paths, repo or project names — routes go out as shapes, labels are closed sets the server enforces. All of it lives in packages/cezar/src/telemetry.ts and packages/web/src/lib/telemetry.ts, plus the desktop shell's error reports in packages/desktop/src-tauri/src/telemetry.rs — the same answer and env blocks; without a yes its failure page offers a Send error report button, and that click is consent for that one report only (no install id).
• Pending owner ratification (2026-09-30): the star ask (GET /api/v1/star-count, the sidebar ⭐ chip, the star-ask dialog, the serve banner line) is default-on and fetches cezar's own star count from github.com; CEZ_NO_BANNER=1 — already the promo block's switch — turns all of it off, request included. It is listed here because a default-on network widening is exactly what the rule above asks to be a deliberate, recorded decision, and this one has not been ratified by the owner yet. The fetch is metadata about cezar's own repository, carries no identifier, happens at most once per six hours per machine (cached in ~/.cache/cez/star-count.json), and every failure is { available: false }. If the owner would rather it were opt-in, the change is one line in starAskSilenced.
• Pending owner ratification (2026-09-30): the star ask (GET /api/v1/star-count, the sidebar ⭐ chip, the star-ask dialog, the serve banner line) is default-on and fetches cezar's own star count from github.com; CEZ_NO_BANNER=1 — already the promo block's switch — turns all of it off, request included. It is listed here because a default-on network widening is exactly what the rule above asks to be a deliberate, recorded decision, and this one has not been ratified by the owner yet. The fetch is metadata about cezar's own repository, carries no identifier unless GITHUB_TOKEN/GH_TOKEN is set (then GitHub sees which account read it), happens at most once per fifteen minutes per machine, and only alongside the cockpit's other requests (no timer of its own) — slower when GitHub's rate-limit headers say the hourly budget cannot afford it (60/h unauthenticated, 5000/h with GITHUB_TOKEN/GH_TOKEN, which it sends when set) — cached in ~/.cache/cez/star-count.json, and every failure is { available: false }. If the owner would rather it were opt-in, the change is one line in starAskSilenced.
• Pending owner ratification (2026-10-11): the fork-parent lookup in git-remotes.ts (#1383) is default-on. When origin is on github.com or a GitHub Enterprise host (*.ghe.com, or one gh is signed in to — github-hosts.ts) and the repo has a second remote, cezar runs one gh api repos/<origin> call against that host, with the user's own gh auth, to learn whether that remote is origin's fork parent. It runs at most once per process, retries after 10 minutes if it got no answer, and never runs under CEZ_DRY_RUN=1. gh repo set-default skips it. Without it, a contributor's fork clone would fork tasks from and open PRs on the fork.
• Owner-approved exception (2026-10-17): Design Mode (spec .ai/specs/2026-10-09-design-mode.md, the task's Preview) is AVAILABLE by default on a LOCAL cockpit, but its toggle starts OFF every time the Preview opens — the user switches it on by clicking; CEZ_DESIGN_MODE=0 turns it off, and it is always off on a hosted one. Switching it on opens a second 127.0.0.1 listener that mirrors the previewed loopback http:// dev server with a picker script injected. It is loopback-only, mirrors only what already listens on loopback, opens only after an explicit click and closes when idle.
• Owner-approved exception (2026-10-22): HTML artifacts (spec .ai/specs/2026-10-22-html-artifacts-and-impact.md, O1) may load scripts and styles from a fixed CDN allowlist — cdnjs, jsDelivr, unpkg, plus Google Fonts — by default; CEZ_ARTIFACTS_CDN=0 drops every https: source. The page is still sandboxed to an opaque origin with connect-src 'none' and data:/blob:-only images, so the CDN seeing the request is the whole widening. The CSP lives in one helper, artifactCsp.
• A missing dependency, an absent peer, a read-only home: degrade to a smaller working cockpit, never fail the boot.
• Prefer a proxy-free, daemon-free mechanism when one exists — and when it doesn't, keep the mechanism invisible: no process to manage, no port to remember, no file to edit.
• Never trade a working default for a knob.
• Adding, renaming, or removing a CEZ_* env var — or changing what its default does — MUST update .env.example in the same commit (and the env table in docs/reference.md when the var is user-facing). .env.example is the env contract's single documentation surface; an undocumented env var is a bug.

Changing a mechanism that already works

Replacing working behavior is the highest-risk change in this repo, and it fails in a characteristic way: the new mechanism is correct, the tests are green, the spec is thorough — and the DEFAULT path quietly lost a guarantee nobody wrote down. #810 and #811 are the worked examples; both shipped a well-specified improvement that left the zero-config user worse off than before.

Name what the old mechanism was load-bearing FOR, not what it was for. Those are different questions. IDLE_TIMEOUT_MS read as session hygiene, and #661 removed it from the monitoring branch for a good reason (it was closing live sessions mid-CI and recording them as done). It was also the only liveness bound on CEZ:MONITORING and the only reason a parked monitor eventually stopped holding a maxParallel slot. Neither dependency was named in the spec, so neither was replaced, and monitoring became a state with no exit. Before deleting a timer, lock, cap or timeout, grep for everything that reaches a terminal state because of it.

A replacement that ships OFF is not a replacement. Diff the default path, not the feature. The question is always: with every new knob at its shipped default, what does the old scenario do now? If the answer is "nothing", the change removed a mechanism and added a setting. A spec's "Resolved assumptions" table answering a COST question with "opt-in, default null" is not an answer to whether the zero-config path still works — cost-safe and functional are separate reviews. See § Zero config: never trade a working default for a knob.

Enumerate the transitions out of every state you add or keep. "Who fires this?" is the question that finds these bugs in one step. A parked run has exactly three wake sources — a user message (deliverMessage), the autonomous nudge (turn-end only), and the monitoring wake timer. Cezar has no process-exit callback, no CI webhook and no sub-agent-completion event, so a state whose only on-by-default exit is "a human types something" is a dead end, however well it renders.

Find every construction site of a shared in-memory object — grep the TYPE, not the field. ActiveRun is built in execute AND in runContinuation; #811 populated state.skills in the first only, so registry /skill expansion worked on new tasks and silently failed on every Continue and every restart recovery. The same shape recurs in the two near-identical turn-end handlers in workflows/run.ts (streaming and non-streaming): a lifecycle change applied to one of them ships half a fix. When you add a field that a delivery path reads, add it everywhere in the same commit or route both sites through one helper.

A fail-open helper needs a populated-input guarantee, or it lies. expandRegistrySlashSkill returning its input unchanged on no-match is right on its own — a backend's own slash commands must survive. Against an empty registry that same branch turns "cezar never loaded the list" into a confident user-facing "Unknown skill". Pair every silent pass-through with a test that pins the empty/absent input case.

Prove the regression test fails without the fix. git stash push -- <source files>, run the new test, confirm red, git stash pop. A test written after the diagnosis passes against the bug more often than anyone expects, and a green-either-way test is how the same regression ships twice. Keep the guard tests that pass both ways — they pin the behavior you did NOT want to change (park mode stays reachable; unknown slashes stay untouched) — but know which is which.

Read the run-history evidence before theorizing, and cite it. .ai/specs/ records the design, git log -S and git merge-base --is-ancestor <commit> <tag> settle "was this in the release the user is on", and a user's "it worked in 0.9.1" is a testable claim, not an opinion. #810 was confirmed in one command before a line of code was read.

The HTTP API

Four invariants. A feature that breaks any of them compiles on its own branch and stops working when it lands — #694 arrived with eleven unreachable routes for exactly this reason.

• Every request and response shape is a zod schema in packages/contract, with its TypeScript type inferred from it (z.infer). Never hand-write an API type, and never declare one in server.ts or in the api-client. The api-client re-exports the contract; the cockpit imports the schema when it wants to validate and the type when it wants to compile.
• Register routes by CHAINING them into a family builder, the way the ~24 families in server.ts already do. Hono accumulates route types through the chain only: a loose app.get(…) statement returns a value nobody keeps, so the route vanishes from AppType and the typed client cannot see it — silently, with the server still serving it.
• Validate bodies, path params and the query string as route MIDDLEWARE, through the trio in src/server/validators.ts. Parsing inside a handler is invisible to hono, which is what let POST /runs accept { totalNonsense: 12345 } from a typed client without complaint.
• Everything answers under /api/v1 (project-scoped: /api/v1/p/:projectId/…). The unversioned surface is gone.

The contract must describe EXACTLY what the route sends — no wider, no narrower. When a schema and its route disagree, fix the SOURCE, never widen the schema; contract-parity*.test.ts asserts both directions and a one-way check passes on real drift. Two mismatches recur often enough to name: writing key: maybeUndefined types a key as always-present that JSON.stringify drops from the wire (spread it conditionally), and an object-literal type: 'x' widens to string during hono's inference, erasing a discriminant consumers narrow on (as const).

Repository layout

Four npm workspaces under a private root that publishes nothing itself:

Rules that follow from that:

• The CLI is not a separate package and should not become one. It is the same program as the service — packages/cezar/src/index.ts boots startServer, but also RunManager, the workspace registry and the worktree machinery, and cezar run executes a workflow with no server at all.
• A dependency belongs to the workspace that imports it. The root carries only what spans all four (typescript, vitest, tsx). A build script counts as an importer: scripts/inline-contract.mjs reaches for esbuild, so esbuild is a devDependency of packages/cezar rather than something inherited from whatever vite happens to hoist.
• Cross-package imports go through the package name, never a relative path — the exceptions are test-only reaches for golden fixtures, and they are ugly on purpose.
• The repo root keeps only what spans workspaces: scripts/dev.mjs (boots both halves) and scripts/release*.mts/release-snapshot.mjs (a release spans every package). Everything else lives in the package that owns it.

Task routing

For a new issue-tracker integration, read docs/adding-issue-tracker.md first. It maps the shared provider seam, registration points, UI metadata and verification requirements.

Comments

Keep them short. A code comment is one or two lines on WHY, never a retelling of WHAT the next lines do. Cite the spec or issue (spec 006, #348) instead of restating it — the reasoning lives there. An explanation that needs a paragraph belongs in the spec or the commit message, not above a function. The same goes for PR descriptions, review comments and CHANGELOG entries: lead with what changed, in a few lines.

Validation

Before any commit or PR, run in order:

npm run typecheck   # tsc --noEmit (api-client + server + web)
npm test            # vitest — server + cockpit unit suites
npm run test:unit   # node:test — fast core-module coverage (packages/cezar/test/unit/)
npm run build       # tsc → dist/, vite → packages/cezar/web/dist/, then the check:pack tarball gate
npm run test:package # pack/install the release tarball and exercise the built CLI (packages/cezar/test/e2e/)

npm test and npm run test:unit are the fast unit gate: no server, no browser. They must stay that way. npm run test:package needs a completed npm run build (it packs the tarball).

Opening a fix PR — any bug fix, telemetry fixes included — also needs a backport decision. Find the newest line (git branch -r --list 'origin/release/v*'); if the bug exists in that line's code (git merge-base --is-ancestor <introducing commit> origin/release/vX.Y.x, or just read the file there), label the PR backport release/vX.Y.x; otherwise say in the PR body why not. "The reported occurrence is already fixed on the line" is not a reason to skip when the code you are hardening is on it too. Rules: SDLC.md § Release lines and backports.

Run vitest through npm, never npx vitest. It is a devDependency of this repo, so npm test uses the installed, version-pinned binary; npx will happily reach past it and fetch a different version from the registry, which is a slow, networked, silently-different test run. To narrow a run, pass vitest's own arguments after --:

npm test -- packages/web/src/routes/settings   # one directory
npm test -- --testTimeout=30000 path/to/one.test.ts
npm test -- -t "the name of one test"

The UI smoke suite is a separate command — it boots the real app and drives it in a real Chrome through the agent-browser provider (.ai/browsers/agent-browser.md):

npm run test:e2e    # .ai/scripts/e2e.sh → test-env-up.sh + vitest (packages/web/e2e/)

It boots the app on a free port with CEZ_DRY_RUN=1 (agent CLIs mocked — no login, no network), reuses an already-healthy instance instead of double-booting, and writes .ai/qa/test-env.json so QA skills attach to the same instance. Stop it with .ai/scripts/test-env-down.sh. Exit contract:

CEZ_DRY_RUN=1 npm run dev still exercises the whole cockpit offline for manual verification.

Related documents

• AGENT_PROTOCOL.md — the agent protocol: the runner seam, the v1 AgentEvent + v2 UiEvent streams, per-backend mapping, the golden-fixture testing contract, and the checklist for adding a new runner.
• SDLC.md — ticket flow, label state machine, QA gate, claim protocol.
• CODE_REVIEW.md — what reviewers check and how severities are assigned.
• BACKWARD_COMPATIBILITY.md — the public surfaces you must not break silently.
• .ai/agentic.config.json — machine-readable pipeline config every om-* skill reads (base branch, validation commands, labels).