AgentHub Daemon

Background service that automatically spawns Claude Code instances to handle tasks and messages from AgentHub.

New to the team? See INSTALL.md for step-by-step setup instructions.

How It Works

Slack → AgentHub Server → WebSocket → Daemon → spawns → claude -p "task"

1. Daemon runs as a background service
2. Connects to AgentHub via WebSocket for each configured agent
3. When a task/message is pushed, spawns a fresh Claude Code instance
4. Claude instance registers, accepts the task, and works on it autonomously
5. Reports completion back to AgentHub (and Slack thread)

Installation

cd agenthub-daemon
npm install
npm run build

Configuration

Create config.json (or copy from config.example.json):

{
  "agenthub_url": "https://agenthub.contetial.com",
  "agenthub_api_key": "your-api-key",
  "max_concurrent": 3,
  "agents": {
    "backend-agent": {
      "working_dir": "/path/to/backend/project",
      "model": "claude-sonnet-4-20250514",
      "enabled": true
    },
    "frontend-agent": {
      "working_dir": "/path/to/frontend/project",
      "model": "claude-sonnet-4-20250514",
      "enabled": true
    }
  }
}

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | agenthub_url | AgentHub server URL | https://agenthub.contetial.com | | agenthub_api_key | API key for AgentHub | Required | | max_concurrent | Max concurrent Claude instances | 3 | | agents | Agent configurations | Required |

Agent Configuration

| Option | Description | Required | |--------|-------------|----------| | working_dir | Project directory for Claude | Yes | | model | Model to use | No | | enabled | Enable/disable this agent | No (default: true) |

Environment Variables

You can also use environment variables:

• AGENTHUB_URL - AgentHub server URL
• AGENTHUB_API_KEY - API key
• AGENTHUB_MAX_CONCURRENT - Max concurrent instances

Usage

Development

npm run dev

Production

npm run build
npm start

As a System Service (Linux)

Create /etc/systemd/system/agenthub-daemon.service:

[Unit]
Description=AgentHub Daemon
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/agenthub-daemon
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=10
Environment=AGENTHUB_API_KEY=your-api-key

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable agenthub-daemon
sudo systemctl start agenthub-daemon

How Tasks Are Processed

When a task arrives:

1. Task is added to priority queue (urgent > high > normal)
2. If under max_concurrent, spawns immediately
3. Claude is spawned with prompt instructing it to:
   • Register with AgentHub
   • Accept the task
   • Complete the work
   • Report completion
4. Output is streamed to daemon console
5. When complete, next queued task is processed

Logs

The daemon logs to stdout:

[Config] Loaded from: config.json
[Config] Agent: backend-agent -> /projects/backend
[WebSocket] Connecting for agent: backend-agent
[WebSocket] Connected for agent: backend-agent
[Daemon] Received task for backend-agent: Fix the authentication bug...
[Queue] Added task abc123 for backend-agent (queue size: 1)
[Spawner] Starting Claude for agent: backend-agent
[backend-agent] ... (Claude output)
[Spawner] Claude exited for backend-agent with code 0 (45.2s)

Limitations

• Each spawned Claude instance is fresh (no context from previous runs)
• Claude must have access to the working directory
• Requires claude CLI to be installed and in PATH