◆ concepts · tools

Built-in tools.

50+ tools ship with Kuzy. Below: every category, every entry mapped to a real implementation in venture_agent/core/tools/. Add anything else via MCP.

Shell + filesystem

run_shell

Runs bash/zsh commands. Streams stdout/stderr back into the agent loop with a 120s default timeout.

bash_background

Async shell — fires a long-running command and lets the agent poll for output later. Good for dev servers, builds, tail -f.

run_code

Executes Python. Inside Docker if available (no network, read-only fs, 512MB / 1 CPU cap). Falls back to direct subprocess with a loud warning.

read_file / write_file

Read/write text and binary files. PDF page ranges supported on read.

edit_file / multi_edit

Anchored find-and-replace with uniqueness checks. Multi-edit runs several edits atomically per file.

apply_patch

Apply a unified diff to one or more files in one shot.

list_dir / find_files / glob / grep

Walk and search the workspace. All results capped at 100 to keep the agent context lean.

cd / pwd

Move the agent's working directory mid-session.

delete_file

Safe delete with sanity checks — refuses to nuke ~/ or the root of a tracked git repo.

Web + browser

web_search

Live web search via Serper (5 results by default). Cites sources.

web_fetch

Plain HTTP GET + readable-text extraction. SSRF-blocked at the URL layer (no localhost, no 10./172./192./169.254/file://).

web_fetch_ai

Same fetch, but pipes the HTML through a vision/LLM step to extract structured data.

browse_web

Headless Chromium via Playwright. Multi-step (8 steps max per call), screenshots, vision-capable.

firecrawl_scrape / firecrawl_search

Web-to-markdown and web-search via Firecrawl. Useful when raw fetch chokes on JavaScript-rendered pages.

see_image

Vision model analyzes a local or remote image (screenshot, photo, design mock). Kuzy does not generate images.

data_extract

Runs an Apify actor against a target URL. 25 credits per call — Kuzy will ask before invoking.

http_request

Raw HTTP (GET/POST/PUT/PATCH) with auth headers. Use this when nothing higher-level fits.

Code, git, vision

git

Branches, commits, diffs, status, push. Kuzy drafts the work — pushing the PR is on you.

lsp

Go-to-definition, hover, refactor hints from the language server. Polyglot.

visual_review

Auto-critique an HTML page or screenshot. Vision model walks the design and reports concrete issues.

create_pdf

Render an HTML file to PDF via Playwright. Useful for reports, invoices, archive snapshots.

Sub-agents + chains

spawn_agent

Spawns a full background Kuzy worker with all 50+ tools. Plan-gated: 2 (Starter) → 10 (Max) → unlimited (Max 20× BYOK).

check_workers / collect_results / kill_workers

Monitor, harvest results, or stop running workers from the parent session.

pipe_results

Feed one worker's output as the prompt of the next — composable pipelines.

delegate_task / delegate_cli

Lighter delegation: pure thinking (no tools) or a one-shot subprocess agent.

chain_save / chain_run / chain_list

Save a sequence of tool calls as a reusable pseudo-tool. Skills are for procedures; chains are for exact tool recipes.

mixture_of_agents

Run the same prompt through several models in parallel and aggregate. Useful for hard reasoning passes.

Memory + state

memory_save

Persist a structured note (topic + content + category) under ~/.henry/memory/memories/.

memory_recall

Embedding-based similarity search over saved memories.

task_create / task_update / task_list / task_get / task_delete

SQLite-backed task CRUD. Used by the desktop todo board and the agent's own planning.

todowrite

File-backed todo list (JSON) that streams update events to the UI in real time.

set_reminder

Schedules a future self-prompt. Fires when the agent next checks reminders.

evolve

Append a paragraph to a SOUL section — Kuzy's self-documentation about how to handle this user or repo.

record_outcome / recall_outcomes

Tracks which strategies worked for which kinds of task. Cumulative across sessions.

checkpoint_save / checkpoint_restore

Snapshot the current session and rewind to it later. Helpful before risky experiments.

Interaction + system

ask_user

Queues a structured question for the user. The agent waits for an answer file-backed in the next turn.

skill

Load or list playbooks from agent_data/skills/ (built-in: deep-research, landing-page, reddit-commenter, dev-mode) and from .kuzy/skills/ in the current repo.

pbcopy / pbpaste

macOS clipboard — copy a result out, paste content in.

Messaging clients

whatsapp

WhatsApp Web via Neonize. Pair once with a QR code; inbound and outbound messages count against credit + rate limit (5/min default).

telegram

Telegram MTProto via Telethon. Session-based; same rate + credit rules as WhatsApp.

twitter_search / twitter_user_tweets / twitter_user_info

Twitter v2 API. Search, timelines, profile data. 3–8 credits per call depending on call type.

MCP bridge

mcp_list_servers

List Model Context Protocol servers registered in ~/.henry/mcp.json.

mcp_list_tools

List tools exposed by a given MCP server.

mcp_call

Invoke a specific MCP tool with arguments. This is how Slack, Postgres, Stripe, Linear, GitHub etc. become Kuzy tools — drop them in your MCP config.

◆ bring your own (MCP)

Plug anything into Kuzy.

Kuzy speaks the Model Context Protocol. Register an MCP server in ~/.henry/mcp.json and its tools become callable from any session via mcp_call — the agent picks them up on next launch.

1. Register the server

~/.henry/mcp.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp"]
    },
    "linear": {
      "command": "uvx",
      "args": ["mcp-server-linear"]
    },
    "internal-api": {
      "command": "node",
      "args": ["./tools/internal-api.mjs"]
    }
  }
}

2. Restart Kuzy

MCP servers are discovered at launch. Inside a session, ask Kuzy to list them:

bash

kuzy "list every MCP server you can see and the tools each exposes"
> mcp_list_servers: 3 found · stripe (14 tools), linear (6 tools), internal-api (2 tools)

3. Use it

bash

kuzy "refund the last invoice for customer cus_PXa12, then post in #ops"
> mcp_call: stripe.list_invoices(customer="cus_PXa12") → invoice_1Q3p…
> mcp_call: stripe.refund_charge(charge_id="ch_3Q3pAa…")
> mcp_call: slack.post(channel="#ops", text="Refund issued for cus_PXa12 — $182.40")

◆ safety model

What stops things from going sideways.

Code sandbox — run_code uses Docker (python:3.13-slim, no network, read-only fs, 512MB RAM, 1 CPU, 64 pids) when Docker is reachable. Without Docker it falls back to direct subprocess execution and emits a loud warning.
URL safety — every outbound HTTP call is checked. Localhost, 10.x, 172.16–31.x, 192.168.x, 169.254.x, *.local, and file:// are refused before they leave the process.
Outbound rate limit — messaging tools (Telegram, WhatsApp, Slack-via-MCP) are capped at 5 messages/minute per channel by default. Tunable via KUZY_OUTBOUND_MESSAGES_PER_MIN.
Secret scanner — outbound logs are scanned for API keys and tokens before they hit the gateway or telemetry.
Worker quota — concurrent spawn_agent calls are capped by plan (2–10, unlimited on BYOK).
Expensive-tool prompt — high-cost tools (data_extract, browser sessions, large scrapes) ask the user before running.