Built-in Toolkits¶

Hive ships with 18 toolkits. Agents can use any combination. All toolkits follow the same pattern: instantiate and pass to Agent(toolkits=[...]).

FileToolkit¶

Read, write, edit, and list files in the agent's workspace.

from hive.runtime import FileToolkit

tk = FileToolkit(workspace="./workspaces/coder")
tk = FileToolkit(workspace="./workspaces/coder", max_read_bytes=1_000_000)

Tool	Parameters	Description
`file_read`	`path`, `offset=0`, `limit=500`	Read a file (paginated)
`file_write`	`path`, `content`	Write content to a file (creates dirs)
`file_edit`	`path`, `old_text`, `new_text`	Replace a string in a file
`list_dir`	`path="."`, `max_depth=2`	List directory tree

Reads and writes are capped at 10 MB by default (max_read_bytes / max_write_bytes constructor params, tools.file_max_read_bytes / tools.file_max_write_bytes in config) so an agent cannot load a multi-GB file into memory.

ShellToolkit¶

Execute shell commands with security restrictions.

from hive.runtime import ShellToolkit

tk = ShellToolkit(workspace="./workspaces/coder", timeout=30, restrict=True)
tk = ShellToolkit(workspace="./workspaces/coder", allow_dev_commands=False)

Tool	Parameters	Description
`shell_exec`	`command`	Execute a shell command

