sanban: Instructions file for Codex

AGENTS.md — Guidance for AI Agents

Project

sanban is a general-purpose kanban board with REST API + MCP server. JSON file storage, no database. Designed for solo devs and AI agents.

File Map

Task	File
Storage/CRUD	sanban/storage.py
REST API	sanban/rest.py (FastAPI)
MCP tools	sanban/mcp_server.py (FastMCP, stdio)
Entry point	sanban/server.py
Frontend	sanban/static/index.html
Board data	~/.sanban/boards/<id>.json
JSON schema	schema.json
Package config	pyproject.toml

API Base

http://localhost:8900/api

Common Tasks

Create a board

curl -X POST http://localhost:8900/api/boards \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-board"}'

Optional: pass columns to customize column names.

curl -X POST http://localhost:8900/api/boards \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-board","columns":["todo","doing","done"]}'

List boards

curl http://localhost:8900/api/boards

Get a board with items

curl http://localhost:8900/api/boards/<board_id>

Delete a board

curl -X DELETE http://localhost:8900/api/boards/<board_id>

Rename a board

curl -X PATCH http://localhost:8900/api/boards/<board_id> \
  -H 'Content-Type: application/json' \
  -d '{"name":"new-name"}'

Add an item

curl -X POST http://localhost:8900/api/boards/<board_id>/items \
  -H 'Content-Type: application/json' \
  -d '{"title":"Fix bug","priority":"high","effort":"S"}'

List items (with filters)

curl 'http://localhost:8900/api/boards/<board_id>/items?status=in_progress&q=bug&tag=urgent&assignee=alice'

Get a single item

curl http://localhost:8900/api/boards/<board_id>/items/<item_id>

Move an item

curl -X PATCH http://localhost:8900/api/boards/<board_id>/items/<item_id> \
  -H 'Content-Type: application/json' \
  -d '{"status":"done"}'