# Pith

> AI-native task management for humans & agents. MCP-first, CLI-native, self-hosted. Bring your own model.

- **Type:** MCP server
- **Install:** `agentstack add mcp-silupanda-pith`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SiluPanda](https://agentstack.voostack.com/s/silupanda)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SiluPanda](https://github.com/SiluPanda)
- **Source:** https://github.com/SiluPanda/pith

## Install

```sh
agentstack add mcp-silupanda-pith
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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)

```bash
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+.

```bash
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

```bash
# 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](https://modelcontextprotocol.io/) 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`):

```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:

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

### Managing tasks

```bash
# 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 

# Update status
pith task update  --status in_progress

# Add a comment
pith task comment  "Started work, ETA 2 hours"

# Search across all tasks
pith search "authentication bug"
```

### Agent sessions

```bash
pith session start --name "Claude Code" --tasks ,
# ... do work ...
pith session end  --summary "Fixed auth bug and added tests"
pith session list
```

### Machine-readable output

Every command supports `--json` for piping into scripts:

```bash
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:

```bash
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:

```bash
# 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](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:

```bash
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

```bash
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

```bash
# 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

```bash
# Decompose from CLI
pith task decompose 

# Get AI-assembled context
pith task context 

# 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:

```bash
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](CONTRIBUTING.md) for development setup and guidelines.

```bash
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](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SiluPanda](https://github.com/SiluPanda)
- **Source:** [SiluPanda/pith](https://github.com/SiluPanda/pith)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-silupanda-pith
- Seller: https://agentstack.voostack.com/s/silupanda
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.