@imdeadpool/colony-cli
Advanced tools
Local-first memory and coordination for Claude Code, Gemini CLI, OpenCode, Codex, and Cursor.
Local-first coordination for fleets of coding agents.
Claims, handoffs, plans, health, and memory for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and other agent runtimes.
npm install -g @imdeadpool/colony-cli
colony install --ide codex
colony health
v0.x - Current Patch LineColony is in the v0 hardening line. Upcoming patches focus on making the shipped coordination loop easier to trust in real multi-agent runs.
colony health, the local viewer, and
mcp_metrics receipts aligned so gaps are visible without digging through
SQLite.@imdeadpool/colony-cli package metadata current so users can see CI, npm
version, downloads, license, and supply-chain posture before installing.Colony is not a hosted control plane and it does not run your agents. Codex, Claude Code, Cursor, OMX, dmux, and other runtimes still execute work. Colony is the shared local substrate they use to coordinate.
It is built for the expensive part of multi-agent work: avoiding repeated
context reloads. Claims, handoffs, timelines, and prior decisions stay compact
until an agent explicitly hydrates the full record. The result is measurable —
colony gain reports both the shared reference model below and live
mcp_metrics rows from your local MCP server.
Runtimes run agents. Colony coordinates agents. Queen publishes claimable plans. Agents pull ready work. Stale signals evaporate.
Measured per-operation savings versus standard agent loops. See the receipts →
A human can ask Codex and Claude to solve the same runtime-manifest bug at the same time. Without a shared loop, both agents diagnose the same Turbopack root escape, edit the same schema file, and race two PRs for one fix.
With Colony, both agents start from hivemind_context, attention_inbox, and
task_ready_for_agent. The first agent records the diagnosis, claims the
task and files, and posts the intended fix. The second agent sees the live
claim and prior diagnosis before editing, so it can stand down, review, or
take a different unclaimed lane.
Colony does not run the agents for you. It makes duplicate work visible early, turns one solution into one implementation branch, and keeps the evidence in a shared task thread.
| Without Colony | With Colony |
|---|---|
| Agents collide on the same files. | Agents claim files before edits. |
| Humans schedule parallel work by hand. | Agents pull ready subtasks from Colony. |
| Progress is trapped in chat windows. | Working state is saved to task threads. |
| Old claims and handoffs stay noisy. | Signals decay, expire, and can be swept. |
| Follow-up ideas disappear. | Proposals can be reinforced and promoted. |
| Task lists become browsing surfaces. | task_ready_for_agent becomes the work picker. |
When a Codex or Claude session finishes a prompt, it doesn't just say "done" —
it returns a structured response with the PR link, the merge SHA, the files
that changed, the verification it ran, and what happened to the worktree
afterward. That format isn't ceremonial: it's the handoff payload. Colony
captures it as one observation, the next agent reads it instead of re-deriving
context, and mcp_metrics records the cost.
The five canonical sections every session response carries:
| Section | What it contains | Why it matters |
|---|---|---|
| Done. | One line. PR link + merge SHA, or "blocked: ". | The next agent can stop reading after the first line if everything's green. |
| Changed | Files touched, each with one-line annotation of what changed. | Code review is git diff; Colony memory is this list. |
| Verified | Lint, tests, build, typecheck — each as a checkmarked line. | Lets the next agent skip re-running what already passed. |
| Cleanup | Worktree pruned, branch deleted, claims released. | Confirms the session left no orphan state behind. |
| Remaining risk | Anything not covered. Empty when there's nothing to flag. | The honest line. If it's empty, the receipt is complete. |
When this format is consistent, every downstream agent can treat the response as a parseable artifact, not prose. That's why the cross-agent handoff costs 400 tokens instead of 30,000 — the receiving agent reads the receipt and resumes; it never re-reads the repo.
The receipt is generated and consumed in the same flow, but three different projects coordinate to make it work:
The structured response gets written through task_post and task_hand_off
into the local SQLite store. After that, colony search "PR #447" finds it,
colony timeline <session_id> replays the work that produced it, and
mcp_metrics carries the token cost. The receipt is searchable; the human
or next agent doesn't need the original chat window.
→ task_post: "PR #447 merged, savings model unified..."
→ task_hand_off: claims released on packages/core, apps/cli, apps/worker
→ obs_8af2c1: full structured body, FTS5-indexed
→ mcp_metrics: 17m 36s wall, ~400 tokens for the handoff
gx) — keeps work in worktrees, not on main
GitGuardEx gives every agent its
own worktree on an agent/* branch. Claims happen in the worktree, edits
happen in the worktree, the PR opens from the worktree, and after merge the
worktree is pruned and the branch is deleted — all in one command. Colony's
branch policy guard refuses claims on dev / main; gx is the part that
makes "claim on a worktree instead" easy to do.
gx branch start "show-live-savings" "codex" # creates agent/codex-show-live-savings
# ... agent works ...
# ... PR merges ...
gx branch end # prunes worktree + deletes branch
The agent's response carries this provenance in the Cleanup line:
"Main clean; agent worktree pruned; remote and local agent branch deleted."
That's gx reporting back through Colony.
OpenSpec holds the proposal-and-delta
representation of every change. Before code is written, the change exists as
openspec/changes/<change-id>/proposal.md plus a tasks.md and spec deltas.
The agent works against that change, and the change ID is the link between
the prompt and the receipt — making every PR traceable back to the spec it
implements.
openspec/changes/show-live-savings/
proposal.md — why
tasks.md — what to do
specs/savings/spec.md — deltas to the spec
After PR lands, the change is archived under openspec/changes/archive/,
keeping the historical record even after the working files move on.
oh-my-codex-colony is the runtime bridge: oh-my-codex runs the agent loop, Colony stores the claim, handoff, health, and memory receipts, and the bridge keeps both sides speaking the same compact coordination language.
| Without this chain | With Colony + gx + OpenSpec + the bridge |
|---|---|
| Agents finish work and the context dies in the chat window. | The receipt persists as an observation, searchable forever. |
Agents edit on main, collisions are common, rollbacks are scary. | Every agent works in an agent/* worktree; merge or discard is one command. |
"Why was this changed?" requires git log archeology and chat history. | The OpenSpec change ID points at the proposal, tasks, and deltas. |
| Runtime state lives apart from coordination state. | The oh-my-codex-colony bridge makes runtime state and Colony receipts align. |
| Every handoff replays repo + git log + chat (~30k tokens). | Every handoff is the structured receipt (~400 tokens). |
The structured response isn't a Colony feature — it's a contract that Colony,
gx, OpenSpec, and the oh-my-codex-colony bridge all happen to agree on.
Anything else that wants to participate (a new runtime, a CI bot, a code-review
agent) just needs to emit the same five sections.
TL;DR — a single cross-agent handoff costs 30,000 tokens without Colony and 400 with it. That's 99% saved on the most expensive coordination event in a multi-agent session, and Colony's
mcp_metricstable records every one so the savings are measured, not estimated.
Coordination is where multi-agent runs burn tokens. Every handoff, every "what was I working on", every "did someone already touch this file" turns into a re-read of the repo, the chat, and the git log. Colony makes those moments cheap by replacing replay with one compact observation.
Six mechanisms compound. The big-bar wins below come from at least two of them stacking on the same operation:
| Mechanism | What changes |
|---|---|
| Compression at rest | Every observation runs through @colony/compress before SQLite. Prose shrinks ~70% while paths, URLs, code, commands, versions, and dates stay byte-for-byte intact. |
| Progressive disclosure | search, timeline, attention_inbox, task_ready_for_agent return compact IDs plus snippets. Full bodies only ship via get_observations([ids]). |
| Cross-session recall | Instead of re-reading 5–10 files plus git log to rederive a prior decision, agents search and pull one observation. |
| Claim-aware routing | task_ready_for_agent returns the next claimable action and exact claim args, so agents stop browsing task lists just to choose work. |
| Stale-signal decay | Expired handoffs, weak claims, and stranded lanes surface as compact attention items instead of full historical transcripts. |
| Tiny handoffs | A durable handoff is branch + task + blocker + next + evidence, not a pasted session log. |
Each row is a real coordination operation. The standard column is what the
same operation costs without a shared substrate (agents must replay context).
The Colony column is the measured cost through mcp_metrics.
| Operation | Standard | Colony | Saved |
|---|---|---|---|
| Cross-agent handoff | 30,000 | 400 | 🟢 99% |
| Quota-exhausted handoff | 22,000 | 500 | 🟢 98% |
| Search result shape | 5,000 | 150 | 🟢 97% |
| Unread message triage | 10,000 | 600 | 🟢 94% |
| Review task timeline | 12,000 | 900 | 🟢 93% |
| Find active owner for a file | 6,000 | 500 | 🟢 92% |
| Ready-work selection | 9,000 | 700 | 🟢 92% |
| Plan subtask claim | 12,000 | 1,100 | 🟢 91% |
| Startup coordination sweep | 25,000 | 2,500 | 🟢 90% |
| Recover stranded lane | 18,000 | 1,800 | 🟢 90% |
| Resume task across sessions | 15,000 | 2,000 | 🟢 87% |
| Coordinate parallel agents | 20,000 | 3,000 | 🟢 85% |
| Operation | Frequency / session | Standard | Colony | Saved |
|---|---|---|---|---|
| Cross-agent handoff | 2x | 30,000 | 400 | 99% |
| Quota-exhausted handoff | 1x | 22,000 | 500 | 98% |
| Search result shape | 8x | 5,000 | 150 | 97% |
| Unread message triage | 4x | 10,000 | 600 | 94% |
| Review task timeline | 4x | 12,000 | 900 | 93% |
| Find active owner for a file | 6x | 6,000 | 500 | 92% |
| Ready-work selection | 3x | 9,000 | 700 | 92% |
| Plan subtask claim | 2x | 12,000 | 1,100 | 91% |
| Examples pattern lookup | 2x | 11,000 | 1,000 | 91% |
| Blocker recurrence | 2x | 10,000 | 900 | 91% |
| Startup coordination sweep | 1x | 25,000 | 2,500 | 90% |
| Recover stranded lane | 1x | 18,000 | 1,800 | 90% |
| Claim-before-edit check | 8x | 4,000 | 450 | 89% |
| Spec context recall | 2x | 14,000 | 1,600 | 89% |
| Health/adoption diagnosis | 1x | 16,000 | 1,800 | 89% |
| Drift / failed-verification recovery | 2x | 13,000 | 1,400 | 89% |
| Resume task across sessions | 3x | 15,000 | 2,000 | 87% |
| Coordinate parallel agents | 10x | 20,000 | 3,000 | 85% |
| Why-was-this-changed | 4x | 8,000 | 1,200 | 85% |
| Recall prior decision | 5x | 8,000 | 1,500 | 81% |
| Storage at rest (per observation) | 1x | 1,000 | 300 | 70% |
The table above is the reference model — the shared baseline for what these operations cost without Colony. The point of Colony is to give you live receipts for the same operations in your own work. Three surfaces, same data:
colony gain # CLI: live + reference, last 7 days
colony gain --hours 24 --json # last 24 hours as JSON
colony gain --operation search # filter live rows to one tool name
colony gain --session-limit 0 # every live session in the window
colony gain --input-cost-per-1m 1.25 --output-cost-per-1m 10
{ "name": "savings_report", "input": { "hours": 24 } }
Or open http://127.0.0.1:6510/savings while colony viewer is running.
Add ?input_usd_per_1m=<usd>&output_usd_per_1m=<usd>, set
COLONY_MCP_INPUT_USD_PER_1M / COLONY_MCP_OUTPUT_USD_PER_1M, or pass the
flags above to convert tokens into estimated USD per operation.
The receipt model. Every wrapped MCP tool call writes a row to the
mcp_metricsSQLite table with(operation, ts, input_bytes, output_bytes, input_tokens, output_tokens, duration_ms, ok, session_id, repo_root, error_code, error_message). Cost is computed at report time from those token receipts and the USD-per-1M rates you pass in, so older rows pick up cost visibility without a schema migration.
Every agent session runs the same six-step coordination loop. Compact first. Hydrate only when needed. Claim before editing.
| # | Step | What it does |
|---|---|---|
| 1 | hivemind_context | Who's active, what's hot, what's owned, recent memory. |
| 2 | attention_inbox | Handoffs, blockers, stale lanes that need attention. |
| 3 | task_ready_for_agent | Pull claimable work matched to this agent — not browse. |
| 4 | task_plan_claim_subtask | Take exactly one unblocked wave slice from a Queen plan. |
| 5 | task_claim_file | Make ownership visible before mutating the file. |
| 6 | task_note_working | Leave a compact resumable trail for the next session. |
Steps 1–3 cost almost nothing (compact IDs and snippets). Full bodies only ship
when an agent explicitly calls get_observations([ids]). That's where the
token savings come from.
Colony sits between the runtimes that execute work and the local SQLite store that persists state. Queen is a peer, not a controller — it publishes claimable plans, but agents still pull and complete the work themselves.
| Layer | Responsibility |
|---|---|
| Codex / Claude Code / Cursor / Gemini CLI / OpenCode | Execute tools, edit files, run tests, talk to the user. |
| OMX / dmux / terminal sessions | Start sessions, panes, worktrees, and runtime process surfaces. |
| Colony | Route work, track claims, record handoffs, store memory, report health. |
| Queen | Publish deterministic wave plans; does not launch shells or command agents. |
This split keeps execution close to the existing agent runtime while making the coordination state shared, inspectable, and local.
npm install -g @imdeadpool/colony-cli
Register one or more runtimes:
colony install --ide claude-code
colony install --ide codex
colony install --ide cursor
colony install --ide gemini-cli
colony install --ide opencode
Check the install:
colony status
Requirements: Node.js 20+, pnpm for repository development, local SQLite
state under ~/.colony.
colony health # readiness, adoption, stale signals
colony health --fix-plan # guided recovery plan
colony status # storage, IDEs, worker, memory
colony search "error or decision" # search prior observations
colony coordination sweep --json # report stale claims, expired handoffs
colony queen sweep # find stalled or unclaimed plans
colony viewer # local read-only graph at :6510
pnpm smoke:codex-omx-pretool # verify lifecycle bridge
pnpm smoke:health-repair-loop # prove bridge + cleanup compose
Installed Codex and Claude hooks inject the quota-safe operating contract:
start with hivemind_context, then attention_inbox, then
task_ready_for_agent; accept or decline handoffs, claim files before edits,
keep task_note_working current, run focused verification, and hand off before
quota or session stop.
colony health shows whether agents are only reading Colony or actually
coordinating through it. The first screen is action-first: bad readiness
areas are grouped into the next exact command or MCP call. Lower-priority
follow-ups stay hidden until --verbose.
Readiness summary
coordination_readiness good
execution_safety ok
queen_plan_readiness good
working_state_migration good
signal_evaporation good
Healthy runs trend toward:
| Metric | Target |
|---|---|
hivemind_context -> attention_inbox | 50%+ |
attention_inbox -> task_ready_for_agent | 90%+ |
task_ready_for_agent -> task_plan_claim_subtask | 30%+ when plans exist |
| claim-before-edit | 50%+ |
| Colony note share | 70%+ |
| stale claims | near zero active |
| If this is red | First move |
|---|---|
coordination_readiness | Check agent startup loop adoption. |
execution_safety | Run pnpm smoke:codex-omx-pretool and verify hook install. |
queen_plan_readiness | Publish or repair claimable Queen plans. |
working_state_migration | Use task_note_working instead of ad hoc notepads. |
signal_evaporation | Run a dry sweep, then explicit safe stale-claim cleanup. |
execution_safety includes a source-level root_cause in --json when edit
telemetry cannot be trusted:
| Root cause | Meaning | First command |
|---|---|---|
lifecycle_bridge_unavailable | runtime/lifecycle bridge is unavailable | colony install --ide <ide> then pnpm smoke:codex-omx-pretool |
lifecycle_bridge_silent | bridge is available, but PreToolUse edit-path telemetry is empty or near-zero | colony install --ide <ide> then colony health --hours 1 --json |
lifecycle_paths_missing | PreToolUse exists, but edit events lack file_path | colony bridge lifecycle --json --ide <ide> --cwd <repo_root> < colony-omx-lifecycle-v1.pre.json |
lifecycle_claim_mismatch | paths exist, but claim metadata does not match edit scope | colony bridge lifecycle --json --ide <ide> --cwd <repo_root> < colony-omx-lifecycle-v1.pre.json |
no_hook_capable_edits | the selected window has no file edit events to diagnose | colony health --hours 1 --json |
When task_claim_file before edits says metric unreliable, fix runtime
bridge or metadata first. Do not treat a bad claim ratio as agent discipline
until omx_runtime_bridge.status is fresh and edit events carry paths.
Safe stale-claim cleanup is opt-in because releasing a claim changes who may edit a file:
colony health --fix-plan
colony coordination sweep --json
colony coordination sweep --release-safe-stale-claims --json
colony health --hours 1
Colony follows a stigmergic model: agents leave local traces, other agents react to useful traces, and stale traces evaporate.
| Biology | Colony |
|---|---|
| ant | agent session |
| nest | repository |
| pheromone | claim, proposal, handoff, message |
| evaporation | TTL, decay, sweep |
| response threshold | agent profile plus ready-work ranking |
| queen | plan publisher, not commander |
Practical effects:
| Capability | Current surface |
|---|---|
| Install runtime hooks | colony install --ide claude-code, codex, cursor, gemini-cli, opencode |
| Capture local observations | lifecycle hooks, prompt events, tool events, session heartbeat |
| Search prior work | colony search, MCP search, timeline, get_observations |
| See active lanes | MCP hivemind_context, attention_inbox, CLI coordination reports |
| Claim work safely | task_ready_for_agent, task_plan_claim_subtask, task_claim_file |
| Coordinate agents | task_post, task_message, handoffs, working notes |
| Publish wave plans | Queen plans and task_plan_* MCP tools |
| Clean stale signals | colony coordination sweep, colony queen sweep, health fix plans |
| Inspect the graph | colony viewer local read-only graph |
| Measure token savings | colony gain, MCP savings_report, viewer /savings |
| Prove behavior | colony health, smoke tests, adoption metrics |
Use Colony when you run more than one coding agent in the same repo, use worktrees or parallel branches, need local-first memory, or want stale claims and handoffs to stop shaping current work.
Installs register the MCP server as colony, so tools appear as
mcp__colony__.... Colony MCP uses progressive disclosure: compact IDs,
snippets, routing hints, and status rows first; full observation bodies only
when requested.
| Tool | Use |
|---|---|
hivemind_context | Start/resume with active lanes, ownership, hot files, memory hits. |
attention_inbox | See handoffs, messages, blockers, stale cleanup, stalled lanes. |
task_ready_for_agent | Pull claimable work matched to the agent. |
task_plan_claim_subtask | Claim a Queen subtask and its file scope. |
task_claim_file | Make ownership visible before editing. |
task_note_working | Save compact resumable state. |
task_message | Send directed or broadcast agent coordination messages. |
task_foraging_report | Review weak proposals and promoted future work. |
savings_report | Live mcp_metrics rows + reference model; same data as colony gain. |
Copy-paste startup:
{
"name": "hivemind_context",
"input": {
"repo_root": "/abs/repo",
"query": "current task or branch",
"memory_limit": 3,
"limit": 20
}
}
{
"name": "attention_inbox",
"input": {
"session_id": "sess_abc",
"agent": "codex",
"repo_root": "/abs/repo"
}
}
{
"name": "task_ready_for_agent",
"input": {
"session_id": "sess_abc",
"agent": "codex",
"repo_root": "/abs/repo",
"limit": 5
}
}
When plan work is claimable, task_ready_for_agent returns
next_tool: "task_plan_claim_subtask" plus exact claim_args. When no work
is claimable, it returns an empty state that tells the agent to publish a
Queen/task plan for multi-agent work.
Full MCP catalog: docs/mcp.md
Default local state:
~/.colony/settings.json
~/.colony/data.db
~/.colony/models/
~/.colony/logs/
SQLite stores the coordination substrate. Embeddings are lazy and local by
default with Xenova/all-MiniLM-L6-v2; Ollama and OpenAI-style providers are
opt-in through settings. Persisted prose is compressed at rest through
@colony/compress; technical tokens such as paths, URLs, code, commands,
versions, dates, and numeric literals are preserved byte-for-byte.
apps/cli user-facing colony binary
apps/mcp-server stdio MCP server and tool registrations
apps/worker local HTTP worker, viewer host, embedding backfill
packages/core MemoryStore facade and domain models
packages/storage SQLite, FTS5, migrations, storage API
packages/hooks lifecycle hook handlers and active-session heartbeat
packages/installers per-runtime integration modules
packages/queen deterministic plan decomposition and sweeps
packages/spec spec grammar, changes, scoped context
docs architecture and workflow docs
Deeper docs:
pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build
Before merging changes:
pnpm typecheck && pnpm lint && pnpm test && pnpm build
MemoryStore so compression, privacy stripping, and storage invariants apply.@colony/storage.@colony/config.get_observations.colony.Today, colony health reports what's wrong. Tomorrow, it should fix what's
wrong. The end state is a coordination substrate that detects, diagnoses, and
repairs itself — so multi-agent fleets stay healthy without a human running
sweep commands by hand.
Legend
| Symbol | Meaning |
|---|---|
| ✅ | shipped, on main, covered by tests |
| 🟡 | partially shipped — works but needs hardening or polish |
| 🔵 | in active design or implementation |
| ⏳ | planned, with a known shape but no PR yet |
| 💭 | exploration — direction is right but specifics are open |
v0 — Observe & Report ✅ shippedThe substrate exists. It tells you the truth about what's happening, captures the evidence in compact form, and gives you the exact command to fix problems yourself. This is the foundation everything else builds on.
Coordination loop primitives
hivemind_context — start/resume with active lanes, ownership, hot files, memory hitsattention_inbox — handoffs, blockers, stale lanes that need attentiontask_ready_for_agent — pull claimable work matched to the agenttask_plan_claim_subtask — claim a Queen subtask and its file scopetask_claim_file — make ownership visible before editingtask_note_working — save compact resumable statetask_message — directed and broadcast agent coordination messagestask_post and task threads — durable per-task discussiontask_hand_off — release files, summarize, declare next stepsStorage and compression
~/.colony/data.db@colony/compress — ~70% prose compression, byte-perfect for paths/URLs/code/commands/versions/datesXenova/all-MiniLM-L6-v2MemoryStore facade that enforces compression invariantsRuntime integration
PreToolUse, PostToolUse, prompt events, session heartbeatmcp__colony__*colony status — installed runtimes, worker state, memory counts, embedding statusHealth and diagnostics
colony health with five readiness pillars (coordination, execution, queen, working state, signal evaporation)colony health --fix-plan — printable per-area recovery commandscolony health --json with root_cause, evidence, and source-level reasonsavailable, silent, paths_missing, claim_mismatch)good/ok classificationToken-savings receipts
mcp_metrics SQLite table — per-call rows with input/output bytes & tokens, duration, ok flagcolony gain CLI showing live receipts plus reference modelsavings_report MCP tool returning the same data/savings viewer route at http://127.0.0.1:6510/savingsCOLONY_MCP_INPUT_USD_PER_1M envpackages/core/src/savings-reference.tsQueen wave plans
task_plan_* MCP tool familycolony queen sweep — find stalled or unclaimed planstask_foraging_report) for weak proposals and promotionsSignal lifecycle
colony coordination sweep)--release-safe-stale-claims flagInspection surfaces
colony viewer — read-only local web graph at :6510colony search — FTS5-backed search across observationscolony timeline <session-id> — per-session chronological viewcolony observe — live task-thread and coordination feedpnpm smoke:codex-omx-pretool, pnpm smoke:health-repair-loopShipping discipline
pnpm publish:cli / --dry-run)scripts/e2e-publish.sh)
time-to-healthy: hours. A human notices the issue, readscolony health --fix-plan, decides which commands are safe, and runs them.
v0.x — Hardening & Adoption 🟡 you are hereEverything in v0 works, but there are seams between "the feature exists" and "the feature is reliable enough to lean on." v0.x closes those seams. Most of these are mechanically simple but require real multi-agent runs to validate.
Lifecycle bridge polish
runtime_bridge_status exposed in --jsonpath_mismatch detection as dominant claim-miss reason.pre.jsonContention triage
owner=unknown (cross-reference session metadata)colony observeAdoption nudges
task_list vs task_ready_for_agent ratio reporting0/107 sessions in current data — needs an explicit nudgetask_ready_for_agent empty-state when plan work exists but isn't claimedcolony health that walks a new repo through first-week setupStale signal sweep ergonomics
--release-safe-stale-claims for explicit cleanupcolony task quota-release-expired --all-safe)Receipts and observability
mcp_metrics schema and populationcolony gain --operation, --hours, --session-limit, --jsoncolony gain if rates are configuredmcp_metrics aggregationMulti-runtime confidence
tests/scenarios/
time-to-healthy: still hours, but the time the human spends deciding what to run drops sharply because every signal carries itscmd:andtool:already.
v1 — Propose & Apply ⏳ plannedThe defining v1 jump: Colony stops printing fix commands and starts running them. Every fix is reversible, audited, and behind an explicit opt-in policy. The CLI surface is tight; the safety properties are loud.
Apply primitives
colony heal --apply --dry-run — show what would changecolony heal --apply --safe-only — only stale-signal sweeps and quota-releasecolony heal --apply --policy=auto — contention rules + branch guard--yes--policy=<file> or .colony/policy.yaml in repo rootContention auto-resolver
Branch policy guard
task_claim_file on main/dev (configurable list)gx branch start "<task>" "<agent>" when claim is rejectedbranch_policy.allowed_prefixes config (default: agent/*)Quota relay
task_claim_quota_release_expired accepts batch inputtask_messageLifecycle reclaim
path_mismatch is detected, attempt automatic reclaim in same sessioncolony health --hours 1Plan-claim auto-nudge
task_ready_for_agent returns plan work, hook injects exact claim_argstask_plan_* toolRepair-as-observation
repair observation with action, target, reasoncolony search "repair" surfaces historycolony observe --repairs filtered live feedcolony gain so healing has a measured costPolicy as code
.colony/policy.yaml schema with allowed_actions, ttl_overrides, branch_rules, takeover_thresholdscolony policy lint validates the filecolony policy show prints effective merged policy
time-to-healthy: minutes. First agent's startup hook runscolony heal --apply --safe-only, regressions clear before the human notices.
v2 — Continuous Healing 💭 explorationMove the loop off the terminal. The worker process — which already hosts the viewer and runs background embedding backfills — gains a heal loop. Adoption of v2 features assumes v1's repair primitives are stable enough that the human's role becomes setting policy, not running commands.
Healing daemon
colony worker --heal runs sweep + safe-fix loop on configurable cadence (default: every 5 min)colony healthmcp_metrics pipeline so cost is measurableAdaptive tuning
Predictive routing
task_ready_for_agent ranks claimable work using mcp_metrics historyfit × estimated_speed × claim_likelihoodSpecialist routing
.colony/specialists.yamlProposal auto-promotion
Failure-pattern memory
task_ready_for_agent annotates ready work with "this kind of edit failed N times before"Replay & rewind
colony replay --until <ts> to show the substrate at a past moment
time-to-healthy: seconds. The worker loop catches regressions as they happen; the human's job becomes policy review, not operations.
v3+ — Federated Colonies 💭 horizonOnce a single repo's substrate is healing itself, the next surface is across repos. Federation is strictly opt-in and observation bodies stay local-first by default. This isn't "Colony in the cloud" — it's "Colony substrates can talk to each other when their owners say so."
time-to-healthy: still seconds, but problems that would have been unique to one repo are now caught early because the substrate has seen them happen elsewhere.
Every roadmap item is judged against one number: how long does it take Colony to detect and repair a regression without human intervention?
| Phase | Time-to-Healthy | Trigger |
|---|---|---|
v0 | hours (human-paced) | someone notices, runs colony health --fix-plan, copy-pastes commands |
v0.x | hours | same, but finding the right command is faster (better evidence) |
v1 | minutes | colony heal --apply runs on first agent's startup or on demand |
v2 | seconds | continuous worker loop catches regressions before they propagate |
v3+ | seconds (cross-repo) | federated substrates flag known-bad patterns before the regression lands |
If a contention sits unresolved for two hours today and for two seconds in v2, that's the win. Everything else — federated memory, predictive routing, policy files — is a means to that end.
These are non-goals, even at v3+. If any of them break, the system stops being Colony and starts being a different product.
mcp_metrics and observations. If you can't colony search it later, it didn't happen.colony heal --apply refuses and surfaces the decision to a human. False-positive auto-fixes are worse than missed ones.The shortest path from "I wish Colony did X" to "Colony does X" is using Colony on real work, then opening an issue with the specific signal you wished was healed automatically. Concretely:
colony health --json output when something felt wrongThe roadmap above is opinionated but not closed. The order of items in any phase is negotiable based on which signals are causing the most pain in real use.
Read CONTRIBUTING.md for the current policy. Today's
contribution path is:
gx branch start "<task>" "<agent-name>"
Then use Colony on real work: start with hivemind_context,
attention_inbox, and task_ready_for_agent; claim files before mutation;
leave task_note_working or task_post breadcrumbs; verify the touched
behavior; and finish with a PR through gx branch finish --via-pr.
Every PR should report where coordination felt wrong: stale claims, confusing
handoffs, missing session context, noisy proposals, stranded sessions, missed
hot files, or edits that should have been claimed before mutation. If nothing
felt wrong, say Coordination friction: none observed.
For code changes, prefer small observable primitives over central orchestration. Colony should help agents coordinate by leaving durable local traces, not by becoming a remote control plane.
Colony started from work on JuliusBrussee's cavemem repository. Credit to JuliusBrussee for the original base.
MIT © Imdeadpool
FAQs
Local-first memory and coordination for Claude Code, Gemini CLI, OpenCode, Codex, and Cursor.
We found that @imdeadpool/colony-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
arXiv now limits authors to two submissions a month as AI slop overwhelms moderators, delays good papers, and sparks debate over applying the limit to everyone.
Research
/Security News
A new GhostAction wave hits hundreds of GitHub repos, expanding CI/CD secret theft to cloud and AI credentials in source code and git history.
Research
/Security News
Tensorlake npm SDK version 0.5.144 was compromised in a ChainDrop / Shai-Hulud attack, delivering credential-stealing malware.