DanWahlin/ai-agent-board

작동 방식 • 기능 • 시작하기 • 환경 변수 • 테스트 • 개발 • 기여

AI 에이전트(GitHub Copilot, Claude Code, OpenAI Codex, OpenCode, Hermes, 또는 OpenClaw)에게 코딩 작업을 위임하는 드래그 앤 드롭 칸반 보드입니다. '백로그'에 작업을 넣고, 에이전트를 선택하면 해당 에이전트가 계획하고 실행하며 작업을 완료하고, 진행 상황을 실시간으로 보드에 스트리밍합니다.

백로그(Backlog) 열에서 작업 생성 → 진행 중(In Progress)으로 드래그— 에이전트 패널이 자동으로 열립니다. 실행 구성— 리포지토리 경로, 브랜치 이름, 에이전트 유형, git worktree 사용 여부를 설정합니다. 에이전트 시작(Start Agent) 클릭— 선택된 에이전트가 작업을 시작하고 실시간으로 진행 상황을 스트리밍합니다. 결과 검토— 실행된 명령어, 수정된 파일, 생성된 출력을 확인합니다. 병합 또는 PR 생성— 브랜치를 로컬에서 main에 병합하거나, 리포지토리에 GitHub 원격 저장소가 있는 경우 PR을 생성합니다.

서버는 여러 AI 코딩 에이전트를 공통 인터페이스 뒤에서 지원하기 위해 프로바이더 패턴(provider pattern)(@codewithdan/agent-sdk-core)을 사용합니다:

— 세션을 생성하고 가용성을 보고하는 AgentProvider
— 작업을 실행하고, 이벤트를 방출하며, 중단을 지원하는 AgentSession
— 타임아웃, 이벤트 캐싱 및 우아한 정리(graceful cleanup)를 통해 세션을 오케스트레이션하는 AgentManager

각 작업은 어떤 에이전트를 사용할지 지정할 수 있습니다. 사용 가능한 에이전트는 설치된 CLI를 확인하여 시작 시 자동으로 감지됩니다. 6가지 프로바이더가 지원됩니다: Copilot, Claude Code, Codex, OpenCode, Hermes, 그리고 OpenClaw. 모든 프로바이더의 이벤트는 공통 AgentEvent 형식으로 정규화되어 WebSocket을 통해 UI로 스트리밍됩니다.

여러 개의 병렬 변경이 필요한 프로젝트의 경우, 작업 그룹(Task Groups) 기능을 사용하여 단일 양식에서 관련 작업 묶음을 정의할 수 있습니다:

• 클릭하여 새 그룹(New Group) 생성 (또는 G 키 누름)

그룹 생성 대화 상자를 열기 위해 설정합니다 – 그룹 수준 구성: 제목, 리포지토리 경로, 기본 브랜치, 우선순위
자식 작업 추가 (2~20개). 각 작업은 고유한 제목, 설명, 에이전트 유형 및 워크트리 토글을 가집니다.
슬라이더(1부터 N까지)로 **병렬성(parallelism)**을 설정합니다. 이는 동시에 실행되는 에이전트 수를 제어합니다. 즉시 시작하려면 **생성 및 실행(Create & Run)**을 클릭하거나, 백로그에 추가하려면 **그룹 생성(Create Group)**을 클릭합니다.

그룹은 전체 진행 상황을 보여주는 단일 카드 형태로 보드에 나타납니다. 클릭하면 개별 자식 상태, 실패 시 재시도 버튼, 그리고 개별 에이전트 패널로 드릴다운할 수 있는 **그룹 패널(Group Panel)**이 확장됩니다. 모든 자식이 성공적으로 완료되면 그룹은 자동으로 "검토(review)" 단계로 진행됩니다.

