@hanzo/dev 2.1.1 → 3.0.2

package/README.md

@@ -1,359 +1,358 @@
-# @hanzo/dev
+<img src="docs/images/every-logo.png" alt="Every Code Logo" width="400">
 
-> State-of-the-art AI development platform with swarm intelligence
+&ensp;
 
-[![npm version](https://badge.fury.io/js/@hanzo%2Fdev.svg)](https://www.npmjs.com/package/@hanzo/dev)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+**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.
 
-@hanzo/dev is an advanced AI development platform that orchestrates multiple AI agents working in parallel. Built with swarm intelligence and Model Context Protocol (MCP) at its core, it achieves industry-leading performance on software engineering benchmarks.
+&ensp;
+## What's new in v0.6.0 (December 2025)
 
-## Features
+- **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`.
 
-- 🤖 **Multi-AI Support**: Integrate with Claude, OpenAI, Gemini, and local AI models
-- 🔧 **Tool Unification**: Single interface for all AI coding assistants
-- 🌐 **MCP Integration**: Full Model Context Protocol support for extensible tools
-- 👥 **Peer Agent Networks**: Spawn multiple agents that collaborate via MCP
-- 🎯 **CodeAct Agent**: Automatic planning, execution, and self-correction
-- 🌍 **Browser Automation**: Control browsers via Hanzo Browser/Extension
-- 📝 **Advanced Editing**: File manipulation with undo, chunk localization
-- 🚀 **Parallel Execution**: Run multiple tasks concurrently across agents
-- 🔍 **SWE-bench Ready**: Optimized for software engineering benchmarks
+ [Read the full notes in RELEASE_NOTES.md](docs/release-notes/RELEASE_NOTES.md)
 
-## Installation
+&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>
+</p>
+
+&ensp;
+<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>
+
+
+
+&ensp;
+## Quickstart
+
+### Run
 
 ```bash
-npm install -g @hanzo/dev
+npx -y @just-every/code
 ```
 
-Or use directly with npx:
+### Install & Run
 
 ```bash
-npx @hanzo/dev
+npm install -g @just-every/code
+code // or `coder` if you're using VS Code
 ```
 
-## Quick Start
+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.
 
-### Interactive Mode
+**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.
 
 ```bash
-dev
+# 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
 ```
 
-This launches an interactive menu where you can:
-- Select your preferred AI tool
-- Configure API keys
-- Access specialized commands
+> ℹ️ 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.
 
-### Direct Tool Access
+&ensp;
+## Commands
 
+### Browser
 ```bash
-# Launch with specific AI provider
-dev --claude
-dev --openai
-dev --gemini
-dev --grok
-dev --local
-
-# Advanced modes
-dev --workspace    # Unified workspace mode
-dev --benchmark    # Run SWE-bench evaluation
-
-# Swarm mode - edit multiple files in parallel
-dev --claude --swarm 5 -p "Add copyright header to all files"
-dev --openai --swarm 10 -p "Fix all ESLint errors"
-dev --gemini --swarm 20 -p "Add JSDoc comments to all functions"
-dev --local --swarm 100 -p "Format all files with prettier"
-```
+# Connect code to external Chrome browser (running CDP)
+/chrome        # Connect with auto-detect port
+/chrome 9222   # Connect to specific port
 
-### Environment Configuration
-
-Create a `.env` file in your project root:
+# Switch to internal browser mode
+/browser       # Use internal headless browser
+/browser https://example.com  # Open URL in internal browser
+```
 
-```env
-# API Keys
-ANTHROPIC_API_KEY=your_key_here
-OPENAI_API_KEY=your_key_here
-GEMINI_API_KEY=your_key_here
-TOGETHER_API_KEY=your_key_here
+### 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"
 
-# Local AI
-HANZO_APP_URL=http://localhost:8080
-LOCAL_LLM_URL=http://localhost:11434
+# 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?"
 
-# Browser Integration
-HANZO_BROWSER_URL=http://localhost:9223
-HANZO_EXTENSION_WS=ws://localhost:9222
+# Write code! (Claude, Gemini and GPT-5 consensus)
+# Creates multiple worktrees then implements the optimal solution
+/code "Show dark mode when I feel cranky"
 ```
 
-## Advanced Features
-
-### Swarm Mode
+### Auto Drive
+```bash
+# Hand off a multi-step task; Auto Drive will coordinate agents and approvals
+/auto "Refactor the auth flow and add device login"
 
-Launch multiple agents to edit files in parallel across your codebase:
+# Resume or inspect an active Auto Drive run
+/auto status
+```
 
+### General
 ```bash
-# Basic swarm usage
-dev --claude --swarm 5 -p "Add copyright header to all files"
+# Try a new theme!
+/themes
 
-# Process specific file types
-dev --openai --swarm 20 -p "Add type annotations" --pattern "**/*.ts"
+# Change reasoning level
+/reasoning low|medium|high
 
-# Maximum parallelism (up to 100 agents)
-dev --gemini --swarm 100 -p "Fix linting errors"
+# Switch models or effort presets
+/model
 
-# Using local provider for cost efficiency
-dev --local --swarm 50 -p "Format with prettier"
+# Start new conversation
+/new
 ```
 
-Features:
-- **Lazy agent spawning**: Agents are created as needed, not all at once
-- **Automatic authentication**: Handles provider login if API keys are available
-- **Parallel execution**: Each agent processes a different file simultaneously
-- **Smart file detection**: Automatically finds all editable files in your project
-- **Progress tracking**: Real-time status updates as files are processed
+## 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
+```
 
-Example: Adding copyright headers to 5 files in parallel:
+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).
 
-```bash
-# Navigate to your test directory
-cd test-swarm
+&ensp;
+## Memory & project docs
+
+Every Code can remember context across sessions:
 
-# Run swarm with Claude
-dev --claude --swarm 5 -p "Add copyright header '// Copyright 2025 Hanzo Industries Inc.' at the top of each file"
+1. **Create an `AGENTS.md` or `CLAUDE.md` file** in your project root:
+```markdown
+# Project Context
+This is a React TypeScript application with:
+- Authentication via JWT
+- PostgreSQL database
+- Express.js backend
+
+## Key files:
+- `/src/auth/` - Authentication logic
+- `/src/api/` - API client code  
+- `/server/` - Backend services
 ```
 
-The swarm will:
-1. Find all editable files in the directory
-2. Spawn up to 5 Claude agents
-3. Assign each agent a file to process
-4. Execute edits in parallel
-5. Report results when complete
+2. **Session memory**: Every Code maintains conversation history
+3. **Codebase analysis**: Automatically understands project structure
 
-Supported providers:
-- `--claude`: Claude AI (requires ANTHROPIC_API_KEY or claude login)
-- `--openai`: OpenAI GPT (requires OPENAI_API_KEY)
-- `--gemini`: Google Gemini (requires GOOGLE_API_KEY)
-- `--grok`: Grok AI (requires GROK_API_KEY)
-- `--local`: Local Hanzo agent (no API key required)
+&ensp;
+## Non-interactive / CI mode
 
-### Workspace Mode
+For automation and CI/CD:
 
-Open a unified workspace with all tools available:
+```shell
+# Run a specific task
+code --no-approval "run tests and fix any failures"
 
-```bash
-dev workspace
-```
+# Generate reports
+code --read-only "analyze code quality and generate report"
 
-Features:
-- Integrated shell, editor, browser, and planner
-- Persistent session state
-- Tool switching without context loss
-- Unified command interface
-
-### MCP Server Configuration
-
-Configure MCP servers in `.mcp.json`:
-
-```json
-{
-  "servers": [
-    {
-      "name": "filesystem",
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-filesystem"],
-      "env": { "MCP_ALLOWED_PATHS": "." }
-    },
-    {
-      "name": "git",  
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-git"]
-    },
-    {
-      "name": "custom",
-      "command": "python",
-      "args": ["my-mcp-server.py"],
-      "transport": "stdio"
-    }
-  ]
-}
+# Batch processing
+code --config output_format=json "list all TODO comments"
 ```
 
-## Architecture
-
-### Core Components
-
-1. **Editor Module** (`lib/editor.ts`)
-   - View, create, and edit files
-   - String replacement with validation
-   - Chunk localization for large files
-   - Undo/redo functionality
-
-2. **MCP Client** (`lib/mcp-client.ts`)
-   - Stdio and WebSocket transports
-   - Dynamic tool discovery
-   - Session management
-   - JSON-RPC protocol
-
-3. **CodeAct Agent** (`lib/code-act-agent.ts`)
-   - Automatic task planning
-   - Parallel step execution
-   - Self-correction with retries
-   - State and observation tracking
-
-4. **Peer Agent Network** (`lib/peer-agent-network.ts`)
-   - Agent spawning strategies
-   - Inter-agent communication
-   - MCP tool exposure
-   - Swarm optimization
-
-5. **Agent Loop** (`lib/agent-loop.ts`)
-   - LLM provider abstraction
-   - Browser automation
-   - Tool orchestration
-   - Execution management
-
-## API Usage
-
-### Programmatic Access
-
-```typescript
-import { CodeActAgent, PeerAgentNetwork, ConfigurableAgentLoop } from '@hanzo/dev';
-
-// Create an agent
-const agent = new CodeActAgent('my-agent', functionCallingSystem);
-await agent.plan('Fix the login bug');
-const result = await agent.execute();
-
-// Create a peer network
-const network = new PeerAgentNetwork();
-await network.spawnAgentsForCodebase('./src', 'claude-code', 'one-per-file');
-
-// Configure agent loop
-const loop = new ConfigurableAgentLoop({
-  provider: {
-    name: 'Claude',
-    type: 'anthropic',
-    apiKey: process.env.ANTHROPIC_API_KEY,
-    model: 'claude-3-opus-20240229',
-    supportsTools: true,
-    supportsStreaming: true
-  },
-  maxIterations: 10,
-  enableMCP: true,
-  enableBrowser: true,
-  enableSwarm: true
-});
-
-await loop.initialize();
-await loop.execute('Refactor the authentication module');
-```
+&ensp;
+## Model Context Protocol (MCP)
+
+Every Code supports MCP for extended capabilities:
 
-### Custom Tool Registration
-
-```typescript
-import { FunctionCallingSystem } from '@hanzo/dev';
-
-const functionCalling = new FunctionCallingSystem();
-
-// Register custom tool
-functionCalling.registerTool({
-  name: 'my_custom_tool',
-  description: 'Does something special',
-  parameters: {
-    type: 'object',
-    properties: {
-      input: { type: 'string', description: 'Tool input' }
-    },
-    required: ['input']
-  },
-  handler: async (args) => {
-    // Tool implementation
-    return { success: true, result: `Processed: ${args.input}` };
-  }
-});
+- **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"]
 ```
 
-## Performance & Benchmarks
+&ensp;
+## Configuration
 
-### SWE-bench Results
+Main config file: `~/.code/config.toml`
 
-Our platform is continuously evaluated on the Software Engineering Benchmark:
+> [!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/`.
 
-| Metric | Score | Details |
-|--------|-------|---------|
-| Success Rate | 15%+ | Solving real GitHub issues |
-| Avg Resolution Time | 90s | Per task completion |
-| Cost Efficiency | $0.10/task | Using swarm optimization |
-| Parallel Speedup | 4.2x | With 5-agent swarm |
+```toml
+# Model settings
+model = "gpt-5.1"
+model_provider = "openai"
 
-### Running Benchmarks
+# Behavior
+approval_policy = "on-request"  # untrusted | on-failure | on-request | never
+model_reasoning_effort = "medium" # low | medium | high
+sandbox_mode = "workspace-write"
 
-```bash
-# Run full SWE-bench evaluation
-dev --benchmark swe-bench
-
-# Run on specific dataset
-dev --benchmark swe-bench --dataset lite
-
-# Custom benchmark configuration
-dev --benchmark swe-bench \
-  --agents 10 \
-  --parallel \
-  --timeout 300 \
-  --output results.json
+# 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"
 ```
 
-### Performance Optimizations
+### Environment variables
 
-1. **Swarm Intelligence**: Multiple agents work on different aspects simultaneously
-2. **Local Orchestration**: Hanzo Zen manages coordination locally, reducing API calls
-3. **Smart Caching**: MCP tools cache results across agents
-4. **Parallel Execution**: CodeAct identifies independent steps and runs them concurrently
+- `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
 
-## Testing
+&ensp;
+## FAQ
 
-```bash
-# Run all tests
-npm test
+**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.
 
-# Run specific test suite
-npm run test:swe-bench
+**Can I use my existing Codex configuration?**
+> 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.
 
-# Watch mode
-npm run test:watch
+**Does this work with ChatGPT Plus?**
+> Absolutely. Use the same "Sign in with ChatGPT" flow as the original.
 
-# Coverage report
-npm run test:coverage
-```
+**Is my data secure?**
+> Yes. Authentication stays on your machine, and we don't proxy your credentials or conversations.
 
+&ensp;
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Every Code maintains compatibility with upstream while adding community-requested features.
 
-### Development Setup
+### Development workflow
 
 ```bash
-# Clone the repository
-git clone https://github.com/hanzoai/dev.git
-cd dev/packages/dev
-
-# Install dependencies
+# Clone and setup
+git clone https://github.com/just-every/code.git
+cd code
 npm install
 
-# Run in development mode
-npm run dev
+# Build (use fast build for development)
+./build-fast.sh
+
+# Run locally
+./code-rs/target/dev-fast/code
+```
 
-# Build
-npm run build
+#### Git hooks
 
-# Run tests
-npm test
+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
+
+
+&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).
+
+&ensp;
 ## License
 
-MIT © [Hanzo AI](https://hanzo.ai)
+Apache 2.0 - See [LICENSE](LICENSE) file for details.
 
-## Acknowledgments
+Every Code is a community fork of the original Codex CLI. We maintain compatibility while adding enhanced features requested by the developer community.
 
-Built by [Hanzo AI](https://hanzo.ai) - Advancing AI infrastructure for developers worldwide.
+&ensp;
+---
+**Need help?** Open an issue on [GitHub](https://github.com/just-every/code/issues) or check our documentation.