Metadata-Version: 2.4
Name: oh-my-kanban
Version: 0.1.4
Summary: Multi-platform project management CLI for AI agents — Plane, Linear, and more
Author-email: ej31 <ej31@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ej31/oh-my-kanban
Project-URL: Repository, https://github.com/ej31/oh-my-kanban
Project-URL: Issues, https://github.com/ej31/oh-my-kanban/issues
Keywords: cli,kanban,project-management,plane,linear,ai-agent,automation,devtools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plane-sdk<1.0,>=0.2.6
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: httpx>=0.28.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Dynamic: license-file

# oh-my-kanban

| [한국어](docs/README_kr.md) | [ENGLISH](docs/README_en.md) |
|---|---|

> Multi-platform project management CLI — built for AI agents first, humans second.

[![PyPI version](https://badge.fury.io/py/oh-my-kanban.svg)](https://pypi.org/project/oh-my-kanban/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-ej31%2Foh--my--kanban-black)](https://github.com/ej31/oh-my-kanban)

## Why oh-my-kanban?

oh-my-kanban is a lightweight CLI designed for **AI agent automation workflows**.

- **Zero-interaction mode** — Full automation via environment variables
- **Machine-readable output** — JSON format for agent pipeline integration
- **Broad Plane coverage** — Work items, cycles, modules, milestones, intake, pages, initiatives, teamspaces, stickies, and more (Community Edition free tier priority)
- **Multi-workspace support** — Profile-based management of multiple environments
- **Self-hosted friendly** — Built and tested on Plane Community Edition (free, self-hosted)

## Installation

### PyPI

```bash
pip install oh-my-kanban
```

### From Source

```bash
git clone https://github.com/ej31/oh-my-kanban.git
cd oh-my-kanban
pip install -e .
```

## Quick Start

### Step 1: Initialize Configuration (Interactive)

```bash
omk config init
```

Provide the following information:

- **Server type**: plane.so cloud or self-hosted
- **API key**: [Generate API token](https://app.plane.so/profile/api-tokens/)
- **Workspace slug**: Extract from URL or enter directly

### Step 2: Agent Mode (Environment Variable Automation)

For unattended automation with AI agents:

```bash
export PLANE_API_KEY="pl_xxxxxxxxxx"
export PLANE_WORKSPACE_SLUG="my-workspace"
export PLANE_PROJECT_ID="your-project-id"  # required for project-scoped commands
export PLANE_BASE_URL="https://api.plane.so"  # or self-hosted URL

# Full automation via environment variables
omk plane work-item list -o json
omk plane cycle create --name "Sprint 1" --start-date "2024-03-06" --end-date "2024-03-20"
omk plane work-item create --name "Fix login bug" --state-id "..."
```

### Step 3: Interactive Mode (Human Usage)

```bash
# Use default profile
omk config show
omk plane work-item list

# Use specific profile
omk --profile production plane work-item list -o table
```

## Configuration

### Configuration File Location

```text
~/.config/oh-my-kanban/config.toml
```

### Profile-Based Multi-Workspace Management

```toml
[default]
base_url = "https://api.plane.so"
api_key = "pl_xxxxx"
workspace_slug = "my-workspace"
output = "table"

[production]
base_url = "https://plane.example.com"
api_key = "pl_yyyyy"
workspace_slug = "prod-workspace"
output = "json"
```

Usage:

```bash
omk --profile production plane work-item list
```

### Environment Variable Priority

Command-line options > Environment variables > Configuration file > Defaults

```bash
# Override via environment variable
PLANE_API_KEY="pl_xxxxxx" omk config show
PLANE_WORKSPACE_SLUG="override-ws" omk plane work-item list
```

### Configuration Management Commands

```bash
# Initialize configuration (interactive)
omk config init

# Display current configuration (API key masked)
omk config show

# Set specific value
omk config set workspace_slug my-new-workspace
omk config set output json

# List profiles
omk config profile list

# Change default profile
omk config profile use production
```

## Command Reference

### Global Options

```bash
omk [OPTIONS] PROVIDER [PROVIDER_OPTIONS] COMMAND [ARGS]
```

| Option | Environment Variable | Description |
|--------|----------------------|-------------|
| `--workspace, -w SLUG` | `PLANE_WORKSPACE_SLUG` | Workspace slug |
| `--project, -p ID` | `PLANE_PROJECT_ID` | Project UUID |
| `--output, -o FORMAT` | - | Output format: `table` \| `json` \| `plain` (default: `table`) |
| `--profile PROFILE` | `PLANE_PROFILE` | Configuration profile (default: `default`) |
| `--version` | - | Show version |

### Provider Subgroups

omk separates commands by provider:
- `omk plane` (or `omk pl`) — Plane project management
- `omk linear` (or `omk ln`) — Linear project management
- `omk github` (or `omk gh`) — GitHub project management (coming soon)
- `omk config` — Configuration management (provider-independent)

### Command Reference

#### omk config — Configuration Management (provider-independent)

```bash
omk config init                              # Initialize configuration (interactive)
omk config show [--profile PROFILE]          # Display current configuration
omk config set KEY VALUE [--profile PROFILE] # Change setting value
omk config profile list                      # List profiles
omk config profile use NAME                  # Change default profile
```

#### omk plane (or omk pl) — Plane Project Management

##### work-item — Work Items

```bash
# List work items
omk plane work-item list [--all] [--per-page N] [--cursor CURSOR] [--priority PRIORITY]

# Get work item details
omk plane work-item get ITEM_ID_OR_IDENTIFIER

# Create work item
omk plane work-item create --name NAME [--state STATE_ID] [--priority PRIORITY] [--description DESC] [--assignee USER_ID]

# Update work item
omk plane work-item update ITEM_ID [--name NAME] [--state STATE_ID] [--priority PRIORITY]

# Delete work item
omk plane work-item delete ITEM_ID [--force]

# Search work items
omk plane work-item search --query QUERY

# Manage relationships
omk plane work-item relation create ITEM_ID --related-work-item ITEM_ID2 --relation-type blocking
omk plane work-item relation list ITEM_ID
omk plane work-item relation delete ITEM_ID --related-work-item ITEM_ID2
```

##### cycle — Cycles/Sprints

```bash
omk plane cycle list [--all]
omk plane cycle create --name NAME [--start-date DATE] [--end-date DATE]
omk plane cycle get CYCLE_ID
omk plane cycle update CYCLE_ID [--name NAME] [--start-date DATE] [--end-date DATE]
omk plane cycle delete CYCLE_ID
omk plane cycle items CYCLE_ID
omk plane cycle add-items CYCLE_ID --items ITEM1 --items ITEM2
omk plane cycle remove-item CYCLE_ID ITEM_ID
```

##### module — Modules

```bash
omk plane module list [--all]
omk plane module create --name NAME [--status STATUS] [--start-date DATE] [--target-date DATE]
omk plane module get MODULE_ID
omk plane module update MODULE_ID [--name NAME] [--status STATUS]
omk plane module delete MODULE_ID
omk plane module items MODULE_ID
omk plane module add-items MODULE_ID --items ITEM1 --items ITEM2
```

##### Other Commands

```bash
omk plane user me                               # Get current user info
omk plane project list [--all]                   # List projects
omk plane state list                             # List states
omk plane label list [--all]                     # List labels
omk plane label create --name NAME [--color HEX] # Create label

omk plane milestone list                         # List milestones
omk plane epic list                              # List epics (list/get only)
omk plane epic get EPIC_ID                       # Get epic details
omk plane page get PAGE_ID                       # Get page (get/create only)
omk plane page create --name NAME [--workspace]  # Create page (project or workspace scope)
omk plane intake list                            # List intake requests

omk plane workspace members                      # List workspace members
omk plane workspace features                     # List workspace features
omk plane teamspace list                         # List teamspaces
omk plane initiative list                        # List initiatives
omk plane sticky list                            # List stickies
omk plane customer list                          # List customers (Enterprise)

omk plane work-item-type list                    # List work item types
omk plane work-item-property list --type TYPE_ID # List custom properties
```

#### omk linear (or omk ln) — Linear Project Management

Set `LINEAR_API_KEY` before use. Optionally set `LINEAR_TEAM_ID` as a default team.

```bash
omk linear me                                          # Current user info
omk linear team list                                   # List teams
omk linear team get TEAM_ID

omk linear issue list [--team TEAM_ID] [--first N]
omk linear issue get ISSUE_ID_OR_KEY                   # UUID or KEY-123 format
omk linear issue create --title TITLE --team TEAM_ID [--priority 0-4] [--state STATE_ID]
omk linear issue update ISSUE_ID [--title TITLE] [--priority 0-4] [--state STATE_ID] [--assignee USER_ID] [--description DESC]
omk linear issue delete ISSUE_ID

omk linear issue comment list ISSUE_ID
omk linear issue comment create ISSUE_ID --body "Comment text"

omk linear state list [--team TEAM_ID]                 # Workflow states
omk linear label list [--team TEAM_ID]                 # Labels
omk linear label get LABEL_ID

omk linear project list [--first N]                    # Projects
omk linear project get PROJECT_ID

omk linear cycle list [--team TEAM_ID]                 # Cycles
omk linear cycle get CYCLE_ID
```

Priority: `0`=none, `1`=urgent, `2`=high, `3`=medium, `4`=low

#### omk github (or omk gh) — GitHub Project Management (coming soon)

```bash
omk github issue list --owner OWNER --repo REPO
omk github project list --owner OWNER
```

**Coming soon.**

## Output Formats / 출력 형식

### Table (Default)

```bash
omk plane work-item list
```

```text
ID                                    NAME           PRIORITY  STATE      ASSIGNEES
12345678-90ab-cdef-1234-567890abcdef  Fix login bug  high      In Progress  alice
87654321-abcd-ef12-3456-7890abcdef12  Add dark mode  medium    To Do      bob, charlie
```

### JSON (Agent Automation)

```bash
omk plane work-item list -o json
```

```json
{
  "data": [
    {
      "id": "12345678-90ab-cdef-1234-567890abcdef",
      "name": "Fix login bug",
      "priority": "high",
      "state": "In Progress",
      "assignees": ["alice"],
      "state_id": "state_uuid_1",
      "project_id": "proj_uuid_1"
    }
  ],
  "pagination": {
    "cursor": "next_cursor_token",
    "has_more": true
  }
}
```

### Plain (Script Parsing)

```bash
omk plane work-item list -o plain
```

```text
12345678-90ab-cdef-1234-567890abcdef|Fix login bug|high|In Progress|alice
87654321-abcd-ef12-3456-7890abcdef12|Add dark mode|medium|To Do|bob,charlie
```

## Server Compatibility

> Development target: **Plane Community Edition (free, self-hosted)**
> Free-tier features are implemented first. Enterprise-only features are out of scope.

### Plane

| Feature | Implemented | plane.so | Self-hosted CE | Notes |
|---------|:-----------:|:--------:|:--------------:|-------|
| Work Items (CRUD) | ✅ | ✅ | ✅ | Comments, links, activities, attachments included |
| Work Item Relations | ✅ | ✅ | ❌ | plane.so & Enterprise only; not available on CE |
| Work Item Worklogs | ✅ | ✅ | ❌ | plane.so & Enterprise only; not available on CE |
| Cycles (CRUD) | ✅ | ✅ | ✅ | Includes item add/remove |
| Modules (CRUD) | ✅ | ✅ | ✅ | Includes item add |
| Milestones (CRUD) | ✅ | ✅ | ✅ | Includes item add/remove |
| Intake (CRUD) | ✅ | ✅ | ✅ | Includes approve/reject |
| Initiatives (CRUD) | ✅ | ✅ | ✅ | Includes epics, labels, projects |
| Teamspaces (CRUD) | ✅ | ✅ | ✅ | Includes members, projects |
| Stickies (CRUD) | ✅ | ✅ | ✅ | - |
| Work Item Types (CRUD) | ✅ | ✅ | ✅ | - |
| Custom Properties (CRUD) | ✅ | ✅ | ✅ | Includes options and values |
| Users / Members | ✅ | ✅ | ✅ | me, workspace members |
| Project Pages | ⚠️ | ✅ | ✅ | get and create only |
| Workspace Pages | ⚠️ | ✅ | ❌ | Enterprise only on self-hosted CE |
| Epics | ⚠️ | ✅ | ✅ | list and get only |
| States | ⚠️ | ✅ | ✅ | list only |
| Labels | ⚠️ | ✅ | ✅ | list and create only |
| Projects | ⚠️ | ✅ | ✅ | list only |
| Workspace Features | ⚠️ | ✅ | ✅ | list only (read-only) |
| Customers (CRUD) | ✅ | ✅ | ❌ | Enterprise only (not available on CE) |

#### Partial Implementation Reasons

| Feature | Missing | Reason |
|---------|---------|--------|
| Project Pages | list, update, delete | Not supported by the Plane Python SDK |
| Workspace Pages | list, update, delete | Not supported by the Plane Python SDK; Enterprise only on CE |
| Epics | create, update, delete | Epic is a special case of Work Item Type; Epic CRUD API is limited in CE |
| States | create, update, delete | System resource managed in project settings; low automation demand for mutations |
| Labels | get, update, delete | Low automation demand for label mutations |
| Projects | create, update, delete | Admin-level operation; considered out of scope for CLI automation |

### Linear

| Feature | Implemented | Notes |
|---------|:-----------:|-------|
| Issues (CRUD) | ✅ | Includes comments |
| Teams | ✅ | list, get |
| States | ✅ | list |
| Labels | ✅ | list, get |
| Projects | ✅ | list, get |
| Cycles | ✅ | list, get |
| Users | ✅ | me |

### GitHub

| Feature | Implemented | Notes |
|---------|:-----------:|-------|
| Issues | ❌ | Coming soon |
| Projects | ❌ | Coming soon |

> GitHub integration is currently a stub. Requires GitHub REST API client integration.

### Notion / Jira

| Feature | Implemented | Notes |
|---------|:-----------:|-------|
| Notion | ❌ | Not started |
| Jira | ❌ | Not started |

## Session Tracking

### Automatic Context Recovery After `/compact`

When Claude Code restarts after a `/compact` command execution, oh-my-kanban automatically recovers your session context through the `SessionStart(compact)` hook.

**Recovered Context:**

- Session objective summary
- Key topics and list of modified files
- Request count and warning statistics
- Plane Work Item details (title, description, recent comments)

The hook automatically fetches Plane WI metadata from the API, so Claude doesn't need to re-query task contents after `/compact`.

**Limitations:**

- Maximum 3 Work Items retrieved
- Total context limit: 3,000 characters
  - Per WI description: 600 characters
  - Per WI comments (up to 5): 300 characters

## Examples

### Example 1: Agent Pipeline — Create Cycle → Create Work Item → Assign

```bash
#!/bin/bash

export PLANE_API_KEY="pl_xxxxxx"
export PLANE_WORKSPACE_SLUG="my-workspace"
export PLANE_PROJECT_ID="proj_uuid"

# 1. Create cycle (ownership is derived automatically from the authenticated user)
CYCLE_ID=$(omk plane cycle create \
  --name "Sprint 1" \
  --start-date "2024-03-06" \
  --end-date "2024-03-20" \
  -o json | jq -r '.data.id')

echo "Created cycle: $CYCLE_ID"

# 2. Create work item
ITEM_ID=$(omk plane work-item create \
  --name "Fix critical bug" \
  --priority high \
  --state-id "$STATE_ID" \
  -o json | jq -r '.data.id')

echo "Created work item: $ITEM_ID"

# 3. Add work item to cycle
omk plane cycle add-items "$CYCLE_ID" --items "$ITEM_ID"

# 4. Assign to user
omk plane work-item update "$ITEM_ID" --assignees "$ASSIGNEE_USER_ID"

echo "Done!"
```

### Example 2: Multi-Workspace Management

```bash
# Fetch work items from production
omk --profile production plane work-item list

# Create work item in development
omk --profile development plane work-item create --name "New feature" --priority medium

# Filter by environment
omk --profile staging plane work-item search --query "bug" -o json | jq '.data[] | select(.priority=="urgent")'
```

### Example 3: Generate Project Status Report

```bash
#!/bin/bash

export PLANE_WORKSPACE_SLUG="my-workspace"

# Generate report in JSON format
omk plane work-item list --all -o json > report.json

# Group by status and count
jq '[.data[] | .state] | group_by(.) | map({state: .[0], count: length})' report.json

# Get top 5 work items by priority
jq '.data | sort_by(.priority) | reverse | .[0:5]' report.json
```

## Roadmap

- [x] **Plane** (plane.so, self-hosted)
  - Note: Developed against **Community Edition (self-hosted, free tier)**. Enterprise-only features are not implemented.
  - Provider subgroup: `omk plane` (or `omk pl`)
  - Examples: `omk plane work-item list`, `omk plane cycle create --name "Sprint 1"`, `omk pl work-item search --query "bug"`
- [ ] **GitHub**
  - Provider subgroup: `omk github` (or `omk gh`)
  - Examples: `omk github issue list --owner ej31 --repo my-repo`, `omk github project list --owner ej31`
- [x] **Linear**
  - Provider subgroup: `omk linear` (or `omk ln`)
  - Examples: `omk linear issue list`, `omk linear issue create --title "Bug" --team TEAM_ID`, `omk ln team list`
- [ ] **Notion**
- [ ] **Jira**

## Contributing

### Environment Setup

```bash
git clone https://github.com/ej31/oh-my-kanban.git
cd oh-my-kanban
pip install -e ".[dev]"
```

### Code Style

- Python 3.10+
- Ruff lint rules: E, F, I, UP, B
- Line length: 100

### Testing

```bash
pytest tests/
```

### Pull Request Process

1. Fork the repository
2. Create a feature branch: `git checkout -b feat/your-feature`
3. Commit changes: `git commit -am 'feat: add your feature'`
4. Push to branch: `git push origin feat/your-feature`
5. Open a Pull Request

## License

MIT License - See [LICENSE](LICENSE) for details

## Support

- **Issues**: [GitHub Issues](https://github.com/ej31/oh-my-kanban/issues)
- **Documentation**: [GitHub Wiki](https://github.com/ej31/oh-my-kanban/wiki)
- **API Reference**: [Plane API Docs](https://docs.plane.so/api-reference)
