AIPIM

    ▄▄█▄▄      █████╗ ██╗██████╗ ██╗███╗   ███╗
  ▀▀▀███▀▀▀   ██╔══██╗██║██╔══██╗██║████╗ ████║
     ███      ███████║██║██████╔╝██║██╔████╔██║
   ▄█████▄    ██╔══██║██║██╔═══╝ ██║██║╚██╔╝██║
  ▐███████▌   ██║  ██║██║██║     ██║██║ ╚═╝ ██║
   ▀█████▀    ╚═╝  ╚═╝╚═╝╚═╝     ╚═╝╚═╝     ╚═╝
     ▀█▀      ═════════════════════════════════

Artificial Intelligence Project Instruction Manager — event-sourced project management with MCP server.

What it is

AIPIM 2.x is a project manager built around an append-only event log. All state (tasks, comments, decisions, assignments) derives from events.jsonl. A SQLite database is rebuilt from those events at startup and used as a fast read model.

An MCP server (Model Context Protocol) exposes tools that Claude Code calls directly — no copy-paste, no clipboard workflow. A REST API serves the same data for the Svelte UI.

Architecture

events.jsonl  ──rebuild──▶  SQLite (read model)
                                  │
                    ┌─────────────┴──────────────┐
                    ▼                            ▼
              MCP server                    REST API
           (Claude Code)          (/api/* + /ui/* + SSE)
                                            │
                                       Svelte UI
                                  (Kanban · Timeline
                                   Task detail · Stats)

All writes go through appendEvent() → applyEvent(). The database is never written to directly.

Quick Start

# Install globally
pnpm install -g aipim

# Initialize in your project
cd my-project
aipim install

# Start the MCP server (default port 3141)
aipim mcp start

# Register with Claude Code
claude mcp add --transport http aipim http://localhost:3141/mcp

# Open the visual UI
aipim ui
# Note: aipim ui already runs aipim mcp start, you don't need to use both

Claude Code will now call AIPIM tools directly. No session prompts, no file pasting. Open the UI at http://localhost:3141/ui/ for a visual Kanban board, event timeline, and task detail panel.

If you are migrating from AIPIM 1.x:

aipim migrate   # reads backlog/*.md and completed/*.md → events.jsonl + SQLite

Commands

aipim install

Scaffolds .project/ in the current directory. Generates CLAUDE.md (or GEMINI.md, CURSOR.md) from templates. Configures .gitattributes for union merge on events.jsonl.

aipim install [--ai claude-code|gemini|cursor] [--guidelines react|astro|...] [--dry-run]

aipim mcp start

Runs migrate → rebuild → starts Hono server.

aipim mcp start [--port 3141] [--project /path/to/project]

Endpoints:

• POST /mcp — JSON-RPC 2.0 for Claude Code
• GET /api/tasks — task list with optional filters (status, assignee, priority)
• GET /api/tasks/:id — task + markdown content + comments
• GET /api/tasks/:id/events — events related to a specific task
• PUT /api/tasks/:id/content — overwrite the task's .md file
• POST /api/events — write an event
• GET /api/events — paginated history (limit max 500, offset)
• GET /api/events/stream — SSE real-time feed
• GET /api/stats — task counts by status
• GET /api/team — team members from config.toml
• GET /api/decisions — ADRs
• GET /ui/* — Svelte UI (served from ui/dist/ when built)

aipim ui

Starts the server and opens the Svelte UI in the browser.

aipim ui [--port 3141] [--project /path] [--open] [--dev]

| View | URL | Description | |------|-----|-------------| | Dashboard | /ui/ | Stats overview + in-progress tasks | | Kanban | /ui/kanban | Columns by status, HTML5 drag-and-drop | | Timeline | /ui/timeline | Chronological event log with filters | | Task detail | /ui/task/:id | Markdown content, editor, comments, history |

In production (aipim ui), static files from ui/dist/ are served by Hono at /ui/*. In development (aipim ui --dev), Vite runs on port 5173 and proxies /api to Hono.

aipim task

aipim task next              # show highest-priority backlog task
aipim task init <type> <name>  # create a new task file

Priority order: P1-S > P1-M > P1-L > P2-S > P2-M > P2-L > P3, oldest first on tie.

aipim team

aipim team list        # list members from .project/config.toml
aipim team whoami      # resolve current actor (AIPIM_USER → git email → member id)
aipim team add         # interactive wizard to add a member
aipim team setup-git   # configure .gitattributes with union merge for events.jsonl

aipim list skills

Lists all built-in context skills available to inject.

aipim list skills

Available Skills:

  pest            Pest PHP
                  Best practices for the Pest PHP testing framework

  tailwind        TailwindCSS v4
                  Maintainable utility-first class management guidelines

  typescript      Strict TypeScript
                  Strict TypeScript rules banning any and enforcing explicit returns

  laravel         Laravel
  react           React
  vue             Vue 3
  rest-api        REST API Design
  php             Modern PHP
  security        Secure Coding
  vitest          Vitest / Jest
  svelte          Svelte 5
  python          Python
  rust            Rust
  langchain       LangChain / LangGraph
  django          Django
  fastapi         FastAPI
  docker          Docker
  prisma          Prisma ORM
  nextjs          Next.js App Router

aipim add skill <name>

Injects a skill's guidelines into CLAUDE.md or GEMINI.md (standard mode), or into .ai/guidelines/skill-<name>.blade.php (Laravel Boost mode). The operation is idempotent — running it twice does not duplicate the content.

aipim add skill typescript
aipim add skill react
aipim add skill security

The skill block is inserted inside the {{SLOT:guidelines}} … {{/SLOT:guidelines}} marker in your AI instruction file and the file signature is recalculated automatically.

aipim migrate

One-time migration from AIPIM 1.x. Reads .project/backlog/*.md and .project/completed/*.md, generates synthetic events, rebuilds SQLite.

aipim update

Updates scaffolded files (templates, scripts) without overwriting customizations.

aipim validate

Checks directory structure, script permissions, and file signatures.

Skills

AIPIM has two complementary skill systems:

Context Modules (aipim add skill)

Inject focused coding guidelines directly into your AI instruction file (CLAUDE.md, GEMINI.md, or .ai/guidelines/ for Laravel Boost projects). These become part of the model's context on every session — no need to re-explain conventions.

19 built-in skills cover: pest, tailwind, typescript, laravel, react, vue, rest-api, php, security, vitest, svelte, python, rust, langchain, django, fastapi, docker, prisma, nextjs.

See docs/skills-context.md for details.

Active Skills (MCP Tools)

Dynamic MCP tools that are enabled per-project via active_skills in .project/config.toml. They are merged with the core tools at runtime — no server restart needed.

[project]
name = "MyApp"
active_skills = ["database"]

Currently available:

| Skill | Tools enabled | Description | |-------|--------------|-------------| | database | aipim_db_schema, aipim_db_query | Read-only access to any local SQLite database |

aipim_db_schema returns the full table/column structure of a .db file. aipim_db_query executes SELECT/EXPLAIN/PRAGMA statements — write operations are blocked at the driver level.

See docs/skills-mcp.md for details.

MCP Tools

Claude Code has access to these tools via the MCP server:

| Tool | Description | |------|-------------| | get_project_context | Project name, stats, active blockers, recent decisions | | get_next_task | Highest-priority backlog task | | list_tasks | All tasks with optional status/assignee/priority filter | | get_task | Single task with comments and full detail | | get_blockers | All blocked tasks | | create_task | Add a task to the backlog | | complete_task | Mark done, move .md to completed/ | | update_task_status | Change status (backlog → in-progress → review → blocked) | | assign_task | Assign to a team member from config.toml | | add_comment | Append a comment (immutable) | | log_decision | Write an ADR to decisions/ |

Additional tools are injected dynamically based on active_skills — see Skills above.

Team Configuration

.project/config.toml is optional. Without it, AIPIM works as a solo-dev setup (actor = git email).

[project]
name = "MyApp"
description = "..."
active_skills = ["database"]  # optional — see Skills section

[[team]]
id = "alice"
name = "Alice Smith"
email = "alice@example.com"
role = "tech-lead"
areas = ["backend", "architecture"]

Actor resolution order: AIPIM_USER env → git user.email matched to a team member id → raw email → "unknown".

.project/ Structure

.project/
├── events.jsonl     # append-only event log (source of truth)
├── data.db          # SQLite (derived, gitignored)
├── config.toml      # project + team configuration
├── context.md       # session state for the AI
├── current-task.md  # active task checklist
├── backlog/         # YYYY-MM-DD-TASK-NNN-name.md
├── completed/       # archived tasks
├── decisions/       # ADRs
├── _templates/      # task, context, adr templates
└── scripts/         # validate-dod.sh, pre-session.sh, ...

events.jsonl uses merge=union git driver so concurrent team