Prism

The operating environment for AI agent pipelines

Agents create tasks, move them across a Kanban board, run multi-stage pipelines, and build up a shared knowledge base — all from a single interface you run locally or in Docker.

Getting started · Folio · Routing · CLI · MCP · Docs

What it does

Most Kanban tools are built for humans tracking human work. Prism is built for agents.

It runs on your machine against your own API key — not a SaaS, single operator, and not a replacement for Jira or Linear.

Folio — knowledge that grows with use

On every new task, agents normally start from zero: they re-discover the stack, re-read the same files, and ignore past decisions. Folio is a navigable, augmentable knowledge base shared between you and your agents that fixes this. The value is asymmetric over time — by the hundredth task the folio beats any static doc.

• Folio → Chapter → Page, stored as human-readable markdown you can browse and edit in the UI (and diff in git).
• Co-authored — both you and agents write pages; agent writes are tagged so you can filter and prune them.
• Stage-aware injection — relevant pages are pulled into each pipeline stage automatically, keyed on the task and the stage's role.
• Write-back — at the end of a run a single conservative step records a decision, a lesson, or a state update — only high-signal knowledge.
• Bootstrap from repo — on the first run in a git-backed space, the folio is seeded from the repo. Opt-in and lazy everywhere else.
• Domain-agnostic — neutral vocabulary works for code, on-call runbooks, research, or writing.

Agents reach Folio through its own MCP server (folio_search, folio_get_page, folio_create_page, …). See the .folio/ directory in this repo for the format itself — it is a working Folio describing Prism.

Agents & Routing — bring your own model

Prism doesn't just run pipelines on Claude. Every agent (senior-architect, developer-agent, code-reviewer, qa-engineer-e2e, …) has an independent CLI tool + model setting, resolved per stage in this order: task override → space override → global setting → the agent's own frontmatter default.

• Two CLI tools today: claude (Claude Code) and opencode — a model-agnostic coding CLI that can point at any OpenAI-compatible endpoint: local inference (e.g. vLLM on your own hardware), a self-hosted proxy, or a third-party provider.
• Configure it from the UI — the Agents & Routing panel (⚙ → Agents & Routing) lists every agent with its resolved model, source (global/space/task), and CLI tool, editable inline.
• Mix and match — keep the highest-stakes reasoning (architecture, irreversible decisions) on a frontier model while running implementation/QA stages on a local model, or vice versa.
• Isolated per run — regardless of which CLI a stage runs on, it still executes inside its own git worktree (see below), so a local model's mistakes never touch your working branch.

opencode isn't bundled in the Docker image (only Claude Code is pre-installed) — install and configure it yourself, then point Prism's routing config at your endpoint. See opencode's docs for provider setup.

Getting started

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/oscarmenendezgarcia/prism/main/install.sh | sh

This installs Node.js ≥ 20 if needed (via nvm), runs npm install -g prism-kanban, and runs prism init to create the data directory and a default settings.json.

curl -fsSL https://raw.githubusercontent.com/oscarmenendezgarcia/prism/main/install.sh | sh -s -- --data-dir /custom/path

Docker

docker compose up -d
# → http://localhost:3000

No Node.js or build tools required locally. Board data persists in ./data/prism.db. The image ships with Claude Code (claude) pre-installed for running pipelines.

The board works without an API key. To enable agent pipelines and auto-task generation, set ANTHROPIC_API_KEY:

ANTHROPIC_API_KEY=sk-... docker compose up -d

Agents that write code need files on disk. Mount each project as a volume in docker-compose.yml and point the Space's Working Directory at it:

services:
  prism:
    volumes:
      - ./data:/app/data                            # board state (already present)
      - /home/user/myproject:/workspace/myproject   # ← your repo

Or run Prism locally for native host filesystem access with no volume mapping.

npm (manual)

npm install -g prism-kanban
prism init           # create data dir + settings.json
prism start          # → http://localhost:3000

Full prerequisites, what prism init creates, and troubleshooting: docs/installation.md.

CLI

prism start          # start the server → http://localhost:3000
prism stop           # SIGTERM, wait up to 35 s for clean exit (--force for SIGKILL)
prism update         # update to the latest npm release
prism doctor         # verify runtime dependencies (--json for CI)
prism --help         # list all commands and flags

Common flags: --port <n> (env PORT), --data-dir <path> (env DATA_DIR), --silent, --no-update-check (env PRISM_NO_UPDATE_CHECK).

prism doctor checks Node version, the node-pty spawn-helper bit, better-sqlite3, the claude CLI, data-dir writability, and server status. Exit 0 if all pass, 1 otherwise; --json emits { ok, checks: [...] } for pipelines.

MCP — let your agent CLI drive Prism

Prism ships two MCP servers:

Prerequisite: the server (prism start or docker compose up) must be running before starting any agent session.

Registration is per CLI tool — an agent pipeline stage routed to opencode (see above) needs the prism MCP server registered in opencode's own config, separate from any Claude Code registration. Without it, that stage can't move tasks, leave comments, or attach artifacts, even though the model itself is running fine.

Claude Code — one-liner from the project root:

claude mcp add prism node ./mcp/mcp-server.js -e KANBAN_API_URL=http://localhost:3000/api/v1

Add to .claude/settings.json (or claude_desktop_config.json, using an absolute path):

{
  "mcpServers": {
    "prism": {
      "command": "node",
      "args": ["./mcp/mcp-server.js"],
      "env": { "KANBAN_API_URL": "http://localhost:3000/api/v1" }
    }
  }
}

{
  "mcp": {
    "prism": {
      "type": "local",
      "command": ["node", "/absolute/path/to/prism/mcp/mcp-server.js"],
      "environment": { "KANBAN_API_URL": "http://localhost:3000/api/v1" },
      "enabled": true
    }
  }
}

opencode requires an absolute path (no relative ./ shorthand) and its own node_modules installed under mcp/ — run cd mcp && npm install first if you haven't already.

Running locally (without Docker)

Prerequisites: Node.js ≥ 20 and native build tools for better-sqlite3 and node-pty — xcode-select --install (macOS), sudo apt install build-essential python3 (Linux), or npm install --global windows-build-tools (Windows).

npm install
cd frontend && npm install && npm run build && cd ..
cd mcp && npm install && cd ..
node server.js                 # → http://localhost:3000

Development mode with Vite HMR:

node server.js &
cd frontend && npm run dev     # → http://localhost:5173

Advanced

Parallel pipeline runs — git worktree isolation

Every run gets its own isolated git worktree — not just concurrent ones. A run must never mutate your main checkout: running in-place let a solo run switch the current branch, commit to the wrong branch, or clobber in-flight work.

• Each run gets its own worktree at .worktrees/run-<short-runId>, branched off HEAD as pipeline/run-<short-runId>.
• Fallback to in-place: a directory that isn't a git repo (or has a detached HEAD) can't be isolated — those runs work directly in the working directory, same as before this existed. If another run is already active in that same non-isolatable directory, the new run is rejected instead of racing it.
• Disable entirely with PIPELINE_WORKTREE_ENABLED=0 — every run then works in-place, at the race risk described above.
• Cleanup is automatic on terminal states (completed, failed, interrupted, aborted); orphans are reaped on the next startup.

The worktree path and branch are git-ignored and never committed.

Environment variables

DATA_DIR isn't a flat default — without an explicit override it's resolved in this order: (1) DATA_DIR env var if set; (2) <packageRoot>/data when running from a git checkout (has a .git directory — this repo, or a dev clone); (3) $XDG_DATA_HOME/prism if XDG_DATA_HOME is set; (4) ~/.local/share/prism otherwise. A global npm install -g prism-kanban install lands on (3) or (4), not ./data — the Docker image sets DATA_DIR=/app/data explicitly, which is why that path shows up there.

Tests

npm test                        # Backend (Node.js test runner)
cd frontend && npm test         # Frontend (Vitest + React Testing Library)

Stack — Node.js (no framework) · React 19 · TypeScript · Tailwind CSS v4 · Vite · Zustand · SQLite (better-sqlite3) · node-pty

MIT © Oscar Menendez · Support the project on Ko-fi