cezar - Moses Yebei

Abstract

Open-source orchestrator and ADE for running Claude Code, Codex, OpenCode, Pi and other AI coding agents in parallel — locally or 24/7 on your own server.

The Problem

Teams that rely on several AI‑coding assistants (Claude Code, Codex, OpenCode, Pi, etc.) often face a fragmented workflow. Each agent runs in its own process, stores state in disparate files, and requires manual orchestration to coordinate multi‑step tasks, schedule runs, or compare variants. Repeatedly starting and stopping agents, managing worktrees, and tracking cost become tedious.

What This Does

cezar centralises those agents in a single control plane.

Parallel execution – every task spawns a new git worktree under .ai/cezar/ and runs each agent step in isolation.
Unified UI – a lightweight web UI (served from packages/cezar/src/server/forge/index.ts) shows live tool calls, token usage, and cost per project.
Automation – the CLI (packages/cezar/src/self-update/cli.ts) and server expose REST endpoints for scheduling, cancelling, or re‑running tasks.
Skills & workflows – skills are Markdown files; workflows are short YAML files that mix agents per step. The orchestrator parses those files and dispatches the agents accordingly.

How It Is Wired

Entry Point – packages/cezar/src/server/server.ts.

server.ts imports forge/index.ts to initialise the Express router, then calls startServer() which binds all REST routes defined in forge/handlers/*.ts.
Each handler (e.g., runHandler) calls runTask() from packages/cezar/src/runs/task.ts.
runTask() creates a git worktree (packages/cezar/src/git/worktree.ts) under .ai/cezar/<task-id>, then iterates over the workflow YAML.
For each step it resolves the skill file (packages/cezar/src/skills/loader.ts), creates an agent instance (packages/cezar/src/agents/agentFactory.ts) and invokes agent.executeStep().
agent.executeStep() performs a tool call, writes the step output to the worktree, and logs cost via packages/cezar/src/metrics/logger.ts.
When all steps finish, task.ts writes a final report to .ai/cezar/<task-id>/report.json and emits a websocket event to the UI.

Files with system‑wide effects

server.ts touches the network (listens on port 3000).
worktree.ts writes to the filesystem under .ai/cezar.
logger.ts records cost to .ai/cezar/usage.json.

The call graph is linear within each task: server -> handler -> runTask -> agentFactory -> agent.executeStep. The only cross‑module dependencies are the shared metrics and git utilities, making the core logic easy to audit.

How To Use It

Setup

git clone https://github.com/moses-y/cezar
cd cezar
npm install          # or pnpm i

The top‑level package.json contains the start script.

Configuration

cp .env.example .env
# edit .env – set PORT, WORKSPACE_DIR, and any agent‑specific credentials

Agent credentials are passed via environment variables (e.g., CLAUDE_API_KEY, OPENAI_API_KEY).

Running

npm run start
# or directly
node packages/cezar/src/server/server.ts

The web UI appears at http://localhost:3000. To launch a task from the CLI:

npx cezar run workflow.yaml

(see alias-cezar-run/package.json for the cezar binary).

Real‑World Use

A data‑engineering team can create a workflow that pulls fresh data, runs a Codex script to generate a summary, then passes the output to a Claude Code agent that writes a new notebook. All steps run automatically, and the UI shows token usage per step, allowing the team to optimise cost.

Code Health & Issues

Low / Security – Secret‑shaped paths – packages/cezar/src/runs/run-secrets.test.ts flags hard‑coded credential patterns.
Coverage – 812 test files cover most core modules, but some agent‑specific adapters lack tests.
CI – GitHub Actions workflow (.github/workflows/ci.yml) runs tests and lints on every push.
Missing docs – While docs/reference.md covers APIs, deployment guides for Docker are absent.

The Bottom Line

cezar offers a pragmatic, file‑based orchestration layer for multiple AI coding agents, with a clear API surface and a lightweight UI. Its linear call graph and minimal third‑party dependencies make it straightforward to audit and extend. Teams that already run agents locally and need a unified scheduler will find it useful, though they should review the hard‑coded secret checks and add missing Docker deployment scripts before production use.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,915 files

TypeScript748
Markdown379
TSX357
JSON57
HTML50
YAML7

React

Module dependencies

The 10 most depended-upon modules of 1,127, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_ackages_cezar_src_runs_store["store"] n1_ages_cezar_src_workflows_run["run"] n2_ages_cezar_src_server_server["server"] n3_ver_loopback_request_testkit["loopback-request.testkit"] n4__cezar_src_core_agent_runner["agent-runner"] n5_ckages_web_e2e_agent_browser["agent-browser"] n6_es_cezar_src_workflows_types["types"] n7_packages_cezar_src_paths["paths"] n8_s_cezar_src_workspace_config["config"] n9_ges_cezar_src_core_ui_events["ui-events"] n4__cezar_src_core_agent_runner --> n9_ges_cezar_src_core_ui_events n0_ackages_cezar_src_runs_store --> n6_es_cezar_src_workflows_types n0_ackages_cezar_src_runs_store --> n4__cezar_src_core_agent_runner n2_ages_cezar_src_server_server --> n4__cezar_src_core_agent_runner n2_ages_cezar_src_server_server --> n6_es_cezar_src_workflows_types n2_ages_cezar_src_server_server --> n0_ackages_cezar_src_runs_store n2_ages_cezar_src_server_server --> n1_ages_cezar_src_workflows_run n2_ages_cezar_src_server_server --> n8_s_cezar_src_workspace_config n2_ages_cezar_src_server_server --> n7_packages_cezar_src_paths n1_ages_cezar_src_workflows_run --> n4__cezar_src_core_agent_runner n1_ages_cezar_src_workflows_run --> n0_ackages_cezar_src_runs_store n1_ages_cezar_src_workflows_run --> n9_ges_cezar_src_core_ui_events n1_ages_cezar_src_workflows_run --> n6_es_cezar_src_workflows_types n6_es_cezar_src_workflows_types --> n4__cezar_src_core_agent_runner n8_s_cezar_src_workspace_config --> n7_packages_cezar_src_paths

Dependencies

4 declared dependencies, none a major version behind. Resolved 4 of 4 against the registry.

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them packages/cezar/src/runs/run-secrets.test.ts

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium3

low1

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release.yml

git push origin "$BRANCH"

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Enable Dependabot or Renovatemedium

9 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.