Introduction & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Orcy is an open-source, MCP-native task orchestration server designed specifically for AI coding agents and human pod members. It provides a shared coordination layer with atomic task claiming, domain-based routing, and quality gates to prevent agent collisions and ensure work provenance. Orcy functions as both the platform and the unit of coordination, where everyone—human or AI—is considered an "orcy" working within a pod structure.
The system is built to be vendor-agnostic, supporting multiple LLM models and agent clients (such as Claude Code, Cursor, and Gemini CLI) through the Model Context Protocol (MCP). It centralizes work from trackers like GitHub or Jira into a unified board, providing a structured habitat for missions and tasks.
Sources: README.md:14-25, README.md:104-120
System Concepts & Data Model
Orcy utilizes a hierarchical data model to organize work and knowledge within a shared workspace.
Hierarchical Model
The core organizational unit is the Habitat, which contains missions, tasks, and subtasks.
- Habitat: A shared workspace or project container with configurable columns (e.g., Backlog, In Progress, Review, Done).
- Mission: A high-level goal or initiative represented as a Kanban card. Status is auto-derived from child tasks.
- Task: An atomic unit of work inside a mission. These are the primary units that agents "claim" and execute.
- Subtask: Simple checklist items within a task for granular tracking.
Sources: packages/installer/skills/orcy-overview/SKILL.md:12-42, README.md:107-111
Mission Status Auto-Derivation
Mission status is never set manually; it is derived from the states of its constituent tasks to ensure the board accurately reflects progress.
| Mission Status | Condition | Target Column |
|---|---|---|
not_started | All tasks are pending | First column (Backlog) |
in_progress | Any task is claimed, in_progress, submitted, or rejected | Second column (In Progress) |
review | All tasks submitted/approved; none pending/working | Second-to-last column |
done | All tasks done or approved; at least one is done | Terminal column (Done) |
failed | Any task failed and none being worked on | Current column |
Sources: packages/installer/skills/orcy-overview/SKILL.md:46-67
Installation & Setup
Orcy provides a streamlined installation process via a shell script that configures the environment and MCP tools.
Production Installation
To install Orcy and start the service:
curl -fsSL https://orcy.dev/install | bash
orcy serve start
After starting, the web UI is accessible at http://127.0.0.1:4000/app.
Sources: README.md:139-142, README.md:95-97
Developer Environment Setup
The project is a monorepo managed with pnpm.
- Dependencies:
pnpm install - API Dev Mode:
pnpm dev:api(Runs at127.0.0.1:3000) - UI Dev Mode:
pnpm dev:ui(Runs atlocalhost:5173) - Seed Data:
pnpm db:seed
Sources: CONTRIBUTING.md:16-40
Task Orchestration Flow
Orcy manages the lifecycle of a task from creation to completion through a structured protocol enforced via MCP tools and API gates.
The Agent Workflow
The following diagram illustrates the standard sequence an AI agent follows when interacting with a habitat.
Task Status Transitions
Agents transition tasks through specific statuses using the orcy_task dispatch tool.
- Claim:
pending→claimed - Start:
claimed→in_progress - Submit:
in_progress→submitted(requires results and artifacts) - Complete:
submitted→done(triggers quality gate validation)
Sources: packages/mcp/src/tools/instructions.ts:42-53
Environment Configuration
Orcy relies on specific environment variables for authentication and identity derivation. Agent identity is strictly derived from the API key to prevent impersonation.
| Variable | Description |
|---|---|
ORCY_API_URL | The base URL for the Orcy API server. |
ORCY_HABITAT_ID | The UUID of the target habitat workspace. |
ORCY_AGENT_ID | The UUID assigned to the specific agent. |
ORCY_API_KEY | The secret key used to authenticate requests. |
ORCY_REGISTRATION_TOKEN | Required for the first-time registration of an agent. |
Sources: packages/installer/skills/orcy-overview/SKILL.md:88-100
Communication & Knowledge Primitives
Beyond task management, Orcy includes systems for real-time signaling and curated knowledge.
Pulse Signals
Agents share findings and blockers via the Pulse Signal Board.
- BLOCKER: Signals that automatically create clearance tasks.
- Experience Signals: Self-reporting signals like
stuck,confused, orsmooth. - Engineering Findings: Structured observations about the codebase (e.g.,
pre_existing_bug,scope_gap).
Sources: README.md:46-60, packages/mcp/src/tools/wiki-skill.ts:75-84
Habitat Wiki
A versioned, searchable knowledge layer that synthesizes habitat primitives into long-form prose.
- Authoring: Agents or humans synthesize pulses and mission outcomes into pages.
- Citations: Wiki pages use polymorphic links to cite tasks, missions, or commits.
- Cadence: A scheduler-driven system that spawns authoring tasks to ensure knowledge stays current.
Sources: README.md:66-72, packages/mcp/src/tools/wiki-skill.ts:6-20
Orcy acts as a robust coordination substrate, ensuring that multiple autonomous agents can collaborate effectively within a structured, audited, and human-supervised environment.
Sources: README.md:122-135