@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.

$3

``
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ 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

$3

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

$3

`bash
npx @ai-taskmanager/agent start
`

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

$3

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

$3

`bash


Start with default server (ai-taskmanager.dev)

npx @ai-taskmanager/agent start

Start with a specific project directory

npx @ai-taskmanager/agent start --dir /path/to/project

Start with a local development server

npx @ai-taskmanager/agent start --server http://localhost:3000
`

$3

`bash


Start the agent

ai-taskmanager-agent start [options]

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

Manage worktrees

ai-taskmanager-agent worktree --list # List active worktrees
ai-taskmanager-agent worktree --create # Create a worktree
ai-taskmanager-agent worktree --remove # Remove a worktree

Show agent status

ai-taskmanager-agent status
`

$3

`bash
npm install -g @ai-taskmanager/agent
ai-taskmanager-agent start
`

How It Works

$3

`
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)

$3

| 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) |

$3

- 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

`typescript
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

`bash


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

$3

Make sure claude is installed and available in your PATH:

`bash
claude --version
``

$3

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

$3

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.