Metadata-Version: 2.4
Name: pitaya
Version: 0.1.0
Summary: Pitaya — an orchestrator of AI coding agents (e.g., Claude Code, Codex CLI) with pluggable and custom strategies
Project-URL: Repository, https://github.com/tact-lang/agent-orchestrator
Project-URL: Issues, https://github.com/tact-lang/agent-orchestrator/issues
Author: TON Studio
Maintainer: TON Studio
License: Copyright 2025 TON Studio
        
        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.
License-File: LICENSE
Keywords: agents,ai,automation,claude-code,codex-cli,coding,developer-tools,docker,orchestrator,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: ==3.13.*
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: click>=8.1.0
Requires-Dist: docker>=7.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=14.0.0
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: watchdog>=6.0.0
Description-Content-Type: text/markdown

# 🎯 Pitaya

<div align="center">

**Orchestrate AI coding agents (Claude Code, Codex CLI, and more)**

[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-required-blue.svg)](https://www.docker.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

</div>

> Note: Pitaya is in public beta. Interfaces and defaults may change between releases.

## Overview

Pitaya is an orchestrator for AI coding agents such as Claude Code and Codex CLI. It runs multiple agents in parallel, compares their results, and helps you pick the best outcome. Each agent works in an isolated Docker container with its own git branch, so you can explore alternative solution paths safely and quickly. You can also define arbitrary custom strategies to build your own multi-stage workflows.

- Parallel strategies (simple, best-of-n, iterative, bug-finding, doc-review)
- Clean TUI with live progress, costs, and artifacts
- Orchestrates Claude Code, Codex CLI, and others via plugins
- Define arbitrary custom strategies (Python) for complex flows
- Strict “agent commits only” mode; artifact-first, no destructive merges
- Resumable runs with detailed logs and events

## Quick Start

Prerequisites

- Docker Desktop or Docker Engine running
- Python 3.13
- Git repository (the tool operates inside your repo)

Install (choose one)

- From PyPI (recommended):

  ```bash
  pip install pitaya
  # or
  pipx install pitaya
  # or (uv as a tool)
  uv tool install pitaya
  ```

  Upgrade:

  ```bash
  pip install -U pitaya
  # or
  pipx upgrade pitaya
  # or
  uv tool upgrade pitaya
  ```

- From a local clone (editable dev install):

  ```bash
  python -m venv .venv && source .venv/bin/activate
  pip install -U pip
  pip install -e .
  ```

Authenticate

- Anthropic (Claude Code): set either `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY`
- OpenAI (Codex plugin): set `OPENAI_API_KEY` (and optionally `OPENAI_BASE_URL`)

Hello world

```bash
pitaya "implement authentication" --strategy simple
```

Best-of-N with scoring

```bash
pitaya "fix bug in user.py" --strategy best-of-n -S n=5
```

Doc review (N reviewers per page, immediate validators, composer)

```bash
pitaya "Review docs" --strategy doc-review -S pages_file=pages.yml -S reviewers_per_page=2
```

Headless JSON output

```bash
pitaya "add tests" --no-tui --output json
```

Override Docker image

```bash
pitaya "task" --plugin codex --docker-image ghcr.io/me/codex-cli:mytag
```

Resume a run

```bash
pitaya --resume run_20250114_123456
```

## CLI Essentials

The CLI is designed to be discoverable and production-ready. Run `pitaya --help` to see grouped options and examples.

Highlights

- Strategy: `--strategy <name>` (use `-S key=value` for strategy params)
- Model: `--model <alias>` (aliases resolved via `models.yaml` when applicable)
- Plugin: `--plugin <claude-code|codex>`
- Parallel runs: `--runs <N>`
- TUI controls: `--no-tui`, `--output <streaming|json|quiet>`
- Maintenance: `--list-runs`, `--show-run <id>`, `--prune`, `--clean-containers <id>`
- Docker image override: `--docker-image <repo/name:tag>`

TUI viewer (offline or live)

```bash
pitaya-tui --run-id run_20250114_123456
# or
pitaya-tui --events-file logs/run_20250114_123456/events.jsonl --output streaming
```

## Strategies

- simple: one agent, one branch
- best-of-n: spawn N agents, score and pick the highest-rated branch
- iterative: loop with propose → review → refine (configurable iterations)
- bug-finding: search for issues across the repo and propose fixes
- doc-review: reviewers per page → validators per reviewer → compose final report
  - Pass pages via `-S pages_file=...`; set `-S reviewers_per_page=<n>` (default 1)
  - Reviewer reports: `reports/doc-review/raw/REPORT_{slug}__r{n}.md`
  - Final report: `reports/doc-review/REPORT.md`

Pass strategy options with `-S key=value`. Example: `-S n=5 -S scorer_prompt="evaluate correctness"`.

## Configuration

You can run everything from the CLI, or add an optional `pitaya.yaml` to set defaults:

```yaml
model: sonnet
plugin_name: claude-code

runner:
  timeout: 3600
  cpu_limit: 2
  memory_limit: 4g
  network_egress: online  # online|offline|proxy
  docker_image: ghcr.io/me/codex-cli:mytag  # optional global override

orchestration:
  max_parallel_instances: auto
  branch_namespace: hierarchical
  snapshot_interval: 30

strategies:
  best-of-n:
    n: 5
  doc-review:
    reviewers_per_page: 2
```

CLI overrides config; `-S` only affects the selected strategy.

## Models

Some plugins (e.g., Claude Code) validate model aliases via `models.yaml`. If an alias isn’t defined, Pitaya warns and passes the string through to the plugin.

## Docker & Plugins

- Unified agent image: `pitaya-agents:latest` (includes Claude Code and Codex CLIs)
- Plugins default to `pitaya-agents:latest`; override per run with `--docker-image <repo/name:tag>`
- Full isolation per instance: dedicated container, workspace mount, and session volume

## Logs & Artifacts

- Logs: `logs/<run_id>/events.jsonl` and structured component logs
- Results: `results/<run_id>/...`
- Branches: `pitaya/<strategy>/<run_id>/k<short8>` (hierarchical namespace)
- Resuming: `--resume <run_id>` picks up from the last consistent snapshot

## Troubleshooting

- Cannot connect to Docker: start Docker Desktop / system service; run `docker info`
- Missing credentials: set `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` (Claude), or `OPENAI_API_KEY` (Codex)
- Model alias not found: add it to `models.yaml` or pass a direct model ID
- Slow or flaky network: use `--parallel conservative` or `--max-parallel <n>`
- Clean stale state: `pitaya --prune` and `pitaya --clean-containers <run_id>`

## Contributing

Issues and PRs are welcome. This project is evolving—feedback on UX, strategies, and plugin support is especially helpful.

Local dev quickstart

```bash
python -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e .

# Optional dev tools
pip install -U ruff black mypy pytest pytest-asyncio

# Lint/format (optional)
ruff check .
black .
```

## Changelog

- See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
- GitHub Releases: https://github.com/tact-lang/agent-orchestrator/releases

## License

MIT License — see [LICENSE](LICENSE).
