| Name | pitaya JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Pitaya — an orchestrator of AI coding agents (e.g., Claude Code, Codex CLI) with pluggable and custom strategies |
| upload_time | 2025-08-22 06:37:14 |
| maintainer | TON Studio |
| docs_url | None |
| author | TON Studio |
| requires_python | ==3.13.* |
| 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. |
| keywords |
agents
ai
automation
claude-code
codex-cli
coding
developer-tools
docker
orchestrator
tui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🎯 Pitaya
<div align="center">
**Orchestrate AI coding agents (Claude Code, Codex CLI, and more)**
[](https://www.python.org/downloads/)
[](https://www.docker.com/)
[](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).
Raw data
{
"_id": null,
"home_page": null,
"name": "pitaya",
"maintainer": "TON Studio",
"docs_url": null,
"requires_python": "==3.13.*",
"maintainer_email": null,
"keywords": "agents, ai, automation, claude-code, codex-cli, coding, developer-tools, docker, orchestrator, tui",
"author": "TON Studio",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/eb/b1/86e46a1469340f9d212693860973918f5967bd7f5e38a7b4a9d88b9b4da4/pitaya-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfaf Pitaya\n\n<div align=\"center\">\n\n**Orchestrate AI coding agents (Claude Code, Codex CLI, and more)**\n\n[](https://www.python.org/downloads/)\n[](https://www.docker.com/)\n[](LICENSE)\n\n</div>\n\n> Note: Pitaya is in public beta. Interfaces and defaults may change between releases.\n\n## Overview\n\nPitaya 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.\n\n- Parallel strategies (simple, best-of-n, iterative, bug-finding, doc-review)\n- Clean TUI with live progress, costs, and artifacts\n- Orchestrates Claude Code, Codex CLI, and others via plugins\n- Define arbitrary custom strategies (Python) for complex flows\n- Strict \u201cagent commits only\u201d mode; artifact-first, no destructive merges\n- Resumable runs with detailed logs and events\n\n## Quick Start\n\nPrerequisites\n\n- Docker Desktop or Docker Engine running\n- Python 3.13\n- Git repository (the tool operates inside your repo)\n\nInstall (choose one)\n\n- From PyPI (recommended):\n\n ```bash\n pip install pitaya\n # or\n pipx install pitaya\n # or (uv as a tool)\n uv tool install pitaya\n ```\n\n Upgrade:\n\n ```bash\n pip install -U pitaya\n # or\n pipx upgrade pitaya\n # or\n uv tool upgrade pitaya\n ```\n\n- From a local clone (editable dev install):\n\n ```bash\n python -m venv .venv && source .venv/bin/activate\n pip install -U pip\n pip install -e .\n ```\n\nAuthenticate\n\n- Anthropic (Claude Code): set either `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY`\n- OpenAI (Codex plugin): set `OPENAI_API_KEY` (and optionally `OPENAI_BASE_URL`)\n\nHello world\n\n```bash\npitaya \"implement authentication\" --strategy simple\n```\n\nBest-of-N with scoring\n\n```bash\npitaya \"fix bug in user.py\" --strategy best-of-n -S n=5\n```\n\nDoc review (N reviewers per page, immediate validators, composer)\n\n```bash\npitaya \"Review docs\" --strategy doc-review -S pages_file=pages.yml -S reviewers_per_page=2\n```\n\nHeadless JSON output\n\n```bash\npitaya \"add tests\" --no-tui --output json\n```\n\nOverride Docker image\n\n```bash\npitaya \"task\" --plugin codex --docker-image ghcr.io/me/codex-cli:mytag\n```\n\nResume a run\n\n```bash\npitaya --resume run_20250114_123456\n```\n\n## CLI Essentials\n\nThe CLI is designed to be discoverable and production-ready. Run `pitaya --help` to see grouped options and examples.\n\nHighlights\n\n- Strategy: `--strategy <name>` (use `-S key=value` for strategy params)\n- Model: `--model <alias>` (aliases resolved via `models.yaml` when applicable)\n- Plugin: `--plugin <claude-code|codex>`\n- Parallel runs: `--runs <N>`\n- TUI controls: `--no-tui`, `--output <streaming|json|quiet>`\n- Maintenance: `--list-runs`, `--show-run <id>`, `--prune`, `--clean-containers <id>`\n- Docker image override: `--docker-image <repo/name:tag>`\n\nTUI viewer (offline or live)\n\n```bash\npitaya-tui --run-id run_20250114_123456\n# or\npitaya-tui --events-file logs/run_20250114_123456/events.jsonl --output streaming\n```\n\n## Strategies\n\n- simple: one agent, one branch\n- best-of-n: spawn N agents, score and pick the highest-rated branch\n- iterative: loop with propose \u2192 review \u2192 refine (configurable iterations)\n- bug-finding: search for issues across the repo and propose fixes\n- doc-review: reviewers per page \u2192 validators per reviewer \u2192 compose final report\n - Pass pages via `-S pages_file=...`; set `-S reviewers_per_page=<n>` (default 1)\n - Reviewer reports: `reports/doc-review/raw/REPORT_{slug}__r{n}.md`\n - Final report: `reports/doc-review/REPORT.md`\n\nPass strategy options with `-S key=value`. Example: `-S n=5 -S scorer_prompt=\"evaluate correctness\"`.\n\n## Configuration\n\nYou can run everything from the CLI, or add an optional `pitaya.yaml` to set defaults:\n\n```yaml\nmodel: sonnet\nplugin_name: claude-code\n\nrunner:\n timeout: 3600\n cpu_limit: 2\n memory_limit: 4g\n network_egress: online # online|offline|proxy\n docker_image: ghcr.io/me/codex-cli:mytag # optional global override\n\norchestration:\n max_parallel_instances: auto\n branch_namespace: hierarchical\n snapshot_interval: 30\n\nstrategies:\n best-of-n:\n n: 5\n doc-review:\n reviewers_per_page: 2\n```\n\nCLI overrides config; `-S` only affects the selected strategy.\n\n## Models\n\nSome plugins (e.g., Claude Code) validate model aliases via `models.yaml`. If an alias isn\u2019t defined, Pitaya warns and passes the string through to the plugin.\n\n## Docker & Plugins\n\n- Unified agent image: `pitaya-agents:latest` (includes Claude Code and Codex CLIs)\n- Plugins default to `pitaya-agents:latest`; override per run with `--docker-image <repo/name:tag>`\n- Full isolation per instance: dedicated container, workspace mount, and session volume\n\n## Logs & Artifacts\n\n- Logs: `logs/<run_id>/events.jsonl` and structured component logs\n- Results: `results/<run_id>/...`\n- Branches: `pitaya/<strategy>/<run_id>/k<short8>` (hierarchical namespace)\n- Resuming: `--resume <run_id>` picks up from the last consistent snapshot\n\n## Troubleshooting\n\n- Cannot connect to Docker: start Docker Desktop / system service; run `docker info`\n- Missing credentials: set `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` (Claude), or `OPENAI_API_KEY` (Codex)\n- Model alias not found: add it to `models.yaml` or pass a direct model ID\n- Slow or flaky network: use `--parallel conservative` or `--max-parallel <n>`\n- Clean stale state: `pitaya --prune` and `pitaya --clean-containers <run_id>`\n\n## Contributing\n\nIssues and PRs are welcome. This project is evolving\u2014feedback on UX, strategies, and plugin support is especially helpful.\n\nLocal dev quickstart\n\n```bash\npython -m venv .venv && source .venv/bin/activate\npip install -U pip\npip install -e .\n\n# Optional dev tools\npip install -U ruff black mypy pytest pytest-asyncio\n\n# Lint/format (optional)\nruff check .\nblack .\n```\n\n## Changelog\n\n- See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.\n- GitHub Releases: https://github.com/tact-lang/agent-orchestrator/releases\n\n## License\n\nMIT License \u2014 see [LICENSE](LICENSE).\n",
"bugtrack_url": null,
"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 \u201cSoftware\u201d), 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 \u201cAS IS\u201d, 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.",
"summary": "Pitaya \u2014 an orchestrator of AI coding agents (e.g., Claude Code, Codex CLI) with pluggable and custom strategies",
"version": "0.1.0",
"project_urls": {
"Issues": "https://github.com/tact-lang/agent-orchestrator/issues",
"Repository": "https://github.com/tact-lang/agent-orchestrator"
},
"split_keywords": [
"agents",
" ai",
" automation",
" claude-code",
" codex-cli",
" coding",
" developer-tools",
" docker",
" orchestrator",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1dfc5d42a00e570f567a6307e6fbb7433d605ea36f98bc76a67868c1310c1de3",
"md5": "64597dbef248edaf223e1bd867247799",
"sha256": "e8b0489fd674b32a7e39cea038ab93d732b140dea12a1015b2dafa806eef3e85"
},
"downloads": -1,
"filename": "pitaya-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64597dbef248edaf223e1bd867247799",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.13.*",
"size": 193162,
"upload_time": "2025-08-22T06:37:12",
"upload_time_iso_8601": "2025-08-22T06:37:12.126049Z",
"url": "https://files.pythonhosted.org/packages/1d/fc/5d42a00e570f567a6307e6fbb7433d605ea36f98bc76a67868c1310c1de3/pitaya-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebb186e46a1469340f9d212693860973918f5967bd7f5e38a7b4a9d88b9b4da4",
"md5": "24e05549a2bb5a0feafecd69a3886658",
"sha256": "dab485a984a2e9c6bdbf68634fbca3a9f15cb28a8aab0bda9448a7b7faa6d505"
},
"downloads": -1,
"filename": "pitaya-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "24e05549a2bb5a0feafecd69a3886658",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.13.*",
"size": 240628,
"upload_time": "2025-08-22T06:37:14",
"upload_time_iso_8601": "2025-08-22T06:37:14.210430Z",
"url": "https://files.pythonhosted.org/packages/eb/b1/86e46a1469340f9d212693860973918f5967bd7f5e38a7b4a9d88b9b4da4/pitaya-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 06:37:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tact-lang",
"github_project": "agent-orchestrator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pitaya"
}
