Orchestrate AI coding agents from your Mac — schedule, monitor, and chain Claude Code tasks on a kanban board.

Website: https://agentforge-landing-weld.vercel.app/

Table of Contents

• Features
• Requirements
• Installation
• Troubleshooting
• Quick Start
• Chat Channels
• Multi-Agent Pipelines (DAG)
• API Reference
• Background Service
• Architecture
• Contributing
• License

Features

• Agents that spawn agents — Any running task can create sub-tasks, build DAG pipelines, and collect results via the bundled Claude Code skill
• Kanban Task Board — Visual Queue / Running / Done columns with live output streaming
• DAG Pipelines — Define task dependencies with automatic cascade execution and failure propagation
• Flexible Scheduling — Immediate, delayed, one-time datetime, and cron-based recurring tasks
• Dual Agent Backends — Run tasks with Claude Code CLI or OpenAI Codex CLI; choose per-task or set a default
• Chat Control — Create tasks and receive notifications from Telegram, Slack, Feishu/Lark, or WeChat
• Persistent Storage — SQLite-backed task history, run logs, and streaming output
• Native macOS App — Electron shell with one-click DMG install

Requirements

• macOS 12.0+ (Apple Silicon or Intel)
• Python 3.12+
• Node.js 18+
• Claude Code CLI installed and on PATH (default agent)
• OpenAI Codex CLI on PATH — optional, required only if using Codex as agent backend (npm install -g @openai/codex)

Installation

Option 1: Desktop App (Recommended)

1. Download the latest AgentForge-*.dmg from the Releases page.
2. Open the DMG and drag AgentForge into /Applications.
3. Launch from Launchpad or the Applications folder.

Option 2: Build from Source

git clone https://github.com/your-org/agentforge.git
cd agentforge

# Install all dependencies
make install-deps

# Build and package a DMG
make package-dmg
# Output: taskboard-electron/out/make/AgentForge-1.0.0-arm64.dmg

Option 3: Development Mode

git clone https://github.com/your-org/agentforge.git
cd agentforge

uv sync
cd taskboard-electron && npm install && cd ..

# Terminal 1: start Python backend
uv run taskboard.py

# Terminal 2: start Electron + Vite dev server
cd taskboard-electron && npm start

Troubleshooting

npm install hangs or freezes

This is the most common setup issue. The Electron binary (~100 MB) is downloaded from GitHub and may stall on slow connections or in China.

Quick fix — use mirrors:

npm config set registry https://registry.npmmirror.com
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
cd taskboard-electron && npm install

Full guide: docs/installation-troubleshooting.md covers:

• How to diagnose whether the hang is network or native compilation
• Mirror setup for China and slow connections
• Installing build tools (macOS / Linux / Windows)
• Node.js version requirements
• Full clean-install procedure

Quick Start

Once the app is running, the backend listens on http://127.0.0.1:9712.

Create a task via the UI: Open AgentForge, click New Task, fill in the title, prompt, and working directory, choose a schedule type, and click Create.

Create a task via curl:

# Run immediately (uses default agent — claude)
curl -X POST http://localhost:9712/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Code review",
    "prompt": "Review the code changes in this directory",
    "working_dir": "~/projects/myapp",
    "schedule_type": "immediate"
  }'

# Run after a delay (seconds)
curl -X POST http://localhost:9712/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Delayed review",
    "prompt": "Review recent commits",
    "working_dir": "~/projects/myapp",
    "schedule_type": "delayed",
    "delay_seconds": 300
  }'

# Recurring cron schedule (daily at 9 AM)
curl -X POST http://localhost:9712/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily digest",
    "prompt": "Summarize TODO comments across the codebase",
    "working_dir": "~/projects/myapp",
    "schedule_type": "cron",
    "cron_expr": "0 9 * * *",
    "max_runs": 30
  }'

# Use Codex CLI instead of Claude Code
curl -X POST http://localhost:9712/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refactor auth module",
    "prompt": "Refactor the authentication module for clarity",
    "working_dir": "~/projects/myapp",
    "schedule_type": "immediate",
    "agent": "codex"
  }'

To set Codex as the default agent for all tasks:

curl -X PUT http://localhost:9712/api/settings \
  -H "Content-Type: application/json" \
  -d '{"default_agent": "codex"}'

Chat Channels

