Harmony Plugin para Claude Code
ycomplex/harmony-plugin
Gerenciamento de projetos integrado ao Claude Code com automação de workflows
Ver no GitHubMCP server que integra o gerenciador de projetos Harmony com Claude Code, oferecendo acesso direto a tarefas, epics, milestones e documentos. Inclui workflow skills para automatizar início e conclusão de trabalhos com sincronização git.
Instalação
npx convez-ai ycomplex/harmony-plugin1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Sincronizar tarefas entre Claude Code e Harmony durante desenvolvimento
- Automatizar transição de estados (To Do → In Progress → Done) ao iniciar/finalizar trabalhos
- Consultar contexto de projeto e histórico de atividades sem sair do editor
- Executar operações em massa em tarefas e gerenciar ciclos/milestones
Veredito

Ferramenta bem estruturada para times que usam Harmony e Claude Code — reduz context-switching significativo. Exige configuração inicial (API token) e dependências externas, mas a integração git com workflow skills agrega valor real para fluxos de desenvolvimento.
README
A tradução para o português deste README ainda está na fila.
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
-
Inside Claude Code, add the marketplace and install the plugin:
/plugin marketplace add ycomplex/harmony-plugin /plugin install harmony-plugin@ycomplex -
Restart Claude Code for the hooks and MCP server to take effect:
/exitThen start
claudeagain. On first startup, the plugin automatically installs dependencies and builds the MCP server (~10 seconds). -
Configure your API token:
/harmony-setupThis saves the token to
.claude/settings.local.json(gitignored) and verifies the connection. -
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
npm install # Install dependencies
npm run build # Compile TypeScript
npm run dev # Watch mode
npm test # Run tests
npx tsc --noEmit # Type-check without emitting
Note: This project uses Node16 module resolution. All imports must use .js extensions.
License
MIT