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.

• 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.

brew tap compozy/compozy
brew install --cask compozy

npm install -g @compozy/cli

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

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.

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.

• 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 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.
• 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 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.

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

[exec]
output_format = "text"

[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
• [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)
• [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.
• max_retries applies to execution-stage ACP failures and inactivity timeouts for compozy exec, compozy tasks run, and compozy reviews fix.
• Built-in CLI defaults retry timed-out or transient ACP failures twice; set max_retries = 0 or pass --max-retries 0 to opt out.
• retry_backoff_multiplier only increases the next attempt timeout; retries restart immediately and do not add a sleep delay.

Reusable agents are flat filesystem bundles discovered from two scopes:

• workspace: .compozy/agents/<name>/
• global: ~/.compozy/agents/<name>/

When the same agent name exists in both places, the workspace directory wins as a whole. Compozy does not merge AGENT.md from one scope with mcp.json from the other.

Each agent directory contains:

• required AGENT.md with YAML frontmatter plus a markdown body
• optional mcp.json using the standard top-level mcpServers shape

Agent directory names are the canonical agent ids. They must match ^[a-z][a-z0-9-]{0,63}$, and compozy is reserved.

Quick start:

compozy agents list
compozy agents inspect reviewer
compozy exec --agent reviewer "Review the staged changes"

Runtime precedence for compozy exec --agent ... is:

explicit CLI flags > AGENT.md runtime defaults > workspace/global config > built-in defaults

mcp.json is only for agent-local MCP servers. The reserved Compozy MCP server is also named compozy, but it is injected by the host and must not appear in mcp.json. That reserved server exists only to expose host-owned tools such as run_agent. Child agent runs receive the reserved compozy server plus the child agent's own mcp.json; they do not inherit the parent agent's local MCP servers.

Use these committed example fixtures as starting points:

• docs/examples/agents/reviewer/AGENT.md for a minimal reusable agent
• docs/examples/agents/repo-copilot/AGENT.md and docs/examples/agents/repo-copilot/mcp.json for an agent with external MCP dependencies

The detailed guide lives in docs/reusable-agents.md.

Compozy extensions are executable subprocess plugins that intercept and modify pipeline behavior without rebuilding the binary. Extensions communicate with the host over JSON-RPC 2.0 on stdin/stdout and can observe lifecycle events, mutate prompts, inject plan sources, modify agent sessions, gate retries, ship skill packs, and register review providers.

Scaffold a new extension project with starter templates:

npx @compozy/create-extension my-ext
npx @compozy/create-extension my-ext --template prompt-decorator
npx @compozy/create-extension my-ext --runtime go

Available templates: lifecycle-observer, prompt-decorator, review-provider, skill-pack.

compozy ext list                   # discover extensions across all scopes
compozy ext inspect <name>         # show manifest, capabilities, enablement status
compozy ext install <source>       # install from a local path or GitHub repo archive
compozy ext uninstall <name>       # remove a user-scoped extension
compozy ext enable <name>          # enable on this machine
compozy ext disable <name>         # disable on this machine
compozy ext doctor                 # validate manifests and report health warnings

Extensions are discovered from three scopes with workspace > user > bundled precedence. User and workspace extensions start disabled and must be explicitly enabled by the local operator.

• Extension author guide
• Architecture overview
• Hook reference -- 32 hooks across 6 pipeline phases
• Host API reference -- 11 typed host methods
• Capability reference -- 19 capability grants
• Trust and enablement
• Testing guide

Use compozy exec when you want one prompt through the same ACP-backed execution stack without creating a full workflow first.

compozy exec "Summarize the current repository changes"
compozy exec --prompt-file prompt.md
cat prompt.md | compozy exec --format json
compozy exec --persist "Review the latest changes"
compozy exec --run-id exec-20260405-120000-000000000 "Continue from the previous session"

Prompt source rules are explicit:

• pass one positional prompt for short inline runs
• use --prompt-file for longer or reusable prompts
• pipe stdin only when neither of the above is provided
• ambiguous combinations are rejected instead of guessed

Output modes:

• --format text is headless by default and writes only the final assistant response to stdout
• --format json streams the lean JSONL contract to stdout and filters ACP metadata that is mostly useful for debugging
• --format raw-json streams the full raw JSONL event trace to stdout
• when --persist is enabled, ~/.compozy/runs/<run-id>/events.jsonl always stores the full raw event stream regardless of the selected stdout format
• operational ACP/runtime logs stay silent by default; use --verbose when you want lifecycle logs on stderr
• --tui opts back into the Bubble Tea interface for interactive inspection
• --persist stores a resumable conversation under ~/.compozy/runs/<run-id>/
• --run-id loads a previously persisted ACP session and appends a new turn

Persisted exec runs use this layout:

~/.compozy/runs/<run-id>/run.db
~/.compozy/runs/<run-id>/run.json
~/.compozy/runs/<run-id>/events.jsonl
~/.compozy/runs/<run-id>/turns/0001/prompt.md
~/.compozy/runs/<run-id>/turns/0001/response.txt
~/.compozy/runs/<run-id>/turns/0001/result.json

compozy exec uses the same config merge rule as the rest of the CLI: flags > workspace [exec] > workspace [defaults] > global [exec] > global [defaults] > built-in defaults.

This walkthrough builds a feature called user-auth from idea to shipped code.

compozy setup

Auto-detects installed agents, copies (or symlinks) core skills into their configuration directories, and installs setup assets shipped by enabled extensions. compozy tasks run and compozy reviews fix now verify that bundled Compozy skills are installed for the selected agent before running. Missing installs block the run, and outdated installs prompt for refresh in interactive terminals.

Inside your AI agent (Claude Code, Codex, Cursor, OpenCode, Pi, etc.):

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

Then:

/cy-idea-factory user-auth

Transforms a raw idea into a structured idea spec — asks targeted questions, researches market and codebase in parallel, runs business analysis and council debate, suggests high-leverage alternatives, and produces a research-backed idea. Skip this step if you already have a clear feature scope.

/cy-create-prd user-auth

Interactive brainstorming session — reads the idea if one exists, asks clarifying questions, spawns parallel agents to research your codebase and the web, produces a business-focused PRD with ADRs.

/cy-create-techspec user-auth

Reads your PRD, explores the codebase architecture, asks technical clarification questions. Produces architecture specs, API designs, and data models.

/cy-create-tasks user-auth

Analyzes both documents, explores your codebase for relevant files and patterns, produces individually executable task files with status tracking, context, and acceptance criteria. Generated task files use task schema v2 (status, title, type, complexity, dependencies). Validate them any time with compozy tasks validate --name user-auth.

compozy tasks run user-auth --ide claude

Each pending task is processed sequentially through the shared daemon — the agent reads the spec, implements the code, validates it, and updates the task status. Use --dry-run to preview prompts without executing. compozy tasks run validates task metadata before execution. Use --skip-validation when validation already ran elsewhere, or --force to continue after validation failures in non-interactive environments.

Option A — AI-powered review inside your agent:

/cy-review-round user-auth

Option B — Fetch from an external provider:

compozy reviews fetch user-auth --provider coderabbit --pr 42

Both produce the same output: .compozy/tasks/user-auth/reviews-001/issue_*.md

compozy reviews fix user-auth --ide claude --concurrent 2 --batch-size 3

Agents triage each issue as valid or invalid, implement fixes for valid issues, and update statuses. Provider threads are resolved automatically.

Repeat steps 7–8. Each cycle creates a new review round (reviews-002/, reviews-003/), preserving full history. When clean — merge and ship.

Compozy bundles 9 core skills that its workflows depend on. They run inside your AI agent — no context switching to external tools.

Optional first-party extension skills:

Install the optional ideation extension with:

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

When agents execute tasks, context gets lost between runs — decisions made, errors hit, patterns discovered. Compozy solves this with a two-tier memory system that gives each agent a running history of the workflow.

Every task execution automatically bootstraps two markdown files inside .compozy/tasks/<name>/memory/:

How it works:

1. Before a task runs, Compozy creates the memory directory and scaffolds both files with section templates if they don't exist yet.
2. The agent reads both memory files before writing any code — treating them as mandatory context, not optional notes.
3. During execution, the agent keeps task memory current: decisions, learnings, errors, and corrections.
4. Only durable, cross-task context gets promoted to shared memory. Task-local details stay in the task file.
5. Before completion, the agent updates memory with anything that helps the next run start faster.

Automatic compaction. Memory files have soft limits (150 lines / 12 KB for shared, 200 lines / 16 KB per task). When a file exceeds its threshold, Compozy flags it for compaction — the agent trims noise and repetition while preserving active risks, decisions, and handoffs.

No duplication. Memory files don't copy what's already in the repo, git history, PRD, or task specs. They capture only what would otherwise be lost between runs: the why behind decisions, surprising findings, and context that makes the next agent immediately productive.

The cy-workflow-memory skill handles all of this automatically when referenced in task prompts. No manual setup required — run compozy tasks run <workflow> and agents inherit context from every previous run.

Execution (compozy exec, compozy tasks run, compozy reviews fix) — ACP-capable runtimes that can run ad hoc prompts and daemon-backed workflow tasks:

Skill installation (compozy setup) — 40+ agents and editors, including Claude Code, Codex, Cursor, Droid, OpenCode, Pi, Gemini CLI, GitHub Copilot, Windsurf, Amp, Continue, Goose, Roo Code, Augment, Kiro CLI, Cline, and many more. compozy setup installs core workflow skills plus any setup assets shipped by enabled extensions. Run compozy setup to see all detected agents on your system.

When installing to multiple agents, Compozy offers two modes:

• Symlink (default) — One canonical copy with symlinks from each agent directory. All agents stay in sync.
• Copy — Independent copies per agent. Use --copy when symlinks are not supported.

compozy setup [flags]

compozy migrate [flags]

compozy sync [flags]

compozy daemon start
compozy daemon status
compozy daemon stop [--force]

compozy workspaces list [--format text|json]
compozy workspaces show <id-or-path> [--format text|json]
compozy workspaces register <path> [--name display-name] [--format text|json]
compozy workspaces unregister <id-or-path> [--format text|json]
compozy workspaces resolve <path> [--format text|json]

compozy tasks validate [--name my-feature | --tasks-dir .compozy/tasks/my-feature] [--format text|json]

compozy tasks run <slug> [flags]

compozy reviews fetch <slug> [--provider coderabbit --pr 42 --round N]
compozy reviews list <slug>
compozy reviews show <slug> [round]
compozy reviews fix <slug> [flags]

compozy runs attach <run-id>
compozy runs watch <run-id>
compozy runs purge

compozy archive [flags]

compozy exec [prompt] [flags]

compozy agents list
compozy agents inspect <name>

compozy agents list
compozy agents inspect reviewer
compozy agents inspect repo-copilot

compozy ext <subcommand> [flags]

// Prepare work without executing
prep, err := compozy.Prepare(context.Background(), compozy.Config{
    Name:     "multi-repo",
    TasksDir: ".compozy/tasks/multi-repo",
    Mode:     compozy.ModePRDTasks,
    DryRun:   true,
})

// Fetch reviews and run remediation
_, _ = compozy.FetchReviews(context.Background(), compozy.Config{
    Name:     "my-feature",
    Provider: "coderabbit",
    PR:       "259",
})

// Preview a legacy artifact migration
_, _ = compozy.Migrate(context.Background(), compozy.MigrationConfig{
    DryRun: true,
})

_ = compozy.Run(context.Background(), compozy.Config{
    Name:            "my-feature",
    Mode:            compozy.ModePRReview,
    IDE:             compozy.IDECodex,
    ReasoningEffort: "medium",
})

// Embed the Cobra command in another CLI
root := compozy.NewCommand()
_ = root.Execute()

cmd/compozy/             CLI entry point
compozy.go               Public Go API + reusable Cobra command helpers
internal/cli/            Cobra flags, interactive form, CLI glue
internal/core/           Internal facade for preparation and execution
  agent/                 IDE command validation and process construction
  agents/                Reusable agent discovery, validation, MCP merge, nested execution
  extension/             Extension manifest, discovery, hooks, Host API, lifecycle
  memory/                Workflow memory bootstrapping, inspection, and compaction detection
  model/                 Shared runtime data structures
  plan/                  Input discovery, filtering, grouping, batch prep
  prompt/                Prompt builders emitting runtime context + skill names
  run/                   Execution pipeline, logging, shutdown, Bubble Tea UI
internal/setup/          Bundled skill and council-agent installer (agent detection, symlink/copy)
internal/version/        Build metadata
sdk/extension/           Public Go SDK for extension authors
sdk/extension-sdk-ts/    Public TypeScript SDK for extension authors
sdk/create-extension/    CLI scaffolder for new extension projects
skills/                  Bundled installable skills
.compozy/config.toml     Optional workspace defaults for CLI execution
.compozy/agents/         Optional reusable agents (`AGENT.md` + optional `mcp.json`)
.compozy/extensions/     Workspace-scoped extensions (starts disabled)
~/.compozy/runs/         Home-scoped runtime artifacts for daemon-managed and persisted exec runs
.compozy/tasks/          Default workflow artifact root (PRDs, TechSpecs, tasks, ADRs, reviews)

make verify    # Full pipeline: fmt → lint → test → build
make fmt       # Format code
make lint      # Lint (zero tolerance)
make test      # Tests with race detector
make build     # Compile binary
make deps      # Tidy and verify modules

Contributions are welcome. See CONTRIBUTING.md for guidelines.

MIT