pi-board

AI-first local task and sprint manager with a Kanban web UI. Manage tasks through conversational AI tools or a drag-and-drop board in your browser.

Installation

From npm

pi install npm:pi-board

From GitHub

pi install git:github.com/JPBallares/pi-board

From local path (development)

pi install /path/to/pi-board

Quick Start

1. Install the package (see above).

2. Start the board server:

   /board

   This opens http://localhost:3333 in your default browser.

3. Create your first sprint and tasks via AI or the web UI.

Web UI

Open the Kanban board with /board or visit http://localhost:3333.

Features

• Kanban columns: Backlog → In Progress → Code Review → UAT → Completed
• Drag & drop: Move tasks between columns; changes persist immediately
• Mobile fallback: Tap the ⋯ menu on any card to move it without drag-and-drop
• Task detail modal: Click any card to view and edit all fields inline
• Search: Filter tasks by title or description (submit-based)
• Filters: Filter by sprint, assignee, or label
• Active sprint quick button: One-click filter to the currently active sprint
• Sort: By priority, order, or creation date — preference saved to localStorage
• Labels: Create colored labels and attach them to tasks
• People: Create assignees with colors; assign during task creation or editing
• Sprints: Only one active sprint at a time; completing a sprint moves all its tasks to Completed
• Auto-refresh: Board updates every 5 seconds when no modal is open
• Keyboard shortcuts:
  • N — New task
  • E — Edit open task
  • D — Delete open task
  • Esc — Close modal
  • ? — Show shortcuts help
• Collapsible columns: Click ▾/▸ to collapse/expand columns; state persists in localStorage
• WIP limits: Set max tasks per column; visual warning when exceeded
• Markdown descriptions: Task descriptions render as Markdown in the detail view
• Overdue notifications: Toast warning when tasks are past their due date
• Stats modal: Burndown chart for the active sprint and assignee workload table
• Export / Import: Download full board as JSON, export filtered tasks as CSV, or restore from JSON

AI Tools

Task Management

| Tool | Description | |------|-------------| | board_create_task | Create a new task. Supports title, description, type, priority, status, sprint, assignee, labels, due date, estimate, and dependencies. Auto-assigns to the active sprint if none specified. | | board_update_task | Update any task field by ID. Can reassign, change status, update labels, dependencies, etc. | | board_list_tasks | List tasks with optional filters (sprint, status, assignee, labels, search, archived) and sorting. | | board_get_task | Get full details of a single task including labels, assignee, dependencies, subtasks, activity, and comments. | | board_delete_task | Delete a task by ID. | | board_duplicate_task | Duplicate a task by ID (creates a copy in Backlog). | | board_move_task | Move a task to a different status column and/or order. |

Sprint Management

| Tool | Description | |------|-------------| | board_create_sprint | Create a new sprint with start and end dates. Automatically activates it and completes the previous active sprint. | | board_complete_sprint | Complete a sprint by ID. All tasks in that sprint are moved to the Completed column. | | board_incomplete_sprint | Reactivate a completed sprint. | | board_get_sprint | Get a single sprint by ID. | | board_update_sprint | Update sprint name, start date, or end date. | | board_delete_sprint | Delete a sprint by ID (fails if tasks are assigned). | | board_archive_sprint_tasks | Archive all completed tasks in a sprint. | | board_get_sprint_stats | Get sprint statistics: total/completed tasks, completion %, story points breakdown. | | board_get_sprint_burndown | Get daily completion data for burndown analysis. |

Labels

| Tool | Description | |------|-------------| | board_create_label | Create a colored label (e.g., "urgent", "frontend"). | | board_list_labels | List all available labels. | | board_update_label | Update a label's name or color by ID. | | board_delete_label | Delete a label by ID. |

People

| Tool | Description | |------|-------------| | board_create_person | Create a person (assignee) with a color. | | board_list_people | List all people. | | board_update_person | Update a person's name or color by ID. | | board_delete_person | Delete a person by ID (unassigns their tasks). |

Subtasks

| Tool | Description | |------|-------------| | board_add_subtask | Add a subtask to a task. | | board_toggle_subtask | Toggle a subtask's completion status. | | board_update_subtask | Update a subtask title or order. | | board_delete_subtask | Delete a subtask by ID. |

Comments

| Tool | Description | |------|-------------| | board_add_comment | Add a comment to a task. | | board_list_comments | List all comments on a task. | | board_delete_comment | Delete a comment by ID. |

Column Settings

| Tool | Description | |------|-------------| | board_list_column_settings | List WIP limits for all columns. | | board_set_column_wip_limit | Set the WIP limit for a column/status. |

Reporting

| Tool | Description | |------|-------------| | board_get_sprint_stats | Get sprint statistics (tasks, completion %, estimates). | | board_get_sprint_burndown | Get burndown data for a sprint. | | board_get_workload | Get assignee workload overview (task count, total points). |

Export / Import

| Tool | Description | |------|-------------| | board_export_json | Export all board data to JSON. | | board_import_json | Import board data from JSON (replaces all existing data). |

Commands

| Command | Description | |---------|-------------| | /board | Start the web UI server and open it in your browser. |

Data Model

Task

• title, description (supports Markdown rendering)
• type: bug | feature | chore
• status: backlog | in-progress | code-review | uat | completed
• priority: urgent | high | medium | low
• order: display order within a column
• sprint_id, assignee_id
• due_date: optional deadline (YYYY-MM-DD)
• estimate: optional story points (integer)
• archived: boolean, hidden from board by default
• labels: many-to-many colored labels
• depends_on: task dependencies (many-to-many, with cycle detection)
• subtasks: checklist items with completion tracking
• activity: audit log of create/update/move/delete operations
• comments: threaded comments on tasks

Sprint

• name, start_date, end_date
• status: active | completed
• Only one sprint may be active at a time

Label

• name, color (hex)

Person

• name, color (hex)

Column Settings

• status, wip_limit: optional max tasks per column

Storage

All data is stored locally in an SQLite database at .pi/board.db. No remote services are used.

Database migrations run automatically on startup to add new columns and tables without breaking existing data.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PI_BOARD_PORT | Port for the web UI server | 3333 |