agent-tasks

AI 코딩 에이전트를 위한 파이프라인 기반 작업 관리. 스테이지 게이트 파이프라인, 다중 에이전트 협업, 실시간 칸반 대시보드를 갖춘 MCP 서버입니다. 작업은 backlog, spec, plan, implement, test, review, done과 같은 구성 가능한 스테이지를 통해 흐르며, 의존성 추적, 승인 워크플로, 아티팩트 버전 관리, 스레드 댓글을 지원합니다.

AI 코딩 에이전트(Claude Code, Codex CLI, Gemini CLI, Aider)를 위해 제작되었지만, 모든 MCP 클라이언트, REST 소비자, WebSocket 리스너와도 잘 작동합니다.

왜 agent-tasks인가?

동일한 코드베이스에서 여러 AI 에이전트를 실행할 때, 단순한 할 일 목록이 아닌 공유 작업 파이프라인이 필요합니다. 스테이지, 의존성, 승인, 가시성이 필요합니다.

Related MCP server: agent-runtime-mcp

기능

• 파이프라인 스테이지 — 프로젝트별로 구성 가능: backlog > spec > plan > implement > test > review > done

• 작업 의존성 — 자동 순환 감지가 있는 DAG; 해결될 때까지 진행을 차단합니다.

• 승인 워크플로 — 스테이지 게이트 승인/거부, 거부 시 자동 회귀

• 다중 에이전트 협업 — 역할(협업자, 검토자, 관찰자), 클레임, 할당

• 하위 작업 계층 — 진행 상황 추적이 있는 부모/자식 작업 트리

• 스레드 댓글 — 모든 작업에 대한 에이전트 간 비동기 토론

• 아티팩트 버전 관리 — 자동 버전 관리 및 diff 뷰어가 있는 스테이지별 문서 첨부

• 전체 텍스트 검색 — 작업 제목 및 설명에 대한 FTS5 검색

• 실시간 칸반 대시보드 — 드래그 앤 드롭, 사이드 패널, 인라인 생성, 다크/라이트 테마

• 3가지 전송 계층 — MCP(stdio), REST API(HTTP), WebSocket(실시간 이벤트)

• TodoWrite 브리지 — Claude Code의 내장 TodoWrite를 가로채 파이프라인에 동기화합니다.

• 스테이지 게이트 — 스테이지별 규칙이 있는 프로젝트별 구성 가능한 게이트: 진행 전에 명명된 아티팩트, 최소 아티팩트 수, 댓글 또는 승인을 요구합니다.

• 결정 로그 — task_artifact(type: "decision")를 통한 구조화된 결정 아티팩트 (Z 때문에 X를 Y보다 선택)

• 학습 전파 — task_artifact(type: "learning")는 통찰(기법, 함정, 결정, 패턴)을 캡처합니다. 완료 시 부모 및 형제 작업에 자동으로 전파됩니다.

• 에이전트 선호도 — task_list(next: true)는 관련 기록(부모, 의존성, 프로젝트)이 있는 에이전트에게 작업을 라우팅하는 것을 타이브레이커로 선호합니다.

• 하트비트 기반 정리 — agent-comm 하트비트 데이터를 사용하여 죽은 에이전트의 작업을 자동으로 실패 처리합니다.

• 작업 정리 훅 — 세션 중지 시 고아 작업을 자동으로 실패 처리하고 세션 시작 시 오래된 작업을 정리합니다.

• 에이전트 브리지 — 작업 이벤트(클레임, 진행, 댓글, 승인) 시 연결된 에이전트에 알립니다.

• 지식 브리지 — 작업 완료 시 학습 및 결정 아티팩트를 agent-knowledge에 자동으로 푸시하며, 임베딩 인덱싱 및 자동 연결을 지원합니다.

빠른 시작

npm에서 설치

npm install -g agent-tasks

또는 소스에서 클론

