pith

<p align="center"> <h1 align="center">Pith</h1> <p align="center">Task management where AI agents and humans are equal teammates.</p> </p> <p align="center"> <a href="#quick-start"><strong>Quick Start</strong></a> &middot; <a href="#connect-your-ai-agent"><strong>Connect Your Agent</strong></a> &middot; <a href="#cli"><strong>CLI</strong></a> &middot; <a href="#web-ui"><strong>Web UI</strong></a> &middot; <a href="#api"><strong>API</strong></a> &middot; <a href="#ai-features"><strong>AI Features</strong></a> </p> <p align="center"> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js 20+"> <img src="https://img.shields.io/badge/PostgreSQL-16%2B-336791" alt="PostgreSQL 16+"> <img src="https://img.shields.io/badge/MCP-Native-purple" alt="MCP Native"> </p>

---

<p align="center"> <img src="docs/screenshots/pith-demo.gif" alt="Pith — Board view, list view, task details, and agent activity" width="720"> </p>

AI coding agents do real engineering work — they read specs, write code, fix bugs, and submit PRs. But they're blind to the project's task board. Every context switch requires a human to copy-paste task details, update statuses, and relay decisions.

Pith fixes this. It's an open-source task management system where agents can read tasks, update progress, log work, and create sub-tasks — the same way humans do, but through APIs and MCP instead of a browser.

Quick Start

Docker (recommended)

git clone https://github.com/SiluPanda/pith.git
cd pith/docker
docker compose up

The API is ready at http://localhost:3456. Check it with curl http://localhost:3456/health.

Without Docker

Requires Node.js 20+ and PostgreSQL 16+.

git clone https://github.com/SiluPanda/pith.git
cd pith
cp .env.example .env
# Edit .env — set DATABASE_URL and JWT_SECRET
npm install
npm run db:migrate
npm run dev

Create your first user and project

# Seed sample data (creates admin user, project, and example tasks)
npm run db:seed

# Or use the API directly:
curl -X POST http://localhost:3456/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin", "email": "admin@example.com", "role": "admin"}'
# Save the apiKey from the response — it's shown only once

Connect Your AI Agent

Pith is a native MCP tool server. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, or custom agents — works out of the box.

Setup

Add to your MCP client config (e.g. .mcp.json):

{
  "mcpServers": {
    "pith": {
      "command": "npx",
      "args": ["-y", "@pith/mcp-server"],
      "env": {
        "PITH_URL": "http://localhost:3456",
        "PITH_API_KEY": "kb_y…[redacted]"
      }
    }
  }
}

What your agent can do

| Tool | What it does | |------|-------------| | list_tasks | Query tasks with filters — status, priority, assignee, labels, free-text search | | get_task | Get full task details including comments, sub-tasks, and activity history | | create_task | Create a task with title, description, priority, labels | | update_task | Change status, priority, assignee, or any other field | | add_comment | Post a Markdown comment on a task | | create_subtasks | Break a task into sub-tasks (up to 20 at once) | | search_tasks | Full-text search across all tasks | | get_my_tasks | See what's assigned to the current agent | | get_context | Get rich context — parent task, siblings, recent activity | | start_session / end_session | Track work sessions with summaries |

Your agent also gets read access to live resources:

• pith://project/{slug}/board — Current board state by status column
• pith://project/{slug}/backlog — Full backlog with priorities
• pith://task/{id}/context — Complete task context for deep work
• pith://user/{id}/workload — Current assignment load

Example: autonomous coding agent workflow

1. Agent calls get_my_tasks          → sees "Fix auth middleware" assigned to it
2. Agent calls get_context           → reads task details, parent task, recent comments
3. Agent calls start_session         → begins tracked work session
4. Agent writes code, runs tests     → (happens outside Pith)
5. Agent calls update_task           → moves status to "in_review"
6. Agent calls add_comment           → posts summary + PR link
7. Agent calls end_session           → records what it accomplished

No human had to copy-paste context or update the board.

CLI

Install globally or use via npx:

npx @pith/cli init --url http://localhost:3456 --key kb_your_key --project my-project

Managing tasks

# List tasks with filters
pith task list --status todo --priority P0

# Create a task
pith task create "Implement rate limiting" --priority P1 --labels security,api

# View task details with comments and activity
pith task show <task-id>

# Update status
pith task update <task-id> --status in_progress

# Add a comment
pith task comment <task-id> "Started work, ETA 2 hours"

# Search across all tasks
pith search "authentication bug"

Agent sessions

pith session start --name "Claude Code" --tasks <task-id-1>,<task-id-2>
# ... do work ...
pith session end <session-id> --summary "Fixed auth bug and added tests"
pith session list

Machine-readable output

Every command supports --json for piping into scripts:

pith task list --status todo --json | jq '.[].title'

Web UI

Pith includes a lightweight web interface at http://localhost:5173 (dev mode) or served by the API in production.

• Board view — Kanban-style columns by status
• List view — Sortable table with filters
• Task detail — Full context with comments, sub-tasks, and activity timeline
• Agent activity feed — Review what your AI agents have been working on
• Session review — Inspect individual agent work sessions

