Pith

Task management where AI agents and humans are equal teammates.

Quick Start · Connect Your Agent · CLI · Web UI · API · AI Features

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_your_api_key_here"
      }
    }
  }
}

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 https://github.com/SiluPanda/pith.git
cd pith
npm install
npm run db:migrate
npm test            # 146 tests
npm run dev         # Start API server with hot reload

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github		.github
docker		docker
docs		docs
packages		packages
task		task
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pith-spec.md		pith-spec.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Pith

Quick Start

Docker (recommended)

Without Docker

Create your first user and project

Connect Your AI Agent

Setup

What your agent can do

Example: autonomous coding agent workflow

CLI

Managing tasks

Agent sessions

Machine-readable output

Web UI

API

Authentication

Key endpoints

Roles

Webhooks

Slack & Discord notifications

AI Features

Configure a provider

What AI can do

Multi-Tenant Mode

Configuration Reference

Environment variables

Project Structure

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages