Metadata-Version: 2.4
Name: claude-kanban
Version: 0.3.1
Summary: A real-time kanban dashboard for monitoring Claude Code/Codex sessions across multiple servers
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: flask>=3.1.3
Requires-Dist: paramiko>=4.0.0
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# Code Agent Kanban

A real-time web dashboard that monitors AI coding sessions across multiple servers (currently supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Codex), displaying them as a kanban board with AI-powered task summaries.

If you run coding agents on multiple machines simultaneously, it's easy to lose track of what each agent is doing. This tool SSHs into your servers, collects sessions, and presents them in a single unified view.

![Claude Code Agent Kanban Screenshot](screenshot.png)

## Features

- **Multi-server monitoring** — SSH into remote servers to collect session data in parallel
- **Live kanban board** — Sessions organized into Running / Completed / Errors columns
- **Multi-provider support** — Switch between `claude` and `codex` providers from Settings
- **AI-powered summaries** — Sessions are summarized by local CLI (`claude` or `codex`) with task description, progress status, and estimated completion percentage
- **Auto-refresh** — Dashboard updates automatically; fast-polls on first load to pick up AI summaries quickly
- **Session lifecycle tracking** — Sessions move from Running to Completed when the Claude Code process exits; resumed sessions move back to Running
- **Web-based configuration** — Add/edit/remove SSH servers and test connections from the Settings panel, no config files needed
- **Summary caching** — Summaries are cached on disk; unchanged sessions won't be re-summarized, even across restarts

## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) package manager
- For `claude` provider: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
- For `codex` provider: Codex CLI installed (`codex`)
- SSH key-based access to remote servers (for multi-server monitoring)

## Quick Start

### Install with uv (recommended)

```bash
uvx claude-kanban
```

### Install with pip

```bash
pip install claude-kanban
claude-kanban
```

### Run from source

```bash
git clone https://github.com/ShenJiahuan/claude-kanban.git
cd claude-kanban
uv run claude-kanban
```

Open http://localhost:5555 in your browser.

By default, it scans the local machine for Claude Code sessions. You can switch provider to Codex in **Settings**.

## How It Works

1. **Session discovery** — Scans provider-specific session logs (`~/.claude/...` or `~/.codex/...`) on each server
2. **Conversation parsing** — Extracts first task messages and latest progress messages from JSONL logs
3. **AI summarization** — Sends conversation excerpts (first 3 + last 6 messages) to local CLI (`claude -p` or `codex exec`)
4. **Lifecycle tracking** — Sessions move between Running and Completed based on activity/process state

## Configuration

All configuration is done through the web UI (**Settings** button). Under the hood, settings are persisted to `~/.claude-kanban/config.yaml`:

```yaml
include_local: true
provider: claude  # claude | codex
servers:
  - host: gpu-server-1.example.com
    user: ubuntu
    label: GPU Server 1
  - host: 10.0.0.50
    user: root
    port: 2222
    key: ~/.ssh/id_ed25519
    label: Dev Box
```

### Server options

| Field   | Required | Default          | Description                    |
|---------|----------|------------------|--------------------------------|
| `host`  | Yes      | —                | Hostname or IP                 |
| `user`  | No       | Current user     | SSH username                   |
| `port`  | No       | 22               | SSH port                       |
| `key`   | No       | `~/.ssh/id_rsa`  | Path to SSH private key        |
| `label` | No       | Same as host     | Display name on the dashboard  |

### Remote server requirements

- Python 3 installed
- For `claude` provider: Claude Code installed (sessions stored in `~/.claude/`)
- For `codex` provider: Codex installed (sessions stored in `~/.codex/`)
- SSH key-based authentication configured

### Environment variables

| Variable         | Default                        | Description               |
|------------------|--------------------------------|---------------------------|
| `KANBAN_CONFIG`  | `~/.claude-kanban/config.yaml` | Path to configuration file |
| `KANBAN_DATA_DIR`| `~/.claude-kanban`             | Data directory for config and summary cache |

## API

| Endpoint                         | Method | Description                          |
|----------------------------------|--------|--------------------------------------|
| `GET /api/sessions`              | GET    | Returns all sessions (cached 30s)    |
| `POST /api/refresh`              | POST   | Force refresh and return sessions    |
| `GET /api/servers`               | GET    | List configured servers              |
| `POST /api/servers`              | POST   | Add a server                         |
| `PUT /api/servers/<id>`          | PUT    | Update a server                      |
| `DELETE /api/servers/<id>`       | DELETE | Remove a server                      |
| `POST /api/servers/<id>/test`    | POST   | Test SSH connection                  |
| `PUT /api/config/local`          | PUT    | Toggle local machine scanning        |
| `PUT /api/config/provider`       | PUT    | Set provider (`claude` / `codex`)    |

## License

MIT