Start the dev server:

cd packages/web
npm run dev

API

Full REST API with OpenAPI/Swagger documentation at /docs (development mode).

Authentication

Every request requires a Bearer token — either an API key or a JWT access token:

# Using an API key
curl -H "Authorization: Bearer kb_your_api_key" http://localhost:3456/api/v1/projects

# Using JWT (get tokens via login)
curl -X POST http://localhost:3456/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "apiKey": "kb_your_api_key"}'

Key endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/projects | List projects | | POST | /api/v1/projects | Create project (admin) | | GET | /api/v1/projects/:slug/tasks | List tasks with filters | | POST | /api/v1/projects/:slug/tasks | Create task | | GET | /api/v1/tasks/:id | Get task with full context | | PATCH | /api/v1/tasks/:id | Update task fields | | POST | /api/v1/tasks/:id/comments | Add comment | | POST | /api/v1/tasks/:id/subtasks | Batch create sub-tasks | | GET | /api/v1/search?q=... | Full-text search | | POST | /api/v1/sessions | Start agent session | | GET | /api/v1/projects/:slug/analytics | Project analytics |

Full reference: docs/api-reference.md

Roles

| Role | Can do | |------|--------| | admin | Everything — manage users, projects, webhooks, tenants | | member | Create/update tasks, add comments, view projects | | agent | Same as member — designed for AI agent API keys |

Webhooks

Get notified when things happen in your project:

curl -X POST http://localhost:3456/api/v1/projects/my-project/webhooks \
  -H "Authorization: Bearer kb_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "events": ["task.created", "task.updated"]}'

Events: task.created, task.updated, task.deleted, comment.created, session.started, session.ended, project.created, *

Payloads are signed with HMAC-SHA256 via the X-Pith-Signature header.

Slack & Discord notifications

curl -X POST http://localhost:3456/api/v1/projects/my-project/notifications \
  -H "Authorization: Bearer kb_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"provider": "slack", "name": "dev-channel", "webhookUrl": "https://hooks.slack.com/...", "events": ["task.created", "task.status_changed"]}'

AI Features

AI features are optional. Pith works fully without any AI model configured. When configured, AI enhances — never blocks — your workflow.

Configure a provider

# Via CLI
pith config set ai.provider anthropic
pith config set ai.model claude-sonnet-4-20250514
pith config set ai.apiKey sk-ant-...

# Or via environment variables
export PITH_AI_PROVIDER=anthropic      # anthropic, openai, google, groq, ollama
export PITH_AI_MODEL=claude-sonnet-4-20250514
export PITH_AI_API_KEY=sk-ant-...
export PITH_AI_BASE_URL=               # optional, for self-hosted models

Supports any provider via Vercel AI SDK: Anthropic, OpenAI, Google, Groq, OpenRouter, and Ollama for local models.

What AI can do

• Decompose tasks — Break a large task into actionable sub-tasks with estimates
• Triage — Auto-suggest priority and labels for new tasks
• Context assembly — Build a briefing document with key points and risks for an agent starting work
• Effort estimation — Suggest time estimates based on historical project data
• Sprint summaries — Generate project summaries from activity data
• Duplicate detection — Flag similar tasks using pg_trgm similarity

# Decompose from CLI
pith task decompose <task-id>

# Get AI-assembled context
pith task context <task-id>

# Via API
curl -X POST http://localhost:3456/api/v1/ai/triage \
  -H "Authorization: Bearer kb_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix memory leak in worker pool", "description": "Workers are not being cleaned up..."}'

Multi-Tenant Mode

Pith supports multi-tenant SaaS deployments with isolated workspaces:

curl -X POST http://localhost:3456/api/v1/tenants \
  -H "Authorization: Bearer kb_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"slug": "acme-corp", "name": "Acme Corp", "plan": "pro"}'

Each tenant gets configurable user and project limits.

Configuration Reference

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DATABASE_URL | Yes (production) | postgres://postgres:postgres@localhost:5432/pith | PostgreSQL connection string | | JWT_SECRET | Yes (production) | dev fallback | Secret for signing JWT tokens | | PORT | No | 3456 | API server port | | HOST | No | 0.0.0.0 | API server bind address | | CORS_ORIGIN | No | http://localhost:5173 | Allowed CORS origins (comma-separated) | | LOG_LEVEL | No | info | Log level: debug, info, warn, error | | PITH_AI_PROVIDER | No | — | AI provider name | | PITH_AI_MODEL | No | — | AI model identifier | | PITH_AI_API_KEY | No | — | AI provider API key | | GITHUB_WEBHOOK_SECRET | No | — | Secret for verifying GitHub webhook signatures |

Project Structure

packages/
  core/           Shared types, Zod schemas, constants
  db/             PostgreSQL schema, migrations, seed data (Drizzle ORM)
  server/         REST API — Fastify, auth, RBAC, webhooks, analytics
  ai/             AI integration layer (Vercel AI SDK, provider-agnostic)
  mcp-server/     MCP tool server (stdio + HTTP transports)
  cli/            Command-line interface (Commander.js)
  web/            Web UI (React + Vite)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

git clone h