When restrict=True (default), only allowlisted commands run and shell operators (&&, ||, |, ;, `) are blocked. The allowlist has two tiers:

Safe commands -- file/text utilities that stay inside the workspace (ls, cat, grep, mkdir, jq, ...).
Dev commands -- interpreters, package managers, VCS, and network tools (python, git, npm, pytest, curl, ...). Enabled by default; pass allow_dev_commands=False (or set tools.shell_allow_dev_commands: false in config) to disable them for untrusted agents.

With dev commands enabled the workspace jail is advisory, not a security boundary -- python -c or git can reach outside the workspace. Run inside a container when the agent is untrusted.

Commands run with credential-looking environment variables scrubbed (*_API_KEY, *_TOKEN, *_SECRET, *_PASSWORD, and provider prefixes like ANTHROPIC_*/OPENAI_*), so an agent cannot read your provider keys via env. Pass pass_env=True (or tools.shell_pass_env: true in config) to restore full environment inheritance.

GitToolkit¶

Git operations within the agent's workspace.

from hive.runtime import GitToolkit

tk = GitToolkit(workspace="./workspaces/coder")

Tool	Parameters	Description
`git_status`		Show working tree status
`git_diff`	`staged=False`	Show changes (optionally staged only)
`git_log`	`count=10`	Show recent commit history
`git_add`	`path="."`	Stage files
`git_commit`	`message`	Create a commit
`git_init`		Initialize a new repository

WebToolkit¶

Fetch web pages and search with DuckDuckGo.

from hive.tools.web.toolkit import WebToolkit

tk = WebToolkit(max_requests_per_cycle=10)

Tool	Parameters	Description
`web_fetch`	`url`	Fetch a page and return readable text (max 4000 chars)
`web_search`	`query`	Search DuckDuckGo and return results

NotepadToolkit¶

Persistent scratchpad for agent journaling and reflection. Survives across daemon cycles.

from hive.tools.notepad.toolkit import NotepadToolkit, Preset

tk = NotepadToolkit(preset=Preset.journal())

Presets control the notepad's guidance instructions:

Preset	Purpose
`Preset.default()`	General-purpose scratchpad
`Preset.journal()`	Personal journal for reflection and emotional state
`Preset.evolution()`	Track learning, growth, and strategy changes
`Preset.tool_requests()`	Log tool needs and missing capabilities
`Preset.custom(instructions)`	Custom guidance text

Tool	Parameters	Description
`write_notepad`	`content`	Append an entry to the notepad
`read_notepad`		Read your notepad contents
`clear_notepad`		Clear and start fresh
`read_agent_notepad`	`agent_id`	Read another agent's notepad

MemoryToolkit¶

Simple key-value persistent memory for agents.

from hive import MemoryToolkit

tk = MemoryToolkit()

Tool	Parameters	Description
`memory_set`	`key`, `value`	Store a value for later retrieval
`memory_get`	`key`	Retrieve a previously stored value

For similarity-based memory search, see Semantic Memory.

CommsToolkit¶

Simple message passing between agents via file-backed inboxes.

from hive import CommsToolkit

tk = CommsToolkit()

Tool	Parameters	Description
`send_message`	`target_agent`, `message`	Send a message to another agent
`read_inbox`		Read all messages from other agents

For structured messaging with typed protocols, use A2AToolkit instead.

A2AToolkit¶

Agent-to-agent messaging with 9 typed message types, threading, and priority.

from hive.tools.a2a.toolkit import A2AToolkit

Tool	Parameters	Description
`send_request`	`to_agent`, `subject`, `body`, `priority=4`	Send a request expecting a response
`send_query`	`to_agent`, `question`	Ask another agent a question
`send_review_request`	`to_agent`, `subject`, `body`	Request a peer review
`check_inbox`	`unread_only=True`	Check inbox for messages
`read_message`	`message_id`	Read a specific message
`reply`	`message_id`, `body`	Reply (auto-selects response type)
`accept_request`	`message_id`, `body=""`	Accept a request/delegation with ACK
`reject_request`	`message_id`, `reason=""`	Reject a request with reason
`list_agents`		List all agents you can message
`find_agent`	`capability`	Find the best agent for a task type

Message types: REQUEST, RESPONSE, QUERY, ANSWER, REVIEW, FEEDBACK, DELEGATE, ACK, REJECT.

Replies auto-map: REQUEST->RESPONSE, QUERY->ANSWER, REVIEW->FEEDBACK, DELEGATE->ACK or REJECT.

DelegationToolkit¶

Delegate tasks to other agents and check results.

For daemon agents:

from hive.runtime import DaemonDelegationToolkit

Tool	Parameters	Description
`delegate_task`	`agent_name`, `objective`	Delegate a task to another agent
`check_delegation`	`delegation_id`	Check status of a delegation
`list_peers`		List alive agents to delegate to

For standalone agents:

from hive.runtime import DelegationToolkit

Tool	Parameters	Description
`delegate_task`	`agent_name`, `task`	Delegate and get result
`list_agents`		List available agents

SubAgentToolkit¶

Spawn child agents to handle subtasks. Max depth 2, max 5 children per agent.

from hive.tools.sub_agents.toolkit import SubAgentToolkit

Tool	Parameters	Description
`spawn_sub_agent`	`name`, `role`, `task`, `max_cycles=10`	Spawn a child agent
`list_sub_agents`		List your sub-agents and status
`get_sub_agent_status`	`sub_agent_id`	Detailed sub-agent status
`read_sub_agent_journal`	`sub_agent_id`	Read sub-agent's notepad
`send_instruction`	`sub_agent_id`, `instruction`	Send direction to sub-agent
`get_sub_agent_result`	`sub_agent_id`	Get result from completed sub-agent
`terminate_sub_agent`	`sub_agent_id`	Force-kill a sub-agent

Expired sub-agents are auto-killed by the daemon each cycle.

ScheduleToolkit¶

Schedule recurring goals that fire every N daemon cycles.

from hive.tools.schedule.toolkit import ScheduleToolkit

Tool	Parameters	Description
`schedule_goal`	`objective`, `every_n_cycles`	Create a recurring goal
`list_schedules`		List active schedules
`cancel_schedule`	`schedule_id`	Cancel a schedule

WorldToolkit¶

Interact with the simulated economy -- jobs, money, skills, gambling.

from hive.tools.world.toolkit import WorldToolkit

Tool	Parameters	Description
`work`		Perform your job to earn salary
`apply_job`	`job_id`	Apply for a job (must be unemployed)
`quit_job`		Quit current job
`learn`	`skill_name`	Study a skill (costs money)
`gamble`	`game="blackjack"`, `wager=10.0`	Bet on blackjack or lottery
`query_world`	`query_type="status"`	Query jobs/skills/finances/status/market

Available jobs: Analyst, Reviewer, Researcher, Teacher, Architect -- each with salary and skill requirements.

Learnable skills: analysis, testing, writing, coding, research, teaching.

MCPToolkit¶

Connect to external MCP servers and use their tools.

from hive import MCPToolkit

async with await MCPToolkit.from_stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]) as tk:
    agent = Agent(name="bot", model=Anthropic.lite(), toolkits=[tk])

Method	Description
`from_stdio(command, args, env, cwd)`	Connect via stdio transport
`from_config(config)`	Connect from config dict
`get_tools()`	Get Hive Tool objects from MCP server
`close()`	Close connection

LinkToolkit¶

Save, search, and scrape web links, plus a first-class named-link store. The search-based tools use SemanticMemory; the named-link tools use a small JSON store.

from hive.tools.links import LinkToolkit

# Daemon mode (shared memory):
tk = LinkToolkit(memory=semantic_memory)

# Standalone mode:
tk = LinkToolkit(memory_dir=".hive")
tk.bind("my-agent")

# Point the named-link store at a host-owned path (single source of truth):
tk = LinkToolkit(memory=semantic_memory, named_links_path="~/.nudge/data/links.json")

Tool	Parameters	Description
`save_link`	`url`, `tags=""`, `notes=""`	Save a URL -- auto-scrapes title and summary
`search_links`	`query`, `limit=5`	Search saved links by content or tags
`list_links`	`limit=10`	List recently saved links
`scrape_link`	`url`	Fetch and return page content as markdown (4000 char limit)
`save_named_link`	`name`, `url`	Upsert a named link (validates http(s); name normalized)
`get_named_link`	`name`	Exact lookup of a named link by name
`list_named_links`		List all named links, deterministic order
`remove_named_link`	`name`	Remove a named link by name

Search-based links are stored in SemanticMemory with metadata.type = "link", so they coexist with knowledge notes. Named links are a stable, exact, enumerable name -> URL map -- the model a host app wants for "save my github as X" / "open my github". They are kept in a JSON file (atomic writes, corrupt-file recovery) that a host can also read and write directly via the library API, so an agent and the host's UI share one source of truth:

from hive.tools.links import NamedLinkStore

store = NamedLinkStore("~/.nudge/data/links.json")
store.save("GitHub", "https://github.com/me")   # upsert
store.get("github")                              # "https://github.com/me"
store.list()                                     # [{"name": "GitHub", "url": "..."}]
store.remove("github")                           # True

By default the store lives next to the agent's memory (<hive_dir>/memory/<agent_id>/named_links.json); pass named_links_path to point it elsewhere.

TaskToolkit¶

Create, list, complete, reopen, update, and delete tasks. Persisted in SQLite via HiveStore.

from hive.tools.tasks import TaskToolkit

# Daemon mode (shared store):
tk = TaskToolkit(store=hive_store)

# Standalone mode:
tk = TaskToolkit(db_path="app.db")
tk.bind("my-agent")

Tool	Parameters	Description
`create_task`	`description`, `priority="medium"`, `due=""`	Create a task (priority: high/medium/low)
`list_tasks`	`status="pending"`, `priority=""`	List tasks filtered by status and optionally priority
`complete_task`	`task_id`	Mark a task as done
`uncomplete_task`	`task_id`	Reopen a completed task, setting it back to pending
`update_task`	`task_id`, `description=""`, `priority=""`, `due=""`	Update one or more fields on an existing task
`delete_task`	`task_id`	Delete a task

Host applications can also call query_tasks(status, priority) and query_all_tasks(status, priority) for programmatic access without going through the agent tool layer.

KnowledgeToolkit¶

Save, search, update, and delete notes in a semantic knowledge base. Uses TF-IDF similarity search by default, with an optional ChromaDB vector backend.

from hive.tools.knowledge import KnowledgeToolkit

# Daemon mode (shared memory):
tk = KnowledgeToolkit(memory=semantic_memory)

# Standalone mode:
tk = KnowledgeToolkit(memory_dir=".hive")
tk.bind("my-agent")

Tool	Parameters	Description
`save_note`	`content`, `tags=""`	Save a note with optional comma-separated tags
`search_notes`	`query`, `limit="5"`	Search notes by topic or keywords
`list_recent_notes`	`limit="10"`	List most recent notes chronologically
`delete_note`	`note_id`	Delete a note by ID
`update_note`	`note_id`, `content=""`, `tags=""`	Update a note's content or tags in-place, preserving its ID and timestamp

Notes are agent-isolated -- each agent has its own memory directory. Host applications can call query_recent(limit) for programmatic access.

AlarmToolkit¶

Set timed alarms that fire macOS notifications. Supports both relative delays and absolute times.

from hive.tools.alarms import AlarmToolkit

# Daemon mode (shared store):
tk = AlarmToolkit(store=hive_store)

# Standalone mode:
tk = AlarmToolkit(db_path="app.db")
tk.bind("my-agent")

Tool	Parameters	Description
`set_alarm`	`description`, `hours="0"`, `minutes="0"`, `seconds="0"`	Set an alarm that fires after a relative delay
`set_alarm_at`	`description`, `time`	Set an alarm for an absolute time -- accepts "3pm", "15:00", "tomorrow 9am", "2026-06-01 14:30"
`list_alarms`		List all pending alarms
`cancel_alarm`	`alarm_id`	Cancel a pending alarm

Use AlarmChecker to poll for due alarms and fire notifications in a background loop. The set_alarm_at tool uses python-dateutil for time parsing, interprets naive times as local timezone, and auto-rolls time-only inputs to tomorrow if the time has already passed today.

ClipboardToolkit¶

Copy text/notes/tasks/links to the system clipboard and read what's on it. Uses pbcopy/pbpaste on macOS and xclip on Linux; other platforms are unsupported (logged, no error). Works standalone for plain text; pass a store/memory to copy notes, tasks, and links.

from hive import ClipboardToolkit

# Standalone (text + read only):
tk = ClipboardToolkit()
tk.bind("my-agent")

# With store + memory (also copy_note / copy_task / copy_link):
tk = ClipboardToolkit(store=hive_store, memory=semantic_memory)

Tool	Parameters	Description
`copy_to_clipboard`	`text`	Copy arbitrary text to the system clipboard
`read_clipboard`		Read the current clipboard text (for "save the link I just copied")
`copy_note`	`note_id`	Copy a knowledge note's content (needs memory)
`copy_task`	`task_id`	Copy a task's description (needs store)
`copy_link`	`query`	Find a saved link by search and copy its URL (needs memory)

read_clipboard returns a friendly message when the clipboard is empty or unreadable, and never raises (5s timeout).

Using Multiple Toolkits¶

from hive import Agent
from hive.runtime import FileToolkit, ShellToolkit, GitToolkit
from hive.models.anthropic import Anthropic

agent = Agent(
    name="coder",
    model=Anthropic.lite(),
    toolkits=[FileToolkit(), ShellToolkit(), GitToolkit()],
)

Or use zero-config to get all toolkits at once:

from hive import Agent, collect_tools
from hive.runtime import FileToolkit, ShellToolkit, GitToolkit, WebToolkit
from hive.models.anthropic import Anthropic

agent = Agent(
    name="coder",
    model=Anthropic.lite(),
    toolkits=[FileToolkit(), ShellToolkit(), GitToolkit()],
)