@openpets/shortcut

Shortcut (formerly Clubhouse) project management integration for OpenCode. Create projects, epics, stories, and manage your agile workflows via API.

Features

• ✅ Create Projects - Unlike Linear and Asana, Shortcut allows creating projects via API
• ✅ Full Project Management - Epics, stories, iterations, workflows
• ✅ Team Collaboration - Members, comments, labels, custom fields
• ✅ Search & Discovery - Powerful search across all entities
• ✅ 138 API Tools - Auto-generated from official OpenAPI spec

Installation

pets add shortcut

Or install directly:

cd pets/shortcut
bun install

Configuration

1. Get Your Shortcut API Token

1. Go to https://app.shortcut.com/settings/api-tokens
2. Click "Generate New Token"
3. Give it a descriptive name (e.g., "OpenCode Integration")
4. Copy the token (starts with sc_token_)

2. Set Environment Variable

Create a .env file:

SHORTCUT_API_TOKEN=your_token_here

Or set it in your environment:

export SHORTCUT_API_TOKEN=your_token_here

3. Test Connection

pets run shortcut --query "test connection"

Usage Examples

Create a Project

opencode run "create a new Shortcut project called 'Website Redesign' with description 'Overhaul of company website'"

List Projects

opencode run "list all projects in my Shortcut workspace"

Create an Epic

opencode run "create an epic called 'Q4 Marketing Campaign' in project 'Marketing'"

Create a Story

opencode run "create a story titled 'Fix login bug on mobile app' in project 'Mobile App' with high priority"

Update a Project

opencode run "update project 'Website Redesign' description to 'Complete redesign with new branding'"

Delete a Project

opencode run "delete project 12345"

Search Stories

opencode run "search for stories about 'authentication' in project 'Mobile App'"

Available Tools

Project Management (Read)

• shortcut-list-projects - List all projects
• shortcut-get-project - Get project details
• shortcut-list-stories - List stories in a project

Project Management (Write)

• ✅ shortcut-create-project - Create a new project
• shortcut-update-project - Update project properties
• shortcut-delete-project - Delete a project

Epic Management

• shortcut-list-epics - List all epics
• shortcut-get-epic - Get epic details
• ✅ shortcut-create-epic - Create a new epic
• shortcut-update-epic - Update an epic
• shortcut-delete-epic - Delete an epic

Story Management

• shortcut-list-stories - List stories
• shortcut-get-story - Get story details
• ✅ shortcut-create-story - Create a new story
• shortcut-update-story - Update a story
• shortcut-delete-story - Delete a story
• shortcut-create-multiple-stories - Bulk create stories

Search & Discovery

• shortcut-search - Search across all entities
• shortcut-search-stories - Search stories
• shortcut-search-epics - Search epics
• shortcut-query-stories - Advanced story queries

Additional Features

• Iterations - Sprint/iteration planning
• Workflows - Manage workflow states
• Members - Team member information
• Labels - Categorization and tagging
• Comments - Discussion threads
• Files - Attachments and uploads
• Custom Fields - Extended attributes
• Documents - Knowledge base integration

Total: 138 tools (71 read-only, 67 write operations)

Available Tools

All 138 tools are loaded by default - no configuration needed!

Project Management

• ✅ shortcut-create-project - Create new projects (unlike Linear/Asana!)
• shortcut-list-projects - List all projects
• shortcut-get-project - Get project details
• shortcut-update-project - Update project
• shortcut-delete-project - Delete project

Epic Management

• ✅ shortcut-create-epic - Create epics
• shortcut-list-epics - List epics
• shortcut-get-epic - Get epic details
• shortcut-update-epic - Update epic
• shortcut-delete-epic - Delete epic

Story Management

• ✅ shortcut-create-story - Create stories
• shortcut-create-multiple-stories - Bulk create stories
• shortcut-update-story - Update story
• shortcut-delete-story - Delete story
• shortcut-get-story - Get story details
• shortcut-query-stories - Search stories

Search & Discovery

• shortcut-search - Search across all entities
• shortcut-search-stories - Search stories
• shortcut-search-epics - Search epics
• shortcut-search-iterations - Search iterations
• shortcut-search-milestones - Search milestones
• shortcut-search-objectives - Search objectives

Additional Features

• Iterations - Sprint planning
• Workflows - Manage workflow states
• Members - Team member info
• Labels - Categorization
• Comments - Discussion threads
• Files - Attachments
• Documents - Knowledge base
• Custom Fields - Extended attributes
• Bulk Operations - Create/delete multiple items

Read-Only Mode

Enable read-only mode to prevent accidental changes:

# Environment variable
export SHORTCUT_READ_ONLY=true

# Or CLI command
pets read-only shortcut on

In read-only mode, all write operations (POST, PUT, DELETE) are disabled:

• ✅ Create project - Blocked
• ✅ Update project - Blocked
• ✅ Delete project - Blocked
• ✅ Create epic - Blocked
• ✅ Create story - Blocked
• ✅ All read operations - Available

Comparison: Why Shortcut?

| Feature | Shortcut | Linear | Asana | Jira | |---------|----------|--------|-------|------| | Create Projects | ✅ Yes | ❌ No | ❌ No | ❌ No | | Create Epics | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | | Create Stories | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | | OpenAPI Spec | ✅ Yes | ✅ Yes | ❌ MCP | ❌ MCP | | Simple Auth | ✅ API Key | ✅ API Key | ❌ OAuth | ❌ OAuth |

Shortcut fills the gap: Unlike Linear and Asana which require manual project creation in their UIs, Shortcut allows full project lifecycle management via API.

Error Handling

Common errors and solutions:

"Unauthorized" (401)

• Check your SHORTCUT_API_TOKEN is set correctly
• Verify the token hasn't expired at https://app.shortcut.com/settings/api-tokens

"Not Found" (404)

• Project/Story/Epic ID doesn't exist
• Check the ID with shortcut-list-projects or shortcut-list-epics

"Unprocessable" (422)

• Invalid data format
• Missing required fields (e.g., name for projects)
• Check the API documentation for required fields

"Rate Limited" (429)

• Too many requests
• Wait a few seconds and retry

API Reference

This plugin is generated from Shortcut's official OpenAPI 3.0 specification:

• Spec URL: https://developer.shortcut.com/api/rest/v3/shortcut.openapi.json
• API Base: https://api.app.shortcut.com
• Documentation: https://developer.shortcut.com/api/rest/v3

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SHORTCUT_API_TOKEN | ✅ Yes | Your Shortcut API token | | SHORTCUT_HOST | ❌ No | API host (default: https://api.app.shortcut.com) | | SHORTCUT_READ_ONLY | ❌ No | Enable read-only mode |

Development

Build

cd pets/shortcut
bun run build

Validate

pets validate

Test Connection

bun run test:connection

Test Create Project

bun run test:create-project

Architecture

This plugin uses OpenPets' OpenAPI code generation:

1. openapi-spec.json - Downloaded from Shortcut's official spec
2. openapi-client.ts - Generated HTTP client utilities
3. openapi-tools.ts - Generated 138 tool definitions
4. index.ts - Main plugin entry point

To regenerate tools after spec updates:

cd pets/shortcut
pets generate-openapi

Resources

• Shortcut API Docs: https://developer.shortcut.com/api/rest/v3
• OpenPets Docs: https://github.com/openpets/pets/tree/main/docs
• Report Issues: https://github.com/openpets/pets/issues

License

MIT © OpenPets