Archivestr/torch

TORCH: Task Orchestration via Relay-Coordinated Handoff

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

Why Run Torch? (The Cool Stuff)

TORCH isn't just another script—it's an operating system for your AI workforce. Here’s why it’s awesome:

• Decentralized Coordination: No central server required. Agents coordinate via Nostr relays like digital telepathy.
• Platform Agnostic: Whether you're running Jules, Codex, or Claude, TORCH is the universal language they all speak.
• Long-Term Memory: Built-in memory systems allow agents to store context, learn from mistakes, and get smarter over time.
• Verifiable Handoffs: Trust, but verify. Agents must pass tests and linters before they can mark a task as complete.
• Self-Healing: If an agent stalls or crashes, the scheduler detects the pulse loss and reassigns the work. The factory must grow.
• Drop-in Divinity: No complex SaaS integrations. Just drop the torch folder into your repo and you're live.

Installation

npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz

TORCH is distributed from GitHub tarballs and is not currently published to the npm registry.

Development

For instructions on how to contribute to TORCH, including building, testing, and linting, please see CONTRIBUTING.md.

Quick start:

npm install
npm run build
npm test

Usage

CLI

The torch-lock CLI allows you to check, lock, and list tasks.

# Check locks for a specific cadence
npx --no-install torch-lock check --cadence daily

# Lock a task for an agent
AGENT_PLATFORM=codex npx --no-install torch-lock lock --agent docs-agent --cadence daily

# List all active locks
npx --no-install torch-lock list

# Mark a task as completed (permanent)
AGENT_PLATFORM=codex npx --no-install torch-lock complete --agent docs-agent --cadence daily

# Initialize TORCH in a new repository
npx --no-install torch-lock init

# Update TORCH configuration and scripts
npx --no-install torch-lock update

# Remove TORCH completely from this project
npx --no-install torch-lock remove

# Run the Dashboard
npx --no-install torch-lock dashboard

Memory CLI

The torch-lock CLI also supports memory operations:

# List memories (optional filters: --agent, --type, --tags, --pinned)
npx --no-install torch-lock list-memories --limit 5

# Inspect a specific memory
npx --no-install torch-lock inspect-memory --id <memory-id>

# Pin/Unpin a memory
npx --no-install torch-lock pin-memory --id <memory-id>
npx --no-install torch-lock unpin-memory --id <memory-id>

# Check memory stats
npx --no-install torch-lock memory-stats

Prompt Governance & Versioning CLI

Agent prompts are changed through a governance workflow that archives the previous version before overwriting, enabling full rollback.

# Propose a change to an agent prompt
npx --no-install torch-lock proposal create \
  --agent my-agent \
  --target src/prompts/daily/my-agent.md \
  --content /path/to/new-content.md \
  --reason "Add missing EXIT CRITERIA section"

# List pending proposals
npx --no-install torch-lock proposal list
npx --no-install torch-lock proposal list --status pending

# Inspect or apply a proposal
npx --no-install torch-lock proposal show --id <proposal-id>
npx --no-install torch-lock proposal apply --id <proposal-id>
npx --no-install torch-lock proposal reject --id <proposal-id> --reason "..."

# List available archived versions of a prompt
npx --no-install torch-lock rollback --target src/prompts/daily/my-agent.md --list

# Roll back to the most recent archived version
npx --no-install torch-lock rollback --target src/prompts/daily/my-agent.md

# Roll back to a specific version by hash fragment
npx --no-install torch-lock rollback --target src/prompts/daily/my-agent.md --strategy <hash>

State Backup CLI

Snapshot agent runtime state (long-term memory and scheduler state) to a timestamped directory under .torch/backups/.

# Create a snapshot
npx --no-install torch-lock backup

# List existing snapshots
npx --no-install torch-lock backup --list

# Write snapshot to a custom directory
npx --no-install torch-lock backup --output /path/to/backup-dir

See docs/prompt-versioning.md for the full workflow, restore procedure, and storage layout.

Configuration (torch-config.json)

Create a torch-config.json file in your project root to configure TORCH for your repository. You can use the included torch-config.example.json as a template.

Configuration options:

• nostrLock.namespace (d-tag/tag namespace)
• nostrLock.relays (array of relay URLs)
• nostrLock.ttlSeconds (lock duration in seconds)
• nostrLock.queryTimeoutMs (timeout for relay queries)
• nostrLock.dailyRoster / nostrLock.weeklyRoster (explicit rosters)
• dashboard.defaultCadenceView (daily, weekly, or all)
• dashboard.defaultStatusView (active or all)
• dashboard.hashtag (custom hashtag for lock events)
• scheduler.firstPromptByCadence.daily / .weekly (first prompt to run)
• scheduler.paused.daily / .weekly (array of agent names to pause locally)

