Hive Tools

Git-backed issue tracking with atomic epic creation. Cells are stored as JSONL files in .hive/issues.jsonl and synced via git.

Migration Note: The old beads_* tool names still work but show deprecation warnings. Update to hive_* tools for the latest features.

hive_create

Create a new cell with type-safe validation.

Parameters:

Parameter	Type	Required	Description
`title`	string	✅	Cell title
`type`	`"bug" \| "feature" \| "task" \| "epic" \| "chore"`	❌	Cell type (default: `"task"`)
`description`	string	❌	Detailed description
`priority`	0-3	❌	Priority (0=urgent, 3=low, default: 2)
`parent_id`	string	❌	Parent cell ID for subtasks

Example:

hive_create({
  title: "Add OAuth authentication",
  type: "feature",
  description: "Implement OAuth 2.0 with refresh tokens",
  priority: 1
})

Returns: { id: "bd-123", title: "...", status: "open", ... }

hive_create_epic

Create an epic with subtasks atomically. Either all cells are created or none (with rollback hints).

Parameters:

Parameter	Type	Required	Description
`epic_title`	string	✅	Epic title
`epic_description`	string	❌	Epic description
`subtasks`	array	✅	Array of subtask definitions

Subtask Schema:

{
  title: string;           // Required
  priority?: 0-3;          // Optional, default: 2
  files?: string[];        // Optional, files this subtask touches
}

Example:

hive_create_epic({
  epic_title: "User Authentication",
  epic_description: "OAuth 2.0 implementation with refresh tokens",
  subtasks: [
    { 
      title: "Create auth schema", 
      priority: 2,
      files: ["src/auth/schema.ts"]
    },
    { 
      title: "Implement OAuth flow",
      priority: 2,
      files: ["src/auth/oauth.ts", "src/auth/tokens.ts"]
    },
    {
      title: "Add token refresh logic",
      priority: 1,
      files: ["src/auth/refresh.ts"]
    }
  ]
})

Returns: { epic_id: "bd-123", subtask_ids: ["bd-123.1", "bd-123.2", ...] }

hive_query

Query cells with filters. Replaces legacy bd list, bd ready, bd wip commands.

Parameters:

Parameter	Type	Required	Description
`status`	`"open" \| "in_progress" \| "blocked" \| "closed"`	❌	Filter by status
`type`	`"bug" \| "feature" \| "task" \| "epic" \| "chore"`	❌	Filter by type
`ready`	boolean	❌	Only unblocked cells
`limit`	number	❌	Max results

Example:

// Get all in-progress cells
hive_query({ status: "in_progress" })

// Get next ready cell
hive_query({ ready: true, limit: 1 })

// Get all open bugs
hive_query({ type: "bug", status: "open" })

Returns: Array of cells matching filters.

hive_update

Update cell status, description, or priority.

Parameters:

Parameter	Type	Required	Description
`id`	string	✅	Cell ID (e.g., `"bd-123"`)
`status`	`"open" \| "in_progress" \| "blocked" \| "closed"`	❌	New status
`description`	string	❌	New description
`priority`	0-3	❌	New priority

Example:

hive_update({
  id: "bd-123",
  status: "blocked",
  description: "Blocked: waiting for API schema from bd-122"
})

hive_close

Close a cell with a reason. Prefer this over hive_update for closure tracking.

Parameters:

Parameter	Type	Required	Description
`id`	string	✅	Cell ID
`reason`	string	✅	Closure reason

Example:

hive_close({
  id: "bd-123",
  reason: "Done: OAuth flow implemented and tested"
})

hive_start

Mark a cell as in-progress. Sets status: "in_progress".

Parameters:

Parameter	Type	Required	Description
`id`	string	✅	Cell ID

Example:

hive_start({ id: "bd-123" })

hive_ready

Get the next ready cell (unblocked, highest priority).

Parameters: None

Example:

hive_ready()
// Returns: { id: "bd-125", title: "...", priority: 0, ... }

hive_sync

Sync cells to git. MANDATORY before ending a session.

Parameters:

Parameter	Type	Required	Description
`auto_pull`	boolean	❌	Pull before push (default: `true`)

Example:

hive_sync()
// Runs: git add .hive && git commit && git pull && git push

Critical: Always call this at session end. Changes not synced are lost.

hive_link_thread

Add metadata linking cell to Agent Mail thread.

Parameters:

Parameter	Type	Required	Description
`cell_id`	string	✅	Cell ID
`thread_id`	string	✅	Thread ID from Agent Mail

Example:

hive_link_thread({
  cell_id: "bd-123",
  thread_id: "msg-thread-42"
})

Session Workflow

// Session start
hive_ready()                              // What's next?
hive_query({ status: "in_progress" })     // What's mid-flight?

// Start work
hive_start({ id: "bd-123" })

// Update if needed
hive_update({
  id: "bd-123",
  description: "Updated scope to include refresh tokens"
})

// Complete
hive_close({
  id: "bd-123",
  reason: "Done: OAuth implemented with refresh"
})

// Session end (MANDATORY)
hive_sync()

Next Steps

Swarm Tools - Task decomposition and parallel coordination
Skills Tools - Knowledge injection system

Hive Tools

On this page