compozy

Anyone can prompt an agent. Making agents work continuously is still an engineering project: loops, triggers, cron, memory, permissions, approvals, observability, and the glue scripts that hold them together. CompozyOS turns that entire agent stack into one product, a complete environment to create, automate, and supervise agent work with the agent CLIs you already use (Claude Code, OpenClaw, and Hermes). Built first for developers and technical operators.

[!WARNING] The v0.3 line is in beta. The previous v0.2.15 product is deprecated and maintained only for critical fixes on legacy/v0.2. Start with the migration guide before replacing an existing v0.2 installation.

✨ Highlights

• Create. Sessions, agents, Loops, and capabilities are objects you author once and reuse, not scripts you rewrite per run.
• Automate. Cron schedules, webhooks, and triggers keep work running with no terminal open.
• Supervise. Approvals, permissions, run state, artifacts, and agent activity stay inspectable while work continues in the background.
• Work survives the terminal. Sessions and Loop runs belong to the daemon, so closing one client does not erase the work.
• Runs the agents you already use. ACP-compatible CLIs (Claude Code, OpenClaw, and Hermes) operate the same daemon-owned state.
• Batteries included. One runtime, one state model: loops, approvals, and memory are core objects, not plugins, reachable from web, CLI, HTTP/SSE, UDS, MCP, and native tools.
• Local-first by default. One Go binary and SQLite-backed stores keep runtime state on the operator's machine unless a configured provider or extension owns an external boundary.
• Remote access stays explicit. The Gateway pairs devices and exposes only the private or public surfaces an operator enables.
• Built to extend. Agents, skills, capabilities, hooks, bridges, and extension kits plug into explicit runtime contracts.
• Compozy Network. Sessions can discover peers, exchange typed messages, delegate work, and close it with receipts over compozy-network/v0.

Installation

The v0.3 beta ships through the channels below. Homebrew continues to serve the deprecated v0.2 line during the beta window and is intentionally omitted here. The compozy formula returns with v0.3.0 stable.

Verified installer

The installer pins the latest published beta and verifies Sigstore provenance before installing the binary on macOS or Linux.

curl -fsSL https://compozy.com/install.sh | sh

NPM

npm install -g @compozy/cli@beta

Go

Go's @latest still resolves the v0.2 stable line while v0.3 is in beta, so install with the explicit tag shown on the latest release:

go install github.com/compozy/compozy@<release-tag>

From Source

git clone https://github.com/compozy/compozy.git
cd compozy
go build -o ./bin/compozy .

The installation guide covers installer flags, Linux packages, source builds, verification, and managed updates.

How It Works

People and agents send commands through public control surfaces. The home-scoped daemon resolves the workspace, applies permissions and runtime policy, coordinates ACP agents, and persists events and resource state. Web and streaming clients read that same daemon-owned truth instead of maintaining a parallel model.

Daemon Runtime Model

compozy daemon start, compozy status, and compozy daemon stop manage the local daemon. Sessions, tasks, Loop runs, memory, automation, tools, and Compozy Network activity keep explicit owners and workspace boundaries. Use structured CLI output (-o json), HTTP/SSE, UDS, MCP, or native tools when another agent or program needs to manage the same resources.

Task Schema v2

Authored task files remain portable Markdown with typed frontmatter. The v0.3 runtime imports them into durable tasks and executes them through Loops; it does not revive the v0.2 tasks run pipeline. See Migrate from v0.2.15 for the exact schema and command changes.

⚙️ Config Files

Global defaults live in ~/.compozy/config.toml; a workspace can override supported fields through .compozy/config.toml. Explicit command flags win over workspace configuration, which wins over global configuration and built-in defaults.

compozy config path
compozy config validate
compozy config show -o json

Configuration, credentials, and provider-home policies have different owners. Follow the configuration guide instead of copying v0.2 state into a v0.3 home.

Reusable Agents

Agent definitions live under ~/.compozy/agents/<name>/ or .compozy/agents/<name>/. Each definition has an AGENT.md and may include an agent-local mcp.json. Workspace definitions override global definitions as a whole.

compozy agent list -o json
compozy agent info general -o json
compozy session new --agent general

Extensions

Extensions add versioned resources and runtime behavior through declared provide surfaces. The daemon owns discovery, enablement, trust decisions, lifecycle, and hooks; extensions do not bypass public runtime contracts.

Build one in three commands

compozy extension init hello --template tool-provider-go
compozy extension dev hello
compozy tool invoke ext__hello__search --workspace . --input '{"query":"compozy"}'

Executable extensions are code-first: declare the tool once in code and compozy extension build generates the manifest. Resource-only extensions can instead hand-write extension.toml and use the same build, dev, reload, and watch loop without running extension code. Walkthrough: Build your first extension.

SDK support

@compozy/extension-sdk (npm, MIT) and github.com/compozy/compozy/sdk/go are published and version-matched to the daemon.

Extension CLI

compozy extension list -o json
compozy extension status <name> -o json
compozy extension provenance <name> -o json
compozy extension logs <name> --follow

Learn more

• Build your first extension
• Extensions
• Publish an extension
• Capabilities and extension kits
• Official CompozyOS skill
• Migration guide

Quick Start

Bootstrap the home, start the daemon, enter the repository you want agents to work in, and create one durable session. CompozyOS infers and registers the workspace from the current directory; use --workspace <id|name|path> only when you need an override.

compozy install
compozy daemon start
compozy session new --agent general --name first-run

The Quick Start continues through the first prompt, live attachment, inspection, and cleanup.

Skills

Skills are daemon-discovered resources with explicit source and scope. Use the structured skill and marketplace surfaces to inspect what is active instead of copying v0.2 setup directories forward.

compozy skill list -o json
compozy skill inspect <name> -o json
compozy marketplace search --kind skill --query <term> -o json

Workflow Memory

Durable memory is scoped and daemon-owned. Agents can inspect, propose, and consolidate memory through the same public contracts as people. The v0.2 workflow-memory files remain ordinary repository artifacts; they are not imported as hidden runtime state.

Supported Agents

CompozyOS runs ACP-compatible agent CLIs and adapters. The active provider catalog and each agent's runtime settings are runtime truth; inspect them before selecting a model or reasoning mode. See the provider guide for authentication and provider-home policies.

CLI Reference

The generated CLI reference is authoritative for verbs, flags, structured output, and exit behavior. Start with:

compozy --help
compozy version
compozy doctor -o json

Documentation

• Runtime overview
• Installation
• Quick Start
• Migrate from v0.2.15
• CLI reference
• Compozy Network protocol
• GitHub releases

️ Development

CompozyOS is a Go and Bun monorepo. Start the daemon with automatic Go rebuilds and the web UI with Vite HMR:

make dev

Run the affected local gate before committing or pushing:

make gate

Delivery finishes in the draft PR: wait for every required CI check to pass on its current head.

Read AGENTS.md and the surface-specific instructions before editing.

Star History

Contributing

Contributions are welcome. Open an issue or pull request, keep public behavior agent-manageable, and run make gate before sending changes, then keep the PR until its current-head CI is green. Security reports belong in the repository's private security channel, not a public issue.

Contributors

Thanks to everyone who has contributed to CompozyOS.

License

CompozyOS is distributed under the MIT License.