@pat-lewczuk/cezar 0.1.2 → 0.1.4

package/README.md

@@ -1,90 +1,294 @@
+<div align="center">
+
 # cezar ⚡
 
-Local cockpit for running and tracking AI agent tasks in your repo. Single
-user, zero config, one command:
+**A local cockpit for running and tracking AI coding-agent tasks in your repo.**
+
+Type a task, pick a workflow, watch the agent work live — steps, tool calls,
+tokens, diffs — in a browser cockpit that runs entirely on your machine.
+Your `claude` login, your `gh`, your files. No accounts, no database, no cloud.
+
+[What it solves](#what-it-solves) · [Who it's for](#who-its-for) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Core concepts](#core-concepts) · [Cockpit tour](#cockpit-tour)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
+![Node 20+](https://img.shields.io/badge/Node-20%2B-339933)
+![TypeScript 5.x](https://img.shields.io/badge/TypeScript-5.x-3178c6)
+![Zero config](https://img.shields.io/badge/config-zero-success)
+![No database](https://img.shields.io/badge/database-none-success)
+
+</div>
+
+---
 
 ```bash
 cd your-repo
-npx cezar
+npx cezar-cli        # → cockpit at http://localhost:4321
 ```
 
-That's it. If you have the `claude` CLI logged in (Pro/Max subscription) and
-`gh` authenticated, there is nothing to configure — cez opens a browser
-cockpit at `http://localhost:4321` where you type a task, pick a workflow and
-watch the agent work live (steps, tool calls, tokens), with a repo view
-(status / diff / log) right next to it.
+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.
+
+---
+
+## 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.
+- **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.
+
+---
 
-No accounts, no database, no cloud. State lives in `.ai/cezar/` inside your repo.
+## Quick start
 
-## What it does
+**Prerequisites:** Node 20+, the [`claude` CLI](https://github.com/anthropics/claude-code)
+logged in (Pro/Max subscription), and — optionally — `git` and the `gh` CLI.
 
-- **Runs** — every agent task is a run: queued → running → done/failed, with a
-  live event log (agent text, tool calls, tool results), token usage per step
-  and cancel/delete controls. Failed run? Take the session over interactively:
-  `claude --resume <session-id>` (shown in the run header).
-- **Workflows** — a YAML file: agent steps + shell checks, with bounded
-  retry loops (`onFail: retry`). The built-in `quick-task` workflow (one agent
-  step) works with zero setup.
-- **Skills** — Markdown files in `.ai/skills/` or `.ai/cezar/skills/`; a workflow
-  step references one via `skill: <name>` and its body becomes the agent's
-  extra system prompt.
-- **Repo view** — branch, working-tree status, diff vs HEAD, recent commits.
+```bash
+cd your-repo
+npx cezar-cli              # start the cockpit for the current repo
+#   or: npx @pat-lewczuk/cezar
+```
 
-## Commands
+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.
 
 ```bash
-npx cezar              # start the cockpit for the current repo
-npx cezar run "task"   # headless run in the terminal (CI-friendly)
-npx cezar init         # scaffold .ai/cezar/ with an example workflow + skill
+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 your logged-in
+`claude` CLI.
+
+> **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 `claude` CLI in headless
+stream-json mode. 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       │     │  claude CLI  (your login)     │
+   │  (isolated branch, parallel) │◄───►│  stream-json · default-deny   │
+   └──────────────────────────────┘     │  tools · acceptEdits in-repo  │
+        │                                 └───────────────────────────────┘
+        │  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:
+
+| Tab | What's in it |
+|---|---|
+| **Runs** | 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. |
+| **Repo** | 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`. Drag an issue onto the task box to prefill the prompt. |
+| **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. |
+
+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
 
-`.ai/cezar/workflows/fix-and-verify.yaml`:
+A workflow is a small YAML file in `.ai/cezar/workflows/`:
 
 ```yaml
 name: fix-and-verify
-description: Implement, then verify; retry with failing output on red.
+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 override
+    skill: project-conventions   # optional — from .ai/skills or .ai/cezar/skills
+    # model: opus                # optional per-step model override
     # allowedTools: [Read, Edit, Write, Grep, Glob, Bash]
   - id: verify
     name: Verify
-    command: "npm test"
+    command: "npm test"          # a check step: exit 0 passes
     onFail:
-      retry: implement           # loop back, at most:
-      max: 2
+      retry: implement           # loop back to an earlier step…
+      max: 2                     # …at most twice
 ```
 
-`{{task}}` is replaced with the task you typed. When a check fails and loops
-back, the failing output is appended to the retried agent's prompt.
+`{{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:
+
+```yaml
+name: triage-and-fix
+skills: [reproduce, root-cause, implement, self-review]
+```
+
+---
 
 ## How it runs agents
 
-cez shells out to your locally installed, logged-in `claude` CLI in headless
-stream-json mode — your subscription, no API key. Tool access is
-default-deny via `--allowedTools`; edits are auto-accepted
-(`--permission-mode acceptEdits`) inside the repo directory.
+cezar shells out to your locally installed, logged-in `claude` CLI in headless
+`stream-json` mode — **your subscription, no API key**. Tool access is
+default-deny via `--allowedTools`, and edits are auto-accepted
+(`--permission-mode acceptEdits`) inside the task's worktree. 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. |
+| `GITHUB_TOKEN` | Fallback for GitHub reads/PRs when `gh` isn't authenticated. |
+
+---
+
+## 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):
+
+```jsonc
+{
+  "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)
+  "plannerModel": "sonnet",  // model the Plan button uses to draft chains
+  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Repo tab)
+}
+```
 
-Useful env vars:
+Run data (`runs.json`, NDJSON event logs, worktrees, `todos.json`) is
+git-ignored automatically; your workflows and skills stay committable.
 
-- `CEZ_DRY_RUN=1` — use the bundled mock instead of the real CLI (demo/dev).
-- `CEZ_CLAUDE_BIN=/path/to/claude` — override the binary.
+---
 
 ## Development
 
 ```bash
 npm install
-npm run dev        # tsx src/index.ts
-npm run build      # tsc → dist/
+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](https://github.com/...) — same core ideas (agent runner, skills,
-declarative workflows, run cockpit), none of the SaaS.
+[**cezar**](https://github.com/comerito/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

package/dist/config.d.ts

@@ -32,6 +32,12 @@ declare const configSchema: z.ZodObject<{
     }>, "many">>;
     /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
     maxParallel: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Which agent backend a task uses unless overridden per task (GUI) or per
+     * step (workflow). The GUI only offers runners actually installed; this is
+     * the preselected default. Also the runner the chain planner uses.
+     */
+    defaultRunner: z.ZodDefault<z.ZodEnum<["claude", "codex", "opencode"]>>;
     /** Model for the chain planner (spec 008) — cheap but reliable at JSON. */
     plannerModel: z.ZodDefault<z.ZodString>;
     /**
@@ -45,6 +51,7 @@ declare const configSchema: z.ZodObject<{
         ref: string;
     }[];
     maxParallel: number;
+    defaultRunner: "claude" | "codex" | "opencode";
     plannerModel: string;
     baseBranch?: string | undefined;
 }, {
@@ -53,6 +60,7 @@ declare const configSchema: z.ZodObject<{
         ref?: string | undefined;
     }[] | undefined;
     maxParallel?: number | undefined;
+    defaultRunner?: "claude" | "codex" | "opencode" | undefined;
     plannerModel?: string | undefined;
     baseBranch?: string | undefined;
 }>;

package/dist/config.js

@@ -19,6 +19,12 @@ const configSchema = z.object({
     skillsRepos: z.array(skillsRepoSchema).default(DEFAULT_SKILLS_REPOS),
     /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
     maxParallel: z.number().int().min(1).max(16).default(2),
+    /**
+     * Which agent backend a task uses unless overridden per task (GUI) or per
+     * step (workflow). The GUI only offers runners actually installed; this is
+     * the preselected default. Also the runner the chain planner uses.
+     */
+    defaultRunner: z.enum(['claude', 'codex', 'opencode']).default('claude'),
     /** Model for the chain planner (spec 008) — cheap but reliable at JSON. */
     plannerModel: z.string().min(1).default('sonnet'),
     /**

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACvC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,EAAE,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE;CAC7C,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;IACpE,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD,2EAA2E;IAC3E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACjD;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC;AAIH,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACvC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,EAAE,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE;CAC7C,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;IACpE,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACxE,2EAA2E;IAC3E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACjD;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC;AAIH,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/dist/core/agent-runner.d.ts

@@ -2,9 +2,19 @@
  * The backend-agnostic seam for running one agent task. Adapted from
  * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
  * no token-budget circuit breaker, no zod response schemas — one run is one
- * `claude` CLI invocation streaming normalized events.
+ * agent-CLI session streaming normalized events.
+ *
+ * Three interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE.
  */
-export type AgentBackend = 'claude-cli';
+/** `claude-cli` is the legacy id kept so old run records still parse. */
+export type AgentBackend = 'claude' | 'codex' | 'opencode' | 'claude-cli';
+/** The user-selectable runners (what config/GUI expose). */
+export type RunnerId = 'claude' | 'codex' | 'opencode';
+export declare const RUNNER_IDS: readonly RunnerId[];
 export interface AgentRunSpec {
     /** Appended to the CLI's default system prompt (`--append-system-prompt`). */
     systemPrompt?: string;
@@ -77,6 +87,13 @@ export type AgentEvent = {
 } | {
     type: 'cost';
     usd: number;
+}
+/** The backend's real session id, once known — codex threads and opencode
+ *  sessions mint their own id, so the run manager persists this to enable
+ *  resume ("Continue") and "open in CLI". Claude's equals `spec.sessionId`. */
+ | {
+    type: 'session';
+    sessionId: string;
 } | {
     type: 'turn-end';
 } | {
@@ -101,8 +118,33 @@ export interface AgentRunResult {
     tokensUsed: number;
     sessionId?: string;
 }
+export interface SessionOptions {
+    /** Close the session shortly after the first turn ends (single-turn
+     *  behavior, used for non-interactive workflow steps). Interactive
+     *  sessions omit this and control `end()` themselves. */
+    autoEndAfterFirstTurn?: boolean;
+}
+/**
+ * A live agent session over one spawned backend process. The process stays
+ * alive between turns and reads further user messages — that's what makes
+ * mid-task follow-ups possible. Implemented identically by every backend
+ * (claude stdin, codex app-server, opencode serve).
+ */
+export interface AgentSession {
+    /** Resolves when the backend process exits — the session is fully over. */
+    result: Promise<AgentRunResult>;
+    /** Write a user message into the live session. False when it is closed. */
+    sendMessage(content: ContentBlock[]): boolean;
+    /** Graceful close: end input, then a SIGTERM→SIGKILL watchdog. */
+    end(): void;
+    /** Hard stop (used by cancel). */
+    interrupt(): void;
+    /** True while the session still accepts messages. */
+    readonly open: boolean;
+}
 export interface AgentRunner {
     readonly backend: AgentBackend;
     run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
     interrupt(): Promise<void>;
 }

package/dist/core/agent-runner.js

@@ -2,7 +2,13 @@
  * The backend-agnostic seam for running one agent task. Adapted from
  * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
  * no token-budget circuit breaker, no zod response schemas — one run is one
- * `claude` CLI invocation streaming normalized events.
+ * agent-CLI session streaming normalized events.
+ *
+ * Three interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE.
  */
-export {};
+export const RUNNER_IDS = ['claude', 'codex', 'opencode'];
 //# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC"}

package/dist/core/backend-detect.d.ts

@@ -1,13 +1,15 @@
 export interface BackendCheck {
-    name: 'claude' | 'gh' | 'git';
+    name: 'claude' | 'codex' | 'opencode' | 'gh' | 'git';
     available: boolean;
     version?: string;
     hint?: string;
 }
 /**
- * Probe the host for everything cez leans on: the `claude` CLI (the agent
- * backend), `gh` (GitHub auth for PR creation) and `git`. Nothing is required
- * except `claude` — the GUI degrades gracefully and shows the hints instead.
+ * Probe the host for everything cez leans on: the agent CLIs (`claude`, and
+ * the optional `codex` / `opencode` alternatives), `gh` (GitHub auth for PR
+ * creation) and `git`. Nothing is required except at least one agent CLI — the
+ * GUI degrades gracefully, only offers the runners that are present, and shows
+ * the hints for the rest.
  */
 export declare function detectEnvironment(): Promise<BackendCheck[]>;
 /** The host's GitHub token: logged-in `gh` first, `GITHUB_TOKEN` fallback. */

package/dist/core/backend-detect.js

@@ -2,12 +2,14 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 const exec = promisify(execFile);
 /**
- * Probe the host for everything cez leans on: the `claude` CLI (the agent
- * backend), `gh` (GitHub auth for PR creation) and `git`. Nothing is required
- * except `claude` — the GUI degrades gracefully and shows the hints instead.
+ * Probe the host for everything cez leans on: the agent CLIs (`claude`, and
+ * the optional `codex` / `opencode` alternatives), `gh` (GitHub auth for PR
+ * creation) and `git`. Nothing is required except at least one agent CLI — the
+ * GUI degrades gracefully, only offers the runners that are present, and shows
+ * the hints for the rest.
  */
 export async function detectEnvironment() {
-    return Promise.all([probeClaude(), probeGh(), probeGit()]);
+    return Promise.all([probeClaude(), probeCodex(), probeOpencode(), probeGh(), probeGit()]);
 }
 async function probeClaude() {
     if (process.env.CEZ_DRY_RUN === '1') {
@@ -40,6 +42,44 @@ async function probeClaude() {
         };
     }
 }
+async function probeCodex() {
+    const bin = process.env.CEZ_CODEX_BIN ?? 'codex';
+    try {
+        const { stdout } = await exec(bin, ['--version'], { timeout: 10_000 });
+        return {
+            name: 'codex',
+            available: true,
+            version: stdout.trim(),
+            hint: 'if not authenticated, run `codex` once and log in',
+        };
+    }
+    catch {
+        return {
+            name: 'codex',
+            available: false,
+            hint: 'optional: install the Codex CLI (npm i -g @openai/codex) and log in to use the Codex runner',
+        };
+    }
+}
+async function probeOpencode() {
+    const bin = process.env.CEZ_OPENCODE_BIN ?? 'opencode';
+    try {
+        const { stdout } = await exec(bin, ['--version'], { timeout: 10_000 });
+        return {
+            name: 'opencode',
+            available: true,
+            version: stdout.trim(),
+            hint: 'if no provider is configured, run `opencode` once to set one up',
+        };
+    }
+    catch {
+        return {
+            name: 'opencode',
+            available: false,
+            hint: 'optional: install OpenCode (https://opencode.ai) and configure a provider to use the OpenCode runner',
+        };
+    }
+}
 async function probeGh() {
     try {
         const { stdout } = await exec('gh', ['auth', 'token'], { timeout: 10_000 });

package/dist/core/backend-detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend-detect.js","sourceRoot":"","sources":["../../src/core/backend-detect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backend-detect.js","sourceRoot":"","sources":["../../src/core/backend-detect.ts"],"names":[],"mappings":"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"}

package/dist/core/claude-cli-runner.d.ts

@@ -1,4 +1,5 @@
-import type { AgentEvent, AgentRunResult, AgentRunSpec, AgentRunner, ContentBlock } from './agent-runner.js';
+import type { AgentEvent, AgentRunResult, AgentRunSpec, AgentRunner, AgentSession, SessionOptions } from './agent-runner.js';
+export type { AgentSession, SessionOptions } from './agent-runner.js';
 /** Default wall-clock cap for a single run before SIGTERM → SIGKILL.
  *  Interactive sessions pass `timeoutMs: 0` to disable it entirely. */
 export declare const DEFAULT_RUN_TIMEOUT_MS: number;
@@ -16,29 +17,6 @@ export interface ClaudeCliRunnerOptions {
     /** Wall-clock timeout for a run (ms); per-spec `timeoutMs` still wins. */
     timeoutMs?: number;
 }
-export interface SessionOptions {
-    /** Close the session shortly after the first turn ends (single-turn
-     *  behavior, used for non-interactive workflow steps). Interactive
-     *  sessions omit this and control `end()` themselves. */
-    autoEndAfterFirstTurn?: boolean;
-}
-/**
- * A live agent session over one spawned claude process. The process stays
- * alive between turns (no `-p`) and reads further user messages from stdin —
- * that's what makes mid-task follow-ups and pasted screenshots possible.
- */
-export interface AgentSession {
-    /** Resolves when the claude process exits — the session is fully over. */
-    result: Promise<AgentRunResult>;
-    /** Write a user message into the live session. False when stdin is closed. */
-    sendMessage(content: ContentBlock[]): boolean;
-    /** Graceful close: EOF on stdin, then the SIGTERM→SIGKILL watchdog. */
-    end(): void;
-    /** Hard stop (used by cancel). */
-    interrupt(): void;
-    /** True while the session still accepts messages. */
-    readonly open: boolean;
-}
 /**
  * `AgentRunner` over the Claude Code CLI in headless stream-json mode. Auth =
  * the host's logged-in Pro/Max subscription (no API key needed). Sandboxing is
@@ -50,7 +28,7 @@ export interface AgentSession {
  * came from @cezar/core's `ClaudeCodeCliRunner`.
  */
 export declare class ClaudeCliRunner implements AgentRunner {
-    readonly backend: "claude-cli";
+    readonly backend: "claude";
     private readonly bin;
     private readonly timeoutMs;
     private lastSession;