• 백로그(Backlog), 진행 중(In Progress), 검토(Review), 완료(Done) 열을 가진 칸반 보드
• 다중 에이전트 지원(Multi-agent support) — 작업별로 GitHub Copilot, Claude Code, OpenAI Codex, OpenCode, Hermes 또는 OpenClaw를 선택할 수 있습니다. 시작 시 사용 가능한 에이전트가 자동으로 감지됩니다.
• 전환 유효성 검사를 포함한 드래그 앤 드롭 작업 관리
• WebSocket을 통한 실시간 에이전트 활동 스트리밍
• ANSI 색상 지원을 갖춘 터미널 스타일 이벤트 뷰어 (xterm.js)
• 이벤트 응집(사고 과정, 명령어, 출력) 기능이 있는 에이전트 패널
• 작업별 Git 워크트리 격리 (선택 사항)
• 로컬 병합 또는 PR(Pull Request) — 워크트리 브랜치를 로컬 메인에 병합하거나, GitHub 원격 저장소가 존재하는 경우 (자동 감지) PR을 생성합니다. 카드가 완료 단계에 도달하거나, 병합 또는 PR 생성이 이루어지거나, 보관/삭제되는 동안 깨끗한 워크트리는 자동으로 제거됩니다.
• 정리(Cleanup)는 등록된 agentboard-*만 제거합니다.

동일한 리포지토리/브랜치 식별자를 가진 worktree; 더티(dirty), 활성(active) 또는 불일치(mismatched) 경로가 유지 및 보고되며, 브랜치는 항상 보존됩니다 - 시작 시 동기화(Startup reconciliation)는 오래된 작업 경로를 복구하고 중단된 실행으로 남겨진 깨끗한 고아(orphaned) Board worktree를 제거합니다
듀얼 데이터베이스 백엔드(Dual database backends) — SQLite (설정 불필요 기본값) 또는 PostgreSQL - 재사용 가능한 작업 구성을 위한 작업 템플릿
작업 그룹(Task Groups) — 하나의 양식에 여러 관련 작업을 정의하고, 설정 가능한 병렬성(slider 1..N)으로 실행하며, 전체 진행 상황을 모니터링합니다 - 작업 생성 시 에이전트를 즉시 시작하는 자동 실행 옵션

• 우선순위 레벨 (critical, high, medium, low)에 이모지 표시 및 색상 코딩된 테두리 적용

• 에이전트 유형, 상태, 우선순위별 작업 필터링 및 정렬

• API 키 인증 (선택 사항 — API_KEY 환경 변수 설정) - 작업 보관(Task archiving)

• 다크/라이트 테마 토글

• 작업 검색 및 필터링

• 단축키 (N: 새 작업, G: 새 그룹, Esc: 패널 닫기)

• Node.js 22+

• npm 10+

• 사용자의 장치에 인증된 에이전트 CLI가 최소 하나 필요:
  GitHub Copilot: CLI 설치 및 인증 완료
  Claude Code: CLI 설치 및 인증 완료
  OpenAI Codex: CLI 설치 및 인증 완료
  OpenCode: CLI 설치 및 인증 완료
  Hermes: Hermes Agent 설치 및 hermes acp --check가 성공해야 함
  OpenClaw: OpenClaw CLI 설치 및 Gateway/세션 접근 구성 필요

Linux, macOS, 그리고 Windows에서 작동합니다.

git clone https://github.com/DanWahlin/ai-agent-board.git
cd ai-agent-board
npm install
...

http://localhost:8081에서 접속합니다.

기본적으로 앱은 SQLite를 사용하며, 설정이 필요 없습니다.

PostgreSQL의 경우, 데이터베이스 컨테이너를 시작하고 DATABASE_URL을 설정해야 합니다.

:

docker compose up -d
# packages/server/.env에 연결 문자열 설정
DATABASE_URL=postgresql://agentboard:your_password@localhost:5433/agentboard

npm run build:server
npm run build:client

현재 단일 호스트 프로덕션 레이아웃은 kanban-server.service를 사용하여 127.0.0.1:8080에서 작동합니다.

, kanban-client.service

on 127.0.0.1:8081

, PostgreSQL in the ai-agent-board-db

