Aif Handoff

Autonomous Kanban board where AI agents plan, implement, and review your tasks — fully hands-off.

lee-to
開発者 lee-to
AI・機械学習 · MIT · TypeScript · 更新日: 7 months ago
136
スター
17
Forks
検証済み
A
安全性:
優秀
A
品質:
aiai-factoryaifhandoffharnessharness-engineeringsddspec-driven-development

logo

AIF Handoff

Autonomous Kanban board where AI agents plan, implement, and review your tasks — fully hands-off.

This project was built using AI Factory — an open-source framework for AI-driven development.

Built on top of AI Factory workflow and powered by runtime profiles through @aif/runtime (Claude and Codex adapters included). Tasks flow through stages automatically: Backlog → Planning → Plan Ready → Implementing → Review → Done — each stage orchestrated by specialized AI subagents following the AIF methodology. In auto mode, review feedback can also trigger an automatic rework loop: Review → request_changes → Implementing. When that loop stops converging, the task is handed off explicitly as Done + manual review required instead of silently passing.

Auto-review is now convergence-aware. You can keep the default full_re_review loop or switch to closure_first via AGENT_AUTO_REVIEW_STRATEGY. When auto-review no longer converges, the task moves to done with manualReviewRequired=true, and the UI surfaces that explicit human handoff instead of silently treating the review as passed.

Runtime Providers Out of the Box

Use the runtime that fits your stack today, then switch per project/task without changing orchestration logic:

⚠️ Warning: Anthropic prohibits using Claude Max / Pro subscriptions outside of the official Claude Code CLI. The SDK transport for Claude calls the Agent SDK directly, which may violate these terms. If you're worried about your subscription getting blocked, use the CLI transport — it runs through the official Claude Code CLI and is safe to use on a Max / Pro subscription. Use the SDK transport at your own risk, or switch to the API transport with an ANTHROPIC_API_KEY for production use.

Need something custom? Add your own runtime adapter module and load it at startup via AIF_RUNTIME_MODULES (comma-separated module specifiers). No fork required.

Key Features

Quick Start

Without Docker

git clone https://github.com/lee-to/aif-handoff.git
cd aif-handoff
npm install
npm run init
npm run dev

Set MCP_PORT in your shell or root .env before npm run dev if you also want the MCP HTTP server in local development. Use an integer port between 1 and 65535; invalid values are ignored by the dev launcher and the settings install route falls back to the local stdio entry instead of writing an HTTP MCP endpoint.

With Docker

git clone https://github.com/lee-to/aif-handoff.git
cd aif-handoff
docker compose up --build

Development starts three services by default. If MCP_PORT is set to a valid integer port, it starts a fourth service for MCP over HTTP. Docker starts all four services.

Service URL Description
API http://localhost:3009 Hono REST + WebSocket server
Web http://localhost:5180 React Kanban UI
Agent (background) Event-driven + polling, dispatches subagents
MCP http://localhost:<MCP_PORT>/mcp Optional local MCP HTTP endpoint

The agent coordinator reacts to task events via WebSocket in near real-time and falls back to 30-second polling. Activity logging can be switched to batch mode (ACTIVITY_LOG_MODE=batch) to reduce DB write amplification. See Configuration for all tuning options.

Authentication

For Codex/OpenAI-compatible profiles, configure OPENAI_API_KEY and optionally OPENAI_BASE_URL (or set profile-level apiKeyEnvVar / baseUrl). See Providers.

Codex OAuth in Docker (without OPENAI_API_KEY)

The dev compose wires up a small in-container broker that runs codex login --device-auth and exposes a guided UI in Settings → Runtime profile → Codex:

  1. Click Start Codex login. The broker spawns the CLI and reads back a verification URL plus a one-time code.
  2. Open the verification page in your browser, enter the code, and complete ChatGPT sign-in.
  3. The CLI exits 0 once ChatGPT confirms and writes ~/.codex/auth.json to the persistent codex-auth volume. The wizard flips to success automatically (status polled every second).
  4. Run docker compose restart agent to pick up the credentials.

Production note: the broker is dev-only. docker-compose.production.yml sets AIF_ENABLE_CODEX_LOGIN_PROXY=false. For production, configure OPENAI_API_KEY in .env instead.

Runtime Defaults

Runtime profiles can now be managed at two scopes:

Effective runtime resolution follows this order:

  1. task override
  2. project default
  3. app default
  4. environment fallback

Planning and review keep their own defaults, but when those are unset they inherit from the task default at the same scope. Chat has its own dedicated project/app default chain.

OpenCode Quick Setup

  1. Start OpenCode server (example with password):
OPENCODE_SERVER_PASSWORD='your-strong-password' opencode serve --hostname 127.0.0.1 --port 60661
  1. Create/update runtime profile in AIF Handoff:
  1. Validate profile connection in UI and use it for chat/task stages.

Full OpenCode options and examples: Providers.

Architecture

