Skip to main content

orion-pm

Give cooperating agents a shared view of work.

MIT licensed · Local Python CLI · Exclusive task claims · No third-party runtime packages

Start locallyRead the complete guide

Two chats can start the same task.

Separate agents can pick the same task and both begin editing. A status label records progress, but it does not establish which worker currently owns the task.

Probe for overlapping work, then claim a task before editing. Keep the returned claim generation and task revision. Use those handles to attach evidence, complete the task, or return unfinished work. Browsers and other tools keep their own resource leases and action permissions.

One store. Two workers. Clear ownership.

Put the reviewed v0.1.0 wheel and its matching SHA256SUMS in an empty folder. Run these blocks in one shell. Verified on CPython 3.11.14, WSL2 Linux and ext4; no package-index download is required.

Install the reviewed wheel

sha256sum --check SHA256SUMS --ignore-missing &&
python3 -m venv .venv &&
.venv/bin/python -m pip install --no-index --no-deps orion_pm-0.1.0-py3-none-any.whl

Create a new local store

umask 077
export PM_DEMO_HOME="$(mktemp -d)/pm-store"
printf '%s\n' '{"schema_version":1,"projects":[{"id":"sample"}]}' > projects.json
.venv/bin/orion-pm --json --home "$PM_DEMO_HOME" init --projects projects.json
.venv/bin/orion-pm --json --home "$PM_DEMO_HOME" add --id example --title "Example work" --project sample --status todo

Claim a task, then return it to todo

.venv/bin/orion-pm --json --home "$PM_DEMO_HOME" probe example
.venv/bin/orion-pm --json --home "$PM_DEMO_HOME" claim example --holder session-a > claim.json
GENERATION=$(.venv/bin/python -c 'import json; print(json.load(open("claim.json"))["data"]["claim"]["generation"])')
REVISION=$(.venv/bin/python -c 'import json; print(json.load(open("claim.json"))["data"]["task"]["revision"])')
.venv/bin/orion-pm --json --home "$PM_DEMO_HOME" release example --holder session-a --generation "$GENERATION" --expect-revision "$REVISION"

Command surface

  • probe · show · surface: Inspect overlapping work, validated ownership and the shared task view. Unknown state remains unknown.
  • claim · renew · release: Acquire a task, retain its generation, renew while working, and return unfinished work to todo.
  • evidence · transition: Attach a scoped result and complete against --generation and the current --expect-revision.
  • overdue · triage · audit: Read recovery information. Triage is report-only; takeover and recovery are explicit guarded operations.

Small core. Useful boundaries.

  • A generation, not just a name: Reacquiring a task creates a new generation. A delayed worker cannot renew, release or complete a replacement claim using its old handle.
  • Evidence with a precise scope: Bind a result to an artifact, observation time and reference. A task marked done is not proof of publication or deployment.
  • Tools keep their leases: A PM task claim does not grant action permission or release a browser or phone. Each tool keeps its own native lease, cleanup and authorization checks.
  • Coordination on one trusted host: Normal operations stay local and offline. The core has no scheduler or legacy-store migration and does not fence workers on another host or isolate hostile same-user processes.

Links