Chapter: getting-started (docs/getting-started.md)
Getting Started
This guide will help you set up the Hive and build your first agent.
Prerequisites
- Python 3.11+ (Download) - Python 3.12 or 3.13 recommended
- pip - Package installer for Python (comes with Python)
- git - Version control
- Claude Code (Install) - Optional, for using building skills
Quick Start
The fastest way to get started:
Linux / macOS:
1. Clone the repository
git clone https://github.com/aden-hive/hive.git
cd hive2. Run automated setup
./quickstart.sh3. Verify installation (optional, quickstart.sh already verifies)
uv run python -c "import framework; import aden_tools; print('✓ Setup complete')"Windows (PowerShell):
1. Clone the repository
git clone https://github.com/aden-hive/hive.git
cd hive2. Run automated setup
.\quickstart.ps13. Verify installation (optional, quickstart.ps1 already verifies)
uv run python -c "import framework; import aden_tools; print('Setup complete')"Note: On Windows, running.\quickstart.ps1requires PowerShell 5.1+. If you see a "running scripts is disabled" error, runSet-ExecutionPolicy -Scope Process -ExecutionPolicy Bypassfirst. Alternatively, use WSL — see environment-setup.md for details.
Building Your First Agent
Agents are not included by default in a fresh clone.
Agents are created using Claude Code or by manual creation in the
exports/ directory. Until an agent exists, agent validation and run
commands will fail.
Option 1: Using Claude Code Skills (Recommended)
This is the recommended way to create your first agent.
Requirements
- Anthropic (Claude) API access
- Claude Code CLI installed
- Unix-based shell (macOS, Linux, or Windows via WSL)
Setup already done via quickstart.sh above
Start Claude Code and build an agent
Use the files-tools initialize_and_build_agent toolFollow the interactive prompts to:
1. Define your agent's goal
2. Design the workflow (nodes and edges)
3. Generate the agent package
4. Test the agent
Option 2: Create Agent Manually
Note: The exports/ directory is where your agents are created. It is not included in the repository (gitignored) because agents are user-generated via Claude Code skills or created manually.Create exports directory if it doesn't exist
mkdir -p exports/my_agentCreate your agent structure
cd exports/my_agent
Create agent.json, tools.py, README.md (see developer-guide.md for structure)
Validate the agent
PYTHONPATH=exports uv run python -m my_agent validateOption 3: Manual Code-First (Minimal Example)
If you prefer to start with code rather than CLI wizards, check out the manual agent example:
View the minimal example
cat core/examples/manual_agent.pyRun it (no API keys required)
uv run python core/examples/manual_agent.pyThis demonstrates the core runtime loop using pure Python functions, skipping the complexity of LLM setup and file-based configuration.
Project Structure
hive/
├── core/ # Core Framework
│ ├── framework/ # Agent runtime, graph executor
│ │ ├── builder/ # Agent builder utilities
│ │ ├── credentials/ # Credential management
│ │ ├── graph/ # GraphExecutor - executes node graphs
│ │ ├── llm/ # LLM provider integrations
│ │ ├── mcp/ # MCP server integration
│ │ ├── runner/ # AgentRunner - loads and runs agents
│ │ ├── runtime/ # Runtime environment
│ │ ├── schemas/ # Data schemas
│ │ ├── storage/ # File-based persistence
│ │ ├── testing/ # Testing utilities
│ │ └── tui/ # Terminal UI dashboard
│ └── pyproject.toml # Package metadata
│
├── tools/ # MCP Tools Package
│ ├── mcp_server.py # MCP server entry point
│ └── src/aden_tools/ # Tools for agent capabilities
│ └── tools/ # Individual tool implementations
│ ├── web_search_tool/
│ ├── web_scrape_tool/
│ └── file_system_toolkits/
│
├── exports/ # Agent Packages (user-generated, not in repo)
│ └── your_agent/ # Your agents created via files-tools workflow
│
├── examples/
│ └── templates/ # Pre-built template agents
│
└── docs/ # DocumentationRunning an Agent
Launch the web dashboard in your browser
hive openRun a specific agent
hive run exports/my_agent --input '{"task": "Your input here"}'API Keys Setup
For running agents with real LLMs:
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here" # Optional
export OPENROUTER_API_KEY="your-key-here" # Optional, for OpenRouter models
export HIVE_API_KEY="your-key-here" # Optional, for Hive LLM
export BRAVE_SEARCH_API_KEY="your-key-here" # Optional, for web searchGet your API keys:
- Anthropic: console.anthropic.com
- OpenAI: platform.openai.com
- OpenRouter: openrouter.ai/keys
- Hive LLM: Hive Discord
- Brave Search: brave.com/search/api
Quickstart can configure OpenRouter and Hive LLM for you interactively. See configuration.md for the full configuration examples.
Testing Your Agent
Run tests
PYTHONPATH=exports uv run python -m my_agent testRun with specific test type
PYTHONPATH=exports uv run python -m my_agent test --type constraint
PYTHONPATH=exports uv run python -m my_agent test --type successNext Steps
1. Dashboard: Run hive open to launch the web dashboard
2. Detailed Setup: See environment-setup.md
3. Developer Guide: See developer-guide.md
4. Build Agents: Use the files-tools initialize_and_build_agent tool in Claude Code
5. Custom Tools: Learn to integrate MCP servers
6. Join Community: Discord
Troubleshooting
ModuleNotFoundError: No module named 'framework'
Reinstall framework package
cd core
uv pip install -e .ModuleNotFoundError: No module named 'aden_tools'
Reinstall tools package
cd tools
uv pip install -e .LLM API Errors
Verify API key is set
echo $ANTHROPIC_API_KEY
echo $OPENROUTER_API_KEY
echo $HIVE_API_KEYPackage Installation Issues
Remove and reinstall
pip uninstall -y framework tools
./quickstart.shGetting Help
- Documentation: Check the /docs folder
- Issues: github.com/adenhq/hive/issues
- Discord: discord.com/invite/MXE49hrKDk
- Build Agents: Use the files-tools workflow to create agents