# hai

AI-orchestrated task board. Like Trello, but your tasks get specified, executed, and delivered by AI — powered by [pi](https://github.com/badlogic/pi-mono).

## Workflow

```
┌──────────┐    ┌──────────┐    ┌────────────┐    ┌───────────┐    ┌──────┐
│  Triage  │───▶│   Todo   │───▶│ In Progress│───▶│ In Review │───▶│ Done │
│          │    │          │    │            │    │           │    │      │
│ raw idea │    │ AI spec'd│    │ AI working │    │ ready to  │    │merged│
│          │    │ & ready  │    │ in worktree│    │   merge   │    │      │
└──────────┘    └──────────┘    └────────────┘    └───────────┘    └──────┘
    pi               ▲              pi                human
 specifies      deps gate        executes            reviews
```

1. **Triage** — Throw rough ideas in. Pi picks them up and writes a proper task spec.
2. **Todo** — Fully specified, ready to go. Scheduler moves them when deps are met.
3. **In Progress** — Pi works the task in an isolated git worktree.
4. **In Review** — Work is done. Merge the worktree and close. Toggle **Auto-merge** in the column header to automatically merge tasks as they arrive.
5. **Done** — Shipped.

Tasks with dependencies are processed sequentially. Independent tasks run in parallel.

## Quick Start

```bash
# Install dependencies
pnpm install

# Start the board (UI only)
pnpm dev dashboard

# Start with AI engine (auto-specify + auto-execute)
pnpm dev dashboard -- --engine

# Create a task via CLI
pnpm dev task create "Fix the login redirect bug"

# List tasks
pnpm dev task list

# Move a task
pnpm dev task move HAI-001 todo

# Attach a screenshot to a task
pnpm dev task attach HAI-001 ./screenshot.png
```

Then open [http://localhost:4040](http://localhost:4040).

## Prerequisites

The AI engine uses [pi](https://github.com/badlogic/pi-mono) agent sessions under the hood. You need:

1. **pi installed:** `npm install -g @mariozechner/pi-coding-agent`
2. **API key configured:** Run `pi` and use `/login` or set `ANTHROPIC_API_KEY`

hai reuses your existing pi authentication — no separate setup needed.

## Packages

| Package | Description |
|---------|-------------|
| `@hai/core` | Domain model — tasks, board columns, file-based store |
| `@hai/dashboard` | Web UI — Express server + kanban board with SSE |
| `@hai/engine` | AI engine — triage (pi), execution (pi + worktrees), scheduling |
| `hai` (cli) | CLI — `hai dashboard`, `hai task create/list/move/attach` |

## Architecture

### Task Storage

Tasks live on disk in `.hai/tasks/` in the project root:

```
.hai/
├── config.json              # Board config + ID counter
└── tasks/
    └── HAI-001/
        ├── task.json        # Metadata (column, deps, timestamps)
        ├── PROMPT.md        # Task specification
        └── attachments/     # Screenshot images (optional)
```

### Board UI

Real-time kanban board at `localhost:4040`:
- Drag-and-drop cards between columns
- Create tasks from the web UI
- Click cards for detail view with move/delete actions
- Server-Sent Events for live updates across tabs

### API Rate Limiting

All API endpoints (`/api/*`) are rate limited to prevent abuse. Limits are applied per client IP:

| Scope | Limit | Window |
|-------|-------|--------|
| General API (`/api/*`) | 100 requests | 1 minute |
| SSE connections (`/api/events`) | 10 connections | 1 minute |

Every API response includes standard rate limit headers:

| Header | Description |
|--------|-------------|
| `RateLimit-Limit` | Maximum requests allowed per window |
| `RateLimit-Remaining` | Requests remaining in the current window |
| `RateLimit-Reset` | Seconds until the rate limit window resets |
| `Retry-After` | Seconds to wait before retrying (only on 429 responses) |

When a client exceeds the limit, the API returns `429 Too Many Requests`.

### AI Engine (`--engine`)

When enabled, three components run:

- **TriageProcessor** — Watches triage column. Spawns a pi agent session that reads the project, understands context, and writes a full PROMPT.md specification. Moves task to todo.

- **Scheduler** — Watches todo column. Resolves dependency graphs. Moves tasks to in-progress when deps are satisfied and concurrency allows (default: 2 concurrent). When `groupOverlappingFiles` is enabled in settings, tasks whose `## File Scope` sections share files are serialized to prevent merge conflicts.

- **TaskExecutor** — Listens for tasks entering in-progress. Creates a git worktree, spawns a pi agent session with full coding tools scoped to the worktree, and executes the specification. Moves to in-review on completion.

Each pi agent session gets:
- Custom system prompt for its role (triage specifier vs task executor)
- Tools scoped to the correct directory (`createCodingTools(cwd)`)
- In-memory sessions (no persistence needed)
- The user's existing pi auth (API keys from `~/.pi/agent/auth.json`)

## Development

```bash
pnpm install
pnpm dev dashboard              # Board only
pnpm dev dashboard -- --engine  # Board + AI engine
pnpm dev task list              # CLI commands
```

## License

ISC