codefleet 0.3.0__tar.gz

codefleet-0.3.0/.env.example

@@ -0,0 +1,17 @@
+# Base directory for fleet data (default: ~/.codex-fleet)
+FLEET_BASE_DIR=~/.codex-fleet
+
+# Default Codex model
+FLEET_DEFAULT_MODEL=gpt-5.4
+
+# Model reasoning effort (xhigh, high, medium, low)
+FLEET_REASONING_EFFORT=xhigh
+
+# Default worker timeout in seconds
+FLEET_DEFAULT_TIMEOUT=600
+
+# Maximum concurrent workers
+FLEET_MAX_CONCURRENT=10
+
+# Comma-separated list of allowed repo paths (empty = allow all)
+FLEET_ALLOWED_REPOS=

codefleet-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short
+
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        run: |
+          python -m pytest tests/ --cov=codefleet --cov-report=term-missing --cov-fail-under=80

codefleet-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.coverage
+.pytest_cache/
+.DS_Store
+*.db
+demo/*.cast
+demo/*.svg

codefleet-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codefleet-0.3.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: codefleet
+Version: 0.3.0
+Summary: Orchestrate fleets of AI coding agents (Codex, Gemini, Claude) with multi-stage workflows
+Project-URL: Homepage, https://github.com/techinfobel/codefleet
+Project-URL: Repository, https://github.com/techinfobel/codefleet
+Project-URL: Issues, https://github.com/techinfobel/codefleet/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,codex,gemini,mcp,orchestration,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'

codefleet-0.3.0/README.md

@@ -0,0 +1,260 @@
+<p align="center">
+  <h1 align="center">codefleet</h1>
+  <p align="center">Orchestrate fleets of AI coding agents across providers</p>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/codefleet"><img src="https://img.shields.io/pypi/v/codefleet" alt="PyPI"></a>
+  <a href="https://pypi.org/project/codefleet"><img src="https://img.shields.io/pypi/pyversions/codefleet" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+</p>
+
+---
+
+An [MCP server](https://modelcontextprotocol.io/) that lets **Claude Code** dispatch work to **Codex**, **Gemini**, and **Claude** agents — running side-by-side in isolated git worktrees, with multi-stage workflows where agents collaborate across provider boundaries.
+
+```
+Claude Code  ──>  codefleet  ──>  Codex worker   (implement)
+                             ──>  Claude worker   (review)
+                             ──>  Codex worker    (refine from review)
+```
+
+<p align="center">
+  <img src="demo/demo.gif" alt="codefleet demo" width="700">
+</p>
+
+## Why
+
+You have access to multiple AI coding agents. Each has different strengths. But there's no way to make them **work together** on the same codebase, passing results between stages, without manual copy-paste.
+
+codefleet fixes this. Define a workflow, pick which agent runs each stage, and let the results flow automatically.
+
+## Install
+
+```bash
+uv pip install codefleet
+```
+
+Or with pip:
+```bash
+pip install codefleet
+```
+
+### Prerequisites
+
+At least one of these AI CLIs must be installed:
+
+| Agent | Install | Verify |
+|-------|---------|--------|
+| **Codex** | `npm i -g @openai/codex` | `codex --version` |
+| **Gemini** | `npm i -g @anthropic-ai/gemini-cli` | `gemini --version` |
+| **Claude** | [claude.ai/download](https://claude.ai/download) | `claude --version` |
+
+Plus **Git** and **Python 3.11+**.
+
+## Register with Claude Code
+
+```bash
+claude mcp add codefleet -- uvx codefleet
+```
+
+That's it. Restart Claude Code and the tools are available.
+
+**With options:**
+```bash
+claude mcp add codefleet \
+  --env FLEET_ALLOWED_REPOS=/path/to/repo-a,/path/to/repo-b \
+  --env FLEET_MAX_SPAWN_DEPTH=2 \
+  -- uvx codefleet
+```
+
+**Verify:**
+```bash
+claude mcp list
+```
+
+## Quick Start
+
+Start Claude Code and ask it to use multi-agent workflows:
+
+> "Use codefleet to add input validation to the registration endpoint. Have Codex implement it, Claude review it, then Codex refine based on the review."
+
+Claude will call `create_workflow` with a 3-stage pipeline. Each stage runs the right agent automatically.
+
+### Single Worker
+
+For simple one-off tasks, use `create_worker` directly:
+
+> "Spin up a Codex worker to add rate limiting to the API gateway"
+
+> "Launch a Claude worker to write tests for the auth module"
+
+> "Use a Gemini worker to refactor the database models"
+
+## Workflows
+
+The workflow engine runs a DAG of stages. Each stage picks an executor, gets a prompt template with variables from previous stages, and runs in an isolated (or inherited) git worktree.
+
+### Write -> Review -> Refine
+
+The core pattern: one agent implements, another reviews, the first refines.
+
+```json
+{
+  "name": "write-review-refine",
+  "task_prompt": "Add input validation to the registration endpoint",
+  "stages": [
+    {
+      "name": "implement",
+      "executor": "codex",
+      "prompt_template": "{task_prompt}",
+      "worktree_strategy": "new",
+      "depends_on": []
+    },
+    {
+      "name": "review",
+      "executor": "claude",
+      "prompt_template": "Review these changes:\n{stage_0_summary}\nFiles: {stage_0_files}",
+      "worktree_strategy": "inherit",
+      "depends_on": [0]
+    },
+    {
+      "name": "refine",
+      "executor": "codex",
+      "prompt_template": "Address this review:\n{stage_1_summary}\n{stage_1_next_steps}",
+      "worktree_strategy": "inherit",
+      "depends_on": [1]
+    }
+  ]
+}
+```
+
+### Parallel Fan-Out + Review
+
+Multiple agents work in parallel, then a reviewer checks all of them:
+
+```json
+{
+  "stages": [
+    {"name": "module-a", "executor": "codex", "worktree_strategy": "new", "depends_on": []},
+    {"name": "module-b", "executor": "gemini", "worktree_strategy": "new", "depends_on": []},
+    {
+      "name": "review",
+      "executor": "claude",
+      "prompt_template": "Review both:\nA: {stage_0_summary}\nB: {stage_1_summary}",
+      "worktree_strategy": "new",
+      "depends_on": [0, 1]
+    }
+  ]
+}
+```
+
+### Competitive Implementation
+
+Two agents implement the same thing, then a judge picks the better one:
+
+```json
+{
+  "stages": [
+    {"name": "codex-impl", "executor": "codex", "prompt_template": "{task_prompt}", "worktree_strategy": "new", "depends_on": []},
+    {"name": "claude-impl", "executor": "claude", "prompt_template": "{task_prompt}", "worktree_strategy": "new", "depends_on": []},
+    {
+      "name": "evaluate",
+      "executor": "claude",
+      "prompt_template": "Compare:\nA: {stage_0_summary}\nB: {stage_1_summary}\nWhich is better?",
+      "worktree_strategy": "new",
+      "depends_on": [0, 1]
+    }
+  ]
+}
+```
+
+See [`examples/`](examples/) for complete, copy-paste-ready workflow files.
+
+## Template Variables
+
+Available in stage `prompt_template` strings:
+
+| Variable | Value |
+|----------|-------|
+| `{task_prompt}` | The workflow's top-level task description |
+| `{stage_N_summary}` | Summary from stage N's result |
+| `{stage_N_files}` | Comma-separated list of files changed in stage N |
+| `{stage_N_next_steps}` | Suggested next steps from stage N |
+| `{stage_N_status}` | `"completed"` or `"blocked"` |
+| `{stage_N_result}` | Full result JSON from stage N |
+
+## MCP Tools
+
+### Workers
+
+| Tool | Description |
+|------|-------------|
+| `healthcheck` | Verify codefleet, agent CLIs, and Git are available |
+| `create_worker` | Launch a single agent in an isolated git worktree |
+| `get_worker_status` | Check worker status |
+| `list_workers` | List workers, optionally filtered by status |
+| `collect_worker_result` | Get parsed results and optional log tails |
+| `cancel_worker` | Cancel a running worker |
+| `cleanup_worker` | Remove worktree, branch, and artifacts |
+
+### Workflows
+
+| Tool | Description |
+|------|-------------|
+| `create_workflow` | Start a multi-stage DAG workflow |
+| `get_workflow_status` | Check workflow and per-stage status |
+| `list_workflows` | List workflows with optional status filter |
+| `cancel_workflow` | Cancel all running stages |
+| `collect_workflow_result` | Get final or all-stage results |
+| `cleanup_workflow` | Clean up all worktrees and branches |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FLEET_DEFAULT_EXECUTOR` | `codex` | Default agent: `codex`, `gemini`, or `claude` |
+| `FLEET_DEFAULT_MODEL` | `gpt-5.4` | Default Codex model |
+| `FLEET_GEMINI_DEFAULT_MODEL` | `gemini-3.1-pro-preview` | Default Gemini model |
+| `FLEET_CLAUDE_DEFAULT_MODEL` | `claude-sonnet-4-6` | Default Claude model |
+| `FLEET_DEFAULT_TIMEOUT` | `600` | Per-worker timeout (seconds) |
+| `FLEET_MAX_CONCURRENT` | `10` | Max simultaneous workers |
+| `FLEET_MAX_SPAWN_DEPTH` | `2` | How deep agents can recursively spawn sub-agents |
+| `FLEET_ALLOWED_REPOS` | *(all)* | Comma-separated allowlist of repo paths |
+| `FLEET_BASE_DIR` | `~/.codex-fleet` | Data directory for workers and DB |
+
+## How It Works
+
+1. **Isolation** — each worker gets its own git worktree and branch (`{executor}/{task}/{id}`)
+2. **Supervision** — background threads monitor processes for completion/timeout
+3. **Structured output** — every agent writes a `result.json` with summary, files changed, test results, and next steps
+4. **Durability** — all state lives in SQLite (WAL mode), survives crashes and restarts
+5. **Concurrency control** — configurable limits on concurrent workers and spawn depth
+
+## Development
+
+```bash
+git clone https://github.com/techinfobel/codefleet
+cd codefleet
+uv pip install -e ".[dev]"
+python -m pytest tests/ -v          # 187 tests
+python -m pytest tests/ --cov       # 93% coverage
+```
+
+## Recording the Demo
+
+```bash
+# Install asciinema + agg (for GIF conversion)
+brew install asciinema
+cargo install --git https://github.com/asciinema/agg
+
+# Record
+asciinema rec demo/demo.cast -c "python demo/demo.py"
+
+# Convert to GIF
+agg demo/demo.cast demo/demo.gif --cols 80 --rows 24
+```
+
+## License
+
+MIT

codefleet-0.3.0/demo/demo.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+Simulated demo for asciinema/terminal recording.
+
+Run: python demo/demo.py
+Record: asciinema rec demo.cast -c "python demo/demo.py"
+Convert: agg demo.cast demo.gif  (or svg-term --in demo.cast --out demo.svg)
+"""
+
+import sys
+import time
+
+# ANSI colors
+BOLD = "\033[1m"
+DIM = "\033[2m"
+GREEN = "\033[32m"
+BLUE = "\033[34m"
+CYAN = "\033[36m"
+YELLOW = "\033[33m"
+MAGENTA = "\033[35m"
+RESET = "\033[0m"
+CHECK = f"{GREEN}\u2713{RESET}"
+SPIN = ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"]
+
+
+def typewrite(text, delay=0.03):
+    for ch in text:
+        sys.stdout.write(ch)
+        sys.stdout.flush()
+        time.sleep(delay)
+    print()
+
+
+def spin_wait(msg, duration=1.5, result="done"):
+    frames = SPIN
+    end_time = time.monotonic() + duration
+    i = 0
+    while time.monotonic() < end_time:
+        sys.stdout.write(f"\r  {CYAN}{frames[i % len(frames)]}{RESET} {msg}")
+        sys.stdout.flush()
+        time.sleep(0.1)
+        i += 1
+    sys.stdout.write(f"\r  {CHECK} {msg} {DIM}({result}){RESET}\n")
+    sys.stdout.flush()
+
+
+def main():
+    print()
+    print(f"  {BOLD}codefleet{RESET} {DIM}v0.3.0{RESET} \u2014 orchestrate fleets of AI coding agents")
+    print()
+    time.sleep(0.5)
+
+    # Show the workflow being created
+    print(f"  {BOLD}Workflow:{RESET} write \u2192 review \u2192 refine")
+    print(f"  {DIM}Task: Add input validation to the registration endpoint{RESET}")
+    print()
+    time.sleep(0.3)
+
+    # Stage 1: Implement (Codex)
+    print(f"  {YELLOW}Stage 1/3{RESET} \u2502 {BOLD}implement{RESET} {DIM}(codex / gpt-5.4){RESET}")
+    spin_wait("Creating worktree", 0.8, "codex/implement/w_a1b2c3")
+    spin_wait("Codex writing code", 2.0, "4 files changed")
+    spin_wait("Running tests", 1.0, "12 passed")
+    print(f"         {CHECK} {GREEN}completed{RESET} \u2014 Added validation to register(), login(), update_profile()")
+    print()
+    time.sleep(0.3)
+
+    # Stage 2: Review (Claude)
+    print(f"  {MAGENTA}Stage 2/3{RESET} \u2502 {BOLD}review{RESET} {DIM}(claude / claude-sonnet-4-6 / effort: high){RESET}")
+    spin_wait("Inheriting worktree from stage 1", 0.5, "same branch")
+    spin_wait("Claude reviewing changes", 2.5, "review complete")
+    print(f"         {CHECK} {GREEN}completed{RESET} \u2014 3 issues found: missing email format check, no rate limit, weak password regex")
+    print()
+    time.sleep(0.3)
+
+    # Stage 3: Refine (Codex)
+    print(f"  {BLUE}Stage 3/3{RESET} \u2502 {BOLD}refine{RESET} {DIM}(codex / gpt-5.4){RESET}")
+    spin_wait("Inheriting worktree from stage 2", 0.5, "same branch")
+    spin_wait("Codex addressing review feedback", 2.0, "3 files changed")
+    spin_wait("Running tests", 1.0, "15 passed")
+    print(f"         {CHECK} {GREEN}completed{RESET} \u2014 All 3 review issues addressed, tests updated")
+    print()
+    time.sleep(0.5)
+
+    # Summary
+    print(f"  {BOLD}{GREEN}\u2501\u2501\u2501 Workflow succeeded{RESET} {DIM}(3 stages, 2 executors, 38s){RESET}")
+    print()
+    print(f"  {DIM}Files changed:{RESET} src/auth/validators.py, src/auth/routes.py,")
+    print(f"                src/auth/tests/test_validators.py, src/auth/rate_limit.py")
+    print(f"  {DIM}Branch:{RESET}        codex/implement/w_a1b2c3")
+    print(f"  {DIM}Commits:{RESET}       3 (implement + review-fixes + refinement)")
+    print()
+
+
+if __name__ == "__main__":
+    main()