convez.ai
MCP ServerProdutividadeIntermediário
ycomplex

Harmony Plugin para Claude Code

ycomplex/harmony-plugin

Gerenciamento de projetos integrado ao Claude Code com automação de workflows

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-plugin

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

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

CommandDescription
harmony loginAdd a project (provide API token)
harmony logout <name>Remove a project
harmony projectsList logged-in projects
harmony project infoShow current project details
harmony project switch <name>Switch active project
harmony tasks list|get|create|updateTask CRUD
harmony tasks queryAdvanced search with filters
harmony tasks comments|commentView/add comments
harmony tasks bulk-create|bulk-updateBulk operations
harmony epics list|create|updateManage epics
harmony labels list|create|manageManage labels
harmony milestones list|create|update|shipManage milestones
harmony cycles list|create|updateManage cycles
harmony subtasks list|add|update|deleteManage subtasks
harmony ac list|add|update|deleteAcceptance criteria
harmony tests list|add|update|deleteTest cases
harmony docs list|get|create|updateProject documents
harmony members listList 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

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

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

Ver o original no GitHub

Bom para

Relacionados