@hanzo/dev 0.6.90 → 0.6.92

package/README.md

@@ -1,407 +1,172 @@
-<img src="docs/images/every-logo.png" alt="Every Code Logo" width="400">
-
-&ensp;
-
-**Every Code** (Code for short) is a fast, local coding agent for your terminal. It's a community-driven fork of `openai/codex` focused on real developer ergonomics: Browser integration, multi-agents, theming, and reasoning control — all while staying compatible with upstream.
-
-&ensp;
-
-## What's new
-
-- **Latest long-session stability sweep** (post-0.6): Auto Drive and Auto Review are now decoupled so background reviews no longer block the command flow. `Esc` returns control immediately and typing works while review finalization continues.
-
-- **Operational upgrades in this cycle**
-  - Auto Review metadata (branch/worktree context) remains queryable through the active Auto Drive session after completion.
-  - Terminal agents are compacted and archived so heavy payloads are reduced while review linkage is preserved.
-  - Core `core`, coordinator, and TUI state maps now have hard caps with bounded drop/trim behavior.
-  - Auto Drive conversation/update queues are bounded in the coordinator; TUI has bounded prompt/agent/runtime caches.
-  - Background review notes are added as non-blocking history-visible notes instead of foreground task-injection.
-  - TUI housekeeping lifecycle is bounded with deterministic stop control.
-  - Stress tests now cover heavy agent churn plus concurrent Auto Review + Esc/typing responsiveness.
-
-- **New/updated models and agents**
-  - Auto Drive CLI model support includes `gpt-5.3-codex` (planning/problem-solving) and `gpt-5.3-codex-spark` (fast coding/fix loops), with `medium | high | xhigh` reasoning controls.
-  - Frontline and alias-aware agent model handling now includes `code-gpt-5.3-codex` and `code-gpt-5.3-codex-spark`, with compatibility alias upgrades for `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5.2-codex`, etc.
-  - Auto Drive decision schema and coordinator payloads now enforce bounded history while preserving goal and recent context.
-
-  See commit `60727b068` and related Auto Drive hardening commits in git history for details.
-
-- **Auto Review** – background ghost-commit watcher runs reviews in a separate worktree whenever a turn changes code; uses `codex-5.1-mini-high` and reports issues plus ready-to-apply fixes without blocking the main thread.
-- **Code Bridge** – Sentry-style local bridge that streams errors, console, screenshots, and control from running apps into Code; ships an MCP server; install by asking Code to pull `https://github.com/just-every/code-bridge`.
-- **Plays well with Auto Drive** – reviews run in parallel with long Auto Drive tasks so quality checks land while the flow keeps moving.
-- **Quality-first focus** – the release shifts emphasis from "can the model write this file" to "did we verify it works".
-- _From v0.5.0:_ rename to Every Code, upgraded `/auto` planning/recovery, unified `/settings`, faster streaming/history with card-based activity, and more reliable `/resume` + `/undo`.
-
-[Read the full notes in RELEASE_NOTES.md](docs/release-notes/RELEASE_NOTES.md)
-
-&ensp;
-
-## Why Every Code
-
-- 🚀 **Auto Drive orchestration** – Multi-agent automation that now self-heals and ships complete tasks.
-- 🌐 **Browser Integration** – CDP support, headless browsing, screenshots captured inline.
-- 🤖 **Multi-agent commands** – `/plan`, `/code` and `/solve` coordinate multiple CLI agents.
-- 🧭 **Unified settings hub** – `/settings` overlay for limits, theming, approvals, and provider wiring.
-- 🎨 **Theme system** – Switch between accessible presets, customize accents, and preview live via `/themes`.
-- 🔌 **MCP support** – Extend with filesystem, DBs, APIs, or your own tools.
-- 🔒 **Safety modes** – Read-only, approvals, and workspace sandboxing.
-
-&ensp;
-
-## AI Videos
-
-&ensp;
-
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=Ra3q8IVpIOc">
-    <img src="docs/images/video-auto-review-play.jpg" alt="Play Auto Review video" width="100%">
-  </a><br>
-  <strong>Auto Review</strong>
-</p>
-
-&ensp;
-
 <p align="center">
