harmony-plugin

Harmony

Tools for Harmony project management — a CLI for your terminal and an MCP server plugin for Claude Code.

CLI

Manage your Harmony tasks, epics, milestones, and more from the terminal.

Install

npm install -g @harmony-ad/harmony

Or run directly with npx:

npx @harmony-ad/harmony --help

Quick start

# Log in with your API token
harmony login --token <your-api-token>

# List tasks
harmony tasks list

# Get a specific task
harmony tasks get B-42

# Create a task
harmony tasks create --title "Fix login bug" --priority high --status "To Do"

# Update a task
harmony tasks update B-42 --status "In Progress"

# JSON output for scripting
harmony tasks list --json

Commands

Command	Description
harmony login	Add a project (provide API token)
harmony logout <name>	Remove a project
harmony projects	List logged-in projects
harmony project info	Show current project details
harmony project switch <name>	Switch active project
harmony tasks list|get|create|update	Task CRUD
harmony tasks query	Advanced search with filters
harmony tasks comments|comment	View/add comments
harmony tasks bulk-create|bulk-update	Bulk operations
harmony epics list|create|update	Manage epics
harmony labels list|create|manage	Manage labels
harmony milestones list|create|update|ship	Manage milestones
harmony cycles list|create|update	Manage cycles
harmony subtasks list|add|update|delete	Manage subtasks
harmony ac list|add|update|delete	Acceptance criteria
harmony tests list|add|update|delete	Test cases
harmony docs list|get|create|update	Project documents
harmony members list	List workspace members
harmony activity <task-id>	Task activity timeline

Multi-project support

Log in to multiple projects and switch between them:

harmony login --token <token-a>
harmony login --token <token-b> --name my-other-project
harmony projects          # see all, * marks active
harmony project switch my-other-project

Config is stored in ~/.harmony/config.json.

Output modes

• Text (default): formatted tables with color
• JSON (--json): machine-readable output for scripting and piping

Claude Code Plugin

This package also serves as a Claude Code plugin, providing an MCP server and workflow skills.

What's included

MCP Server — gives Claude Code direct access to Harmony:

• Query, create, and update tasks
• Manage labels, comments, and activity history
• Work with projects, documents, cycles, and milestones
• Bulk operations on tasks

Workflow Skills:

• start-work — Begin a piece of work: find/create the Harmony task, move it to In Progress, create an isolated git worktree, and recommend an execution route
• finish-work — Land completed work: verify readiness, rebase, squash merge, clean up the worktree, and move the task to Done

Prerequisites

• Claude Code installed
• superpowers plugin installed (used by workflow skills)
• A Harmony account with an API token

Installation

1. Inside Claude Code, add the marketplace and install the plugin:

   /plugin marketplace add ycomplex/harmony-plugin
   /plugin install harmony-plugin@ycomplex
   

2. Restart Claude Code for the hooks and MCP server to take effect:

   /exit
   

   Then start claude again. On first startup, the plugin automatically installs dependencies and builds the MCP server (~10 seconds).

3. Configure your API token:

   /harmony-setup
   

   This saves the token to .claude/settings.local.json (gitignored) and verifies the connection.

4. Restart Claude Code one more time for the MCP server to pick up the token.

To receive automatic updates, run /plugin, go to the Marketplaces tab, select ycomplex, and enable auto-update.

Manual token configuration

If you prefer to set the token without /harmony-setup:

direnv — Create .envrc in your project root:

export HARMONY_API_TOKEN="hmy_your_token_here"

Claude Code settings — Create .claude/settings.local.json in your project root:

{
  "env": {
    "HARMONY_API_TOKEN": "hmy_your_token_here"
  }
}

Shell profile — Add export HARMONY_API_TOKEN="hmy_your_token_here" to ~/.zshrc or ~/.bashrc.

How it works

The plugin's SessionStart hook automatically installs dependencies and builds the TypeScript MCP server on first use. Subsequent sessions skip the build if dist/index.js already exists.

The MCP server starts automatically when the plugin is enabled and provides tools prefixed with mcp__harmony__ (e.g., mcp__harmony__get_task).

Development