# Orc[hestrator]

> The shared work board for humans and AI agents. An MCP server that keeps work items,
> dependencies, gates, agent presence and claims in one place, so an agent on any machine works
> from the same state.

## What it is

Orc[hestrator] is a Model Context Protocol server for agent work management, plus a web UI for the
human. Items move through `queue → work → review → done` with server-enforced transitions,
dependency gating and note-schema gates. Every session registers as a `hostname / agent_id /
session_id` triple, heartbeats, and can claim an item or a free-form resource so two agents do not
duplicate work. Attribution is recorded per request.

It is not an agent runtime: it does not spawn or supervise agents. It is not a memory system:
memory stores facts, Orc stores the structure of work.

## Concepts

- Items: hierarchical work units, four levels, with priority, complexity, tags and due dates.
- Workflow: trigger transitions (start, complete, block, resume, cancel, reopen).
- Dependencies: directed edges with an `unblock_at` threshold; cycles rejected.
- Notes: keyed per phase; required notes gate transitions.
- Presence: sessions with heartbeat and stale reaping.
- Claims: work items or free-form resources, with conflict detection.
- Attribution: `agent_id` resolved per request and stored on writes.

## Tools

31 tools, 7 prompts, 6 resources. The full list is generated in `docs/TOOLS.md`.

The eight that matter in a normal session: `get_context`, `get_next_item`, `manage_items`,
`create_work_tree`, `advance_item`, `manage_notes`, `agent_register`/`agent_heartbeat`/`agent_end`,
and `claim`/`release`/`conflicts`.

## Install

Distribution on PyPI: `orc-hestrator-server` (the name `orc-hestrator` is reserved by the
PyPI normalization rules; the repository and brand stay `orc-hestrator`).

```bash
# stdio (default) — runs in the client's process
uvx orc-hestrator-server

# central HTTP server — needs the 'ui' extra (fastapi + uvicorn)
uvx --from 'orc-hestrator-server[ui]' orc-serve
```

Configuration: `ORC_DB` (database path, default `~/.orc/tasks.db`), `ORC_CONFIG` (note-schema
config), `MCP_HOST`/`MCP_PORT` (default 127.0.0.1:3201). The transport is chosen by the command:
`orc` (and `orc-mcp`) run stdio, `orc-serve` runs `streamable-http` (needs the `[ui]` extra);
`MCP_TRANSPORT` remains an override. Details in `docs/CONFIGURATION.md`.

## Links

- Site: https://orc-hestrator.dev
- PyPI: https://pypi.org/project/orc-hestrator-server/
- Repository: https://github.com/filhocf/orc-hestrator
- Formerly published as `task-orchestrator-py`. License: MIT.
