7.3 KiB
Hanzo Dev
dev: a coding agent for the terminal. Hanzo owns the front door; upstream owns the engines.
Shape
crates/hanzo-dev: the binary.main.rsis the whole command surface; each subcommand hands off to a library.crates/hanzo-config: provider and product home.crates/hanzo-tui: the Hanzo account behind /login, /logout, /auth, /status and /usage (shells out to thehanzoCLI).crates/hanzo-kai: Kai, the controller.upstream/codex: submodule of hanzoai/codex (openai/codex plus Hanzo's commits). The gitlink is the pin. Crates are path dependencies; the checkout stays pristine (git -C upstream/codex status --porcelainempty after build and test).- The cloud-driven wasm loop lives in
hanzo-inc/dev; nothing here depends on it.
Working here
make build the dev binary (must pass, no warnings)
make test the Hanzo suite
make test-upstream hanzoai/codex's own suite
make bump how to move upstream/codex forward
Upstream
Never edit upstream by hand. A change upstream hard-codes is a commit on hanzoai/codex main, made in upstream/codex, pushed before the gitlink moves. Anything that need not live in upstream's crates goes in a hanzo-* crate here.
Bump = merge: in upstream/codex, git fetch upstream && git merge upstream/main; resolve in git; find new Codex strings (git diff ORIG_HEAD -G'"[^"]*Codex' -- 'codex-rs/*.rs') and new env!("CARGO_PKG_VERSION") reads (make test names them); fix as commits; make build test; push; commit the gitlink. Root Cargo.toml [workspace.dependencies]/[patch] mirror the fork's codex-rs/Cargo.toml; refresh on a bump. Dev's own additions: the hanzo-* crates, the rusqlite patch, no v8 patch.
The delta (git log --no-merges upstream/main..main in upstream/codex):
codex-rs/hanzocrate: names,API_BASE,DEFAULT_MODEL,is_hanzo, catalog,model::pick, the controller interface,version,pace,effort. Upstream crates read it; never the reverse.- Hooks, no-ops until the binary fills them:
codex_app_server::register(Extension)andcodex_tui::register(Account { login, logout, show, usage }). Without an account, /login and /auth are hidden and /usage needs ChatGPT. - Commits prefixed
tui:,cli:,config:,core:,words:,brand:,version:. - Repeated tool-cycle guard (
core/src/session/cycle.rs): an identical step answered identically fails the turn withrepeated identical tool-use cycle detected; cloud's coding loop reads that mark. - Rate limits never surface:
hanzo::pacehonorsx-ratelimit-*andRetry-After; 429/503/overload retry with jitter (1–60 s), no cap while the turn lives, shown asturn.waiting. Test:crates/hanzo-dev/tests/pace.rs. - Reasoning effort is one table,
hanzo::effort(autosends none, so the router decides). Test:tests/effort.rs. - TUI:
/contextshows window use;/usageon Hanzo runshanzo usage summary --range(daily/weekly/cumulative → 24h/7d/30d).
Dev reads only Hanzo directories: ~/.hanzo/dev (or DEV_HOME), <repo>/.hanzo/dev/, /etc/hanzo/dev/. Never .codex. A profile with no provider gets Hanzo. Test: tests/launch.rs.
Version
Set by hand in root Cargo.toml [workspace.package], npm/package.json, and the tag; release.yml refuses a mismatch. Only hanzo-dev carries it (hanzo::version::set); every other crate asks hanzo::version::get() at run time. Dev's libraries stay 0.0.0 so a release recompiles one crate.
Release
release.yml on a pushed tag: version opens a draft; five build jobs on xl-linux-amd64 upload; publish checks 28 assets, then Homebrew and npm. Branch runs build a draft only (delete by hand). All GitHub calls go through scripts/ghapi.sh (retries rate limits and 5xx).
Cache: sccache via hanzoai/ci bin/cache (pinned CI_SHA) in the org ci-cache bucket. Key covers the upstream pin, toolchain, root Cargo.toml/Cargo.lock minus the version, and build env; not crates/. Only main and tags write. Traps: cargo-zigbuild must live at ~/.cargo/bin (its path is hashed into every object); any CARGO_* var except CARGO_BUILD_JOBS busts the cache. Warm build ≈ 5–7 min; engine moved ≈ 18; cold ≈ 25.
Review and memory models
On Hanzo, approval review and memory extraction use DEFAULT_MODEL; the reviewer takes its preferred id only when the catalog serves it, else the parent's model. Test: tests/review.rs.
Kai (controller)
Kai returns a validated operation or an explicit abstention, never advice. crates/hanzo-kai: loop (flow), ledger (ledger), tools. Search is tgrep (hanzo-trigram, in process); seams are traits (find::Finder, decide::Transport).
- Action: typed
operation(search,decide,mutate,generate,edit,test,revert),source(rule,kai,model,recover), preconditions, expected, verification. Only the verifier settles an outcome. - Cheapest first: an action that applies runs with no inference; else one Kai decision (
fix.site@1,fix.turn@1); else low then full-effort generation; elserecover. Per-program outage cooldowns. - Ahead: the first call starts beside the search; a settled search or moved state cancels it.
- Revision-bound: preconditions checked just before execution; an edit invalidates pending decisions. Caches key on content, not commits.
- Recover: fewer failing tests is progress; the same failure fingerprint with no state change picks a different action or escalates.
- Fast path
mutate: generic token transforms at top sites, eight at once, 2.5 s cap (8 s while a call is pending); slow tests narrowed to the failing ones. - Test runs leave nothing: untracked, unignored files a run creates are swept (
tools::Litter). Hypothesis storage goes to the run's temp dir. - Ledger:
kai/ledger.jsonlbeside the trace, replayable, redacted. - Generation: Zen or enso-flash (
kai.toml[generate]), streamed, budgeted. Edits requested as strict JSON (edits[]offile,line,old,new); reasoning calls cap at 16,384 tokens at effort low. A malformed answer gets onerepair, an empty escalation onefallback. - Transport: HTTP
POST /v1/decisions; ZAP over UDS is the planned alternative.
House rules
- Hanzo APIs:
https://api.hanzo.ai/v1/only. - Keep upstream's interaction model and animation; the branding is ours.
- Linux, macOS, Windows all work.
- Upstream project names appear only in
NOTICE. - just-every/code (
~/work/just-every/code) is reference only; ports recorded inmigration/.
2026-11-16: codex bump for the service_tier 400 (hanzo-inc/cloud#756)
upstream/codex → 6eda8a71 (hanzoai/codex#8). api.hanzo.ai refuses every service_tier
with a 400 ("would buy something this model's price does not cover"). The fork no
longer sends one to a Hanzo base URL and no longer offers the Fast tier for Hanzo
models (hanzo::SERVICE_TIERS = false, hanzo::service_tier_for). The fix reaches
users with the next tag-driven release; merging to main ships nothing on its own.
2026-11-16: codex bump for dev doctor's thread inventory (hanzo-inc/cloud#762)
upstream/codex → cdd641a1 (hanzoai/codex#9). When a session rolls over, the old
rollout file stays on disk while the thread row points at the new one. dev doctor now
counts that old file as "superseded" instead of reporting a missing row and a
duplicate thread. Ships with the next tag-driven release.