Hydra

Hydra

A self-extending AI agent that writes its own tools at runtime.

[](https://github.com/kai-linux/hydra/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](./LICENSE) [](https://ai.pydantic.dev/) [](https://modelcontextprotocol.io/)

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.

The loop

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

Example session

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)
       ...

Quick start

git clone https://github.com/kai-linux/hydra.git
cd hydra
pip install -e .

export ANTHROPIC_API_KEY="sk-ant-..."
hydra

On 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.

Usage

Interactive REPL

hydra

REPL commands:

• /tools — list all loaded tools
• /clear — clear conversation history
• /quit — exit

As a library

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())

MCP server mode

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)

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hydra": {
      "command": "hydra",
      "args": ["serve"]
    }
  }
}

Claude Desktop now has access to every tool Hydra owns.

From another PydanticAI agent

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")

Architecture

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

Meta-tools

| 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 |

Execution model

• Sync or async. A generated run() can be def or async def. Async tools are awaited automatically.
• Structured returns. run() may return a str, dict, list, or pydantic BaseModel. 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).

Safety

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.

Configuration

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)

Development

pip install -e ".[dev]"
pytest tests/
ruff check hydra/ tests/

Why not just function calling?

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 [NORTHSTAR.md](NORTHSTAR.md) for the vision, [STRATEGY.md](STRATEGY.md) for positioning, and [PLAN.md](PLAN.md) for the roadmap.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kai-linux
• Source: kai-linux/hydra
• License: MIT

Install and usage instructions live in the source repository linked above.