Dashboard

The dashboard provides a live view of lock events.

npx --no-install torch-lock dashboard --port 4173 --host 127.0.0.1
# Open http://localhost:4173/dashboard/

By default, the dashboard binds to 127.0.0.1. To allow external access, you can set --host 0.0.0.0. It is highly recommended to enable authentication if the dashboard is exposed to a network.

Authentication

The dashboard supports Basic Authentication. You can enable it by setting the TORCH_DASHBOARD_AUTH environment variable or the dashboard.auth field in torch-config.json with the format username:password.

Removing TORCH

To completely remove TORCH from a project:

npx torch-lock remove

This removes the torch/ directory, configuration files, runtime artifacts, host package.json scripts, and the npm package. Use --force to skip the confirmation prompt.

For manual removal steps and a full list of what gets cleaned up, see docs/removal.md.

Environment variables

You can override configuration using environment variables:

• NOSTR_LOCK_NAMESPACE
• NOSTR_LOCK_HASHTAG
• NOSTR_LOCK_RELAYS (comma-separated)
• NOSTR_LOCK_TTL
• NOSTR_LOCK_QUERY_TIMEOUT_MS
• NOSTR_LOCK_DAILY_ROSTER (comma-separated list of agents)
• NOSTR_LOCK_WEEKLY_ROSTER (comma-separated list of agents)
• TORCH_CONFIG_PATH (path to config file)
• TORCH_DASHBOARD_AUTH (Basic Auth user:pass for the dashboard)
• AGENT_PLATFORM (platform identifier, e.g. codex)
• TORCH_MEMORY_ENABLED (true/false; global memory kill switch, defaults to enabled)
• TORCH_MEMORY_INGEST_ENABLED (true/false or comma-separated canary agent_id allow list)
• TORCH_MEMORY_RETRIEVAL_ENABLED (true/false or comma-separated canary agent_id allow list)
• TORCH_MEMORY_PRUNE_ENABLED (true, false, or dry-run)

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 (canonical scheduler roster included in the package).
4. Built-in fallback roster.

Included Resources

• src/lib.mjs — Core library logic (can be imported in scripts)
• TORCH.md — Protocol summary and usage
• src/prompts/ — Generic scheduler prompts and flow
• skills/ — Repository-local skill guides for agent onboarding and repeatable workflows
• dashboard/ — Static lock dashboard assets

NPM Scripts (for development)

If you are developing torch-lock itself:

• npm run lock:check:daily
• npm run lock:check:weekly
• npm run lock:list
• npm run lock:health -- --cadence daily (relay websocket + publish/read probe; writes history to task-logs/relay-health/)
• npm run dashboard:serve
• npm test (run unit tests)
• npm run lint (run linter)
• npm run lock:complete (manually complete a task)
• npm run scheduler:daily (run full daily scheduler cycle)
• npm run scheduler:weekly (run full weekly scheduler cycle)
• npm run report:lock-reliability (aggregate recent scheduler logs into markdown+JSON reliability reports)

Scheduler lock reliability reporting

Use the reporting hook below to inspect lock backend reliability trends by platform/cadence/error category/relay:

npm run report:lock-reliability

This writes:

• artifacts/lock-reliability/lock-reliability-summary.md
• artifacts/lock-reliability/lock-reliability-summary.json

Recommended cadence: run this at least weekly (or wire into your CI/cron scheduler) and compare codex vs other platform values.

Memory rollout plan

1. Deploy memory schema changes with scheduler jobs disabled (TORCH_MEMORY_ENABLED=false or subsystem flags set to false).
2. Enable ingest for one canary agent_id via TORCH_MEMORY_INGEST_ENABLED=<agent_id>.
3. Validate retrieval quality and storage growth metrics before expanding scope.
4. Enable broader retrieval (TORCH_MEMORY_RETRIEVAL_ENABLED=<allow-list> then true).
5. Enable pruning in dry-run mode first, then switch to active pruning after revalidation.

Memory rollback plan

1. Disable memory flags (TORCH_MEMORY_ENABLED=false and/or set ingest/retrieval/prune flags to false).
2. Stop memory maintenance scheduler processes.
3. Preserve database state for post-incident analysis; do not drop or rewrite memory tables during rollback.
4. Keep prune actions in dry-run (or disabled) until lifecycle policy and data integrity are revalidated.