@ai-taskmanager/agent

Local CLI agent for AI Task Manager — orchestrate Claude Code execution with safety guards, approval workflows, and real-time monitoring.

한국어 | 日本語

What is this?

AI Task Manager is a web-based task management system that lets you create, assign, and monitor AI-powered tasks executed by Claude Code. This package is the local agent that runs on your machine, connects to the web dashboard, and executes tasks in your project directory.

Prefer a GUI? Try the Desktop App — a native macOS app with system tray integration that manages agents without the terminal.

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   Web Dashboard  │ ◄─SSE──►  Next.js Server   │ ◄─REST──►  Local Agent    │
│   (Browser UI)   │         │  (Supabase DB)   │         │  (This package) │
└─────────────────┘         └──────────────────┘         └────────┬────────┘
                                                                  │
                                                          ┌───────▼───────┐
                                                          │  Claude Code  │
                                                          │  (CLI)        │
                                                          └───────────────┘

Features

• Task Execution — Receives tasks from the web dashboard and executes them via Claude Code CLI
• Git Worktree Isolation — Each task runs in its own git worktree to prevent conflicts
• Approval Workflow — File edits, commands, and git operations can require user approval before execution
• Real-time Streaming — Task output streams to the web dashboard in real-time via SSE
• Offline Resilience — Messages are queued to disk when disconnected and flushed on reconnect
• Automatic Recovery — Crash handlers report active tasks as failed; state syncs on reconnect
• Multi-project Analysis — Analyze GitHub issues and PRs across multiple repositories

Prerequisites

• Node.js ≥ 24.0.0
• Claude Code CLI — installed and authenticated (claude command available in PATH)
• Git — for worktree isolation
• AI Task Manager account — sign up at ai-taskmanager.dev

Quick Start

1. Get a Pairing Code

Open the AI Task Manager web app, log in, and click "Connect Agent" to generate a pairing code.

2. Start the Agent

npx @ai-taskmanager/agent start <pairing-code>

That's it! The agent will connect to the server and wait for tasks.

3. Create a Task

Go to the web dashboard, create a new task with instructions, and assign it to your connected agent. The agent will:

1. Create an isolated git worktree
2. Execute the task via Claude Code
3. Stream output back to the dashboard in real-time
4. Clean up the worktree when done

Usage

Basic

# Start with default server (ai-taskmanager.dev)
npx @ai-taskmanager/agent start <pairing-code>

# Start with a specific project directory
npx @ai-taskmanager/agent start <pairing-code> --dir /path/to/project

# Start with a local development server
npx @ai-taskmanager/agent start <pairing-code> --server http://localhost:3000

CLI Commands

# Start the agent
ai-taskmanager-agent start <pairing-code> [options]

Options:
  -s, --server <url>   Server URL (default: https://ai-taskmanager.dev)
  -d, --dir <path>     Project directory (default: current directory)

# Manage worktrees
ai-taskmanager-agent worktree --list          # List active worktrees
ai-taskmanager-agent worktree --create <name> # Create a worktree
ai-taskmanager-agent worktree --remove <name> # Remove a worktree

# Show agent status
ai-taskmanager-agent status

Global Installation

npm install -g @ai-taskmanager/agent
ai-taskmanager-agent start <pairing-code>

How It Works

Task Lifecycle

Pending → Running → Completed
                  ↘ Failed
                  ↘ Cancelled

1. Pending — Task created in web dashboard, waiting for agent
2. Running — Agent received task, Claude Code executing
3. Completed — Task finished successfully
4. Failed — Execution error, timeout (15 min), or agent crash
5. Cancelled — Cancelled by user or system (60 min with no agent)

Safety Guards

| Guard | Description | | ---------------------------- | ---------------------------------------------------------------------------------- | | Execution Timeout | Tasks automatically fail after 15 minutes of execution | | Initial Response Timeout | Fails fast if Claude CLI doesn't respond within 60 seconds | | Crash Recovery | uncaughtException / unhandledRejection handlers report active tasks as failed | | Graceful Shutdown | SIGINT/SIGTERM cleanly aborts tasks and reports failure to server | | Offline Queue | Messages queued to disk (max 500) when disconnected, flushed on reconnect | | State Sync | On reconnect, agent syncs with server to resolve state mismatches | | Server Cleanup | Server auto-fails stale tasks (30 min) and cancels orphaned pending tasks (60 min) |

Connection & Heartbeat

• Agent sends a heartbeat every 30 seconds
• Server considers connection stale after 75 seconds (tolerates 1 missed heartbeat + 15s buffer)
• After 3 consecutive heartbeat failures, agent triggers reconnection
• Server runs throttled cleanup every 5 minutes to handle zombie tasks

Programmatic API

import { Agent, ClaudeExecutor, WorkspaceManager } from "@ai-taskmanager/agent";

// Create and start an agent
const agent = new Agent({
  serverUrl: "https://ai-taskmanager.dev",
  pairingCode: "YOUR_CODE",
  projectPath: "/path/to/project",
  worktreeBase: "/path/to/project/.worktrees",
});

await agent.start();

// ... agent runs and handles tasks automatically

await agent.stop();

Development

# Clone the monorepo
git clone https://github.com/wtdlee/ai-taskmanager.git
cd ai-taskmanager

# Install dependencies
pnpm install

# Build the agent
pnpm build:agent

# Run in development mode (watch)
cd packages/agent && pnpm dev

# Run tests
pnpm test

# Lint
pnpm lint

Environment

| Variable | Description | Default | | ---------- | ----------------- | ---------------------------- | | --server | Server URL | https://ai-taskmanager.dev | | --dir | Project directory | Current working directory |

Troubleshooting

"Claude CLI not found"

Make sure claude is installed and available in your PATH:

claude --version

Connection keeps dropping

• Check your network connection
• The agent automatically reconnects after 3 failed heartbeats
• Server-side cleanup runs every 5 minutes — tasks won't be lost

Task stays "running" after agent crash

The server automatically detects stale tasks:

• 30 minutes without activity → marked as failed
• 5 minutes after agent disconnect → marked as failed
• You can also manually mark tasks as failed from the web dashboard

License

MIT — see LICENSE for details.