AgentForge

A local-first macOS command center for running Claude Code and OpenAI Codex CLI as schedulable, observable tasks.

AgentForge turns agent work into a visible local workflow: queue tasks, watch live runs, schedule recurring checks, route tasks from chat, and distill repeated patterns into reusable skills.

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

Why AgentForge

• Stop babysitting terminals. Create tasks once, then monitor queue, running, and done states from a kanban board.
• Run the right agent per job. Use Claude Code or Codex CLI on each task, with a configurable default.
• Make agent work repeatable. Schedule immediate, delayed, one-time, or cron tasks, then reuse successful patterns through the Skill Library.
• Keep execution local. The backend listens on 127.0.0.1, stores state in SQLite, and runs agent CLIs on your Mac.

Quick Start

Install The App

1. Download the latest AgentForge-*.dmg from Releases.
2. Drag AgentForge into /Applications.
3. Launch it, choose a working directory, and create your first task.

Run From Source

git clone https://github.com/hetaoBackend/agentforge.git
cd agentforge/taskboard-electron

bun install --ignore-scripts
bun run start

The Electron dev command builds the renderer, starts the Bun backend, and reloads the app while you work.

Build A DMG

cd taskboard-electron
bun run make

The packaged app bundles the compiled Bun backend at taskboard-electron/out/make/AgentForge-1.0.0-arm64.dmg.

What You Can Do

Area	What it gives you
Tasks	Kanban queue for pending, scheduled, blocked, running, completed, failed, and cancelled work.
Scheduling	Immediate, delayed, scheduled_at, and cron schedules with max-run limits.
Live output	Structured stream output from Claude Code or Codex CLI, persisted per run.
Heartbeats	Recurring checks that can decide whether to trigger, resume, or notify.
Skill Library	Pattern detection across completed runs, editable SKILL.md drafts, and native skill installation.
Chat channels	Telegram, Slack, Feishu/Lark, and WeChat adapters for creating or tracking tasks from chat.
DAG pipelines	Task dependencies, failure propagation, and upstream result injection for multi-agent workflows.

Requirements

• macOS 12+
• Bun 1.3+
• Claude Code CLI or OpenAI Codex CLI on PATH

Skill Library

The Skill Library turns repeated work into reusable agent skills.

1. Detect recurring recipes and pitfalls across completed task runs.
2. Distill useful patterns into standard SKILL.md drafts.
3. Approve the draft before anything is installed.
4. Deliver approved skills to ~/.agentforge/skills, symlinked into ~/.claude/skills and ~/.agents/skills.

The automatic sweep is off by default because it spends tokens. Enable it in Settings, or run a manual scan from the Skills tab.

Architecture

┌─────────────────────┐        HTTP/JSON        ┌─────────────────────┐
│ Electron + React UI │  <--------------------> │ Bun TypeScript API  │
│ Task board renderer │      127.0.0.1:9712     │ Scheduler + runner  │
└─────────────────────┘                         └──────────┬──────────┘
                                                            │
                                      ┌─────────────────────┼─────────────────────┐
                                      │                     │                     │
                                  SQLite              TaskScheduler         AgentExecutor
                              ~/.agentforge           cron + delayed       claude / codex

• taskboard-electron/src/main.ts starts and stops the backend with the desktop app.
• taskboard-electron/src/renderer/App.tsx renders the task board, heartbeats, settings, and skills.
• backend/taskboard.ts serves the REST API through Bun.serve.
• backend/src/db.ts stores tasks, runs, output events, settings, heartbeats, and skills in SQLite.
• backend/src/executor.ts runs Claude Code or Codex CLI and persists streaming output.
• backend/src/scheduler.ts polls for due tasks and handles schedules, heartbeats, and skill sweeps.

API Quick Example

All API routes are served at http://127.0.0.1:9712/api.

curl -X POST http://127.0.0.1:9712/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review auth changes",
    "prompt": "Review the latest auth module diff for regressions and missing tests.",
    "working_dir": "~/projects/myapp",
    "schedule_type": "immediate",
    "agent": "codex"
  }'

Common task endpoints:

Method	Endpoint	Description
GET	/api/tasks	List tasks
POST	/api/tasks	Create a task
GET	/api/tasks/:id	Read one task
POST	/api/tasks/:id/cancel	Cancel a task
POST	/api/tasks/:id/retry	Retry a failed task
GET	/api/tasks/:id/events	Read structured output events
GET	/api/health	Backend health check

Chat Channels

Channels are optional. They let teammates create tasks or receive updates from the tools where they already talk.

Channel	Transport	Notes
Telegram	Bot API polling	Simple bot token setup.
Slack	Socket Mode	Uses bot and app-level tokens.
Feishu / Lark	WebSocket long connection	No public IP required.
WeChat	Local bridge	Experimental text-only bridge.

Channel adapters live in backend/src/channels/ and can be configured from the app settings page or REST endpoints.

Multi-Agent Pipelines

AgentForge ships with skills/agentforge/, a Claude Code skill that lets one task create and manage other AgentForge tasks.

That enables fan-out research, fan-in summaries, dependency gates, upstream result injection, and scheduled sub-workflows.

User
  |
  v
Task A --creates--> Task B
  |                 Task C
  |                   |
  `------depends------v
                   Task D

Install the bundled skill:

ln -s /path/to/agentforge/skills/agentforge ~/.claude/skills/agentforge

Development

Backend:

cd backend
bun taskboard.ts

Frontend and Electron app:

cd taskboard-electron
bun run start

Quality gates:

# Backend CI gate
make check

# Frontend CI gate
cd taskboard-electron
bun run typecheck
bun run lint
bun run format:check
bun run test
bun run build:check

Troubleshooting

If bun install stalls while downloading Electron, use a mirror:

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
cd taskboard-electron
bun install --registry https://registry.npmmirror.com --ignore-scripts

More setup notes live in docs/installation-troubleshooting.md.

Contributing

1. Fork the repository and create a feature branch.
2. Run the app in development mode with cd taskboard-electron && bun run start.
3. Keep changes scoped and run the relevant quality gate before opening a PR.

Key files:

• backend/ - Bun/TypeScript backend, scheduler, executor, API, and channels.
• taskboard-electron/src/main.ts - Electron main process.
• taskboard-electron/src/renderer/App.tsx - React renderer.
• skills/agentforge/ - bundled skill for agent-to-agent delegation.

License

MIT - see LICENSE.