oh-my-kanban

한국어	ENGLISH

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

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

pip install oh-my-kanban

From Source

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

Quick Start

Step 1: Initialize Configuration (Interactive)

omk config init

Provide the following information:

• Server type: plane.so cloud or self-hosted
• API key: Generate API token
• Workspace slug: Extract from URL or enter directly

Step 2: Agent Mode (Environment Variable Automation)

For unattended automation with AI agents:

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)

# 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

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

Profile-Based Multi-Workspace Management

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

omk --profile production plane work-item list

Environment Variable Priority

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

# 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

# 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

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)

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

# 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

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

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

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.

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)

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

Coming soon.

Output Formats / 출력 형식

Table (Default)

omk plane work-item list

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)

omk plane work-item list -o 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)

omk plane work-item list -o plain

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

#!/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

# 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

#!/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

• 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
• 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

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

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 for details

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• API Reference: Plane API Docs