Compozy

Orchestrate AI coding agents from idea to shipped code — in a single pipeline.

<a href="https://github.com/compozy/compozy/actions/workflows/ci.yml">
  <img src="https://github.com/compozy/compozy/actions/workflows/ci.yml/badge.svg" alt="CI">
</a>
<a href="https://pkg.go.dev/github.com/compozy/compozy">
  <img src="https://pkg.go.dev/badge/github.com/compozy/compozy.svg" alt="Go Reference">
</a>
<a href="https://goreportcard.com/report/github.com/compozy/compozy">
  <img src="https://goreportcard.com/badge/github.com/compozy/compozy" alt="Go Report Card">
</a>
<a href="https://github.com/compozy/compozy/raw/v0.2.11/LICENSE">
  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
</a>
<a href="https://github.com/compozy/compozy/releases">
  <img src="https://img.shields.io/github/v/release/compozy/compozy?include_prereleases" alt="Release">
</a>

One CLI to replace scattered prompts, manual task tracking, and copy-paste review cycles. Compozy drives the full lifecycle of AI-assisted development: product ideation, technical specification, task breakdown with codebase-informed enrichment, concurrent execution across agents, and automated PR review remediation.

✨ Highlights

• One command, 40+ agents. Install core workflow skills into Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini, and 40+ other agents and editors with compozy setup, plus any setup assets shipped by enabled extensions.
• Idea to code in a structured pipeline. Optional Idea → PRD → TechSpec → Tasks → Execution → Review. Each phase produces plain markdown artifacts that feed into the next. Start from an idea for full research and debate, or jump straight to PRD if you already have a clear scope.
• Codebase-aware enrichment. Tasks aren't generic prompts. Compozy spawns parallel agents to explore your codebase, discover patterns, and ground every task in real project context.
• Multi-agent execution. Run tasks through ACP-capable runtimes like Claude Code, Codex, Cursor, Droid, OpenCode, Pi, or Gemini — just change --ide. Concurrent batch processing with configurable timeouts, retries, and exponential backoff, all with a live terminal UI.
• Reusable agents. Package a prompt, runtime defaults, and optional agent-local MCP servers under .compozy/agents/<name>/, then run it from compozy exec --agent <name> or through nested run_agent calls.
• Workflow memory between runs. Agents inherit context from every previous task — decisions, learnings, errors, and handoffs. Two-tier markdown memory with automatic compaction keeps context fresh without manual bookkeeping.
• Provider-agnostic reviews. Fetch review comments from CodeRabbit, GitHub, or run AI-powered reviews internally. All normalize to the same format. Provider threads resolve automatically after fixes.
• Markdown everywhere. PRDs, specs, tasks, reviews, and ADRs are human-readable markdown files. Version-controlled, diffable, editable between steps. No vendor lock-in.
• Frontmatter for machine-readable metadata. Tasks and review issues keep parseable metadata in standard YAML frontmatter instead of custom XML tags.
• Executable extensions. Intercept and modify any pipeline phase with subprocess hooks. Ship custom prompt decorators, lifecycle observers, review providers, and skill packs using the TypeScript or Go SDKs.
• Single binary, local-first. Compiles to one Go binary with zero runtime dependencies. Your code and data stay on your machine.
• Embeddable. Use as a standalone CLI or import as a Go package into your own tools.

📦 Installation

Homebrew

brew install compozy/compozy/compozy

NPM

npm install -g @compozy/cli

Go

go install github.com/compozy/compozy/cmd/compozy@latest

From Source

git clone git@github.com:compozy/compozy.git
cd compozy && make verify && go build ./cmd/compozy

Then install core skills into your AI agents:

compozy setup          # interactive — pick agents and skills
compozy setup --all    # install everything to every detected agent

compozy setup installs Compozy's core workflow skills plus any setup assets shipped by enabled extensions.

If you want the optional ideation workflow and council roster, install the first-party cy-idea-factory extension first:

compozy ext install --yes compozy/compozy --remote github --ref <tag> --subdir extensions/cy-idea-factory
compozy ext enable cy-idea-factory
compozy setup

Execution runtimes are separate from skill installation. To run compozy exec, compozy tasks run, or compozy reviews fix, install an ACP-capable runtime or adapter on PATH for the --ide you choose:

When the direct ACP command is not installed, Compozy can also fall back to supported launchers such as npx @zed-industries/codex-acp when the launcher is available locally. Codex defaults to gpt-5.5; using that model with a local codex-acp binary requires @zed-industries/codex-acp >= 0.12.0. Update with npm install -g @zed-industries/codex-acp@latest, or explicitly choose a model supported by your installed adapter.

🔄 How It Works

Workflow artifacts stay in .compozy/tasks/<name>/. These are the PRDs, TechSpecs, ADRs, tasks, reviews, and memory files that you read and edit between steps.

The daemon owns runtime state under ~/.compozy/. Daemon-managed task runs, review-fix runs, and persisted exec sessions allocate ~/.compozy/runs/<run-id>/, while attach and watch clients reconnect through daemon snapshots and streams instead of reading workspace-local run files directly.

Task and review issue files use YAML frontmatter for parseable metadata such as status, title, type, severity, and provider_ref. compozy sync now reconciles authored workflow artifacts into the daemon global.db catalog and performs one-time cleanup for legacy generated _meta.md / _tasks.md artifacts when they are encountered. compozy archive moves completed workflows only after synced daemon state says they are eligible. If you have an older project with XML-tagged artifacts, run compozy migrate once before using daemon-backed workflow commands.

Daemon Runtime Model

• compozy daemon start|status|stop manages the home-scoped daemon lifecycle. daemon start is idempotent, and task/review/exec commands auto-start the daemon when needed.
• compozy workspaces list|show|register|unregister|resolve exposes the daemon workspace registry. Workspaces are also lazily registered when you run daemon-backed commands inside them.
• compozy tasks run <slug> is the canonical single-workflow runner. In interactive terminals it attaches to the TUI by default; in non-interactive environments it falls back to streaming. Use --ui, --stream, --detach, or --attach to override that behavior. Add --parallel-tasks to opt into dependency-aware parallel execution for task files inside one workflow.
• compozy tasks run --multiple alpha,beta starts one daemon-owned queue for several task workflows. Use tasks run --multiple when the same flags and runtime defaults should apply to an ordered batch; keep using tasks run <slug> for one workflow or scripts that expect one run ID per invocation. Add --parallel to run the batch concurrently — each child runs in its own isolated git worktree, bounded by --parallel-limit (default 2).
• Independent compozy tasks run invocations from different workspaces run concurrently on the shared home-scoped daemon. When another workspace already has an active run, the CLI prints a warning with the busy workspace and run ID before starting the new run.
• compozy runs attach <run-id> restores the interactive TUI for an existing daemon-managed run, while compozy runs watch <run-id> streams textual observation from the same snapshot-plus-stream transport.
• compozy reviews fetch|list|show|fix is the canonical review command family.

Task Schema v2

Task files now use the v2 frontmatter shape: status, title, type, complexity, and dependencies. Legacy v1 task-only keys are no longer part of the schema. type must come from the workspace task type registry: either [tasks].types in .compozy/config.toml or the built-in defaults frontend, backend, docs, test, infra, refactor, chore, bugfix.

---
status: pending
title: Add task validation preflight to tasks run
type: backend
complexity: medium
dependencies:
  - task_02
---

Validate task files at any time with compozy tasks validate --name <feature>. compozy tasks run <feature> runs the same preflight automatically; use --skip-validation only when tasks were validated elsewhere, or --force to continue after validation failures in non-interactive runs.

⚙️ Config Files

Compozy can load global defaults from ~/.compozy/config.toml and override them per workspace with .compozy/config.toml.

• The CLI discovers the nearest .compozy/ directory by walking upward from the current working directory.
• If ~/.compozy/config.toml exists, Compozy loads it once at command startup.
• If .compozy/config.toml exists in the resolved workspace, it overrides the global config field by field.
• Explicit CLI flags always win over config values.

Precedence is:

explicit flags > workspace command section > workspace [defaults] > global command section > global [defaults] > built-in defaults

Example:

[defaults]
ide = "codex"
model = "gpt-5.5"
reasoning_effort = "medium"
access_mode = "full"
timeout = "10m"
tail_lines = 0
add_dirs = ["../shared"]
auto_commit = false
max_retries = 2
retry_backoff_multiplier = 1.5

[tasks]
types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]

[tasks.run]
include_completed = false
run_multiple_mode = "enqueued"
run_multiple_parallel_limit = 2

[tasks.run.parallel]
enabled = false
max_concurrency = 4

[tasks.run.parallel.conflict_resolver]
ide = "codex"
model = "gpt-5.5"
reasoning_effort = "medium"
max_attempts = 1
validation_command = []

[exec]
output_format = "text"

[recovery]
enabled = false
ide = "codex"
model = "gpt-5.5"
reasoning_effort = "medium"
max_attempts = 1

[fix_reviews]
concurrent = 2
batch_size = 3
include_resolved = false

[fetch_reviews]
provider = "coderabbit"
nitpicks = false

Supported sections:

• [defaults] for shared execution defaults such as ide, model, reasoning_effort, access_mode, timeout, tail_lines, add_dirs, auto_commit, max_retries, and retry_backoff_multiplier
• [exec] for output_format plus exec-specific runtime overrides such as ide, model, reasoning_effort, access_mode, timeout, tail_lines, add_dirs, max_retries, and retry_backoff_multiplier
• [tasks] for the allowed task type list used by cy-create-tasks and compozy tasks validate
• [tasks.run] for workflow-run defaults used by compozy tasks run, such as include_completed, run_multiple_mode, and run_multiple_parallel_limit
• [tasks.run.parallel] for dependency-aware parallel execution inside one PRD task workflow, including enabled, max_concurrency, and the conflict-resolver agent under [tasks.run.parallel.conflict_resolver]
• [fix_reviews] for concurrent, batch_size, and include_resolved
• [fetch_reviews] for provider and nitpicks (controls CodeRabbit review-body comments; default is enabled when unset)
• [recovery] for agentic recovery defaults used by run-producing commands: enabled, ide, model, reasoning_effort, and max_attempts
• [sound] for optional run-completion audio presets or absolute file paths

Notes:

• Both ~/.compozy/config.toml and .compozy/config.toml are optional. If both are absent, Compozy keeps the current built-in defaults.
• .compozy/tasks remains the fixed workflow root in this version; the config file does not change the workflow root path.
• Unknown keys and invalid value types are rejected during config loading.
• Relative add_dirs are resolved against the owning config scope: the user home directory for ~/.compozy/config.toml and the workspace root for .compozy/config.toml.
• [tasks.run] run_multiple_mode controls tasks run --multiple scheduling. Valid values are "enqueued" and "parallel"; when unset, the built-in default is "enqueued".
• run_multiple_mode = "parallel" runs the batch concurrently, with each child in its own isolated git worktree. The CLI --parallel flag overrides this config value for a single invocation.
• [tasks.run] run_multiple_parallel_limit caps how many children run at once in parallel mode. It must be a positive integer and defau