A self-extending AI agent that writes its own tools at runtime.
Hydra ships with a handful of seed tools and grows from there. Ask it to do something its toolbox doesn't cover, and it writes the tool, validates it, hot-loads it, runs it, and keeps it for next time. Over months of use, the toolbox becomes a reflection of how you work.
User request
│
▼
┌──────────────────────────────────┐
│ Is there already a tool for it? │──── yes ──► run_tool ──► response
└──────────────┬───────────────────┘
│ no
▼
┌──────────────────────────────────┐
│ create_tool │
│ - LLM writes Python │
│ - validate + save to disk │
│ - hot-load into registry │
└──────────────┬───────────────────┘
│
▼
run_tool ──► response
you> Get me the top 3 Hacker News stories.
hydra> (scrape_hacker_news already exists — running it)
1. [159] Fixing a 20-year-old bug in Enlightenment E16
https://iczelia.net/posts/e16-20-year-old-bug/
...
you> Now translate the first headline to German.
hydra> I don't have a translate tool yet. Creating translate_text ...
> Tool created and loaded.
"Einen 20 Jahre alten Bug in Enlightenment E16 beheben"
you> Translate the next headline too.
hydra> (translate_text already exists — running it)
...
git clone https://github.com/kai-linux/hydra.git
cd hydra
pip install -e .
export ANTHROPIC_API_KEY="sk-ant-..."
hydraOn first run Hydra copies a small set of seed tools (fetch_webpage, wiki_summary, currency_convert, scrape_hacker_news, hash_text, url_unshorten) into ~/.hydra/tools/ so the REPL is useful immediately. From there, every new tool the agent writes lands in the same directory.
hydraREPL commands:
/tools— list all loaded tools/clear— clear conversation history/quit— exit
import asyncio
from hydra.agent import create_hydra_agent
async def main():
agent, deps = create_hydra_agent()
result = await agent.run(
"Convert 100 USD to EUR using current rates",
deps=deps,
)
print(result.output)
# Follow-up in the same session reuses the tool
result2 = await agent.run(
"Now convert 50 GBP to JPY",
deps=deps,
message_history=result.all_messages(),
)
print(result2.output)
asyncio.run(main())Expose every tool Hydra has written to other agents (Claude Desktop, Claude Code, PydanticAI, …):
hydra serve # stdio (Claude Desktop)
hydra serve --transport sse --port 8000 # SSE (remote clients)Add to claude_desktop_config.json:
{
"mcpServers": {
"hydra": {
"command": "hydra",
"args": ["serve"]
}
}
}Claude Desktop now has access to every tool Hydra owns.
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerHTTP
hydra = MCPServerHTTP(url="http://localhost:8000/sse")
agent = Agent("anthropic:claude-sonnet-4-20250514", mcp_servers=[hydra])
async with agent.run_mcp_servers():
result = await agent.run("List and run available Hydra tools")hydra/
├── agent.py # PydanticAI agent with the meta-tools
├── tool_generator.py # LLM code generation + self-healing retries
├── tool_store.py # Persistence, dynamic import, seeding
├── executor.py # Sync/async execution, subprocess sandbox
├── _runner.py # Sandbox subprocess entry point
├── mcp_server.py # FastMCP server exposing the toolbox
├── cli.py # Rich interactive REPL
└── seed_tools/ # Ships with the repo, copied on first run
├── fetch_webpage.py
├── wiki_summary.py
├── currency_convert.py
├── scrape_hacker_news.py
├── hash_text.py
└── url_unshorten.py
~/.hydra/tools/ # Your personal, growing toolbox
| Tool | Description |
|---|---|
list_tools |
Show all currently loaded tools |
create_tool |
Generate a new tool via LLM |
run_tool |
Execute a tool by name |
view_tool_source |
Inspect a tool's source code |
remove_tool |
Delete a tool permanently |
- Sync or async. A generated
run()can bedeforasync def. Async tools are awaited automatically. - Structured returns.
run()may return astr,dict,list, or pydanticBaseModel. Non-strings are serialized to JSON for the agent. - Self-healing retries. If a tool raises at runtime, the agent feeds the code + traceback back to the LLM, rewrites the tool, saves the new version, and retries (default: 2 retries).
Generated tools run in a subprocess sandbox by default:
- Each invocation spawns a fresh subprocess with a timeout (30s default)
- Crashes in the child do not affect the parent
- Pre-load validation: syntax check,
run()presence, blocklist for obvious exfil patterns
Limits you should know about:
- The subprocess inherits your filesystem and network access. This contains runaway code, not malicious code. Treat it like running code from a gist you trust — not code from strangers.
- The blocklist is substring-based and trivially bypassed by a determined adversary. Do not expose Hydra to untrusted user input.
Dev escape hatch: HYDRA_UNSAFE_INPROCESS=1 skips the sandbox and runs tools in-process (faster, but no isolation). Use only when iterating locally.
hydra --tools-dir /path/to/my/tools # point at a different toolbox
hydra --model anthropic:claude-sonnet-4-20250514
hydra list-tools # list without entering the REPL
HYDRA_NO_SEED=1 hydra # skip first-run seed copy
HYDRA_UNSAFE_INPROCESS=1 hydra # run tools in-process (no sandbox)pip install -e ".[dev]"
pytest tests/
ruff check hydra/ tests/Standard function calling needs you to define tools upfront. Hydra's tools are emergent: they don't exist until the agent needs them, and they persist once they do. The agent is both the user and the author of its own API surface. Usage patterns shape capabilities.
See NORTH_STAR.md for the vision, STRATEGY.md for positioning, and PLAN.md for the roadmap.
MIT