Docker container, and a dedicated nginx ingress on 127.0.0.1:18085

. Cloudflare Tunnel이 해당 nginx ingress를 대상으로 하며, Cloudflare Access가 사용자 인증을 제공합니다. 이 오리진들을 공용 또는 Tailscale 인터페이스에 바인딩하지 마십시오.

변경 사항을 푸시하기 전에 결정론적 게이트(deterministic gate)를 사용하십시오. 이는 클라이언트 빌드, 서버 빌드, 그리고 필수 Playwright E2E 스위트를 실행합니다. E2E가 실행되지 않으면 명령이 실패합니다.

npm run gate:required
# 이 클론에 커밋된 pre-push 훅을 활성화합니다
npm run hooks:install

POST /api/orchestrations

은 안정적인 통합 파사드(integration facade)입니다. 이는 Idempotency-Key, 정확한 프로젝트 ID/이름/별칭, 그리고 준비된 에이전트를 요구합니다. 이 엔드포인트는 작업을 생성하고 실행을 영구적으로 요청합니다. 재실행(replay) 시에는 Idempotent-Replay: true가 포함된 원래의 작업이 반환됩니다. 프로젝트 별칭은 프로젝트 생성/업데이트 API를 통해 관리됩니다. 작업 링크는 /projects/:projectId/tasks/:taskId를 사용하며, 해당 작업을 패널에서 직접 엽니다.

서비스 자격 증명은 의도적으로 다음 범위로 제한됩니다:
projects:read,
agents:read,
tasks:create,
tasks:read,
tasks:message,
그리고 groups:create.

이들은 프로젝트 병합(merge), PR 생성, 리소스 삭제 또는 변경(mutate)을 할 수 없습니다. API_KEY는 UI를 위한 레거시 전면 접근 자격 증명으로 유지됩니다.| COPILOT_MODEL

| claude-opus-4-20250514

| Copilot SDK 세션용 모델 (Model for Copilot SDK sessions) |
| CLAUDE_MODEL

| claude-opus-4-20250514

| Claude 코드 세션용 모델 (Model for Claude Code sessions) |
| CODEX_MODEL

| gpt-5.2-codex

| OpenAI Codex 세션용 모델 (Model for OpenAI Codex sessions) |
| HERMES_COMMAND

| hermes

| ACP 서버 시작에 사용되는 Hermes CLI 명령어 또는 절대 경로 (Hermes CLI command or absolute path used to start the ACP server) |
| HERMES_MODEL

| configured default

| Hermes 세션의 표시/설정된 모델 레이블입니다. Hermes ACP는 자체 활성 설정을 사용합니다. (Display/configured model label for Hermes sessions; Hermes ACP uses its own active config) |
| HERMES_ACCEPT_HOOKS

| (unset) | 헤드리스(headless) ACP 세션에서 Hermes 시작 후크 프롬프트를 자동 승인하도록 설정하려면 true로 설정합니다. (Set to true to auto-approve Hermes startup hook prompts in headless ACP sessions) |
| OPENCLAW_COMMAND

| openclaw

| ACP 브리지를 시작하는 데 사용되는 OpenClaw CLI 명령어 또는 절대 경로 (OpenClaw CLI command or absolute path used to start the ACP bridge) |
| OPENCLAW_GATEWAY_URL

| (SDK 기본값) | openclaw acp로 전달되는 선택적 OpenClaw Gateway WebSocket URL입니다. (Optional Openclaw Gateway WebSocket URL forwarded to openclaw acp)

| OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD

| (unset) | 환경 변수를 통해 전달되는 선택적 OpenClaw Gateway 자격 증명입니다. (Optional Openclaw Gateway credentials passed through environment variables) |
| COPILOT_DENIED_TOOLS

| (unset) | Copilot 세션에서 거부할 쉼표로 구분된 도구 이름 목록입니다. (Comma-separated tool names to deny in Copilot sessions) |
| ALLOWED_REPO_ROOTS

