No single AI model should be both the maker and the checker. Crossagent is a cross-model agent orchestrator that routes planning and implementation to one AI, then review and verification to another — the same maker-checker principle that makes human code review effective, applied to AI agents.
┌────────┐ plan.md ┌────────┐ review.md ┌────────┐ changes ┌────────┐
│ 1.PLAN ├──────────►│2.REVIEW├────────────►│3.IMPL ├─────────►│4.VERIFY│
│ Claude │ │ Codex │ │ Claude │ │ Codex │
└────────┘ └────────┘ └────────┘ └────────┘
The pipeline-timeline UI running a live workflow — phase execution in the terminal drawer, real-time status on the board, and rendered artifacts in the reader.
AI coding agents are powerful — but trusting a single model to plan, implement, and judge its own work is like letting a student grade their own exam. Crossagent exists because no single AI model should be both the maker and the checker.
We couldn't find any tool that addressed all of these problems at once, so we built one.
This is the primary driver behind Crossagent. Most AI coding tools use one model for everything. Crossagent breaks that pattern by routing execution and review to different AI providers — Claude builds, Codex reviews (or vice versa). A second model with a different training lineage catches assumptions, blind spots, and failure modes that self-review misses. This maker-checker separation is the same principle that makes code review between humans effective, applied to AI agents.
Every input and output — plans, reviews, prompts, memory — is a plain file you can inspect, edit, and version-control. Nothing is hidden in opaque embeddings or databases. You can read exactly what your agents see and override anything before the next phase runs.
No more clicking "approve" on every file edit. Crossagent runs agents in full auto-execute mode within a sandbox that only has access to the directories you explicitly specify. If the verification phase fails, it automatically retries the implement-verify cycle. Hands-off execution with guardrails — not hands-off with fingers crossed.
Every workflow builds knowledge. Crossagent maintains three tiers of persistent memory — global, project, and workflow — and feeds it back into future runs automatically. Codebase patterns, conventions, lessons learned, and domain context compound across repositories. The tool gets smarter with every run instead of starting from zero each time.
Crossagent runs on top of CLI tools that use subscription-based plans (Claude Code via Claude Pro/Max, Codex CLI via ChatGPT Pro), not per-token API billing. No surprise invoices, no cost anxiety mid-workflow. You know what you're paying before you start.
- Atomic State Management: All state transitions (phase bumps, configuration changes, memory updates) use atomic writes and file locking. This prevents data corruption even if the CLI and Web UI access the same workflow simultaneously.
- Multi-Round Iteration: Finished a feature? Use the Follow-up feature to archive all current artifacts into a numbered "round" and reset to Phase 1. Subsequent rounds automatically carry over relevant context from previous iterations.
- Searchable Workflow Picker: Manage hundreds of workflows with ease using the project-grouped, searchable picker. Supports type-to-filter and full keyboard navigation.
- Deep Observability: Every retry attempt is preserved. View archived
plan.mdversions and their corresponding chat logs directly in the Web UI to understand exactly why a phase was retried. - Pipeline-Timeline UI: The default web layout shows all four phases as a progress board with live status indicators, a collapsible terminal drawer, and an artifact reader with metadata rail — density and drawer state persist across reloads.
- Concurrent Session Safety: The server atomically deduplicates spawn requests; a second browser tab connecting to the same workflow phase reattaches to the running session rather than spawning a duplicate PTY.
- Claude Code CLI and Codex CLI — both authenticated
brew tap grikwong/tap
brew install crossagentRequires Go 1.25+.
git clone https://github.com/grikwong/crossagent.git
cd crossagent
make install # Builds and installs to /usr/local/bin (may prompt for sudo)More install options
make build # Compile without installing
make install PREFIX=$HOME/.local # User-local (~/.local/bin)
go install github.com/grikwong/crossagent/cmd/crossagent@latestWindows: Use WSL and follow the steps above. Native Windows is not supported (Unix PTY dependency).
make start # Build + launch Web UI at http://localhost:3456
make check # Preflight checks + auto-install + build (no server launch)
crossagent serve --open # Or run directly with browser auto-openOn macOS, make check will detect missing dependencies and offer to install them automatically via Homebrew. Set CROSSAGENT_AUTO_INSTALL=1 to skip the prompt (auto-yes) or CROSSAGENT_AUTO_INSTALL=0 for report-only mode.
- Click + — enter a name, repo path, and feature description.
- Run Plan — Claude writes
plan.md. Review it in the artifact sidebar. - Run Review — Codex reviews the plan and writes
review.md. - Run Implement — Claude implements per the reviewed plan.
- Run Verify — Codex examines the diff and writes
verify.md.
| Phase | Agent | Produces | Key outputs |
|---|---|---|---|
| 1. Plan | Claude Code | plan.md |
Overview, affected files, implementation phases, test gates, risks |
| 2. Review | Codex CLI | review.md |
Edge cases, correctness, security, verdict (APPROVE / APPROVE WITH CHANGES / REQUEST REWORK) |
| 3. Implement | Claude Code | Code changes | Reads plan + review. Use --phase N for sub-phases |
| 4. Verify | Codex CLI | verify.md |
Status (PASS / FAIL), plan drift, issues, ship recommendation |
The default layout is the pipeline-timeline view: a top titlebar with workflow selector and search, a phase board showing all four phases in order, a collapsible terminal drawer at the bottom, and an artifact reader with an info rail on the right.
| Control | Action |
|---|---|
| Run [Phase] | Starts the current phase in the embedded terminal drawer |
| Advance | Manually advance to the next phase |
| Done | Mark the workflow complete |
| Artifact reader | Click any phase card or artifact tab to view rendered markdown |
| Terminal drawer | Collapse or expand the terminal (state persists across reloads) |
| Workflow selector | Switch between workflows; supports type-to-filter search |
| Description (pencil) | Edit the feature description — only available before the workflow has started |
Environment variables: CROSSAGENT_PORT (default 3456), CROSSAGENT_HOME (default ~/.crossagent).
The CLI is the engine under the Web UI. It also works standalone.
crossagent new <name> [--repo <path>] [--add-dir <path>]...
crossagent status [--json]
crossagent list [--json]
crossagent use <name>
crossagent reset <name>crossagent plan [--force]
crossagent review [--force]
crossagent implement [--phase <n>] [--force]
crossagent verify [--force]
crossagent next # Run whatever comes nextWorkflows are grouped under projects (defaults to default). Projects provide scoped memory shared across related workflows.
crossagent projects list [--json]
crossagent projects new <name>
crossagent projects delete <name>
crossagent projects show <name> [--json]
crossagent projects rename <old> <new>
crossagent projects suggest [--description <text>] [--json]
crossagent move <workflow> --project <project>Three tiers: workflow (memory.md), project (~/.crossagent/projects/<name>/memory/), and global (~/.crossagent/memory/).
crossagent memory show [--global|--project [name]] [--json]
crossagent memory list [--global|--project [name]] [--json]
crossagent memory edit [--global|--project [name]]Ships with builtin claude, codex, and gemini agents. Register custom agents and reassign phases:
crossagent agents list [--json]
crossagent agents add <name> --adapter <claude|codex|gemini> [--command <cmd>] [--display-name <name>]
crossagent agents remove <name>
crossagent agents show [--workflow <name>] [--json]
crossagent agents assign <phase> <agent> [--workflow <name>]
crossagent agents reset <phase> [--workflow <name>]
crossagent agents autoselect [--workflow <name>] [--json]Adapters are constrained to claude, codex, or gemini — the three
supported CLI protocols (each encodes a different set of flag
conventions, sandbox controls, and prompt-passing mechanics). Pick the
adapter that matches the binary you're wiring up. Custom agents can
override the binary path via --command (for example to run a specific
Gemini binary name):
crossagent agents add gemini-pro --adapter gemini --command gemini --display-name "Gemini Pro"
crossagent agents assign plan gemini-proagents autoselect picks an agent for each phase of a workflow based on
the currently registered agents (case-insensitive substring match on name
and display name):
| Phase | Preference order |
|---|---|
| plan | gemini → claude → codex → first |
| review | codex/gpt → claude → first |
| implement | claude → codex → first |
| verify | gemini → codex → claude → first |
With only the builtin agents installed, the heuristic picks gemini for
plan and verify (since a gemini builtin is now registered), while
implement stays on claude and review stays on codex. If the
gemini binary isn't installed on PATH, launching those phases will
surface a "command not found" error — reassign with agents assign or
remove the gemini builtin expectation by picking an explicit agent per
phase.
The Web UI exposes the same controls:
- Models button in the top bar opens a modal for listing, adding, and deleting agents (builtins cannot be deleted).
- The ⚙ gear in the sidebar Phases header opens the same modal scrolled to per-phase assignment dropdowns for the active workflow.
- The ✨ Auto-select button inside the modal runs
agents autoselectfor the active workflow.
crossagent advance # Manually advance phase
crossagent done # Mark workflow complete
crossagent log # Display all artifacts
crossagent open # Open workflow directory
crossagent phase-cmd <phase> --json # Launch params without executing (used by Web UI)crossagent new cross-repo-feature \
--repo ~/projects/backend \
--add-dir ~/projects/frontend \
--add-dir ~/projects/shared-typesAll agents get access to all specified directories.
- Don't skip review. It catches architectural issues before you spend time implementing.
- Use sub-phases. Break implementation into small testable chunks with
--phase N. - Read the artifacts. They're your documentation — plan, review, verification report.
- Force re-runs. If a phase produced poor results, use
--forceto redo it.
Crossagent is free, open source, and local-first. It is usable today but should be treated as operator tooling for technically capable users who can install the required CLIs and review generated output.
Crossagent is a single Go binary with an embedded HTTP/WebSocket server and vanilla JS frontend. See docs/architecture.md for the full architecture document.
| Layer | Role | Location |
|---|---|---|
| Core | Go binary — state, agents, prompts, judging | cmd/, internal/ |
| Integration | --json output for machine consumption |
CLI flags |
| Web UI | Embedded Go HTTP/WebSocket server + vanilla JS frontend | internal/web/ |
Two external Go dependencies: github.com/creack/pty (Unix PTY allocation) and github.com/gorilla/websocket (WebSocket server for terminal streaming).
Source layout
crossagent/
├── cmd/crossagent/main.go # CLI entry point (includes serve command)
├── internal/
│ ├── state/ # Config, workflow, project, memory
│ ├── agent/ # Agent registry, phase assignments, launcher
│ ├── cli/ # JSON types, ordered serialization
│ ├── prompt/ # Template-based prompt generation & memory context
│ │ └── templates/ # Embedded Go templates
│ ├── judge/ # Verdict parsing for review & verify
│ └── web/ # Embedded HTTP/WebSocket server + frontend assets
│ ├── server.go # HTTP server setup, routes, static file serving
│ ├── api.go # REST API handlers (23 endpoints)
│ ├── terminal.go # WebSocket + PTY handler, chat history capture
│ ├── session.go # SessionManager — PTY session lifecycle & spawn dedup
│ ├── embed.go # go:embed directive for frontend assets
│ └── public/ # Vanilla JS frontend (HTML, CSS, JS, vendored libs)
│ ├── js/ # ES modules (state.js, api.js, util.js, derive.js, …)
│ │ └── regions/ # Per-region components (pipeline-board, terminal-drawer, …)
│ ├── pipeline.css # Pipeline-timeline layout styles
│ └── terminal-drawer.css
├── web/ # Legacy Node.js server (retained for reference)
├── test/ # Integration tests
├── docs/ # Architecture document
└── Makefile
State is stored in ~/.crossagent/ — workflows, projects, agents, and memory tiers are all plain files.
Agent CLI not found — Crossagent requires claude and codex CLI tools to be installed and authenticated. Install Claude Code and Codex CLI, then run each once to authenticate.
Web UI not loading — Check if port 3456 is already in use: lsof -i :3456. Use CROSSAGENT_PORT=8080 crossagent serve to specify an alternate port. If the binary was built without the embedded frontend, rebuild with make build.
Permission errors on ~/.crossagent/ — Crossagent now automatically canonicalizes all symlinks (resolving /Users vs /private/var/users on macOS) and explicitly authorizes the ~/.crossagent home directory to avoid sandbox write failures. If issues persist, ensure the directory is owned by your user: ls -la ~/.crossagent. Fix with chown -R $(whoami) ~/.crossagent if needed.
PTY session failures — PTY allocation requires a Unix-like OS (macOS or Linux). Windows is not natively supported; use WSL. If PTY errors persist, ensure your terminal emulator supports pseudo-terminals.
make build # Compile
make test # Unit + integration tests
make clean # Remove build artifacts
make check # Preflight checks + auto-install + build
make start # Preflight checks + auto-install + build + launch Web UImake uninstall # Removes CLI binary
rm -rf ~/.crossagent # Removes all workflow dataAGPL-3.0-or-later — free for commercial use. If you modify Crossagent and serve it to users (including over a network), you must share the source under the same license.
See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Open an issue before large changes.
See CONTRIBUTORS.md.
Report vulnerabilities via SECURITY.md. Do not open public issues for undisclosed vulnerabilities.