Control AgentForge from your favorite messaging app. Channels auto-start when the corresponding environment variables are detected.

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
export TELEGRAM_ALLOWED_USERS="123456789"   # optional — restrict access by user ID

export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_APP_TOKEN="xapp-..."
export SLACK_ALLOWED_USERS="U012AB3CD"   # optional

curl -X POST http://127.0.0.1:9712/api/feishu/settings \
  -H "Content-Type: application/json" \
  -d '{
    "feishu_app_id": "cli_xxxx",
    "feishu_app_secret": "your_app_secret",
    "feishu_default_working_dir": "~/projects",
    "feishu_enabled": "true"
  }'

curl -X POST http://127.0.0.1:9712/api/channels/settings \
  -H "Content-Type: application/json" \
  -d '{
    "weixin_enabled": "true",
    "weixin_default_working_dir": "~/projects",
    "weixin_base_url": "https://ilinkai.weixin.qq.com",
    "weixin_account_id": ""
  }'

See channels/README.md for detailed setup, notification behavior, and adding custom channels.

Multi-Agent Pipelines (DAG)

AgentForge ships with a Claude Code skill (skills/agentforge/) that lets any agent running inside Claude Code create and manage other AgentForge tasks — enabling recursive, multi-agent workflows.

          User
           |
           v
     [ Task A ]  ──creates──>  [ Task B ]  [ Task C ]
                                    |
                                  creates
                                    v
                               [ Task D ]  (depends on B)

Install the skill

# Symlink into your Claude Code skills directory
ln -s /path/to/agentforge/skills/agentforge ~/.claude/skills/agentforge

What the skill enables

• Fan-out / fan-in — Spawn N sub-tasks in parallel, poll until complete, synthesize results
• DAG dependencies — --depends-on <ids> makes downstream tasks wait for upstream to finish; failures cascade-cancel the rest
• Result injection — --inject-result prepends upstream output into the downstream prompt automatically
• Scheduled sub-workflows — Combine cron, delayed, and immediate schedules within a pipeline

Example — parallel research pipeline

Research the top 3 competitors of Acme Corp.
For each competitor, create a separate AgentForge task that:
  1. Gathers recent news and financials
  2. Writes a one-page summary
Then create a final task (depends-on the above 3) that
synthesizes everything into a comparative report.

AgentForge handles scheduling, dependency tracking, and result passing automatically.

API Reference

All endpoints are served at http://127.0.0.1:9712/api.

Background Service

To keep the backend running persistently without the desktop app:

<!-- ~/Library/LaunchAgents/com.agentforge.taskboard.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agentforge.taskboard</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/uv</string>
        <string>run</string>
        <string>/path/to/agentforge/taskboard.py</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/agentforge</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/agentforge.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/agentforge.err</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.agentforge.taskboard.plist

Architecture

┌──────────────────┐     HTTP/JSON      ┌──────────────────┐
│   React Frontend │ <────────────────> │  Python Backend  │
│   (Kanban UI)    │   localhost:9712   │  (Scheduler+API) │
└──────────────────┘                   └───────┬──────────┘
                                               |
                               ┌───────────────┼───────────────┐
                               v               v               v
                         [ SQLite DB ]   [ Scheduler ]   [ Claude CLI ]

• Python backend (taskboard.py) — single-file BaseHTTPRequestHandler server. Manages tasks in SQLite (~/.agentforge/tasks.db), runs claude or codex CLI via AgentExecutor, and schedules work with TaskScheduler (polls every 2 s, supports cron via croniter).
• Electron shell (taskboard-electron/) — spawns the Python backend on start, kills it on quit. Loads React renderer from Vite dev server (dev) or bundled assets (prod).
• React frontend (App.jsx) — single-component kanban board that polls the REST API and renders colorized streaming output.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository and create a feature branch.
2. Start the app in development mode (see Option 3 above).
3. Make your changes and verify them manually — there are no automated tests.
4. Open a pull request with a clear description of the change.

Key files:

• taskboard.py — entire Python backend (DB, scheduler, executor, HTTP handlers)
• taskboard-electron/src/main.js — Electron main process
• taskboard-electron/src/renderer/App.jsx — React frontend (~1500 lines)
• channels/ — pluggable chat channel adapters (Telegram, Slack, Feishu, WeChat)
• skills/agentforge/ — Claude Code skill for agent-to-agent delegation

License

MIT — see LICENSE for details.