TORCH: Task Orchestration via Relay-Coordinated Handoff

TORCH is a portable Nostr-based task locking toolkit for multi-agent coordination.

First-run quickstart

From the repository root:

npm install
cp torch-config.json /path/to/your-project/torch-config.json # optional template step when vendoring TORCH
npm run lock:check:daily
AGENT_PLATFORM=codex npm run lock:lock -- --agent docs-agent --cadence daily
npm run lock:list

Project configuration (torch-config.json)

Create a torch-config.json file in your project root (or set TORCH_CONFIG_PATH) to override defaults per repo:

• nostrLock.namespace (d-tag/tag namespace)
• nostrLock.relays
• nostrLock.ttlSeconds
• nostrLock.queryTimeoutMs
• nostrLock.dailyRoster / nostrLock.weeklyRoster
• dashboard.defaultCadenceView (daily, weekly, or all)
• dashboard.defaultStatusView (active or all)
• scheduler.firstPromptByCadence.daily / .weekly

Weekly alignment maintenance is available via src/prompts/weekly/repo-fit-agent.md, which is designed to keep TORCH defaults and docs tuned to the host repository over time.

Default first-run behavior is configured so daily scheduling starts with scheduler-update-agent.

Optional dashboard:

npm run dashboard:serve
# then open http://localhost:4173/dashboard/

Included

• src/nostr-lock.mjs — Generic lock/check/list CLI
• src/docs/TORCH.md — Protocol summary and usage
• src/prompts/ — Generic scheduler prompts and flow
• skills/ — Repository-local skill guides for agent onboarding and repeatable workflows
• examples/ — Optional scheduler overlay examples for adapting TORCH to downstream repositories
• dashboard/index.html — Static lock dashboard

CLI dependencies

Declared in package.json and pinned:

• [email protected]
• [email protected]

NPM script helpers

• npm run lock:check:daily
• npm run lock:check:weekly
• npm run lock:list
• npm run lock:lock -- --agent <agent-name> --cadence <daily|weekly>
• npm run dashboard:serve

Environment variables

• NOSTR_LOCK_NAMESPACE
• NOSTR_LOCK_RELAYS
• NOSTR_LOCK_TTL
• NOSTR_LOCK_QUERY_TIMEOUT_MS
• NOSTR_LOCK_DAILY_ROSTER
• NOSTR_LOCK_WEEKLY_ROSTER
• TORCH_CONFIG_PATH
• AGENT_PLATFORM

Roster precedence

The lock CLI resolves roster names in this order:

1. NOSTR_LOCK_DAILY_ROSTER / NOSTR_LOCK_WEEKLY_ROSTER (comma-separated env overrides).
2. torch-config.json (nostrLock.dailyRoster / nostrLock.weeklyRoster).
3. src/prompts/roster.json (daily / weekly canonical scheduler roster).
4. Built-in fallback roster (used only if src/prompts/roster.json is unreadable).

lock --agent validates names against the resolved cadence roster, and check/list report lock events whose agent names do not match scheduler roster entries exactly.

Example

NOSTR_LOCK_NAMESPACE=my-project \
AGENT_PLATFORM=codex \
node src/nostr-lock.mjs lock --agent docs-agent --cadence daily