# Harmony - Full Documentation for AI Agents

> Work with your AI Agents in Harmony — the shared surface where people and agents run the same loop.

Harmony is a collaborative project management board 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