compozy

command module
v0.4.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 4 Imported by: 0

README ΒΆ

CompozyOS

CompozyOS

The system around the agent, already built.

An operating system for AI agents.

CI Release Go Report Card Go Reference

Anyone can prompt an agent. Making agents work continuously is still an engineering project: loops, triggers, cron, 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, Codex, and Cursor). Built first for developers and technical operators.

[!NOTE] v0.4.0 is the first stable CompozyOS release. The previous v0.2 product has reached end of life and receives no further releases. Start with the migration guide before replacing an existing v0.2 installation.

CompozyOS web shell

✨ 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, Codex, and Cursor) operate the same daemon-owned state.
  • Batteries included. One runtime, one state model: loops and approvals 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, and extension kits plug into explicit runtime contracts.

πŸ“¦ Installation

Verified installer

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

curl -fsSL https://compozy.com/install.sh | sh
Homebrew
brew install compozy/compozy/compozy
NPM
npm install -g @compozy/cli
Go

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

CompozyOS control surfaces, daemon, runtime resources, state, and extension boundaries

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, automation and tools 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 an app

Use @compozy/client for TypeScript or github.com/compozy/compozy/sdk/go/client for Go to connect an external app to your running daemon. Both clients provide typed operations and agent streams; app tokens authorize trusted browser origins on the local listener.

Follow the Build an app tutorials for Node, a server-backed chat UI, browser access, Go, and token administration. The API reference includes generated SDK calls for each operation. These app SDK surfaces are experimental in 0.4; pin the exact version matching your daemon.

πŸš€ 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

Workflow memory is ordinary repository files under .compozy/tasks/<name>/memory/, written and read by the spec-cycle skills. The v0.2 workflow-memory files remain 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

πŸ› οΈ Development

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

make dev

To populate the Northstar Pay demo and leave its daemon running in the background:

make demo-seed
# Optional isolated home and secondary port:
make demo-seed DEMO_HOME="$HOME/.compozy-demo-other" DEMO_PORT=2125

This builds the daemon and Web bundle, replaces the seed-owned scenario, and starts the demo at http://localhost:2124 using ~/.compozy-demo by default. The main instance is unchanged. To reseed a running demo, first stop its daemon with COMPOZY_HOME="$HOME/.compozy-demo" ./bin/compozy daemon stop (use your custom home if overridden). The raw go run ./scripts/demo-seed --home <path> command remains available for data-only seeding. Existing demos in ~/.agh can still be selected explicitly with DEMO_HOME.

To prepare the same demo and open it in the Electron desktop shell:

make demo-seed-desktop
# The same overrides apply:
make demo-seed-desktop DEMO_HOME="$HOME/.compozy-demo-other" DEMO_PORT=2125

The desktop shell uses the demo home for its runtime connection and Electron profile. Quitting Electron leaves the demo daemon running in the background. As with demo-seed, stop an already-running demo before reseeding it.

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

Star History Chart

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

Contributors

πŸ“„ License

CompozyOS is distributed under the MIT License.

Documentation ΒΆ

Overview ΒΆ

Package main is the root Compozy CLI entrypoint for go install github.com/compozy/compozy.

Directories ΒΆ

