@telora/daemon

Agent orchestration daemon for Telora - spawns and manages Claude Code instances to work on deliveries autonomously.

Overview

The Telora daemon watches for active strategies in your Telora organization and spawns Claude Code Agent Teams to execute them. Each strategy gets a single Agent Team that coordinates work across all deliveries and issues.

Key features:

• Strategy-level Agent Teams: One team per strategy manages all deliveries, building a task DAG and coordinating parallel execution
• Multi-repo support: Multiple daemons can run against the same Telora org, each handling strategies for different repos
• Integration branch workflow: Teams work on isolated branches, auto-merge to integration on success
• Worktree isolation: Each team gets its own git worktree
• Dynamic delivery pickup: Teams detect and incorporate new deliveries added mid-execution

Installation

# Install as a dev dependency in your project
npm install --save-dev @telora/daemon

# Or run directly with npx
npx @telora/daemon

Note: The .mcp.json file for Claude Code integration is auto-generated by npx telora-daemon init.

Quick Start

Option 1: Interactive Setup (Recommended)

cd /path/to/your/repo
npx @telora/daemon init

The setup wizard will guide you through:

• Telora URL configuration
• Organization ID
• Integration branch name
• Max concurrent agents

Then set your tracker ID and start the daemon:

export TELORA_TRACKER_ID=your-tracker-id-here
npx telora-daemon

Option 2: Manual Setup

1. Get your Tracker ID from Telora:

   • Go to Settings → AI Work Trackers
   • Click "Generate Tracker ID" on your profile
   • Copy the tracker ID

2. Configure environment variables in your repo:

cd /path/to/your/repo

# Create .env file
cat > .env << EOF
TELORA_URL=https://your-telora-instance.supabase.co
TELORA_TRACKER_ID=your-tracker-id-here
TELORA_ORGANIZATION_ID=your-org-id-here
EOF

3. Start the daemon:

npx telora-daemon

Configuration

The daemon is configured via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TELORA_URL | Yes | - | Telora API URL | | TELORA_TRACKER_ID | Yes | - | Your tracker ID for authentication | | TELORA_ORGANIZATION_ID | Yes | - | Organization to watch for work | | TELORA_REPO_PATH | No | cwd() | Path to git repository | | TELORA_INTEGRATION_BRANCH | No | integration | Branch for agent merges | | TELORA_WORKTREE_DIR | No | .telora/worktrees | Directory for git worktrees | | TELORA_LOG_DIR | No | .telora/logs | Directory for agent logs | | CLAUDE_CODE_PATH | No | claude | Path to Claude Code executable | | MAX_TOTAL_SESSIONS | No | 5 | Max concurrent agents | | SESSION_TIMEOUT_MS | No | 3600000 | Session timeout (1 hour) | | TOKEN_LIMIT | No | 200000 | Max tokens per session | | COST_LIMIT | No | 10.0 | Max cost per session ($) |

CLI Options

npx telora-daemon [options]

Options:
  -V, --version        Output version number
  -v, --verbose        Enable verbose logging
  -c, --config <path>  Path to config file (default: .telora/daemon.json)
  --dry-run            Print configuration and exit
  -h, --help           Display help

Config File

Instead of environment variables, you can use a JSON config file. The daemon looks for .telora/daemon.json by default.

{
  "teloraUrl": "https://your-telora-instance.supabase.co",
  "organizationId": "your-organization-uuid",
  "productId": "your-product-uuid",
  "integrationBranch": "integration",
  "maxTotalSessions": 5
}

Configuration priority (highest to lowest):

1. Environment variables
2. Config file values
3. Default values

Security note: The trackerId must always be set via the TELORA_TRACKER_ID environment variable. It cannot be set in the config file (which is safe to commit to git).

Available config file fields:

• teloraUrl - Telora API URL
• organizationId - Organization UUID
• productId - Product UUID (scopes daemon to one product; omit to handle all)
• repoPath - Repository path
• worktreeDir - Worktree directory
• integrationBranch - Integration branch name
• claudeCodePath - Claude Code executable path
• logDir - Log directory
• maxTotalSessions - Max concurrent agents
• sessionTimeoutMs - Session timeout in milliseconds
• tokenLimit - Max tokens per session
• costLimit - Max cost per session in dollars

How It Works

Strategy Team Execution Model

1. Strategy polling: The daemon polls Telora every 30 seconds for active strategies with an assigned agent role and queued deliveries
2. Filtering: Only picks up strategies for the configured productId (if set)
3. Team spawning: For each ready strategy, spawns a single Claude Code Agent Team (one team per strategy)
4. Task DAG: The team lead reads all deliveries and issues, builds a dependency graph respecting delivery priority and file overlap
5. Parallel execution: Workers execute issues in parallel where safe (no file conflicts), sequentially where needed
6. Delivery progression: As issues complete, deliveries advance through workflow stages (coding -> verify -> done)
7. Merge on success: When all deliveries are complete, the strategy branch is merged to integration
8. Dynamic pickup: If new deliveries are added to the strategy mid-execution, the team incorporates them automatically

Key daemon modules

• strategy-executor.ts - Strategy team lifecycle (spawn, monitor, completion)
• task-dag-builder.ts - Pure function that builds dependency graphs from deliveries/issues
• strategy-prompt-builder.ts - Builds the team lead's prompt with all context
• delivery-lifecycle.ts - Extracted guard evaluation, stage transition, git merge functions
• completion-handler.ts - Per-delivery completion (used by team lead for sub-delivery transitions)
• spawner.ts - Process spawning with Agent Teams mode always enabled

Multi-Repo Setup

To run agents on multiple repositories:

1. Set productId in each daemon's .telora/daemon.json (or TELORA_PRODUCT_ID env var)
2. Run one daemon per repository:

# Terminal 1 - Repo A (productId set in .telora/daemon.json)
cd /path/to/repo-a
npx telora-daemon

# Terminal 2 - Repo B (productId set in .telora/daemon.json)
cd /path/to/repo-b
npx telora-daemon

Each daemon only picks up deliveries for the configured product.

Signals

• SIGINT / SIGTERM: Graceful shutdown (waits for agents to checkpoint)
• SIGUSR1: Print status of running agents

Running in Production vs Development

For production use, always run the daemon with the compiled version:

# Local install (recommended)
npm install --save-dev @telora/daemon
npx telora-daemon

# Or from source
cd packages/daemon
npm run build
npm start

Do NOT use npm run dev (watch mode) when agents are running. The file watcher will restart the daemon whenever source files change, which kills any running agents and may leave sessions in a stuck "running" state.

If you need to modify daemon code while agents are working:

1. Wait for agents to complete
2. Or stop the daemon gracefully (Ctrl+C)
3. Make your changes
4. Restart the daemon

Requirements

• Node.js 20+
• Claude Code CLI (claude) installed and authenticated
• Git repository with write access
• Active Telora account with AI Work Tracker

License

MIT