# Harmony - Full Documentation for AI Agents

> Agent-native Kanban where humans and AI stay in sync.

Harmony is a collaborative project management and Kanban board application with an MCP server and REST API for AI agent integration. This document contains everything an agent needs to set up and use Harmony.

## Complete Onboarding Journey

This section walks through the full setup from zero to a working agent integration.

### 1. Create Account

- Go to https://gethmy.com/auth
- Fill in: display name, email address, password (minimum 6 characters)
- Email confirmation may be required before first login

### 2. First Login

- After signing in, Harmony auto-creates a personal workspace ("[Your Name]'s Workspace")
- A starter board ("My First Board") is created with three columns: To Do, In Progress, Done
- A sample welcome card (#1) is added to get you started

### 3. Generate API Key

- Go to https://gethmy.com/user/keys
- Click "Generate New Key"
- Give it a name (e.g., "Claude Code")
- Copy the key immediately - it starts with `hmy_` and is stored as a SHA-256 hash, so it cannot be retrieved again

### 4. Automated Agent Setup

Run this single command - fully non-interactive:

```
npx @gethmy/mcp setup --api-key <YOUR_KEY> --global --agents claude
```

Replace `claude` with `codex`, `cursor`, or `windsurf` as needed. You can pass multiple agents: `--agents claude cursor`.

### 5. Verify

```
npx @gethmy/mcp status
```

Should show "Status: Configured" with your workspace and project.

### 6. First Action

Use `/hmy #1` to start working on the sample welcome card.

### Verification Checkpoints

Use these to confirm each stage is complete:

- **Account created:** You can access https://gethmy.com while logged in
- **API key works:** `curl -H "X-API-Key: hmy_..." https://gethmy.com/api/v1/workspaces` returns HTTP 200
- **MCP configured:** `npx @gethmy/mcp status` shows "Status: Configured"

## Quick Setup

Prerequisites: A Harmony account at https://gethmy.com

1. Get an API key at https://gethmy.com/user/keys (click "Generate New Key", key starts with `hmy_`)
2. Run: `npx @gethmy/mcp setup`

The setup wizard will:
- Validate your API key
- Detect installed AI agents (Claude Code, Cursor, Codex)
- Install skills globally (recommended) or locally
- Let you select your workspace and project

### Adding to a New Project

Run setup again in the new project directory:

```
cd my-new-project
npx @gethmy/mcp setup
```

It detects your existing configuration and only asks for the project context.

## CLI Commands

```
npx @gethmy/mcp setup              # Smart setup wizard
npx @gethmy/mcp status             # Show current configuration
npx @gethmy/mcp reset              # Clear all configuration
npx @gethmy/mcp serve              # Start MCP server (called by agents automatically)
```

### Setup Flags (Non-Interactive)

| Flag                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| -k, --api-key <key>        | API key (skips prompt)                               |
| -e, --email <email>        | Your email for auto-assignment                       |
| -a, --agents <agents...>   | Agents to configure: claude, codex, cursor, windsurf |
| -g, --global               | Install skills globally (recommended)                |
| -l, --local                | Install skills locally in project directory          |
| -w, --workspace <id>       | Set workspace context                                |
| -p, --project <id>         | Set project context                                  |
| --skip-context             | Skip workspace/project selection                     |
| -f, --force                | Overwrite existing configuration                     |

## Supported AI Agents

| Agent          | Workflow Command         | Config Location                       |
| -------------- | ------------------------ | ------------------------------------- |
| Claude Code    | /hmy #42                 | ~/.claude/settings.json               |
| OpenAI Codex   | /prompts:hmy #42         | ~/.codex/config.toml                  |
| Cursor         | MCP tools auto-available | .cursor/mcp.json                      |

## Card Workflow

When you start working on a card (e.g., `/hmy #42`):

1. Find - Locates the card by short ID, UUID, or name
2. Move - Moves the card to "In Progress" column
3. Label - Adds the "agent" label to indicate AI is working
4. Assign - Auto-assigns the card to you (if email is configured)
5. Track - Starts a session timer visible in the UI
6. Implement - Work on the task with progress updates
7. Complete - Move to "Review" when done

## Available MCP Tools (29 total)

### Card Operations
- harmony_create_card - Create a new card
- harmony_update_card - Update card properties
- harmony_move_card - Move card to different column
- harmony_delete_card - Delete a card
- harmony_assign_card - Assign to team member
- harmony_search_cards - Search by title/description
- harmony_get_card - Get card details by UUID
- harmony_get_card_by_short_id - Get card by short ID (e.g., #42)

### Card Link Operations
- harmony_add_link_to_card - Create a link between two cards
- harmony_remove_link_from_card - Remove a link between cards
- harmony_get_card_links - Get all links for a card

Link Types: relates_to, blocks, duplicates, is_part_of

### Column Operations
- harmony_create_column - Create new column
- harmony_update_column - Update column properties
- harmony_delete_column - Delete column

### Label Operations
- harmony_create_label - Create new label
- harmony_add_label_to_card - Add label to card
- harmony_remove_label_from_card - Remove label

### Subtask Operations
- harmony_create_subtask - Create subtask
- harmony_toggle_subtask - Toggle completion
- harmony_delete_subtask - Delete subtask

### Context Operations
- harmony_list_workspaces - List workspaces
- harmony_list_projects - List projects
- harmony_get_board - Get full board state
- harmony_get_workspace_members - Get team members
- harmony_set_workspace_context - Set active workspace
- harmony_set_project_context - Set active project
- harmony_get_context - Get current context

### Natural Language
- harmony_process_command - Process natural language commands

### Agent Session Tracking
- harmony_start_agent_session - Start tracking work on a card
- harmony_update_agent_progress - Update progress, status, blockers
- harmony_end_agent_session - End session (completed/paused)
- harmony_get_agent_session - Get current session state

### Prompt Generation
- harmony_generate_prompt - Generate an AI-ready prompt from a card

Prompt Variants:
- analysis - Understand the problem and create a plan
- draft - Design a solution approach
- execute - Full implementation (default)

Parameters: cardId, shortId, variant, includeDescription, includeSubtasks, includeLinks, customConstraints

The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and includes relevant context from linked cards.

## REST API

Base URL: https://gethmy.com/api

Authentication: Pass your API key via the X-API-Key header.

```
curl -X GET "https://gethmy.com/api/v1/workspaces" \
  -H "X-API-Key: hmy_your_key_here"
```

### Endpoints

| Endpoint                        | Method | Description                |
| ------------------------------- | ------ | -------------------------- |
| /v1/workspaces                  | GET    | List workspaces            |
| /v1/workspaces/:id/projects     | GET    | List projects in workspace |
| /v1/workspaces/:id/members      | GET    | Get workspace members      |
| /v1/board/:projectId            | GET    | Get full board state       |
| /v1/cards                       | POST   | Create card                |
| /v1/cards/:id                   | GET    | Get card                   |
| /v1/cards/:id                   | PATCH  | Update card                |
| /v1/cards/:id                   | DELETE | Delete card                |
| /v1/cards/:id/move              | POST   | Move card                  |
| /v1/search?q=query              | GET    | Search cards               |
| /v1/columns                     | POST   | Create column              |
| /v1/columns/:id                 | PATCH  | Update column              |
| /v1/columns/:id                 | DELETE | Delete column              |
| /v1/labels                      | POST   | Create label               |
| /v1/cards/:id/labels            | POST   | Add label to card          |
| /v1/cards/:id/labels/:labelId   | DELETE | Remove label               |
| /v1/subtasks                    | POST   | Create subtask             |
| /v1/subtasks/:id/toggle         | POST   | Toggle subtask             |
| /v1/subtasks/:id                | DELETE | Delete subtask             |
| /v1/cards/:id/links             | GET    | Get card links             |
| /v1/cards/:id/links             | POST   | Create card link           |
| /v1/links/:id                   | DELETE | Delete card link           |
| /v1/cards/:id/prompt            | GET    | Generate prompt from card  |
| /v1/nlu                         | POST   | Process natural language   |

## Configuration

### Global Configuration

Stored in ~/.harmony-mcp/config.json:

```json
{
  "apiKey": "hmy_...",
  "apiUrl": "https://gethmy.com/api",
  "userEmail": "you@example.com",
  "activeWorkspaceId": null,
  "activeProjectId": null
}
```

### Local Project Configuration

Stored in .harmony-mcp.json in your project root:

```json
{
  "workspaceId": "uuid-here",
  "projectId": "uuid-here"
}
```

Priority: Local config overrides global config for workspace and project context.
Security: API key is never stored locally (only in global config) to prevent accidental commits.

Add .harmony-mcp.json to your .gitignore.

### Auto-Assignment

When your email is configured during setup, cards are automatically assigned to you when you start an agent session. The email must match your Harmony account email.

Update email: `npx @gethmy/mcp setup --email you@example.com`

## Architecture

```
AI Agent (Claude Code, Cursor, etc.)
    │
    │ MCP Protocol
    ▼
@gethmy/mcp (local server)
    │
    │ API Key Auth (X-API-Key header)
    ▼
Harmony API (Edge Function)
    │
    ▼
Database (Supabase/PostgreSQL)
```

Key benefits:
- No database credentials needed - just a Harmony API key
- Any Harmony user can use it
- Business logic stays in Harmony
- Centralized security and rate limiting

## Links

- Website: https://gethmy.com
- npm package: https://www.npmjs.com/package/@gethmy/mcp
- Quick reference: https://gethmy.com/llms.txt