GitHub - tact-lang/pitaya

🎯 Pitaya

Orchestrate AI coding agents (Claude Code, Codex CLI) with pluggable strategies and a clean TUI.

Note: Pitaya is in public beta. Interfaces and defaults may evolve.

What It Does

Runs multiple agents in parallel and helps you pick the best result
Uses per‑task branches in your repo to keep alternatives safe and reviewable
Displays a clean, adaptive TUI with live progress, costs, and tokens
Supports custom Python strategies for multi‑stage workflows

Built‑in strategies: simple, scoring, best‑of‑n, iterative, bug‑finding, doc‑review

Demo

Watch a short video demo of the TUI and orchestration:

demo.mp4

Install

pip install pitaya
# or
pipx install pitaya
# or
uv tool install pitaya

Build the Docker image

Pitaya runs agents inside Docker. You need a Docker image that contains the agent CLI(s) you plan to use:

claude (for --plugin claude-code)
codex (for --plugin codex, Pitaya bundles @openai/codex@0.63.0 by default)

You can build a ready‑to‑use image from this repository’s Dockerfile:

git clone https://github.com/tact-lang/pitaya
cd pitaya
docker build -t pitaya-agents:latest .

Prefer a custom image? Use any base you like as long as it includes the required CLI(s) above. You can point Pitaya to a different image via --docker-image or set runner.docker_image in pitaya.yaml.

Authenticate:

Claude Code: set CLAUDE_CODE_OAUTH_TOKEN (subscription) or ANTHROPIC_API_KEY
Codex CLI: set CODEX_API_KEY (preferred). Pitaya also auto-detects OPENAI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, etc., plus optional base URLs such as OPENROUTER_BASE_URL.

Quickstart

From the root of a git repo:

pitaya "Create a HELLO.txt file with 'Hello from Pitaya' text in it and commit it"

More examples:

# Parallel candidates with scoring (pick the best)
pitaya "Write the funniest and most original joke possible" --strategy best-of-n -S n=5

# Iterative refine (generate → review → refine)
pitaya "Write the funniest and most original joke possible" --strategy iterative -S iterations=3

# Headless JSON output (pure NDJSON)
pitaya "task" --json

OpenRouter (Codex plugin) example:

pitaya "Write the funniest and most original joke possible" \
  --plugin codex \
  --model "gpt-5.1-codex" \
  --api-key "$OPENROUTER_API_KEY" \
  --base-url https://openrouter.ai/api/v1

Documentation

Start here: docs/index.md
Quickstart: docs/quickstart.md
CLI: docs/cli.md
TUI: docs/tui.md
Strategies: docs/strategies.md
Custom Strategies: docs/custom-strategies.md
Configuration: docs/configuration.md
Plugins: docs/plugins.md

Configuration (peek)

Optional pitaya.yaml to set defaults:

model: sonnet
plugin_name: claude-code
orchestration:
  max_parallel_instances: auto
  branch_namespace: hierarchical

CLI overrides config; -S key=value only affects the selected strategy.

Results & Logs

Logs: .pitaya/logs/<run_id>/events.jsonl and JSONL component logs (orchestration.jsonl, runner.jsonl, tui.jsonl, other.jsonl)
Results: .pitaya/results/<run_id>/ (summary.json, metadata.json, branches.txt, instance_metrics.csv, instances/.json)
Branches: pitaya/<strategy>/<run_id>/k<short8> (hierarchical namespace)
Resume: pitaya --resume <run_id>

Contributing

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

Dev quickstart:

git clone https://github.com/tact-lang/pitaya
cd pitaya
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

Changelog

See CHANGELOG.md for release notes and version history
GitHub Releases: https://github.com/tact-lang/pitaya/releases

License

MIT License — see LICENSE.