# Tools Reference

This page documents the most commonly used hive-mcp MCP tools organized by category.

> **Convention**: Always pass `directory` parameter with your working directory to ensure correct project scoping.

---

## ⚠️ Naming: this page uses the legacy flat tool names

The tool surface was consolidated into **domain roots with subcommands**. The examples
below still use the pre-consolidation flat names (`mcp_memory_add`, `swarm_spawn`,
`hivemind_shout`). The *semantics and parameters* are still accurate — only the call shape
changed. Translate as you read:

| Legacy flat name | Consolidated form |
|---|---|
| `mcp_memory_add` | `memory` → `add` |
| `mcp_memory_query` / `_query_metadata` | `memory` → `query` |
| `mcp_memory_get_full` | `memory` → `get` |
| `mcp_memory_search_semantic` | `memory` → `search` |
| `swarm_spawn` / `_kill` / `_status` | `agent` → `spawn` / `kill` / `status` |
| `swarm_dispatch` | `agent` → `dispatch` |
| `swarm_broadcast` | `hivemind` → `shout` |
| `hivemind_shout` / `_ask` / `_status` | `hivemind` → `shout` / `ask` / `status` |

So `mcp_memory_add(content: "...", type: "decision")` is now
`memory(command: "add", content: "...", type: "decision")`.

Core ships roots for `memory`, `project`, `code`, `swarm`, `fs`, `git`, `emacs`, `preset`,
`web`, `events`, `multi` and `migrate-kanban`; addons contribute more. `multi` batches any
of them into a single call — see the DSL verbs below.

### DSL verbs (for `multi`)

| Verb | Operation | Verb | Operation |
|---|---|---|---|
| `m+` | memory add | `b+` | kanban create |
| `m?` | memory query | `b>` | kanban update |
| `m@` | memory get | `b?` | kanban list |
| `m/` | memory search | `s~` | session wrap |
| `k>` | kg edge | `s<` | session catchup |
| `k^` | kg traverse | `g!` | git commit |
| `a+` | agent spawn | `p?` | preset list |
| `a!` | agent dispatch | `p/` | preset search |

Ops are numbered from `$0`; a later op can reference an earlier result by id.

*This page is due a rewrite against the consolidated surface. Until then, treat the mapping
above as authoritative and the bodies below as reference for parameters and semantics.*

---

## Table of Contents

1. [Hivemind Communication](#hivemind-communication)
2. [Memory System](#memory-system)
3. [Swarm Coordination](#swarm-coordination)
4. [File Operations](#file-operations)
5. [Git (Magit)](#git-magit)
6. [Session Lifecycle](#session-lifecycle)
7. [Clojure Development](#clojure-development)

---

## Hivemind Communication

Tools for coordinating between lings and the human coordinator.

### hivemind_shout

**Purpose**: Broadcast status/progress to the hivemind coordinator in real-time.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `event_type` | Yes | One of: `started`, `progress`, `completed`, `error`, `blocked` |
| `message` | No | Human-readable status message |
| `task` | No | Current task description |
| `data` | No | Additional structured data |
| `directory` | No | Working directory for project scoping |

**Example Usage**:
```
# Report task start
hivemind_shout(event_type="started", task="Implement auth module", directory="/path/to/project")

# Report progress
hivemind_shout(event_type="progress", message="Completed 3/5 endpoints", directory="/path/to/project")

# Report completion
hivemind_shout(event_type="completed", message="Auth module implemented with tests", directory="/path/to/project")

# Report being blocked
hivemind_shout(event_type="blocked", message="Need clarification on OAuth provider", directory="/path/to/project")
```

**Common Patterns**:
- Always shout `started` at task beginning
- Use `progress` for multi-step work to keep coordinator informed
- End with `completed` or `error` - this is **mandatory** for hivemind coordination
- Include meaningful messages that describe what was done

---

### hivemind_ask

**Purpose**: Request a decision from the human coordinator. **Blocks** until response received.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `question` | Yes | What decision do you need? |
| `options` | No | Array of available choices (omit for free-form) |
| `timeout_ms` | No | Timeout in ms (default: 300000 = 5 min) |
| `directory` | No | Working directory for project scoping |

**Example Usage**:
```
# Multiple choice question
hivemind_ask(
  question="Should I delete these 50 unused files?",
  options=["yes", "no", "show me first"],
  directory="/path/to/project"
)

# Free-form question
hivemind_ask(
  question="What naming convention should I use for the new API endpoints?",
  directory="/path/to/project"
)
```

**Common Patterns**:
- Use before destructive operations
- Use when multiple valid approaches exist
- Use when requirements are ambiguous
- Keep questions specific and actionable

---

### hivemind_status

**Purpose**: Get current hivemind coordinator status including active agents and pending questions.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `directory` | No | Filter to agents from specific project |

**Example Usage**:
```
hivemind_status(directory="/path/to/project")
```

**Returns**:
- Active agents and their status
- Pending questions awaiting human decision
- Channel connection status

---

## Memory System

Persistent project memory stored in Chroma vector database.

### mcp_memory_add

**Purpose**: Store a memory entry (note, convention, decision, or snippet).

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `type` | Yes | `note`, `snippet`, `convention`, or `decision` |
| `content` | Yes | The content to store |
| `tags` | No | Array of categorization tags |
| `duration` | No | TTL: `ephemeral`(1d), `short`(7d), `medium`(30d), `long`(90d), `permanent` |
| `directory` | No | Working directory for project scoping |
| `agent_id` | No | Agent identifier for attribution |

**Example Usage**:
```
# Store a decision
mcp_memory_add(
  type="decision",
  content="Use PostgreSQL for primary storage due to JSONB support and team expertise",
  tags=["architecture", "database"],
  duration="long",
  directory="/path/to/project"
)

# Store a code snippet
mcp_memory_add(
  type="snippet",
  content="(defn safe-get [m k default] (or (get m k) default))",
  tags=["clojure", "utils"],
  duration="medium",
  directory="/path/to/project"
)

# Store a convention
mcp_memory_add(
  type="convention",
  content="All API handlers must validate input at boundary using spec",
  tags=["api", "validation"],
  duration="permanent",
  directory="/path/to/project"
)
```

**Common Patterns**:
- Use `decision` for architectural choices and rationale
- Use `convention` for team/project standards
- Use `snippet` for reusable code patterns
- Use `note` for general observations
- Tag entries for easier retrieval

---

### mcp_memory_query / mcp_memory_query_metadata

**Purpose**: Retrieve memory entries by type with optional filtering.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `type` | Yes | `note`, `snippet`, `convention`, `decision`, or `conversation` |
| `tags` | No | Filter by tags |
| `limit` | No | Max results (default: 20) |
| `scope` | No | `nil`=project+global, `all`, `global`, or specific scope |
| `directory` | No | Working directory for project scoping |

**Example Usage**:
```
# Get all decisions
mcp_memory_query(type="decision", directory="/path/to/project")

# Get conventions tagged with "api"
mcp_memory_query(type="convention", tags=["api"], directory="/path/to/project")

# Efficient metadata-only query (10x fewer tokens)
mcp_memory_query_metadata(type="note", limit=50, directory="/path/to/project")
```

**Common Patterns**:
- Use `_metadata` variant for browsing/listing (saves tokens)
- Follow up with `mcp_memory_get_full` for specific entries
- Filter by tags when looking for specific topics

---

### mcp_memory_get_full

**Purpose**: Get full content of a memory entry by ID.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `id` | Yes | ID of the memory entry |

**Example Usage**:
```
# After getting IDs from metadata query
mcp_memory_get_full(id="abc123-def456")
```

---

### mcp_memory_search_semantic

**Purpose**: Find conceptually related entries using vector similarity search.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Natural language query |
| `type` | No | Filter by memory type |
| `limit` | No | Max results (default: 10) |

**Example Usage**:
```
# Find entries about error handling
mcp_memory_search_semantic(query="how do we handle API errors and validation failures")

# Find architecture decisions about caching
mcp_memory_search_semantic(query="caching strategy", type="decision")
```

**Common Patterns**:
- Use for conceptual searches when keywords might vary
- Great for finding related patterns and decisions
- Combine with type filter to narrow results

---

## Swarm Coordination

Tools for managing parallel Claude agents (lings).

### swarm_spawn

**Purpose**: Create a new Claude ling instance for parallel work.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `name` | Yes | Name for the ling (used in buffer name) |
| `presets` | No | Array of preset names (e.g., `["tdd", "clarity"]`) |
| `role` | No | Predefined role: `tester`, `reviewer`, `documenter`, etc. |
| `cwd` | No | Working directory for the ling |
| `terminal` | No | Terminal type: `vterm` or `eat` (default: vterm) |

**Example Usage**:
```
# Spawn a TDD-focused ling
swarm_spawn(name="test-writer", presets=["tdd"], cwd="/path/to/project")

# Spawn a documentation ling
swarm_spawn(name="docs-writer", presets=["documenter"], cwd="/path/to/project")

# Spawn with multiple presets
swarm_spawn(name="careful-coder", presets=["clarity", "tdd"], cwd="/path/to/project")
```

**Common Patterns**:
- Always set `cwd` to ensure correct project context
- Use meaningful names for easy identification
- Apply presets matching the task type

---

### swarm_dispatch

**Purpose**: Send a task/prompt to a specific ling.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `slave_id` | Yes | ID of the target ling |
| `prompt` | Yes | The task to send |
| `files` | No | Files this task will modify (for conflict detection) |
| `timeout_ms` | No | Optional timeout |

**Example Usage**:
```
swarm_dispatch(
  slave_id="ling-abc123",
  prompt="Write unit tests for the auth module in src/auth/",
  files=["src/auth/auth_test.clj"]
)
```

**Common Patterns**:
- Specify `files` to enable conflict detection
- Include clear, complete task descriptions
- Lings work autonomously - provide full context

---

### swarm_status

**Purpose**: Get status of all active lings or a specific ling.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `slave_id` | No | Get status of specific ling only |

**Example Usage**:
```
# Get all lings status
swarm_status()

# Get specific ling status
swarm_status(slave_id="ling-abc123")
```

---

### swarm_kill

**Purpose**: Terminate a ling instance.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `slave_id` | Yes | ID to kill, or `"all"` to kill all |
| `directory` | No | When `slave_id="all"`, only kills lings from this project |

**Example Usage**:
```
# Kill specific ling
swarm_kill(slave_id="ling-abc123")

# Kill all lings in project
swarm_kill(slave_id="all", directory="/path/to/project")
```

---

### swarm_broadcast

**Purpose**: Send the same prompt to all active lings simultaneously.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | Message to broadcast |

**Example Usage**:
```
swarm_broadcast(prompt="Stop current work and prepare for wrap")
```

---

## File Operations

Tools for reading and writing files.

### read_file

**Purpose**: Read contents of a file.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `path` | Yes | Absolute path to file |
| `offset` | No | Line to start from (default: 0) |
| `limit` | No | Max lines to read (default: 2000) |

**Example Usage**:
```
# Read entire file
read_file(path="/path/to/project/src/core.clj")

# Read specific section
read_file(path="/path/to/project/src/core.clj", offset=100, limit=50)
```

---

### file_write

**Purpose**: Write content to a file. Creates parent directories if needed.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `file_path` | Yes | Absolute path to write |
| `content` | Yes | Content to write |

**Example Usage**:
```
file_write(
  file_path="/path/to/project/src/new_module.clj",
  content="(ns project.new-module)\n\n(defn hello [] \"world\")"
)
```

---

### grep

**Purpose**: Search for patterns in files using ripgrep.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `pattern` | Yes | Regex pattern to search |
| `path` | No | Directory to search (default: cwd) |
| `include` | No | File pattern filter (e.g., `*.clj`) |
| `max_results` | No | Max results (default: 100) |

**Example Usage**:
```
# Find all defn declarations
grep(pattern="defn.*handler", include="*.clj", path="/path/to/project/src")

# Find TODO comments
grep(pattern="TODO", path="/path/to/project")
```

---

### glob_files

**Purpose**: Find files matching a glob pattern.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `pattern` | Yes | Glob pattern (e.g., `**/*.clj`) |
| `path` | No | Root directory (default: cwd) |

**Example Usage**:
```
# Find all Clojure files
glob_files(pattern="**/*.clj", path="/path/to/project")

# Find test files
glob_files(pattern="**/*_test.clj", path="/path/to/project")
```

---

## Git (Magit)

Git operations through Emacs Magit integration.

> **Important**: Always pass `directory` to target your project, not the MCP server's directory.

### magit_status

**Purpose**: Get comprehensive git status including branch, files, and commits.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `directory` | Yes | Your project directory |

**Example Usage**:
```
magit_status(directory="/path/to/project")
```

**Returns**:
- Current branch and upstream
- Staged/unstaged/untracked files
- Ahead/behind counts
- Stashes
- Recent commits

---

### magit_commit

**Purpose**: Create a git commit.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `message` | Yes | Commit message |
| `all` | No | Stage all changes before committing |
| `directory` | Yes | Your project directory |

**Example Usage**:
```
magit_commit(
  message="feat: Add user authentication module",
  directory="/path/to/project"
)

# Stage all and commit
magit_commit(
  message="fix: Resolve null pointer in parser",
  all=true,
  directory="/path/to/project"
)
```

---

### magit_push / magit_pull

**Purpose**: Sync with remote repository.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `directory` | Yes | Your project directory |
| `set_upstream` | No | (push only) Set upstream tracking |

**Example Usage**:
```
# Push changes
magit_push(directory="/path/to/project")

# Push new branch with upstream
magit_push(directory="/path/to/project", set_upstream=true)

# Pull from upstream
magit_pull(directory="/path/to/project")
```

---

### magit_stage

**Purpose**: Stage files for commit.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `files` | Yes | File path or `"all"` for all modified |
| `directory` | Yes | Your project directory |

**Example Usage**:
```
# Stage specific file
magit_stage(files="src/core.clj", directory="/path/to/project")

# Stage all modified
magit_stage(files="all", directory="/path/to/project")
```

---

## Session Lifecycle

Tools for managing work sessions with context preservation.

### mcp_run_workflow("catchup")

**Purpose**: Restore context at session start. Loads recent decisions, conventions, and work state.

**Example Usage**:
```
mcp_run_workflow(name="catchup", args={"directory": "/path/to/project"})
```

**Common Patterns**:
- Run at the start of every session
- Provides context from previous sessions
- Helps maintain continuity across conversations

---

### mcp_run_workflow("wrap")

**Purpose**: End session with summary and memory crystallization.

**Example Usage**:
```
mcp_run_workflow(name="wrap", args={"directory": "/path/to/project"})
```

---

### wrap_crystallize

**Purpose**: Persist session learnings to long-term memory.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `directory` | No | Working directory for project scoping |
| `agent_id` | No | **Required for lings**: Your `CLAUDE_SWARM_SLAVE_ID` |

**Example Usage**:
```
# For coordinator
wrap_crystallize(directory="/path/to/project")

# For lings (CRITICAL: pass agent_id)
wrap_crystallize(directory="/path/to/project", agent_id="ling-abc123")
```

**Common Patterns**:
- Lings **must** pass `agent_id` for proper attribution
- Creates session summary from recent notes
- Promotes high-score entries to long-term memory

---

### session_complete

**Purpose**: Complete ling session: commits changes, moves kanban tasks, crystallizes wrap. All-in-one session end.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `commit_msg` | Yes | Git commit message |
| `directory` | No | Working directory |
| `agent_id` | No | Ling's slave-id (required for attribution) |
| `task_ids` | No | Kanban task IDs to mark done |

**Example Usage**:
```
session_complete(
  commit_msg="feat: Implement user registration flow",
  directory="/path/to/project",
  agent_id="ling-abc123",
  task_ids=["task-xyz789"]
)
```

**Common Patterns**:
- Use instead of separate git/kanban/wrap calls
- Single atomic operation for session end
- Always pass `agent_id` for lings

---

## Clojure Development

Tools for Clojure development via CIDER.

### cider_eval_silent

**Purpose**: Evaluate Clojure code silently (no REPL output). Fast for routine operations.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `code` | Yes | Clojure code to evaluate |

**Example Usage**:
```
# Evaluate expression
cider_eval_silent(code="(+ 1 2 3)")

# Load namespace
cider_eval_silent(code="(require '[my.namespace :as ns])")

# Run tests
cider_eval_silent(code="(clojure.test/run-tests 'my.namespace-test)")
```

**Common Patterns**:
- Use for routine evaluations
- Prefer over `cider_eval_explicit` unless debugging
- Good for automated checks and data queries

---

### cider_doc / cider_info

**Purpose**: Get documentation and metadata for Clojure symbols.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `symbol` | Yes | Symbol name (qualified or unqualified) |

**Example Usage**:
```
# Get docstring
cider_doc(symbol="map")
cider_doc(symbol="clojure.string/join")

# Get full metadata (namespace, arglists, source location, specs)
cider_info(symbol="defn")
```

---

### kondo_lint

**Purpose**: Lint Clojure code using clj-kondo.

**Key Parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `path` | Yes | File or directory to lint |
| `level` | No | Min severity: `error`, `warning` (default), `info` |

**Example Usage**:
```
# Lint single file
kondo_lint(path="/path/to/project/src/core.clj")

# Lint directory, errors only
kondo_lint(path="/path/to/project/src", level="error")

# Full lint with warnings
kondo_lint(path="/path/to/project/src", level="warning")
```

**Common Patterns**:
- Run after making changes to verify syntax
- Use `level="error"` for quick checks

---

## Quick Reference Card

| Task | Tool | Key Params |
|------|------|------------|
| Report status | `hivemind_shout` | `event_type`, `message` |
| Ask human | `hivemind_ask` | `question`, `options` |
| Store knowledge | `mcp_memory_add` | `type`, `content`, `tags` |
| Find knowledge | `mcp_memory_search_semantic` | `query` |
| Spawn worker | `swarm_spawn` | `name`, `presets`, `cwd` |
| Send task | `swarm_dispatch` | `slave_id`, `prompt` |
| Read file | `read_file` | `path` |
| Write file | `file_write` | `file_path`, `content` |
| Git status | `magit_status` | `directory` |
| Commit | `magit_commit` | `message`, `directory` |
| Start session | `mcp_run_workflow` | `name="catchup"` |
| End session | `session_complete` | `commit_msg`, `agent_id` |
| Eval Clojure | `cider_eval_silent` | `code` |
| Lint code | `kondo_lint` | `path` |

---

## See Also

- [[Home]] - Wiki home
- [[Core-Engine]] - Host, harness, and the tool-root mechanism
- [[Agents-and-Skills]] - Agent definitions and presets
- [[Presets]] - Swarm preset system
- [[Kanban]] - Task management
- [[Session-Continuity]] - catchup and wrap