7.0 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.