openproject-llm-skill

A Claude Code toolkit for working with OpenProject via the API v3.

Inspired by clickup-tool and clickup-tool-plugin.

Features

• Full CRUD on work packages (create, read, update)
• Time tracking (log, list, delete entries)
• Project and user lookups
• Metadata endpoints (statuses, types, priorities, versions)
• Compact JSON output — verbose HAL responses compressed to essential fields
• Claude Code integration: auto-trigger skill, slash commands, session hook, analyst agent

Quick start

Requirements

• Python 3.11+
• An OpenProject instance with API access
• A personal API token (generate at <your-instance>/my/access_token)

Install

# Clone
git clone https://github.com/your-org/openproject-llm-skill
cd openproject-llm-skill

# Install with uv
uv pip install -e .

# Or pip
pip install -e .

Configure

cp .env.example .env

Edit .env:

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_TOKEN=your_personal_api_token

Verify

openproject-tool whoami

Expected output:

{
  "status": "ok",
  "user": {
    "id": 1,
    "login": "admin",
    "name": "Administrator",
    "email": "admin@example.com"
  },
  "instance": "https://your-instance.openproject.com"
}

Usage examples

# List projects
openproject-tool get-projects

# Get all open bugs in a project
openproject-tool get-work-packages --project myproject --type Bug --status "New"

# Create a work package
openproject-tool create-work-package 5 "Fix login redirect" \
  --type-id 1 --priority-id 8 --due-date 2024-02-01

# Update status and close a WP
openproject-tool update-work-package 42 --status-id 12 --percent-done 100

# Add a comment
openproject-tool add-comment 42 "Fixed in commit abc123"

# Log 2.5h with a comment
openproject-tool log-time 42 2.5 --comment "Debugging session"

# Check what I worked on today
openproject-tool get-time-entries --limit 10

Claude Code integration

Add this repository to your Claude Code plugins. The following are automatically available:

• Auto-trigger skill — activates when you mention OpenProject tasks, work packages, sprints, etc.
• Slash commands — /op-wps, /op-wp, /op-create-wp, /op-update-wp, /op-log-time, etc.
• SessionStart hook — verifies connection on every session
• Analyst agent — for sprint reports, cross-project analysis, and time summaries

See CLAUDE.md for full Claude Code documentation.

OpenProject API

This toolkit targets API v3 (the current stable version). Authentication uses HTTP Basic Auth with apikey as the username and your personal token as the password.

Relevant docs:

• API Introduction
• Work Packages
• Time Entries
• Projects

License

MIT