Update agent-workflows skill with error reduction patterns and sanitize hermes-setup.md
This commit is contained in:
shokollm
201
docs/hermes-setup.md
Normal file
201
docs/hermes-setup.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# Hermes Setup Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Hermes is the primary orchestrator and gateway in the Kugetsu system. It handles:
|
||||
|
||||
- Spawning and managing subagents
|
||||
- Message passing between agents
|
||||
- Repository access via Git API
|
||||
- Task delegation and parallelization
|
||||
|
||||
**Key Constraint:** The delegate_task function has a hard limit of 3 concurrent tasks.
|
||||
|
||||
---
|
||||
|
||||
## Installation via Curl Script
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Linux/macOS environment
|
||||
- curl, git, and basic build tools installed
|
||||
- LLM provider API key (for cloud providers)
|
||||
|
||||
### Installation Steps
|
||||
|
||||
```bash
|
||||
# Clone the Hermes repository
|
||||
git clone https://git.example.com/shoko/hermes.git ~/repositories/hermes
|
||||
|
||||
# Run the installation script
|
||||
cd ~/repositories/hermes && ./install.sh
|
||||
|
||||
# Verify installation
|
||||
hermes --version
|
||||
|
||||
# Initialize with non-interactive mode (if config exists)
|
||||
hermes init --non-interactive
|
||||
```
|
||||
Alternative: Direct Download
|
||||
|
||||
```bash
|
||||
curl -L https://git.example.com/shoko/hermes/releases/latest/download/hermes -o ~/.local/bin/hermes
|
||||
chmod +x ~/.local/bin/hermes
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
hermes --version
|
||||
```
|
||||
---
|
||||
|
||||
## Programmatic Configuration
|
||||
|
||||
If you already have an API token, configure Hermes entirely via files and commands.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.hermes/skills ~/.hermes/cache
|
||||
```
|
||||
|
||||
### Configure via .env File
|
||||
|
||||
Create `~/.hermes/.env`:
|
||||
|
||||
```bash
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
OPENROUTER_API_KEY=sk-or-...
|
||||
GITEA_TOKEN=your_token
|
||||
HERMES_DEFAULT_MODEL=openrouter/anthropic/claude-sonnet-4
|
||||
```
|
||||
### Configure via config.yaml
|
||||
|
||||
```yaml
|
||||
hermes:
|
||||
name: kugetsu-orchestrator
|
||||
log_level: info
|
||||
max_parallel_tasks: 3
|
||||
task_timeout: 3600
|
||||
|
||||
gitea:
|
||||
instance: https://git.example.com
|
||||
owner: shoko
|
||||
repo: kugetsu
|
||||
token_env: GITEA_TOKEN
|
||||
|
||||
agents:
|
||||
default_model: openrouter/anthropic/claude-sonnet-4
|
||||
temperature: 0.7
|
||||
thinking_enabled: true
|
||||
```
|
||||
### Automate Configuration with hermes config set
|
||||
|
||||
Set configuration programmatically:
|
||||
|
||||
```bash
|
||||
hermes config set agents.default_model "openrouter/anthropic/claude-sonnet-4"
|
||||
hermes config set agents.temperature 0.7
|
||||
hermes config set gitea.instance "https://git.example.com"
|
||||
hermes config set gitea.owner "shoko"
|
||||
hermes config set gitea.repo "kugetsu"
|
||||
hermes config set opencode.managed_by "hermes"
|
||||
hermes config set opencode.default_mode "agent"
|
||||
hermes config list
|
||||
```
|
||||
## LLM Providers with API Key Only
|
||||
|
||||
These providers work with just an environment variable or API key:
|
||||
|
||||
### OpenRouter (Recommended)
|
||||
|
||||
```bash
|
||||
export OPENROUTER_API_KEY="sk-or-..."
|
||||
hermes config set agents.default_model "openrouter/anthropic/claude-sonnet-4"
|
||||
```
|
||||
Supports: Anthropic, OpenAI, Mistral, Llama, Gemini, and more.
|
||||
|
||||
### Anthropic (Direct)
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
hermes config set agents.default_model "anthropic/claude-sonnet-4"
|
||||
```
|
||||
|
||||
### OpenAI Compatible
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
hermes config set agents.default_model "openai/gpt-4o"
|
||||
```
|
||||
|
||||
### Groq (Fast, Free Tier)
|
||||
|
||||
```bash
|
||||
export GROQ_API_KEY="gsk_..."
|
||||
hermes config set agents.default_model "groq/llama-3.1-70b"
|
||||
```
|
||||
## OpenCode Integration
|
||||
|
||||
OpenCode can be managed by Hermes as an orchestrator-controlled coding agent.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Install OpenCode
|
||||
curl -L https://opencode.ai/install.sh | sh
|
||||
|
||||
# Configure Hermes to manage OpenCode
|
||||
hermes config set opencode.managed_by "hermes"
|
||||
hermes config set opencode.binary_path "~/.opencode/bin/opencode"
|
||||
hermes config set opencode.default_mode "agent"
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
OpenCode runs as a subagent under Hermes:
|
||||
|
||||
```
|
||||
Task: Write a Python script
|
||||
Agent: opencode
|
||||
Model: openrouter/anthropic/claude-sonnet-4
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- Orchestrated: Hermes manages task routing to OpenCode
|
||||
- Consistent Context: Shared cache and session management
|
||||
- Unified Logging: All agent activity flows through Hermes
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
hermes --version
|
||||
|
||||
# List configuration
|
||||
hermes config list
|
||||
|
||||
# Test Gitea connection
|
||||
hermes doctor
|
||||
|
||||
# Run a test task
|
||||
hermes task status
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Config not loading
|
||||
|
||||
```bash
|
||||
hermes --config ~/.hermes/config.yaml config list
|
||||
```
|
||||
|
||||
### API key not found
|
||||
|
||||
```bash
|
||||
export $(cat ~/.hermes/.env | xargs)
|
||||
hermes config list
|
||||
```
|
||||
|
||||
### Gitea connection failed
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: token $GITEA_TOKEN" https://git.example.com/api/v1/user
|
||||
```
|
||||
Reference in New Issue
Block a user