@kimohy/colay

Colay

Install

Requires Node.js 22 or newer. Install the stable channel (the default) with:

npm install --global @kimohy/colay
colay --version

Beta and nightly channels are available when you explicitly opt in:

npm install --global @kimohy/colay@beta
npm install --global @kimohy/colay@nightly

Colay currently supports Windows x64, macOS Apple Silicon (ARM64), and Linux x64. The Linux x64 package contains a musl-linked binary and deliberately has no npm libc selector, so it can install on both musl and glibc Linux hosts. For beta and stable builds without Node.js, download the matching archive from GitHub Releases. Nightly workflow artifacts expire after 14 days; npm is the normal way to install a nightly.

Colay is a local-first enterprise orchestrator for approved Codex CLI, Claude Code, and Gemini CLI installations. It selects a provider and logical model profile, records why it made that decision, preserves work in isolated Git worktrees, and can resume from a vendor-neutral checkpoint after a provider becomes unavailable.

The orchestrator never rotates identities, bypasses quotas, scrapes usage pages, extracts credentials, purchases credits, or calls unofficial provider endpoints. Provider inference is performed only by the official CLIs with their existing authenticated state. Tests use fake binaries and consume no provider credit.

Commands

colay init
colay daemon {start|status|stop|restart}
colay run "<task>"
colay run --task-file task.json
colay run --plan-only "<task>"
colay status [--json]
colay providers [--json]
colay providers {enable|disable} <provider>
colay profiles [--json]
colay profiles set <provider> <profile> --model <id> [--effort low|medium|high]
colay profiles reset <provider> <profile>
colay usage [--json]
colay usage override <provider> --entered-by <audit-identity> [--used N] [--limit N] [--remaining N]
colay handover <task-id> --to <provider>
colay pause <task-id>
colay resume <task-id>
colay cancel <task-id>
colay explain-routing <task-id> [--json]
colay checkpoint <task-id> [--json]
colay doctor [--json]
colay compatibility [--json]
colay migrate {status|plan}
colay migrate apply [--dry-run]
colay migrate rollback plan [--backup <local-backup>]
colay migrate rollback apply --plan-hash <sha256> --approved-by <identity>
colay rollback plan --to <version>
colay rollback apply --to <version> --plan-hash <sha256> --approved-by <identity>
colay tui [task-id]

colay tui is the primary durable chat workspace. It starts or reconnects to the repository daemon, restores the latest session and selected task, and shows a text-only task list, conversation timeline, inspector, attention queue, and explicit composer target. The daemon continues after the TUI closes.

The wide layout has three panes; medium terminals hide the inspector, narrow terminals show one selected primary view, and terminals below 60 columns become read-only until resized. Use Tab/Shift+Tab to traverse panes, Ctrl+P or /tasks to switch tasks, Ctrl+O for the overview, Ctrl+L for the full log, and Ctrl+T to change the composer target. Selecting a task never silently retargets the composer. /admin opens the preserved five-panel administration dashboard and returns to chat without losing the explicit target. ? shows keyboard help; q exits when the composer is not focused.

colay daemon start is idempotent while its repository-local lease is healthy. The TUI performs daemon reconnect on startup. A stopped or stale daemon leaves the timeline readable but disables messages and task controls until colay daemon restart; it never opens a network listener. Messages are redacted before durable command submission and again before conversation projection.

Use /plan after sending a session-level goal. The daemon invokes one eligible official CLI in an explicitly read-only sandbox, requires exactly one bounded JSON task-graph proposal, validates its DAG, providers, profiles, concurrency, and write-scope isolation, and persists the revision without creating a task or worktree. /approve opens a text confirmation containing the exact proposal hash, nodes, dependencies, scopes, providers/profiles, risks, and proposed parallelism. Only y submits typed approval for that exact revision/hash; n/Esc, an offline daemon, an invalid plan, or a changed hash fails closed. Chat text such as "yes" has no approval authority.

No writable task before approval is a hard boundary. Exact approval atomically materializes the graph as queued session tasks. The daemon then claims only dependency-ready tasks, enforcing exact global/provider limits and normalized write-scope ownership in SQLite. Independent tasks run concurrently through official CLI adapters in separate Git worktrees and reach completed only after sealed checkpoint evidence and independent verification.

Phase 3 established the exact proposal-hash approval boundary, Phase 4 added bounded parallel execution, and Phase 5 completes the approved-result workflow without weakening either boundary.

Send @task-<id> ... to create an ordered durable instruction for one current graph task, or @all ... to fan out separately auditable instructions. Task selection still never changes the composer target. After intended sources are completed and verified, /integrate creates a read-only sealed preview. Its card displays the exact SHA-256 hash, base, ordered evidence, changed paths, blockers, and dedicated destination. /approve requires y for that exact preview; every source is revalidated before application only to the retained .colay/integration/<batch-id> worktree. /resolve turns a resolvable overlap or application failure into one auditable task whose result requires a new preview and approval. Merge to the user's branch, push, publication, automatic cleanup, and /retry remain unavailable.

Model profiles

Colay analyzes each task and automatically selects economy, standard, or premium; users do not choose a model per run. The built-in mappings below are current as of 2026-07-20:

Provider	Economy (low)	Standard (medium)	Premium (high)
Codex	gpt-5.6-luna	gpt-5.6-terra	gpt-5.6-sol
Claude	claude-haiku-4-5	claude-sonnet-5	claude-fable-5
Gemini	gemini-3.1-flash-lite	gemini-3.5-flash	gemini-3.1-pro-preview

Inspect effective settings with colay profiles or colay profiles --json. Administrators can override one entry with colay profiles set <provider> <profile> --model <id> [--effort low|medium|high], and remove the writable-layer override with colay profiles reset <provider> <profile>. Reset reveals the compiled or lower-precedence value; it does not delete it. The TUI exposes the same matrix and editor under f:profiles.

Layered TOML remains supported for managed deployments. A configured model must also be available to the installed official provider CLI and the authenticated account; a preset does not grant model access.

Configuration

Colay resolves versioned TOML configuration in this order, with later layers overriding earlier ones:

compiled defaults
< $COLAY_HOME/config.toml
< <repository>/.colay/config.toml
< $COLAY_CONFIG
< --config

COLAY_HOME defaults to ~/.colay on Unix and %USERPROFILE%\.colay on Windows. Configuration files are partial overrides: tables merge by key, while arrays replace the lower-precedence array rather than concatenate. Every loaded file must declare the supported config_version. Absent automatic layers are ignored, but normal runtime commands fail when an explicitly selected $COLAY_CONFIG or --config file is missing. init is the creation-path exception: it treats a missing explicit selector as the destination for its new minimal override.

Repository state remains local to the repository (by default, .colay); personal defaults and environment-selected configuration are global inputs, not a global state directory. A legacy .codex/orchestrator/config.toml is discovered without moving its state. If automatic discovery finds both legacy and current repository configuration, Colay fails closed until --config explicitly selects one. init writes a minimal configuration override and initializes state safely. Other read-only commands do not create repository state, but the first run—including run --plan-only—initializes and persists repository state. Start from config.example.toml.

See docs/architecture.md, docs/security.md, docs/operations.md, docs/compatibility.md, docs/testing.md, and docs/release.md for the implemented boundary and current limitations.