-  <a href="https://youtu.be/UOASHZPruQk">
-    <img src="docs/images/video-auto-drive-new-play.jpg" alt="Play Introducing Auto Drive video" width="100%">
-  </a><br>
-  <strong>Auto Drive Overview</strong>
+  <img src="docs/logo.png" alt="Hanzo Dev" width="400">
 </p>
 
-&ensp;
+# Hanzo Dev
 
-<p align="center">
-  <a href="https://youtu.be/sV317OhiysQ">
-    <img src="docs/images/video-v03-play.jpg" alt="Play Multi-Agent Support video" width="100%">
-  </a><br>
-  <strong>Multi-Agent Promo</strong>
-</p>
+Hanzo Dev is our coding agent. It runs in your terminal, reads and edits the
+repository you point it at, runs commands in a sandbox, and drives a browser
+when a task needs one. Models are served by [Hanzo AI](https://hanzo.ai) —
+`enso` and the `zen5` family — over the metered gateway at `api.hanzo.ai`.
 
-&ensp;
+It ships inside the Hanzo CLI. `hanzo dev` is the command.
 
-## Quickstart
+| <img src="docs/screenshots/simple.png" alt="A session in progress" width="100%"><br>A session in progress | <img src="docs/screenshots/diff.png" alt="Reviewing a diff" width="100%"><br>Reviewing a diff |
+|:--:|:--:|
+| <img src="docs/screenshots/browser.png" alt="Driving a browser" width="100%"><br>Driving a browser | <img src="docs/screenshots/agents.png" alt="Several agents on one task" width="100%"><br>Several agents on one task |
 
-### Run
+## Install
 
 ```bash
-npx -y @hanzo/dev
+curl -fsSL https://hanzo.sh | sh
+hanzo auth login
 ```
 
-### Install & Run
+`hanzo auth login` signs you in through Hanzo IAM and links the machine to your
+account. Then, from any repository:
 
 ```bash
-npm install -g @hanzo/dev
-dev
+hanzo dev
 ```
 
-Note: If another tool already provides a `code` command (e.g. VS Code), our CLI is also installed as `coder`. Use `coder` to avoid conflicts.
-
-**Authenticate** (one of the following):
-
-- **Sign in with ChatGPT** (Plus/Pro/Team; uses models available to your plan)
-  - Run `code` and pick "Sign in with ChatGPT"
-- **API key** (usage-based)
-  - Set `export OPENAI_API_KEY=xyz` and run `code`
-
-### Install Claude & Gemini (optional)
-
-Every Code supports orchestrating other AI CLI tools. Install these and config to use alongside Code.
+Give it the task on the command line to run headless instead:
 
 ```bash
-# Ensure Node.js 20+ is available locally (installs into ~/.n)
-npm install -g n
-export N_PREFIX="$HOME/.n"
-export PATH="$N_PREFIX/bin:$PATH"
-n 20.18.1
-
-# Install the companion CLIs
-export npm_config_prefix="${npm_config_prefix:-$HOME/.npm-global}"
-mkdir -p "$npm_config_prefix/bin"
-export PATH="$npm_config_prefix/bin:$PATH"
-npm install -g @anthropic-ai/claude-code @google/gemini-cli @qwen-code/qwen-code
-
-# Quick smoke tests
-claude --version
-gemini --version
-qwen --version
+hanzo dev "fix the failing tests in ./core and explain what was wrong"
 ```
 
-> ℹ️ Add `export N_PREFIX="$HOME/.n"` and `export PATH="$N_PREFIX/bin:$PATH"` (plus the `npm_config_prefix` bin path) to your shell profile so the CLIs stay on `PATH` in future sessions.
-
-&ensp;
+## Choosing a model
 
-## Commands
-
-### Browser
+Model ids come from the gateway, which is the only authority on the catalog —
+there is no allowlist in the client.
 
 ```bash
-# Connect code to external Chrome browser (running CDP)
-/chrome        # Connect with auto-detect port
-/chrome 9222   # Connect to specific port
-
-# Switch to internal browser mode
-/browser       # Use internal headless browser
-/browser https://example.com  # Open URL in internal browser
+hanzo dev --model enso          # our frontier model
+hanzo dev --model enso-ultra    # the largest reasoning tier
+hanzo dev --model zen5-coder    # tuned for code
 ```
 
-### Agents
-
-```bash
-# Plan code changes (Claude, Gemini and GPT-5 consensus)
-# All agents review task and create a consolidated plan
-/plan "Stop the AI from ordering pizza at 3AM"
-
-# Solve complex problems (Claude, Gemini and GPT-5 race)
-# Fastest preferred (see https://arxiv.org/abs/2505.17813)
-/solve "Why does deleting one user drop the whole database?"
+Browse everything available with `curl https://catalog.hanzo.ai/v1/models`.
 
-# Write code! (Claude, Gemini and GPT-5 consensus)
-# Creates multiple worktrees then implements the optimal solution
-/code "Show dark mode when I feel cranky"
-```
+## Backends
 
-### Auto Drive
+Hanzo Dev is the default and the one we build. The same session launcher can
+also drive two other agents if you already have them installed, so you can keep
+one set of habits across all three:
 
 ```bash
-# Hand off a multi-step task; Auto Drive will coordinate agents and approvals
-/auto "Refactor the auth flow and add device login"
-
-# Resume or inspect an active Auto Drive run
-/auto status
+hanzo dev              # our agent (default)
+hanzo dev claude       # or: hanzo code --claude
+hanzo dev codex        # or: hanzo code --codex
 ```
 
-### General
-
-```bash
-# Try a new theme!
-/themes
-
-# Change reasoning level
-/reasoning low|medium|high
+`hanzo dev` is a spelling of `hanzo code dev`, not a second implementation —
+every spelling resolves through the same launcher.
 
-# Switch models or effort presets
-/model
+## Options
 
-# Start new conversation
-/new
 ```
-
-## CLI reference
-
-```shell
-code [options] [prompt]
-
-Options:
-  --model <name>        Override the model for the active provider (e.g. gpt-5.1)
-  --read-only          Prevent file modifications
-  --no-approval        Skip approval prompts (use with caution)
-  --config <key=val>   Override config values
-  --oss                Use local open source models
-  --sandbox <mode>     Set sandbox level (read-only, workspace-write, etc.)
-  --help              Show help information
-  --debug             Log API requests and responses to file
-  --version           Show version number
+hanzo dev [OPTIONS] [BACKEND|TASK] [TASK] [-- <PASSTHROUGH>...]
+
+  --model <MODEL>     Gateway model id, e.g. enso, enso-ultra, zen5-coder
+  --backend <NAME>    dev (default) | claude | codex
+  --brand <BRAND>     Tenant for auth: hanzo | lux | zoo | pars | bootnode
+  --ask               Ask before each action instead of auto-approving (alias: --safe)
+  --no-sandbox        Drop the sandbox and auto-approve. Per-invocation, never persisted
+  --no-route          Call the backend's own model account instead of the metered gateway
+  --no-mcp            Do not attach the Hanzo MCP toolset
+  --project-mcp       Also load the repo's own .mcp.json servers (off by default — a repo is untrusted)
+  --link / --no-link  Stream the session to Hanzo cloud, or never
+  --resume <ID>       Resume a prior linked session by its cloud session id
+  -c, --config <FILE> Use a specific config file
+  -v, --verbose       Increase logging verbosity
 ```
 
-Note: `--model` only changes the model name sent to the active provider. To use a different provider, set `model_provider` in `config.toml`. Providers must expose an OpenAI-compatible API (Chat Completions or Responses).
-
-&ensp;
-
-## Memory & project docs
-
-Every Code can remember context across sessions:
-
-1. **Create an `AGENTS.md` or `CLAUDE.md` file** in your project root:
+Anything after `--` is passed verbatim to the backend.
 
-```markdown
-# Project Context
+Two defaults worth knowing. Sessions run sandboxed and auto-approve inside that
+sandbox; `--ask` tightens it, `--no-sandbox` removes it. Model calls route
+through `api.hanzo.ai` so usage is metered on your Hanzo account; `--no-route`
+sends them to the backend's own account instead.
 
-This is a React TypeScript application with:
+## In a session
 
-- Authentication via JWT
-- PostgreSQL database
-- Express.js backend
+Type `/` for the full list. The ones you will reach for:
 
-## Key files:
-
-- `/src/auth/` - Authentication logic
-- `/src/api/` - API client code
-- `/server/` - Backend services
 ```
-
-2. **Session memory**: Every Code maintains conversation history
-3. **Codebase analysis**: Automatically understands project structure
-
-&ensp;
-
-## Non-interactive / CI mode
-
-For automation and CI/CD:
-
-```shell
-# Run a specific task
-code --no-approval "run tests and fix any failures"
-
-# Generate reports
-code --read-only "analyze code quality and generate report"
-
-# Batch processing
-code --config output_format=json "list all TODO comments"
-```
-
-&ensp;
-
-## Model Context Protocol (MCP)
-
-Every Code supports MCP for extended capabilities:
-
-- **File operations**: Advanced file system access
-- **Database connections**: Query and modify databases
-- **API integrations**: Connect to external services
-- **Custom tools**: Build your own extensions
-
-Configure MCP in `~/.code/config.toml` Define each server under a named table like `[mcp_servers.<name>]` (this maps to the JSON `mcpServers` object used by other clients):
-
-```toml
-[mcp_servers.filesystem]
-command = "npx"
-args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
-```
-
-&ensp;
-
-## Configuration
-
-Main config file: `~/.code/config.toml`
-
-> [!NOTE]
-> Every Code reads from both `~/.code/` and `~/.codex/` for backwards compatibility, but it only writes updates to `~/.code/`. If you switch back to Codex and it fails to start, remove `~/.codex/config.toml`. If Every Code appears to miss settings after upgrading, copy your legacy `~/.codex/config.toml` into `~/.code/`.
-
-```toml
-# Model settings
-model = "gpt-5.1"
-model_provider = "openai"
-
-# Behavior
-approval_policy = "on-request"  # untrusted | on-failure | on-request | never
-model_reasoning_effort = "medium" # low | medium | high
-sandbox_mode = "workspace-write"
-
-# UI preferences see THEME_CONFIG.md
-[tui.theme]
-name = "light-photon"
-
-# Add config for specific models
-[profiles.gpt-5]
-model = "gpt-5.1"
-model_provider = "openai"
-approval_policy = "never"
-model_reasoning_effort = "high"
-model_reasoning_summary = "detailed"
+/plan       create a comprehensive plan (multiple agents)
+/solve      solve a challenging problem (multiple agents)
+/code       perform a coding task (multiple agents)
+/auto       work autonomously on long tasks with Auto Drive
+/agents     create and configure agents
+/browser    open the internal browser
+/chrome     connect to a running Chrome over CDP
+/diff       show the git diff, including untracked files
+/review     review your changes for potential issues
+/undo       restore the workspace to the last snapshot
+/branch     work on a branch in a worktree
+/merge      merge the worktree branch back to the default
+/model      choose model and reasoning effort
+/reasoning  change reasoning effort (minimal/low/medium/high)
+/theme      switch color themes
+/status     session configuration and token usage
+/limits     weekly and hourly rate limits
+/mcp        manage MCP servers (status/on/off/add)
+/init       write an AGENTS.md for this repository
+/resume     resume a past session for this folder
+/new        start a new chat
 ```
 
-### Environment variables
-
-- `CODE_HOME`: Override config directory location
-- `OPENAI_API_KEY`: Use API key instead of ChatGPT auth
-- `OPENAI_BASE_URL`: Use OpenAI-compatible API endpoints (chat or responses)
-- `OPENAI_WIRE_API`: Force the built-in OpenAI provider to use `chat` or `responses` wiring
-
-&ensp;
-
-## FAQ
-
-**How is this different from the original?**
-
-> This fork adds browser integration, multi-agent commands (`/plan`, `/solve`, `/code`), theme system, and enhanced reasoning controls while maintaining full compatibility.
-
-**Can I use my existing Codex configuration?**
+Full list with descriptions: [docs/slash-commands.md](docs/slash-commands.md).
 
-> Yes. Every Code reads from both `~/.code/` (primary) and legacy `~/.codex/` directories. We only write to `~/.code/`, so Codex will keep running if you switch back; copy or remove legacy files if you notice conflicts.
+## Project context
 
-**Does this work with ChatGPT Plus?**
+Run `/init` in a repository and Hanzo Dev writes an `AGENTS.md` describing what
+it found. Edit that file — it is read at the start of every session in that
+directory, so it is where project conventions, architecture notes and "do not
+touch this" rules belong.
 
-> Absolutely. Use the same "Sign in with ChatGPT" flow as the original.
+## Tools
 
-**Is my data secure?**
+The Hanzo MCP toolset is attached by default: filesystem, shell, browser, and
+the rest of the Hanzo surface. Add your own servers with `/mcp add`, or per
+repository in `.mcp.json` — the latter is off unless you pass `--project-mcp`,
+because a repository you just cloned should not get to run a server with your
+session's key.
 
-> Yes. Authentication stays on your machine, and we don't proxy your credentials or conversations.
+## Documentation
 
-&ensp;
+- [Getting started](docs/getting-started.md)
+- [Configuration](docs/config.md)
+- [Authentication](docs/authentication.md)
+- [Sandboxing](docs/sandbox.md)
+- [Themes](docs/THEME_CONFIG.md)
+- [Hanzo docs](https://docs.hanzo.ai/docs)
 
-## Contributing
-
-We welcome contributions! Every Code maintains compatibility with upstream while adding community-requested features.
-
-### Development workflow
+## Building from source
 
 ```bash
-# Clone and setup
-git clone https://github.com/just-every/code.git
-cd code
-npm install
-
-# Build (use fast build for development)
+git clone https://github.com/hanzoai/dev.git
+cd dev
 ./build-fast.sh
-
-# Run locally
-./code-rs/target/dev-fast/code
-```
-
-#### Git hooks
-
-This repo ships shared hooks under `.githooks/`. To enable them locally:
-
-```bash
-git config core.hooksPath .githooks
 ```
 
-The `pre-push` hook runs `./pre-release.sh` automatically when pushing to `main`.
-
-### Opening a pull request
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Make your changes
-4. Run tests: `cargo test`
-5. Build successfully: `./build-fast.sh`
-6. Submit a pull request
+`./build-fast.sh` is the required check — it must pass cleanly, warnings
+included. See [DEVELOPING.md](DEVELOPING.md) and [LLM.md](LLM.md) for the
+workspace layout and the rules that apply inside it.
 
-&ensp;
-
-## Legal & Use
-
-### License & attribution
-
-- This project is a community fork of `openai/codex` under **Apache-2.0**. We preserve upstream LICENSE and NOTICE files.
-- **Every Code** (Code) is **not** affiliated with, sponsored by, or endorsed by OpenAI.
-
-### Your responsibilities
-
-Using OpenAI, Anthropic or Google services through Every Code means you agree to **their Terms and policies**. In particular:
-
-- **Don't** programmatically scrape/extract content outside intended flows.
-- **Don't** bypass or interfere with rate limits, quotas, or safety mitigations.
-- Use your **own** account; don't share or rotate accounts to evade limits.
-- If you configure other model providers, you're responsible for their terms.
-
-### Privacy
-
-- Your auth file lives at `~/.code/auth.json`
-- Inputs/outputs you send to AI providers are handled under their Terms and Privacy Policy; consult those documents (and any org-level data-sharing settings).
-
-### Subject to change
-
-AI providers can change eligibility, limits, models, or authentication flows. Every Code supports **both** ChatGPT sign-in and API-key modes so you can pick what fits (local/hobby vs CI/automation).
+## Contributing
 
-&ensp;
+Branch, make the change, make `./build-fast.sh` pass, open a pull request.
+Bugs and feature requests: [github.com/hanzoai/dev/issues](https://github.com/hanzoai/dev/issues).
 
 ## License
 
-Apache 2.0 - See [LICENSE](LICENSE) file for details.
-
-Every Code is a community fork of the original Codex CLI. We maintain compatibility while adding enhanced features requested by the developer community.
+Apache-2.0 — see [LICENSE](LICENSE).
 
-## &ensp;
+## Lineage
 
-**Need help?** Open an issue on [GitHub](https://github.com/just-every/code/issues) or check our documentation.
+Hanzo Dev is a fork of [just-every/code](https://github.com/just-every/code), which is
+itself a fork of [openai/codex](https://github.com/openai/codex). Both are Apache-2.0,
+and this repository preserves the upstream `LICENSE` and `NOTICE`. Hanzo Dev is not
+affiliated with, sponsored by, or endorsed by either project.