Noureddine RAMDI / Compozy: orchestrating AI coding agents with context-aware pipelines in Go

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
898 Words
github-stars go cli ai-agent workflow concurrency markdown

compozy/compozy

Every time you juggle multiple AI coding agents and prompts, you end up with a fragmented, manual mess. Compozy addresses this by turning the chaos into a structured pipeline—from ideation through execution to review—while grounding every task in your project’s actual codebase. This Go-based CLI orchestrates AI agents with a focus on context, concurrency, and version-controlled markdown workflows.

how compozy structures AI coding workflows

Compozy is a command-line tool written in Go that orchestrates a pipeline of AI coding agents and editors, designed to replace scattered prompts and manual task tracking with a unified, repeatable process. The pipeline moves sequentially through these stages: Idea → Product Requirements Document (PRD) → Technical Specification → Tasks → Execution → Review.

At its core, Compozy supports over 40 AI agents and editors—including Claude Code, Codex, Cursor, Gemini, and more—via the ACP (Agent Communication Protocol) runtime interface. This means it can integrate with a wide range of AI backends as long as they implement the ACP-compatible runtime commands.

All workflow artifacts—such as PRDs, specs, tasks, and reviews—are stored as plain markdown files with YAML frontmatter. This design choice lets you keep your AI-generated content version-controlled and editor-friendly, without locking you into a proprietary format or platform.

The architecture centers on a two-tier memory system using markdown files to persist workflow state between runs. This supports incremental progress and auditability. The CLI is distributed as a single binary with zero runtime dependencies, making it easy to install and embed as a Go package.

concurrency, context-awareness, and workflow memory: the technical backbone

What really sets Compozy apart is the codebase-aware enrichment phase before task execution. Parallel AI agents explore your repository concurrently to discover code patterns, dependencies, and context. This grounding enables Compozy to turn generic, context-free prompts into informed, context-rich instructions tailored to your specific project.

The concurrency model allows multiple tasks and agents to run simultaneously, with configurable retries and timeouts to handle errors or slow responses gracefully. This parallelism reduces workflow turnaround time compared to strictly sequential orchestrations.

The use of a markdown-based, two-tier memory system is a pragmatic design decision. It trades off some real-time interactivity for transparency and simplicity. You get fully version-controlled artifacts and can inspect or modify workflow state manually if needed. This also means the tool is provider-agnostic and does not impose a cloud or database dependency.

However, this approach comes with complexity in setup and operation. You must install and configure ACP-compatible runtimes separately, and the CLI depends on these external agents to function effectively. The orchestration logic is opinionated, which may require some adaptation if your workflow or AI providers differ.

Overall, the code is surprisingly clean for a multi-agent orchestration system, and the structured pipeline enforces best practices in AI-assisted development workflows.

quick start with compozy

The project provides several installation options depending on your platform and preference:

# Homebrew
brew tap compozy/compozy
brew install --cask 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

After installation, you need to install core skills into your AI agents:

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

For the optional ideation workflow and council roster, install the cy-idea-factory extension:

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

To run tasks or execute code, you must have an ACP-capable runtime installed and accessible via your PATH, matching the --ide flag you choose. Supported runtimes include Claude Agent, Codex CLI, GitHub Copilot CLI, Cursor, Droid, OpenCode, pi ACP, and Gemini CLI.

who benefits from compozy?

Compozy fits developers and teams orchestrating multiple AI coding agents who want a structured, repeatable pipeline that integrates directly with their codebase and version control. Its markdown-first workflow artifacts and provider-agnostic design make it flexible and auditable.

The tradeoff is the complexity of setup: you must install and manage ACP runtimes separately, understand the pipeline stages, and adapt to Compozy’s opinionated conventions. For solo developers or teams experimenting with AI coding, it might be overkill. But for those building production-grade AI-assisted development workflows, the codebase-aware enrichment and concurrency model are worth the effort.

In sum, Compozy is a practical tool that solves a real pain point in multi-agent AI coding orchestration, especially when context and traceability matter. The Go implementation and single-binary distribution make it easy to integrate into diverse environments, though it demands a learning curve and runtime setup. Worth exploring if you want to tame AI coding chaos with structure and context.

→ GitHub Repo: compozy/compozy ⭐ 579 · Go