Path Synopsis
cmd
compozy command
Package main is the CompozyOS CLI entrypoint.
Package main is the CompozyOS CLI entrypoint.
compozy-catalog command
compozy-codegen command
desktop
schema
Package appschema embeds the canonical cross-language desktop app state schema.
Package appschema embeds the canonical cross-language desktop app state schema.
extensions
internal
acp
Package acp provides the Compozy ACP client implementation.
Package acp provides the Compozy ACP client implementation.
admission
Package admission owns the daemon-wide new-work admission boundary.
Package admission owns the daemon-wide new-work admission boundary.
agentidentity
Package agentidentity resolves daemon-validated caller identity for agent-facing CLI and UDS operations.
Package agentidentity resolves daemon-validated caller identity for agent-facing CLI and UDS operations.
api/core
Package core provides the shared transport-facing API layer used by HTTP and UDS bindings.
Package core provides the shared transport-facing API layer used by HTTP and UDS bindings.
api/ginutil
Package ginutil owns process-wide Gin runtime coordination shared by Compozy transports.
Package ginutil owns process-wide Gin runtime coordination shared by Compozy transports.
api/testutil
Package testutil provides shared helpers for API-layer tests.
Package testutil provides shared helpers for API-layer tests.
appstatecontract
Package appstatecontract owns the shared desktop app-state wire version.
Package appstatecontract owns the shared desktop app-state wire version.
automation
Package automation hosts the runtime automation components and re-exports the canonical automation model from `internal/automation/model`.
Package automation hosts the runtime automation components and re-exports the canonical automation model from `internal/automation/model`.
automation/model
Package model defines the transport-agnostic automation domain model shared by configuration, persistence, runtime, and API layers.
Package model defines the transport-agnostic automation domain model shared by configuration, persistence, runtime, and API layers.
cli
clientstate
Package clientstate persists opaque, workspace-scoped client state and publishes committed changes in workspace sequence order.
Package clientstate persists opaque, workspace-scoped client state and publishes committed changes in workspace sequence order.
cmdpalette
Package cmdpalette owns the daemon-canonical command catalog and invocation contract.
Package cmdpalette owns the daemon-canonical command catalog and invocation contract.
cmdpalette/corecmds
Package corecmds provides the complete daemon-owned core command inventory.
Package corecmds provides the complete daemon-owned core command inventory.
codegen/jsbin
Package jsbin resolves workspace-pinned JS tool binaries with a bunx fallback.
Package jsbin resolves workspace-pinned JS tool binaries with a bunx fallback.
codegen/storeschema
Package storeschema owns deterministic sqlc and Atlas generation for Compozy stores.
Package storeschema owns deterministic sqlc and Atlas generation for Compozy stores.
command
Package command owns session-aware slash command projection and parsing.
Package command owns session-aware slash command projection and parsing.
config/lifecycle
Package lifecycle owns the config-apply lifecycle matrix shared by runtime, API, CLI, web, docs, and codegen checks.
Package lifecycle owns the config-apply lifecycle matrix shared by runtime, API, CLI, web, docs, and codegen checks.
daemon
Package daemon wires the Compozy runtime packages into a single long-lived process.
Package daemon wires the Compozy runtime packages into a single long-lived process.
deadentity
Package deadentity owns workspace-scoped failure streaks and durable dead-runtime recovery.
Package deadentity owns workspace-scoped failure streaks and durable dead-runtime recovery.
demoseed
Package demoseed prepares a coherent local workspace for product demonstrations.
Package demoseed prepares a coherent local workspace for product demonstrations.
events
Package events owns canonical runtime event names and metadata shared by producers, logs, notifications, and contract tests.
Package events owns canonical runtime event names and metadata shared by producers, logs, notifications, and contract tests.
extension/agentplugin
Package agentplugin reads and validates portable Agent Plugins packages.
Package agentplugin reads and validates portable Agent Plugins packages.
extension/surfaces
Package surfaces defines the static extension resource surface policy.
Package surfaces defines the static extension resource surface policy.
extensionenv
Package extensionenv defines the persistence boundary for extension environment bindings.
Package extensionenv defines the persistence boundary for extension environment bindings.
extensioninput
Package extensioninput defines the persistence boundary for non-secret extension inputs.
Package extensioninput defines the persistence boundary for non-secret extension inputs.
extensionmcp
Package extensionmcp defines instance-scoped MCP overrides and sticky runtime names.
Package extensionmcp defines instance-scoped MCP overrides and sticky runtime names.
fileutil
Package fileutil provides shared filesystem helpers for Compozy components.
Package fileutil provides shared filesystem helpers for Compozy components.
gateway
Package gateway owns durable exposure policy and reconciliation contracts.
Package gateway owns durable exposure policy and reconciliation contracts.
hooks
Package hooks defines the dependency-free core types for the Compozy lifecycle hooks platform.
Package hooks defines the dependency-free core types for the Compozy lifecycle hooks platform.
listcursor
Package listcursor provides versioned, query-bound opaque cursors for stable list pagination.
Package listcursor provides versioned, query-bound opaque cursors for stable list pagination.
logger
Package logger configures Compozy structured logging.
Package logger configures Compozy structured logging.
loop
Package loop owns loop-domain validation and compile surfaces.
Package loop owns loop-domain validation and compile surfaces.
loop/dsl
Package dsl defines the compozy.loop/v1 authoring document.
Package dsl defines the compozy.loop/v1 authoring document.
loop/dsl/refs
Package refs validates loop template and CEL references against one namespace.
Package refs validates loop template and CEL references against one namespace.
loop/gate
Package gate evaluates loop verification gates.
Package gate evaluates loop verification gates.
loop/goal
Package goal defines the durable convergence contracts implemented by the Loop store.
Package goal defines the durable convergence contracts implemented by the Loop store.
marketplace
Package marketplace owns Compozy-curated discovery feeds and their durable projection.
Package marketplace owns Compozy-curated discovery feeds and their durable projection.
mcp
mcp/securehttp
Package securehttp provides outbound HTTP clients for remote MCP and OAuth services.
Package securehttp provides outbound HTTP clients for remote MCP and OAuth services.
mcppolicy
Package mcppolicy owns the shared security policy for remote MCP endpoints.
Package mcppolicy owns the shared security policy for remote MCP endpoints.
mention
Package mention parses @-mention tokens from prompt text.
Package mention parses @-mention tokens from prompt text.
monitor
Package monitor owns daemon-native session monitors: durable-for-the-daemon watches that wake their owning agent session when a terminal exits, a terminal prints a pattern, or a timer elapses.
Package monitor owns daemon-native session monitors: durable-for-the-daemon watches that wake their owning agent session when a terminal exits, a terminal prints a pattern, or a timer elapses.
outboundpolicy
Package outboundpolicy defines the shared destination boundary for outbound network clients.
Package outboundpolicy defines the shared destination boundary for outbound network clients.
procutil
Package procutil provides shared process helpers for Compozy runtime components.
Package procutil provides shared process helpers for Compozy runtime components.
profile
Package profile owns durable profile identity, selection, resolution, and crash-convergent lifecycle operations.
Package profile owns durable profile identity, selection, resolution, and crash-convergent lifecycle operations.
providerauth
Package providerauth contains provider-auth diagnostics shared by CLI and daemon settings surfaces.
Package providerauth contains provider-auth diagnostics shared by CLI and daemon settings surfaces.
providers
Package providers owns provider authentication classification and probes.
Package providers owns provider authentication classification and probes.
providerusage
Package providerusage owns profile-scoped, in-memory usage snapshots and collection lifetimes.
Package providerusage owns profile-scoped, in-memory usage snapshots and collection lifetimes.
reasoning
Package reasoning owns the cross-surface reasoning-effort vocabulary.
Package reasoning owns the cross-surface reasoning-effort vocabulary.
redact
Package redact provides the process-wide canonical secret redactor.
Package redact provides the process-wide canonical secret redactor.
resources
Package resources provides the canonical desired-state persistence kernel and typed adapter boundary for extensibility resources.
Package resources provides the canonical desired-state persistence kernel and typed adapter boundary for extensibility resources.
retention
Package retention provides lifecycle management for periodic retention work.
Package retention provides lifecycle management for periodic retention work.
retry
Package retry provides small context-aware retry and backoff primitives.
Package retry provides small context-aware retry and backoff primitives.
scheduler
Package scheduler implements the daemon-owned mechanical task scheduler.
Package scheduler implements the daemon-owned mechanical task scheduler.
session
Package session orchestrates Compozy session lifecycle around ACP-backed agents.
Package session orchestrates Compozy session lifecycle around ACP-backed agents.
sessionprocess
Package sessionprocess tracks session-owned OS processes independently of agent lifetime.
Package sessionprocess tracks session-owned OS processes independently of agent lifetime.
skills
Package skills provides the core types and loading primitives for AgentSkills `SKILL.md` files.
Package skills provides the core types and loading primitives for AgentSkills `SKILL.md` files.
skillscan
Package skillscan discovers skill definition files under filesystem roots.
Package skillscan discovers skill definition files under filesystem roots.
speed
Package speed owns the cross-surface ACP speed vocabulary.
Package speed owns the cross-surface ACP speed vocabulary.
sse
Package sse provides shared server-sent event decoding helpers.
Package sse provides shared server-sent event decoding helpers.
store
Package store provides shared persistence types, validation, and helper primitives.
Package store provides shared persistence types, validation, and helper primitives.
store/globaldb/schema
Package schema embeds the global database schema and migration directory.
Package schema embeds the global database schema and migration directory.
store/sessiondb/schema
Package schema embeds the session database schema and migration directory.
Package schema embeds the session database schema and migration directory.
store/workspacedb
Package workspacedb owns per-workspace SQLite database lifecycle helpers.
Package workspacedb owns per-workspace SQLite database lifecycle helpers.
store/workspacedb/schema
Package schema embeds the workspace database schema and migration directory.
Package schema embeds the workspace database schema and migration directory.
task
Package task defines the canonical task-domain models, interfaces, limits, and validation helpers shared by persistence, runtime, and transport layers.
Package task defines the canonical task-domain models, interfaces, limits, and validation helpers shared by persistence, runtime, and transport layers.
terminal
Package terminal owns resident terminal processes, their byte streams, and shared attachments.
Package terminal owns resident terminal processes, their byte streams, and shared attachments.
terminal/idgen
Package idgen creates permanent terminal identifiers from cryptographic entropy.
Package idgen creates permanent terminal identifiers from cryptographic entropy.
terminal/journal
Package journal owns terminal command persistence and retained byte artifacts.
Package journal owns terminal command persistence and retained byte artifacts.
testutil
Package testutil provides shared test helpers for internal packages.
Package testutil provides shared test helpers for internal packages.
testutil/mcpfixture
Package mcpfixture provides deterministic official-MCP-SDK fixtures for runtime and OAuth integration tests.
Package mcpfixture provides deterministic official-MCP-SDK fixtures for runtime and OAuth integration tests.
toolmeta
Package toolmeta renders safe, provider-neutral tool progress presentation metadata.
Package toolmeta renders safe, provider-neutral tool progress presentation metadata.
toolruntime
Package toolruntime tracks long-running tool subprocess ownership and scoped interrupts.
Package toolruntime tracks long-running tool subprocess ownership and scoped interrupts.
tools
Remove the leftover-reference filter in v0.6.0; retain the retired ID tombstones.
Remove the leftover-reference filter in v0.6.0; retain the retired ID tombstones.
vault
Package vault owns encrypted daemon-managed secret material.
Package vault owns encrypted daemon-managed secret material.
version
Package version provides build metadata injected via ldflags.
Package version provides build metadata injected via ldflags.
windowmanager
Package windowmanager owns workspace-scoped window topology and semantic mutations.
Package windowmanager owns workspace-scoped window topology and semantic mutations.
workref
Package workref provides tiny shared workspace reference value objects used to pass workspace identifiers and paths through transport and runtime helpers.
Package workref provides tiny shared workspace reference value objects used to pass workspace identifiers and paths through transport and runtime helpers.
workspace
Package workspace defines workspace domain models, sentinel errors, and resolver contracts used across Compozy runtime packages.
Package workspace defines workspace domain models, sentinel errors, and resolver contracts used across Compozy runtime packages.
workspacefiles
Package workspacefiles serves ranked file and folder search under one directory root from a cached, git-backed index with a bounded walk fallback.
Package workspacefiles serves ranked file and folder search under one directory root from a cached, git-backed index with a bounded walk fallback.
scripts
air-state-dir command
air-state-lock command
demo-seed command
dev-http-endpoint command
Command dev-http-endpoint prints the daemon's configured HTTP connect endpoint as "host\tport" without requiring a running daemon.
Command dev-http-endpoint prints the daemon's configured HTTP connect endpoint as "host\tport" without requiring a running daemon.
sdk
go module
web
e2e/fixtures/session-pull-request-seeder command
Command session-pull-request-seeder gives an existing workspace-root session a settled branch snapshot and caches the pull request for that branch in a stopped isolated daemon home, for the topbar PR chip journeys (E2E-001, E2E-003).
Command session-pull-request-seeder gives an existing workspace-root session a settled branch snapshot and caches the pull request for that branch in a stopped isolated daemon home, for the topbar PR chip journeys (E2E-001, E2E-003).
e2e/fixtures/sessions-board-seeder command
Command sessions-board-seeder writes stopped sessions for the Sessions board browser journeys (E2E-005..E2E-007) into a stopped isolated daemon home.
Command sessions-board-seeder writes stopped sessions for the Sessions board browser journeys (E2E-005..E2E-007) into a stopped isolated daemon home.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL