### Install Dependencies

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Install all required project dependencies.

```bash
npm install
```

--------------------------------

### Start OpenCode Server

Source: https://github.com/lee-to/aif-handoff/blob/main/README.md

Use this command to start the OpenCode server with a specified password, hostname, and port. Ensure the password is strong.

```bash
OPENCODE_SERVER_PASSWORD='your-strong-password' opencode serve --hostname 127.0.0.1 --port 60661
```

--------------------------------

### Start Development Environment

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Launch the development server.

```bash
npm run dev
```

--------------------------------

### Setup Database

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Initialize the database for local development.

```bash
npm run db:setup
```

--------------------------------

### Project Configuration Example

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Example of a project configuration file (.ai-factory/config.yaml) specifying language settings, artifact paths, workflow behavior, and Git integration options.

```yaml
# .ai-factory/config.yaml

language:
  ui: en
  artifacts: en
  technical_terms: keep  # keep or translate

paths:
  plan: .ai-factory/PLAN.md
  plans: .ai-factory/plans/
  fix_plan: .ai-factory/FIX_PLAN.md
  roadmap: .ai-factory/ROADMAP.md
  description: .ai-factory/DESCRIPTION.md
  architecture: .ai-factory/ARCHITECTURE.md
  docs: docs/
  rules_file: .ai-factory/RULES.md
  references: .ai-factory/references/

workflow:
  auto_create_dirs: true
  plan_id_format: slug  # slug, timestamp, or uuid
  analyze_updates_architecture: true
  architecture_updates_roadmap: true
  verify_mode: normal  # strict, normal, or lenient

git:
  enabled: true
  base_branch: main
  create_branches: true
  branch_prefix: feature/
  skip_push_after_commit: false
```

--------------------------------

### Copy Example Environment File

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

Use this command to copy the example environment file to a new file named .env. This is the first step in configuring your project's environment variables.

```bash
cp .env.example .env
```

--------------------------------

### Start AIF Handoff with Docker

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

Clones the repository and starts the API, Web UI, and Agent services using Docker Compose.

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

--------------------------------

### MCP Tool Usage Examples

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Examples of using the MCP tool within AI agents to interact with Handoff tasks. These calls demonstrate listing, getting, creating, syncing, and pushing task-related data.

```typescript
// MCP tool usage examples (called by AI agents)

// List tasks with pagination
const tasks = await mcp.call("handoff_list_tasks", {
  projectId: "project-uuid",
  status: "backlog",
  limit: 20,
  offset: 0
});

// Get full task details
const task = await mcp.call("handoff_get_task", {
  taskId: "task-uuid"
});

// Create a new task
const newTask = await mcp.call("handoff_create_task", {
  projectId: "project-uuid",
  title: "Implement feature X",
  description: "Details about the feature",
  priority: 2,
  tags: ["feature"],
  autoMode: true
});

// Sync task status bidirectionally
const syncResult = await mcp.call("handoff_sync_status", {
  taskId: "task-uuid",
  newStatus: "implementing",
  sourceTimestamp: new Date().toISOString(),
  direction: "aif_to_handoff",
  paused: true  // Prevent Handoff from picking up during manual work
});

// Push plan content with annotation validation
await mcp.call("handoff_push_plan", {
  taskId: "task-uuid",
  planContent: "# Implementation Plan\n\n<!-- handoff:task:task-uuid -->\n\n..."
});
```

--------------------------------

### Install and Run AIF Handoff (Without Docker)

Source: https://github.com/lee-to/aif-handoff/blob/main/README.md

Installs and runs the AIF Handoff project locally without using Docker. Ensure Node.js is installed.

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

--------------------------------

### Plan Annotation Example

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/mcp-sync.md

Example of a plan annotation used as the first line in plan files. This annotation enables traceability and validation between plan files and Handoff tasks.

```markdown
<!-- handoff:task:a1b2c3d4-e5f6-7890-abcd-ef1234567890 -->

# Implementation Plan: User Authentication

...
```

--------------------------------

### Clone and Setup Repository

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Initial commands to clone the repository and navigate to the project directory.

```bash
git clone https://github.com/<your-username>/aif-handoff.git
cd aif-handoff
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat: add new task filtering
fix: resolve WebSocket reconnection issue
docs: update API reference
```

--------------------------------

### GET /projects

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Retrieves all projects with their configuration including budget limits.

```APIDOC
## GET /projects

### Description
Retrieves all projects with their configuration including budget limits for each AI agent stage.

### Method
GET

### Endpoint
/projects

### Response
#### Success Response (200)
- **id** (string) - Project UUID.
- **name** (string) - Project name.
- **rootPath** (string) - Filesystem path for the project.
- **plannerMaxBudgetUsd** (number) - Budget limit for the planner agent.
- **planCheckerMaxBudgetUsd** (number) - Budget limit for the plan checker agent.
- **implementerMaxBudgetUsd** (number) - Budget limit for the implementer agent.
- **reviewSidecarMaxBudgetUsd** (number) - Budget limit for the review sidecar agent.
- **parallelEnabled** (boolean) - Whether parallel execution is enabled.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.

#### Response Example
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Project",
    "rootPath": "/path/to/project",
    "plannerMaxBudgetUsd": 10,
    "planCheckerMaxBudgetUsd": 2,
    "implementerMaxBudgetUsd": 15,
    "reviewSidecarMaxBudgetUsd": 2,
    "parallelEnabled": false,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
]
```

--------------------------------

### Start OpenCode Server

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/providers.md

Command to launch the OpenCode HTTP server on a specific host and port.

```bash
opencode serve --hostname 127.0.0.1 --port 4096
```

--------------------------------

### Install AIF Handoff Locally

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

Installs the required Claude Code CLI and project dependencies for local development.

```bash
npm i -g @anthropic-ai/claude-code   # required — Agent SDK uses Claude Code CLI
git clone https://github.com/lee-to/aif-handoff.git
cd aif-handoff
npm install
```

--------------------------------

### List All Projects

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Retrieve a list of all projects, including their configuration details such as AI agent budget limits. This is useful for viewing existing project setups.

```bash
curl -s http://localhost:3009/projects

# Response
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Project",
    "rootPath": "/path/to/project",
    "plannerMaxBudgetUsd": 10,
    "planCheckerMaxBudgetUsd": 2,
    "implementerMaxBudgetUsd": 15,
    "reviewSidecarMaxBudgetUsd": 2,
    "parallelEnabled": false,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
]
```

--------------------------------

### GET /agent/readiness

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Checks if agent authentication is correctly configured.

```APIDOC
## GET /agent/readiness

### Description
Checks whether agent authentication is configured via ANTHROPIC_API_KEY and/or Claude profile auth.

### Method
GET

### Endpoint
/agent/readiness

### Response
#### Success Response (200)
- **ready** (boolean) - Readiness status
- **hasApiKey** (boolean) - Whether API key is present
- **hasClaudeAuth** (boolean) - Whether Claude auth is present
- **authSource** (string) - Source of authentication
- **detectedPath** (string) - Path to auth file
- **message** (string) - Status message
- **checkedAt** (string) - Timestamp of check

#### Response Example
{
  "ready": true,
  "hasApiKey": false,
  "hasClaudeAuth": true,
  "authSource": "claude_profile",
  "detectedPath": "/Users/you/.claude/auth.json",
  "message": "Agent authentication is configured.",
  "checkedAt": "2026-03-28T17:10:00.000Z"
}
```

--------------------------------

### Available npm Scripts

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

A list of available npm scripts for managing the project, including starting the development server, building the project, running tests, and setting up the database.

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm test
```

```bash
npm run db:setup
```

```bash
npm run db:push
```

--------------------------------

### Start AIF Handoff in Production

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

Deploys the application using the production-specific Docker Compose configuration with security hardening.

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

--------------------------------

### Start Development Docker Compose

Source: https://github.com/lee-to/aif-handoff/blob/main/README.md

Launches all services for development using Docker Compose. Access the Web UI at localhost:5180 and the API at localhost:3009.

```bash
docker compose up --build
```

--------------------------------

### GET /agent/readiness

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/configuration.md

Verifies the authentication state and runtime registry availability for the agent.

```APIDOC
## GET /agent/readiness

### Description
Verifies the runtime registry availability and checks if at least one execution path is configured (enabled profile, usable auth, or Codex CLI path).

### Method
GET

### Endpoint
/agent/readiness

### Response
#### Success Response (200)
- **ready** (boolean) - Indicates if the runtime registry is available and configured.
- **runtime_descriptors** (array) - List of available runtime descriptors.
- **enabled_profile_count** (number) - Count of enabled runtime profiles.
- **auth_diagnostics** (object) - Diagnostic information regarding authentication sources.
```

--------------------------------

### GET /tasks

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Retrieves all tasks for a specific project.

```APIDOC
## GET /tasks

### Description
Retrieves all tasks for a project, sorted by status order and position within each column.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **projectId** (string) - Required - The ID of the project to fetch tasks for.

### Response
#### Success Response (200)
- **id** (string) - Task UUID.
- **projectId** (string) - Associated project ID.
- **title** (string) - Task title.
- **description** (string) - Task description.
- **status** (string) - Current status.
- **priority** (number) - Priority level.
- **position** (number) - Kanban position.
- **autoMode** (boolean) - Whether auto mode is enabled.
- **tags** (array) - List of tags.

#### Response Example
[
  {
    "id": "task-uuid-1",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication",
    "status": "backlog"
  }
]
```

--------------------------------

### Start AI Chat Conversation

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Initiates a new AI chat conversation. Include `explore: true` for initial exploration.

```bash
curl -X POST http://localhost:3009/chat \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "message": "How is the authentication module structured?",
    "clientId": "ws-client-123",
    "explore": true
  }'
```

--------------------------------

### Example handoff_list_tasks response

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/mcp-sync.md

The expected JSON response structure when calling the handoff_list_tasks tool.

```json
{
  "items": [{ "id": "abc-123", "title": "Example task", "status": "backlog" }],
  "total": 42,
  "limit": 20,
  "offset": 0
}
```

--------------------------------

### GET /settings/config

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/configuration.md

Retrieves the parsed configuration settings as a JSON object.

```APIDOC
## GET /settings/config

### Description
Reads the project configuration and returns it as a JSON object.

### Method
GET

### Endpoint
/settings/config
```

--------------------------------

### GET /projects/:id/defaults

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/configuration.md

Retrieves the resolved paths and workflow settings for a specific project.

```APIDOC
## GET /projects/:id/defaults

### Description
Returns the resolved configuration paths and workflow settings for a given project ID.

### Method
GET

### Endpoint
/projects/:id/defaults

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.
```

--------------------------------

### Custom Runtime Adapter Implementation

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Implement a custom runtime adapter to integrate new AI providers. This TypeScript example shows the basic structure for defining an adapter and its capabilities.

```typescript
// my-runtime-adapter.ts
import type { RuntimeAdapter, RuntimeRegistry } from "@aif/runtime";

const adapter: RuntimeAdapter = {
  descriptor: {
    id: "my-runtime",
    providerId: "my-provider",
    displayName: "My Custom Runtime",
    capabilities: {
      supportsResume: false,
      supportsSessionList: false,
      supportsAgentDefinitions: false,
      supportsStreaming: true,
      supportsModelDiscovery: true,
      supportsApprovals: false,
      supportsCustomEndpoint: true,
    },
  },

  async run(input) {
    const { prompt, projectRoot, options } = input;

    // Call your AI provider
    const response = await myProvider.complete({
      prompt,
      model: options?.model || "default-model",
      maxTokens: options?.maxTokens || 4096,
    });

    return {
      outputText: response.text,
      sessionId: response.sessionId || null,
      usage: {
        inputTokens: response.usage?.input || 0,
        outputTokens: response.usage?.output || 0,
        totalTokens: response.usage?.total || 0,
        costUsd: response.usage?.cost || 0,
      },
    };
  },

  async listModels() {
    return [
      { id: "model-v1", name: "Model V1", description: "Fast model" },
      { id: "model-v2", name: "Model V2", description: "Advanced model" },
    ];
  },
};

// Export the registration function
export function registerRuntimeModule(registry: RuntimeRegistry) {
  registry.registerRuntime(adapter, { source: "module" });
}

// Load via environment variable:
// AIF_RUNTIME_MODULES=/path/to/my-runtime-adapter.ts
```

--------------------------------

### Readiness Check Endpoint

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

This command performs an optional readiness check for the agent service by sending a GET request to the /agent/readiness endpoint. It helps verify if the agent is operational.

```bash
curl -s http://localhost:3009/agent/readiness
```

--------------------------------

### Create Project

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Initializes a new project with the specified configuration.

```http
POST /projects
```

--------------------------------

### Initialize and Manage Database

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/getting-started.md

Commands to set up the initial SQLite database or push schema changes to the existing database.

```bash
npm run db:setup
```

```bash
npm run db:push
```

--------------------------------

### Create a New Project

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Use this endpoint to create a new project. You can specify optional budget limits in USD for AI agents. Omit budget values for unlimited.

```bash
curl -X POST http://localhost:3009/projects \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "New Feature Project",
    "rootPath": "/home/dev/projects/new-feature",
    "plannerMaxBudgetUsd": 10,
    "implementerMaxBudgetUsd": 20
  }'

# Response: 201 Created
{
  "id": "generated-uuid",
  "name": "New Feature Project",
  "rootPath": "/home/dev/projects/new-feature",
  "plannerMaxBudgetUsd": 10,
  "planCheckerMaxBudgetUsd": null,
  "implementerMaxBudgetUsd": 20,
  "reviewSidecarMaxBudgetUsd": null,
  "parallelEnabled": false,
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T10:00:00.000Z"
}
```

--------------------------------

### List Projects

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Retrieves a list of all configured projects.

```http
GET /projects
```

```json
[
  {
    "id": "uuid",
    "name": "My Project",
    "rootPath": "/path/to/project",
    "plannerMaxBudgetUsd": 10,
    "planCheckerMaxBudgetUsd": 2,
    "implementerMaxBudgetUsd": 15,
    "reviewSidecarMaxBudgetUsd": 2,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
]
```

--------------------------------

### GET /health

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Checks the health status and uptime of the system.

```APIDOC
## GET /health

### Description
Returns the current status and uptime of the system.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - System status
- **uptime** (number) - System uptime in seconds

#### Response Example
{
  "status": "ok",
  "uptime": 123
}
```

--------------------------------

### GET /tasks/:id/comments

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Retrieves a list of comments for a specific task.

```APIDOC
## GET /tasks/:id/comments

### Description
Returns an array of comment objects for the specified task, sorted by createdAt ascending.

### Method
GET

### Endpoint
/tasks/:id/comments

### Parameters
#### Path Parameters
- **id** (string) - Required - The task UUID

### Response
#### Success Response (200)
- **comments** (array) - List of comment objects
```

--------------------------------

### Configure environment variables

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Defines authentication keys, server ports, agent timeouts, and database paths in a .env file.

```bash
# .env file configuration

# Authentication
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
OPENROUTER_API_KEY=sk-or-xxxxx

# Server ports
PORT=3009
WEB_PORT=5180

# Agent behavior
POLL_INTERVAL_MS=30000
AGENT_STAGE_STALE_TIMEOUT_MS=5400000
AGENT_STAGE_RUN_TIMEOUT_MS=3600000
AGENT_FIRST_ACTIVITY_TIMEOUT_MS=60000
AGENT_USE_SUBAGENTS=true
AGENT_BYPASS_PERMISSIONS=true
COORDINATOR_MAX_CONCURRENT_TASKS=3

# Database
DATABASE_URL=./data/aif.sqlite

# Logging
LOG_LEVEL=debug
ACTIVITY_LOG_MODE=sync

# Telegram notifications (optional)
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_USER_ID=987654321

# Custom runtime modules
AIF_RUNTIME_MODULES=/path/to/adapter1.ts,/path/to/adapter2.ts
```

--------------------------------

### GET /tasks/:id/attachments/:filename

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Downloads a file-backed attachment from a task.

```APIDOC
## GET /tasks/:id/attachments/:filename

### Description
Downloads a file-backed attachment from the task. The filename must match the attachment name.

### Method
GET

### Endpoint
/tasks/:id/attachments/:filename

### Parameters
#### Path Parameters
- **id** (string) - Required - Task ID
- **filename** (string) - Required - Attachment filename

### Response
#### Success Response (200)
- **binary** (file) - Binary file with Content-Disposition: attachment
```

--------------------------------

### GET /tasks/:id

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Retrieves the full details of a specific task.

```APIDOC
## GET /tasks/:id

### Description
Retrieves the full task object by its ID.

### Method
GET

### Endpoint
/tasks/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the task

### Response
#### Success Response (200)
- **task** (object) - Full task object.
```

--------------------------------

### POST /projects

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Creates a new project with optional budget limits.

```APIDOC
## POST /projects

### Description
Creates a new project with optional budget limits for AI agents.

### Method
POST

### Endpoint
/projects

### Request Body
- **name** (string) - Required - Project name.
- **rootPath** (string) - Required - Filesystem path.
- **plannerMaxBudgetUsd** (number) - Optional - Budget limit.
- **implementerMaxBudgetUsd** (number) - Optional - Budget limit.

### Request Example
{
  "name": "New Feature Project",
  "rootPath": "/home/dev/projects/new-feature",
  "plannerMaxBudgetUsd": 10,
  "implementerMaxBudgetUsd": 20
}

### Response
#### Success Response (201)
- **id** (string) - Generated project UUID.
- **name** (string) - Project name.
- **rootPath** (string) - Filesystem path.
- **plannerMaxBudgetUsd** (number) - Budget limit.
- **implementerMaxBudgetUsd** (number) - Budget limit.

#### Response Example
{
  "id": "generated-uuid",
  "name": "New Feature Project",
  "rootPath": "/home/dev/projects/new-feature",
  "plannerMaxBudgetUsd": 10,
  "implementerMaxBudgetUsd": 20
}
```

--------------------------------

### GET /settings/config/status

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/configuration.md

Checks if the configuration file (config.yaml) exists in the project.

```APIDOC
## GET /settings/config/status

### Description
Checks if the config.yaml file exists for the current project.

### Method
GET

### Endpoint
/settings/config/status
```

--------------------------------

### POST /projects

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Creates a new project.

```APIDOC
## POST /projects

### Description
Creates a new project with the provided configuration.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **name** (string) - Required - Project name (1-200 chars)
- **rootPath** (string) - Required - Absolute path to project root
- **plannerMaxBudgetUsd** (number) - Optional - Budget for planner agent
- **planCheckerMaxBudgetUsd** (number) - Optional - Budget for plan-checker agent
- **implementerMaxBudgetUsd** (number) - Optional - Budget for implementer agent
- **reviewSidecarMaxBudgetUsd** (number) - Optional - Per-sidecar budget for review/security sidecars

### Response
#### Success Response (201)
- **project** (object) - The created project object
```

--------------------------------

### Create Runtime Profile

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Use this command to create a new runtime profile for an AI provider. Ensure the API key environment variable is set.

```bash
curl -X POST http://localhost:3009/runtime-profiles \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Claude Sonnet",
    "runtimeId": "claude",
    "providerId": "anthropic",
    "transport": "sdk",
    "apiKeyEnvVar": "ANTHROPIC_API_KEY",
    "defaultModel": "sonnet",
    "enabled": true
  }'
```

--------------------------------

### Get Project MCP Config

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Retrieves the MCP server configuration for a specific project.

```http
GET /projects/:id/mcp
```

```json
{
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["./server.js"]
    }
  }
}
```

```json
{ "mcpServers": {} }
```

--------------------------------

### Manage Docker deployment

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Commands for building, running, and authenticating within the Docker environment.

```bash
# Development with hot reload
docker compose up --build

# Production deployment
docker compose -f docker-compose.production.yml up --build

# Authenticate inside container
docker compose exec agent claude login
docker compose restart
```

--------------------------------

### List Available Runtimes

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Fetches a list of available AI runtime profiles, including their IDs, providers, and capabilities.

```bash
curl -s http://localhost:3009/runtime-profiles/runtimes
```

--------------------------------

### GET /tasks/{taskId}

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Retrieves detailed information about a specific task, including its plan, logs, and activity.

```APIDOC
## GET /tasks/{taskId}

### Description
Retrieves full task details including plan, implementation log, review comments, and agent activity timeline.

### Method
GET

### Endpoint
/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the task.
- **projectId** (string) - The ID of the project the task belongs to.
- **title** (string) - The title of the task.
- **description** (string) - The description of the task.
- **status** (string) - The current status of the task.
- **priority** (integer) - The priority of the task.
- **plan** (string) - The implementation plan for the task.
- **implementationLog** (string) - Log of the implementation steps.
- **reviewComments** (string) - Comments from the review process.
- **agentActivityLog** (string) - Timeline of agent activities.
- **tokenTotal** (integer) - Total tokens used for the task.
- **costUsd** (number) - Total cost in USD for the task.
- **autoMode** (boolean) - Indicates if auto mode is enabled.
- **tags** (array of strings) - Tags associated with the task.
- **createdAt** (string) - Timestamp when the task was created.
- **updatedAt** (string) - Timestamp when the task was last updated.

#### Response Example
```json
{
  "id": "task-uuid-1",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Implement user authentication",
  "description": "Add login and registration endpoints",
  "status": "done",
  "priority": 2,
  "plan": "# Implementation Plan\n\n## Overview\n...",
  "implementationLog": "Created auth module...",
  "reviewComments": "Code looks good. Minor suggestions...",
  "agentActivityLog": "[{{\"timestamp\":\"...\",\"tool\":\"Edit\",\"summary\":\"Updated auth.ts\"}}]",
  "tokenTotal": 45000,
  "costUsd": 0.135,
  "autoMode": true,
  "tags": ["feature", "auth"],
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T14:30:00.000Z"
}
```
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/lee-to/aif-handoff/blob/main/CONTRIBUTING.md

Execute the test suite and linting tools to ensure code quality.

```bash
npm test
npm run lint
```

--------------------------------

### GET /tasks/{taskId}/comments

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Retrieves all comments associated with a specific task, including both human and agent-generated comments.

```APIDOC
## GET /tasks/{taskId}/comments

### Description
Retrieves all comments for a task, including both human and agent comments with attachments.

### Method
GET

### Endpoint
/tasks/{taskId}/comments

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task whose comments are to be retrieved.

### Response
#### Success Response (200 OK)
- Returns an array of comment objects. Each object may contain details like author, content, timestamp, and attachments.

#### Response Example
```json
[
  {
    "id": "comment-uuid-1",
    "taskId": "task-uuid-1",
    "author": "user@example.com",
    "content": "This plan looks good, but can we add a section on error handling?",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "attachments": []
  },
  {
    "id": "comment-uuid-2",
    "taskId": "task-uuid-1",
    "author": "agent@ai.com",
    "content": "Added error handling section to the plan.",
    "createdAt": "2026-01-15T12:30:00.000Z",
    "attachments": []
  }
]
```
```

--------------------------------

### Configure Codex Adapter (SDK Transport)

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/providers.md

Set up the Codex adapter with SDK transport, which wraps the Codex CLI. Authentication is handled by 'codex auth login'.

```json
{
  "projectId": null,
  "name": "Codex SDK",
  "runtimeId": "codex",
  "providerId": "openai",
  "transport": "sdk",
  "defaultModel": "gpt-5.4",
  "enabled": true
}
```

--------------------------------

### Check Agent Readiness

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Verifies if the agent is correctly configured with authentication credentials.

```http
GET /agent/readiness
```

```json
{
  "ready": true,
  "hasApiKey": false,
  "hasClaudeAuth": true,
  "authSource": "claude_profile",
  "detectedPath": "/Users/you/.claude/auth.json",
  "message": "Agent authentication is configured.",
  "checkedAt": "2026-03-28T17:10:00.000Z"
}
```

--------------------------------

### GET /health

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/mcp-sync.md

Health check endpoint used primarily for Docker health monitoring when the server is running in HTTP mode.

```APIDOC
## GET /health

### Description
Exposes a health check endpoint for Docker healthchecks when running in HTTP transport mode.

### Method
GET

### Endpoint
/health
```

--------------------------------

### Import Roadmap Tasks

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Parses the project's ROADMAP.md file and converts milestones into tasks.

```http
POST /projects/:id/roadmap/import
```

```json
{
  "roadmapAlias": "v1.0",
  "created": 5,
  "skipped": 2,
  "taskIds": ["uuid-1", "uuid-2", "..."],
  "byPhase": {
    "1": { "created": 3, "skipped": 1 },
    "2": { "created": 2, "skipped": 1 }
  }
}
```

--------------------------------

### POST /projects/:id/roadmap/import

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Imports roadmap tasks from the project root.

```APIDOC
## POST /projects/:id/roadmap/import

### Description
Reads .ai-factory/ROADMAP.md, converts milestones into tasks, and creates them as backlog items.

### Method
POST

### Endpoint
/projects/:id/roadmap/import

### Parameters
#### Path Parameters
- **id** (string) - Required - Project ID

#### Request Body
- **roadmapAlias** (string) - Required - Alias for grouping imported tasks

### Response
#### Success Response (201)
- **roadmapAlias** (string) - Alias used
- **created** (number) - Count of created tasks
- **skipped** (number) - Count of skipped tasks
- **taskIds** (array) - List of created task IDs
- **byPhase** (object) - Breakdown of created/skipped by phase

#### Response Example
{
  "roadmapAlias": "v1.0",
  "created": 5,
  "skipped": 2,
  "taskIds": ["uuid-1", "uuid-2"],
  "byPhase": {
    "1": { "created": 3, "skipped": 1 }
  }
}
```

--------------------------------

### POST /projects/{projectId}/roadmap/import

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Imports tasks from a project's ROADMAP.md file, converting milestones to structured tasks.

```APIDOC
## POST /projects/{projectId}/roadmap/import

### Description
Imports tasks from a project's `.ai-factory/ROADMAP.md` file, converting milestones to structured tasks with automatic deduplication and tagging.

### Method
POST

### Endpoint
/projects/{projectId}/roadmap/import

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project.

#### Request Body
- **roadmapAlias** (string) - Required - An alias for the roadmap version being imported.

### Request Example
```bash
curl -X POST http://localhost:3009/projects/550e8400-e29b-41d4-a716-446655440000/roadmap/import \
  -H "Content-Type: application/json" \
  -d '{ 
    "roadmapAlias": "v1.0"
  }'
```

### Response
#### Success Response (201 Created)
- **roadmapAlias** (string) - The alias of the imported roadmap.
- **created** (integer) - The number of tasks successfully created.
- **skipped** (integer) - The number of tasks skipped (e.g., due to duplication).
- **taskIds** (array) - An array of IDs for the created tasks.
- **byPhase** (object) - An object detailing created and skipped tasks per phase.
  - **[phaseNumber]** (object) - Contains `created` and `skipped` counts for a specific phase.

#### Response Example
```json
{
  "roadmapAlias": "v1.0",
  "created": 5,
  "skipped": 2,
  "taskIds": ["uuid-1", "uuid-2", "uuid-3", "uuid-4", "uuid-5"],
  "byPhase": {
    "1": { "created": 3, "skipped": 1 },
    "2": { "created": 2, "skipped": 1 }
  }
}
```
```

--------------------------------

### Configure Granular Permissions

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/configuration.md

Configure specific allow rules for shell commands in JSON settings files. Unlisted commands will be denied in headless agent mode.

```json
{
  "permissions": {
    "allow": [
      "Bash(npm install:*)",
      "Bash(npm run:*)",
      "Bash(npm test:*)",
      "Bash(npx:*)",
      "Bash(git:*)"
    ]
  }
}
```

--------------------------------

### Check API Server Health

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Use this endpoint to get the current health status and uptime of the API server. It's useful for monitoring and load balancer health checks.

```bash
curl -s http://localhost:3009/health

# Response
{
  "status": "ok",
  "uptime": 3600
}
```

--------------------------------

### Configure Claude Adapter (CLI Transport)

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/providers.md

Configure the Claude adapter for CLI transport. This spawns the 'claude' binary as a subprocess. Authentication is handled by 'claude /login'.

```json
{
  "projectId": null,
  "name": "Claude CLI",
  "runtimeId": "claude",
  "providerId": "anthropic",
  "transport": "cli",
  "defaultModel": "claude-sonnet-4-5",
  "enabled": true
}
```

--------------------------------

### Create a New Task

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Create a new task within a project. This endpoint allows configuration of automation settings, priority, and optional tags. The task is initially placed in the backlog.

```bash
curl -X POST http://localhost:3009/tasks \
  -H "Content-Type: application/json" \
  -d '{ 
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add password reset functionality",
    "description": "Users should be able to reset their password via email",
    "priority": 2,
    "autoMode": true,
    "isFix": false,
    "skipReview": false,
    "useSubagents": true,
    "tags": ["feature", "auth", "email"]
  }'
```

--------------------------------

### List Projects

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/mcp-sync.md

Lists all available projects.

```APIDOC
## GET /lee-to/aif-handoff/handoff_list_projects

### Description
List all projects.

### Method
GET

### Endpoint
/lee-to/aif-handoff/handoff_list_projects

### Parameters
No parameters required.
```

--------------------------------

### Tool: handoff_get_task

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/mcp-sync.md

Retrieves full details for a specific task, including plans, descriptions, and logs.

```APIDOC
## Tool: handoff_get_task

### Description
Get a single task by ID with full detail (including plan, description, logs).

### Parameters
#### Query Parameters
- **taskId** (UUID) - Required - Task ID
```

--------------------------------

### Retrieve Task Details

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Fetches full task metadata, including implementation logs, review comments, and agent activity.

```bash
curl -s http://localhost:3009/tasks/task-uuid-1
```

--------------------------------

### Supported Runtimes

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/providers.md

Lists the available runtimes, their providers, supported transports, and capabilities.

```APIDOC
## Supported Runtimes

| Runtime      | Provider     | Transports    | Resume         | Sessions       | Agent Defs    | Light Model         | Status                    |
| ------------ | ------------ | ------------- | -------------- | -------------- | ------------- | ------------------- | ------------------------ |
| `claude`     | `anthropic`  | SDK, CLI, API | Yes (SDK/CLI)  | Yes (SDK/CLI)  | Yes (SDK/CLI) | `claude-haiku-3-5`  | Built-in                  |
| `codex`      | `openai`     | SDK, CLI, API | Yes (SDK only) | Yes (SDK only) | No            | default             | Built-in                  |
| `opencode`   | `opencode`   | API           | Yes            | Yes            | No            | null (configurable) | Built-in                  |
| `openrouter` | `openrouter` | API           | No             | No             | No            | null (configurable) | Built-in                  |
| Custom       | Any          | Any           | Configurable   | Configurable   | Configurable  | Configurable        | Via `AIF_RUNTIME_MODULES` |

Capabilities are **transport-aware**: the same adapter may expose different capabilities depending on the selected transport. For example, the Codex adapter supports resume/sessions via SDK transport but not via CLI. Use `resolveAdapterCapabilities(adapter, transport)` to get the effective set.
```

--------------------------------

### POST /tasks

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

Creates a new task within the system.

```APIDOC
## POST /tasks

### Description
Creates a new task and triggers a 'task:created' WebSocket event.

### Method
POST

### Endpoint
/tasks

### Parameters
#### Request Body
- **projectId** (string) - Required - Project UUID
- **title** (string) - Required - Task title (1-500 chars)
- **description** (string) - Optional - Task description
- **attachments** (array) - Optional - File attachments (max 10)
- **priority** (integer) - Optional - Priority level (0-5)
- **autoMode** (boolean) - Optional - Auto-advance through agent pipeline
- **isFix** (boolean) - Optional - Marks the task as fix-flow task
- **skipReview** (boolean) - Optional - Skip the review stage
- **paused** (boolean) - Optional - Pause agent processing
- **useSubagents** (boolean) - Optional - Run via custom subagents
- **roadmapAlias** (string) - Optional - Roadmap alias for grouping
- **tags** (string[]) - Optional - Tags for filtering/categorization

### Response
#### Success Response (201)
- **task** (object) - The created task object.
```

--------------------------------

### HTML for CREATE_TASK Action

Source: https://github.com/lee-to/aif-handoff/blob/main/docs/api.md

This HTML snippet represents a structured action emitted by the agent to create a task. The client parses this to display a confirmation card for user approval.

```html
<!--ACTION:CREATE_TASK-->
{"title": "Task title", "description": "Detailed description"}
<!--/ACTION-->
```

--------------------------------

### POST /tasks

Source: https://context7.com/lee-to/aif-handoff/llms.txt

Creates a new task in the backlog.

```APIDOC
## POST /tasks

### Description
Creates a new task in the backlog with configurable automation settings.

### Method
POST

### Endpoint
/tasks

### Request Body
- **projectId** (string) - Required - Project ID.
- **title** (string) - Required - Task title.
- **description** (string) - Optional - Task description.
- **priority** (number) - Optional - Priority level.
- **autoMode** (boolean) - Optional - Enable automation.
- **isFix** (boolean) - Optional - Is a bug fix.
- **skipReview** (boolean) - Optional - Skip review stage.
- **useSubagents** (boolean) - Optional - Use subagents.
- **tags** (array) - Optional - List of tags.

### Request Example
{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Add password reset functionality",
  "description": "Users should be able to reset their password via email",
  "priority": 2,
  "autoMode": true,
  "tags": ["feature", "auth", "email"]
}
```