git clone https://github.com/keshrath/agent-tasks.git
cd agent-tasks
npm install
npm run build

옵션 1: MCP 서버 (AI 에이전트용)

MCP 클라이언트 구성(Claude Code, Cline 등)에 추가하세요:

{
  "mcpServers": {
    "agent-tasks": {
      "command": "npx",
      "args": ["agent-tasks"]
    }
  }
}

대시보드는 첫 번째 MCP 연결 시 http://localhost:3422에서 자동으로 시작됩니다.

옵션 2: 독립 실행 서버 (REST/WebSocket 클라이언트용)

node dist/server.js --port 3422

Claude Code 통합

구성이 완료되면(위의 빠른 시작 참조), Claude Code는 8개의 MCP 도구를 모두 직접 사용할 수 있습니다 — 작업 생성, 스테이지 진행, 아티팩트 추가, 댓글 작성 등. 자세한 통합 단계는 설정 가이드를 참조하세요.

MCP 도구 (8)

모든 도구와 엔드포인트에 대한 자세한 설명은 전체 API 참조를 참조하세요.

REST API (18개 엔드포인트)

모든 엔드포인트는 JSON을 반환합니다. CORS가 활성화되어 있습니다. 자세한 내용은 전체 API 참조를 참조하세요.

GET  /health                          Health check with version + uptime
GET  /api/tasks                       List tasks (status, stage, project, assignee filters)
GET  /api/tasks/:id                   Get a single task
GET  /api/tasks/:id/subtasks          Subtasks of a parent
GET  /api/tasks/:id/artifacts         Artifacts (filter by stage)
GET  /api/tasks/:id/comments          Comments on a task
GET  /api/tasks/:id/dependencies      Dependencies for a task
GET  /api/dependencies                All dependencies across all tasks
GET  /api/pipeline                    Pipeline stage configuration
GET  /api/overview                    Full state dump
GET  /api/agents                      Online agents
GET  /api/search?q=                   Full-text search

POST /api/tasks                       Create a new task
PUT  /api/tasks/:id                   Update task fields
PUT  /api/tasks/:id/stage             Change stage (advance or regress)
POST /api/tasks/:id/comments          Add a comment
POST /api/cleanup                     Trigger manual cleanup

테스트

npm test              # 355 tests across 13 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test

환경 변수

의존성

필수: Node.js >= 20.11, better-sqlite3 (번들 포함)

선택 사항 (소프트 의존성 — 실패 시 열림, HTTP 전용, npm 의존성 없음):

• agent-comm — 하트비트 기반 작업 정리 및 이벤트 알림. agent-comm은 하트비트를 추적하고 → agent-tasks는 하트비트를 확인하여 → 죽은 에이전트의 작업을 자동으로 실패 처리합니다. 또한 클레임/진행 시 직접 메시지를 보내고 댓글/승인 시 채널에 게시합니다. agent-comm이 없으면 오래된 에이전트 감지 및 알림은 정상적으로 건너뜁니다.

• agent-knowledge — 작업 학습 및 결정을 위한 지식 영속화. 작업 완료 시 KnowledgeBridge는 POST /api/knowledge를 통해 learning 및 decision 아티팩트를 agent-knowledge에 푸시합니다. 항목은 임베딩으로 자동 인덱싱되고, 유사 항목에 자동 연결되며, git 동기화됩니다. agent-knowledge가 없으면 아티팩트는 agent-tasks에만 남습니다.

문서

• API 참조 — 8개의 MCP 도구, 18개의 REST 엔드포인트, WebSocket 프로토콜

• 아키텍처 — 소스 구조, 설계 원칙, 데이터베이스 스키마

• 대시보드 — 칸반 보드 기능, 키보드 단축키, 스크린샷

• 설정 가이드 — 설치, 클라이언트 설정 (Claude Code, OpenCode, Cursor, Windsurf), 훅

• 변경 로그

라이선스

MIT — LICENSE 참조