packages/
├── shared/    # Types, schema, state machine, env, constants, logger
├── runtime/   # Runtime registry, adapters, module loader, workflow specs
├── data/      # Centralized DB access layer (@aif/data)
├── api/       # Hono REST + WebSocket server (port 3009)
├── web/       # React + Vite + TailwindCSS — Kanban UI (port 5180)
└── agent/     # Coordinator (node-cron) + runtime-driven subagent orchestration

Database access is centralized in packages/data. api and agent must use @aif/data; direct DB imports in those packages are blocked by ESLint guards.

Agent Pipeline

The coordinator polls every 30 seconds and delegates to .claude/agents/ definitions:

Stage Agent What it does
Backlog → Planning → Plan Ready plan-coordinator Iterative plan refinement via plan-polisher
Plan Ready → Implementing → Review implement-coordinator Parallel task execution with worktrees + quality sidecars
Review → Done / Review → request_changes → Implementing / Review → Done + manual review required review-sidecar + security-sidecar (+ auto review gate in coordinator) Code review and security audit in parallel; in auto mode, structured blocking findings drive rework until success or explicit manual handoff

Auto-Review Convergence

Fault Tolerance

All agents are loaded via settingSources: ["project"] from .claude/agents/*.md — the same agent definitions used by AI Factory.

Execution Modes

AIF Handoff supports two execution modes, configurable globally via AGENT_USE_SUBAGENTS or per-task in the UI:

Mode AGENT_USE_SUBAGENTS How it works Trade-off
Subagents true Each stage runs through specialized coordinator agents (plan-coordinator, implement-coordinator, review-sidecar + security-sidecar) that iteratively refine the result until quality criteria are met Higher quality — plans are polished in multiple rounds, implementation gets parallel workers with quality sidecars, reviews are thorough. Takes more time and tokens
Skills false (default) Each stage runs as a single-pass AIF skill (/aif-plan, /aif-implement, /aif-review, /aif-security-checklist) Faster execution with lower token usage, but no iterative refinement — good enough for simpler tasks or quick prototyping

Tech Stack

Layer Technology
Runtime Node.js + TypeScript
Monorepo Turborepo
Database SQLite (better-sqlite3 + drizzle-orm)
API Hono + @hono/node-server + WebSocket
Validation zod + @hono/zod-validator
Frontend React + Vite + TailwindCSS
Drag & Drop @dnd-kit
Server State @tanstack/react-query
Runtime SDKs Pluggable adapters — Claude (Agent SDK) + Codex (CLI/SDK/API)
Scheduler node-cron

Docker

The project includes full Docker support (Angie reverse proxy + Node services).

Development

docker compose up --build

Web UI at localhost:5180, API at localhost:3009, MCP at localhost:${MCP_PORT:-3100}.

Production

docker compose -f docker-compose.production.yml up --build

Authentication: set ANTHROPIC_API_KEY in .env, or log in via docker compose exec agent claude login and then docker compose restart (see Authentication above).

Only ports 80/443 are exposed. API is bound to localhost only. Includes security hardening (no-new-privileges, resource limits), healthchecks, log rotation, and automatic SSL via Let's Encrypt (ACME).

Variable Default Description
ANTHROPIC_API_KEY — API key (or use claude login)
DOMAIN localhost Domain for SSL certificate (ACME)
PORT 3009 Host port for API
MCP_PORT 3100 Host port for MCP HTTP server (1-65535)
WEB_PORT 5180 Host port for Web UI (dev)
WEB_HOST localhost Web UI dev server host (Vite)
HTTP_PORT 80 Host port for Web UI (production)
HTTPS_PORT 443 HTTPS port (production)
PROJECTS_DIR ./projects Host directory for project files (dev)
PROJECTS_MOUNT /home/www Project files path inside containers

A .devcontainer/ config is also included for JetBrains / VS Code.

Scripts

Command Description
npm run dev Start all services with hot reload
npm run build Build all packages
npm test Run all tests (Vitest)
npm run init Initialize database
npm run db:setup Build shared package and initialize SQLite DB
npm run db:push Push schema changes via drizzle-kit

Troubleshooting

If you enabled subagents and the workflow runs for too long or frequently times out, disable them in your environment (this is the default):

AGENT_USE_SUBAGENTS=false

If an LLM report says it lacks permissions for specific actions during workflow execution, either grant the required permissions in .claude/settings.local.json or bypass permission checks via environment variable:

AGENT_BYPASS_PERMISSIONS=true

Documentation

Guide Description
Getting Started Installation, setup, first steps
Architecture Agent pipeline, state machine, data flow
API Reference REST endpoints, WebSocket events
Configuration Environment variables, logging, auth
Providers Runtime profiles, adapters, capability matrix

ui-light ui-dark ui-light-list ui-dark-list

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

Security

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure instructions.

License

MIT License — see LICENSE for details.

🔓 サインインしてさらに解放
GitHub でサインイン