| $HOME , temp, current workspace | 허용되는 리포지토리 루트 경로 (쉼표로 구분): (Allowed repo root paths (comma-separated)) |
| ALLOWED_ORIGINS

| http://localhost:8081,http://localhost:4175,http://localhost:4176 | CORS 오리진입니다. (CORS origins) |
| ALLOWED_HOSTS

| localhost,127.0.0.1 | WebSocket 업그레이드를 위한 서버 측 호스트 허용 목록입니다. 운영 환경에서는 신뢰할 수 있는 리버스 프록시 호스트 이름을 추가하세요. (Server-side Host allowlist for WebSocket upgrades. Add the trusted reverse-proxy hostname in production.) |
| AGENT_TIMEOUT_MS

| 3600000 | 기본 최대 에이전트 실행 시간(60분)입니다. 작업은 이를 1~240분으로 재정의할 수 있습니다. (Default max agent execution time (60 minutes). Tasks can override this from 1–240 minutes.) |
| API_URL

| http://localhost:8080 | Vite 프록시 대상입니다. (Vite proxy target) |
| VITE_ALLOWED_HOSTS

| localhost,127.0.0.1 | .env 또는 프로세스 환경에서 로드되는 Vite HTTP 및 프록시-업그레이드 호스트 허용 목록입니다. 신뢰할 수 있는 리버스 프록시 호스트 이름을 추가하고 와일드카드는 절대 사용하지 마세요. (Vite HTTP and proxy-upgrade Host allowlist. Loaded from .env or the process environment. Add trusted reverse-proxy hostnames; never use a wildcard.) |
| PROJECTS_DIR

| ~/projects | 호스트 프로젝트 경로입니다. (Host projects path)

Agent Board는 기본적으로 각 실행을 60분으로 설정합니다. 작업의 **시간 제한(Time limit)**을 1~240분으로 설정하여 이 기본값을 재정의할 수 있으며, 통합 기능은 timeoutMinutes (또는 timeout_minutes)를 통해 Hermes 플러그인을 전송할 수 있습니다. 시간 초과된 오케스트레이션은 상태와 기록이 추적되도록 동일한 카드에서 POST /api/orchestrations/:id/retry을 통해 재시도해야 합니다.

더 긴 시간 제한이 있다고 해서 컨텍스트 한 시간을 자동으로 채우거나 다시 보내는 것은 아닙니다. 선택된 제공업체가 자체적인 대화/컨텍스트 창을 제어하며, Agent Board는 초기 작업을 전달한 다음 제공업체의 이벤트를 소비합니다. 더 긴 실행도 여전히 더 많은 모델 호출을 수행하고 더 많은 도구 출력을 생성할 수 있습니다. 서버는 작업당 인메모리 이벤트 캐시를 2,000개 이벤트로 제한하며, WebSocket 전송을 위해 빠른 출력을 병합(coalesces)하지만, 작업이 재실행되거나 삭제될 때까지 원본 이벤트를 데이터베이스에 영구 저장합니다. 따라서 운영자는 events 테이블을 모니터링하고 보존 정책에 따라 오래된 대용량 작업을 아카이브/삭제해야 합니다.

ai-agent-board/
├── packages/
│ ├── client/ # React 프론트엔드
...

# 필수 결정론적 게이트: 클라이언트 빌드, 서버 빌드, E2E
npm run gate:required
# E2E 전용; 포트 3002/4176에서 격리된 테스트 앱 프로세스를 시작합니다.
...

.githooks/pre-push에 있는 로컬 pre-push 훅은 npm run gate:required를 실행합니다. 이를 활성화하려면 클론할 때 한 번 npm run hooks:install을 실행하고 core.hooksPath .githooks를 사용해야 합니다.

7개의 테스트 파일이 81개의 테스트를 커버합니다:

npm run dev # 클라이언트 + 서버
npm run dev:server # API만 (포트 8080)
npm run dev:client # Vite만 (포트 8081)
...

CONTRIBUTING.md를 참조하세요.