| name | {{AGENT_NAME_LOWER}}-agent |
| description | Complete guide to using and extending {{AGENT_NAME}} Agent — CLI usage, setup, configuration, spawning additional agents, gateway platforms, skills, voice, tools, profiles, and a concise contributor reference. Load this skill when helping users configure {{AGENT_NAME}}, troubleshoot issues, spawn agent instances, or make code contributions. |
{{AGENT_NAME}} Agent
{{AGENT_NAME}} Agent is an open-source AI agent framework that runs in your terminal, messaging platforms, and IDEs. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. {{AGENT_NAME}} works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 15+ others) and runs on Linux, macOS, and WSL.
What makes {{AGENT_NAME}} different:
- Self-improving through skills — {{AGENT_NAME}} learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
- Persistent memory across sessions — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
- Multi-platform gateway — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 8+ other platforms with full tool access, not just chat.
- Provider-agnostic — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
- Profiles — run multiple independent {{AGENT_NAME}} instances with isolated configs, sessions, skills, and memory.
- Extensible — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.
People use {{AGENT_NAME}} for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access.
This skill helps you work with {{AGENT_NAME}} Agent effectively — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it.
Docs: https://docs.YOUR_AGENT_DOMAIN/docs/
Quick Start
curl -fsSL https://raw.githubusercontent.com/NousResearch/{{AGENT_NAME_LOWER}}-agent/main/scripts/install.sh | bash
opencode
opencode run -q "What is the capital of France?"
{{AGENT_NAME_LOWER}} setup
{{AGENT_NAME_LOWER}} doctor
CLI Reference (DEPRECATED — hermes CLI removed)
The hermes CLI has been removed from the system. All interaction now goes through opencode (the OpenCode CLI). The commands below are historical reference only.
Global Flags (opencode equivalents)
opencode [flags] [command]
--version, -V Show version
--resume, -r SESSION Resume session by ID or title
--continue, -c [NAME] Resume by name, or most recent session
--skills, -s SKILL Preload skills (comma-separate or repeat)
--yolo Skip dangerous command approval
No subcommand defaults to interactive chat.
Chat
opencode [flags]
-q, --query TEXT Single query, non-interactive
-m, --model MODEL Model (e.g. deepseek-v4-flash)
-v, --verbose Verbose output
-Q, --quiet Suppress banner, spinner, tool previews
Configuration
{{AGENT_NAME_LOWER}} setup [section] Interactive wizard (model|terminal|gateway|tools|agent)
{{AGENT_NAME_LOWER}} config View current config
{{AGENT_NAME_LOWER}} config edit Open config in $EDITOR
{{AGENT_NAME_LOWER}} config set KEY VAL Set a config value
{{AGENT_NAME_LOWER}} config path Print config path
{{AGENT_NAME_LOWER}} config check Check for missing/outdated config
{{AGENT_NAME_LOWER}} doctor [--fix] Check dependencies and config
{{AGENT_NAME_LOWER}} status [--all] Show component status
Tools & Skills
{{AGENT_NAME_LOWER}} tools Interactive tool enable/disable (curses UI)
{{AGENT_NAME_LOWER}} tools list Show all tools and status
{{AGENT_NAME_LOWER}} tools enable NAME Enable a toolset
{{AGENT_NAME_LOWER}} tools disable NAME Disable a toolset
{{AGENT_NAME_LOWER}} skills list List installed skills
{{AGENT_NAME_LOWER}} skills search QUERY Search the skills hub
{{AGENT_NAME_LOWER}} skills install ID Install a skill
{{AGENT_NAME_LOWER}} skills inspect ID Preview without installing
{{AGENT_NAME_LOWER}} skills update Update outdated skills
{{AGENT_NAME_LOWER}} skills uninstall N Remove a hub skill
MCP Servers
MCP servers are configured in ~/.config/opencode/opencode.jsonc. Use the opencode native MCP integration.
Gateway (Messaging Platforms)
{{AGENT_NAME_LOWER}} gateway run Start gateway foreground
{{AGENT_NAME_LOWER}} gateway install Install as background service
{{AGENT_NAME_LOWER}} gateway start/stop Control the service
{{AGENT_NAME_LOWER}} gateway restart Restart the service
{{AGENT_NAME_LOWER}} gateway status Check status
{{AGENT_NAME_LOWER}} gateway setup Configure platforms
Sessions
Sessions are managed through opencode's native session system. Use opencode --resume or opencode --continue.
Cron Jobs
Cron jobs are managed through ~/.{{AGENT_NAME_LOWER}}/cron/jobs.json and the launchd cron dispatcher. Edit jobs.json directly or use the Python cron API.
Profiles
Agent profiles live at ~/.config/opencode/agents/*.md. List with ls ~/.config/opencode/agents/.
{{AGENT_NAME_LOWER}} profile list List all profiles
{{AGENT_NAME_LOWER}} profile create NAME Create (--clone, --clone-all, --clone-from)
{{AGENT_NAME_LOWER}} profile use NAME Set sticky default
{{AGENT_NAME_LOWER}} profile delete NAME Delete a profile
{{AGENT_NAME_LOWER}} profile show NAME Show details
Other
{{AGENT_NAME_LOWER}} insights [--days N] Usage analytics
{{AGENT_NAME_LOWER}} update Update to latest version
{{AGENT_NAME_LOWER}} honcho setup/status Honcho memory integration
{{AGENT_NAME_LOWER}} memory setup/status/off Memory provider config
{{AGENT_NAME_LOWER}} acp ACP server (IDE integration)
Slash Commands (In-Session)
Type these during an interactive chat session.
Session Control
/new (/reset) Fresh session
/clear Clear screen + new session (CLI)
/retry Resend last message
/undo Remove last exchange
/title [name] Name the session
/compress Manually compress context
/stop Kill background processes
/rollback [N] Restore filesystem checkpoint
/background <prompt> Run prompt in background
/queue <prompt> Queue for next turn
/resume [name] Resume a named session
Configuration
/config Show config (CLI)
/model [name] Show or change model
/provider Show provider info
/prompt [text] View/set system prompt (CLI)
/personality [name] Set personality
/reasoning [level] Set reasoning (none|low|medium|high|xhigh|show|hide)
/verbose Cycle: off → new → all → verbose
/voice [on|off|tts] Voice mode
/yolo Toggle approval bypass
/skin [name] Change theme (CLI)
/statusbar Toggle status bar (CLI)
Tools & Skills
/tools Manage tools (CLI)
/toolsets List toolsets (CLI)
/skills Search/install skills (CLI)
/skill <name> Load a skill into session
/cron Manage cron jobs (CLI)
/reload-mcp Reload MCP servers
/plugins List plugins (CLI)
Info
/help Show commands
/commands [page] Browse all commands (gateway)
/usage Token usage
/insights [days] Usage analytics
/status Session info (gateway)
/profile Active profile info
Exit
/quit (/exit, /q) Exit CLI
Key Paths & Config
~/.{{AGENT_NAME_LOWER}}/config.yaml Main configuration
~/.{{AGENT_NAME_LOWER}}/.env API keys and secrets
~/.{{AGENT_NAME_LOWER}}/skills/ Installed skills
~/.{{AGENT_NAME_LOWER}}/sessions/ Session transcripts
~/.{{AGENT_NAME_LOWER}}/logs/ Gateway and error logs
~/.{{AGENT_NAME_LOWER}}/auth.json OAuth tokens and credential pools
~/.{{AGENT_NAME_LOWER}}/{{AGENT_NAME_LOWER}}-agent/ Source code (if git-installed)
Profiles use ~/.{{AGENT_NAME_LOWER}}/profiles/<name>/ with the same layout.
Config Sections
Edit with {{AGENT_NAME_LOWER}} config editor{{AGENT_NAME_LOWER}} config set section.key value.
| Section | Key options |
|---|
model | default, provider, base_url, api_key, context_length |
agent | max_turns (90), tool_use_enforcement |
terminal | backend (local/docker/ssh/modal), cwd, timeout (180) |
compression | enabled, threshold (0.50), target_ratio (0.20) |
display | skin, tool_progress, show_reasoning, show_cost |
stt | enabled, provider (local/groq/openai) |
tts | provider (edge/elevenlabs/openai/kokoro/fish) |
memory | memory_enabled, user_profile_enabled, provider |
security | tirith_enabled, website_blocklist |
delegation | model, provider, max_iterations (50) |
smart_model_routing | enabled, cheap_model |
checkpoints | enabled, max_snapshots (50) |
Full config reference: https://docs.YOUR_AGENT_DOMAIN/docs/user-guide/configuration
Providers
18 providers supported. Set via {{AGENT_NAME_LOWER}} modelor{{AGENT_NAME_LOWER}} setup`.
| Provider | Auth | Key env var |
|---|
| OpenRouter | API key | OPENROUTER_API_KEY |
| Anthropic | API key | ANTHROPIC_API_KEY |
| Nous Portal | OAuth | {{AGENT_NAME_LOWER}} login --provider nous` |
| OpenAI Codex | OAuth | {{AGENT_NAME_LOWER}} login --provider openai-codex` |
| GitHub Copilot | Token | COPILOT_GITHUB_TOKEN |
| DeepSeek | API key | DEEPSEEK_API_KEY |
| Hugging Face | Token | HF_TOKEN |
| Z.AI / GLM | API key | GLM_API_KEY |
| MiniMax | API key | MINIMAX_API_KEY |
| Kimi / Moonshot | API key | KIMI_API_KEY |
| Alibaba / DashScope | API key | DASHSCOPE_API_KEY |
| Kilo Code | API key | KILOCODE_API_KEY |
| Custom endpoint | Config | model.base_url + model.api_key in config.yaml |
Plus: AI Gateway, OpenCode Zen, OpenCode Go, MiniMax CN, GitHub Copilot ACP.
Full provider docs: https://docs.YOUR_AGENT_DOMAIN/docs/integrations/providers
Toolsets
Enable/disable via {{AGENT_NAME_LOWER}} tools(interactive) or{{AGENT_NAME_LOWER}} tools enable/disable NAME.
| Toolset | What it provides |
|---|
web | Web search and content extraction |
browser | Browser automation (Browserbase, Camofox, or local Chromium) |
terminal | Shell commands and process management |
file | File read/write/search/patch |
code_execution | Sandboxed Python execution |
vision | Image analysis |
image_gen | AI image generation |
tts | Text-to-speech |
skills | Skill browsing and management |
memory | Persistent cross-session memory |
session_search | Search past conversations |
delegation | Subagent task delegation |
cronjob | Scheduled task management |
clarify | Ask user clarifying questions |
moa | Mixture of Agents (off by default) |
homeassistant | Smart home control (off by default) |
Tool changes take effect on /reset (new session). They do NOT apply mid-conversation to preserve prompt caching.
Voice & Transcription
STT (Voice → Text)
Voice messages from messaging platforms are auto-transcribed.
Provider priority (auto-detected):
- Local faster-whisper — free, no API key:
pip install faster-whisper
- Groq Whisper — free tier: set
GROQ_API_KEY
- OpenAI Whisper — paid: set
VOICE_TOOLS_OPENAI_KEY
Config:
stt:
enabled: true
provider: local
local:
model: base
TTS (Text → Voice)
| Provider | Env var | Free? |
|---|
| Edge TTS | None | Yes (default) |
| ElevenLabs | ELEVENLABS_API_KEY | Free tier |
| OpenAI | VOICE_TOOLS_OPENAI_KEY | Paid |
| Kokoro (local) | None | Free |
| Fish Audio | FISH_AUDIO_API_KEY | Free tier |
Voice commands: /voice on (voice-to-voice), /voice tts (always voice), /voice off.
Spawning Additional {{AGENT_NAME}} Instances
Run additional {{AGENT_NAME}} processes as fully independent subprocesses — separate sessions, tools, and environments.
When to Use This vs delegate_task
| delegate_task | Spawning `{{AGENT_NAME_LOWER}}`` process |
|---|
| Isolation | Separate conversation, shared process | Fully independent process |
| Duration | Minutes (bounded by parent loop) | Hours/days |
| Tool access | Subset of parent's tools | Full tool access |
| Interactive | No | Yes (PTY mode) |
| Use case | Quick parallel subtasks | Long autonomous missions |
One-Shot Mode
terminal(command="opencode run -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)
# Background for long tasks:
terminal(command="opencode run -q 'Set up CI/CD for ~/myapp'", background=true)
Interactive PTY Mode (via tmux)
{{AGENT_NAME}} uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
# Start
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'opencode'", timeout=10)
# Wait for startup, then send a message
terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)
# Read output
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)
# Send follow-up
terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)
# Exit
terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
Multi-Agent Coordination
# Agent A: backend
terminal(command="tmux new-session -d -s backend -x 120 -y 40 '{{AGENT_NAME_LOWER}} -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)
# Agent B: frontend
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 '{{AGENT_NAME_LOWER}} -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)
# Check progress, relay context between them
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
Session Resume
# Resume most recent session
terminal(command="tmux new-session -d -s resumed 'opencode --continue'", timeout=10)
# Resume specific session
terminal(command="tmux new-session -d -s resumed '{{AGENT_NAME_LOWER}} --resume 20260225_143052_a1b2c3'", timeout=10)
Tips
- Prefer
delegate_task for quick subtasks — less overhead than spawning a full process
- Use
-w (worktree mode) when spawning agents that edit code — prevents git conflicts
- Set timeouts for one-shot mode — complex tasks can take 5-10 minutes
- Use
opencode run -q for fire-and-forget — no PTY needed
- Use tmux for interactive sessions — raw PTY mode has
\r vs \n issues with prompt_toolkit
- For scheduled tasks, use the
cronjob tool instead of spawning — handles delivery and retry
Troubleshooting
Voice not working
- Check
stt.enabled: true in config.yaml
- Verify provider:
pip install faster-whisper or set API key
- Restart gateway:
/restart
Tool not available
{{AGENT_NAME_LOWER}} tools` — check if toolset is enabled for your platform- Some tools need env vars (check
.env)
/reset after enabling tools
Model/provider issues
{{AGENT_NAME_LOWER}} doctor — check config and dependencies{{AGENT_NAME_LOWER}} login` — re-authenticate OAuth providers- Check
.env has the right API key
Changes not taking effect
- Tools/skills:
/reset starts a new session with updated toolset
- Config changes:
/restart reloads gateway config
- Code changes: Restart the CLI or gateway process
Skills not showing
{{AGENT_NAME_LOWER}} skills list — verify installed{{AGENT_NAME_LOWER}} skills config — check platform enablement- Load explicitly:
/skill name or {{AGENT_NAME_LOWER}} -s name`
Gateway issues
Check logs first:
grep -i "failed to send\|error" ~/.{{AGENT_NAME_LOWER}}/logs/gateway.log | tail -20
Where to Find Things
| Looking for... | Location |
|---|
| Config options | {{AGENT_NAME_LOWER}} config edit` or Configuration docs |
| Available tools | {{AGENT_NAME_LOWER}} tools list` or Tools reference |
| Slash commands | /help in session or Slash commands reference |
| Skills catalog | {{AGENT_NAME_LOWER}} skills browse or Skills catalog |
| Provider setup | {{AGENT_NAME_LOWER}} model` or Providers guide |
| Platform setup | {{AGENT_NAME_LOWER}} gateway setup or Messaging docs |
| MCP servers | {{AGENT_NAME_LOWER}} mcp list` or MCP guide |
| Profiles | {{AGENT_NAME_LOWER}} profile list` or Profiles docs |
| Cron jobs | {{AGENT_NAME_LOWER}} cron list` or Cron docs |
| Memory | {{AGENT_NAME_LOWER}} memory status` or Memory docs |
| Env variables | {{AGENT_NAME_LOWER}} config env-path` or Env vars reference |
| CLI commands | {{AGENT_NAME_LOWER}} --help or CLI reference |
| Gateway logs | ~/.{{AGENT_NAME_LOWER}}/logs/gateway.log |
| Session files | ~/.{{AGENT_NAME_LOWER}}/sessions/ or {{AGENT_NAME_LOWER}} sessions browse` |
| Source code | ~/.{{AGENT_NAME_LOWER}}/{{AGENT_NAME_LOWER}}-agent/ |
Contributor Quick Reference
For occasional contributors and PR authors. Full developer docs: https://docs.YOUR_AGENT_DOMAIN/docs/developer-guide/
Project Layout
{{AGENT_NAME_LOWER}}-agent/
├── run_agent.py # AIAgent — core conversation loop
├── model_tools.py # Tool discovery and dispatch
├── toolsets.py # Toolset definitions
├── cli.py # Interactive CLI ({{AGENT_NAME}}CLI)
├── {{AGENT_NAME_LOWER}}_state.py # SQLite session store
├── agent/ # Prompt builder, compression, display, adapters
├── {{AGENT_NAME_LOWER}}_cli/ # CLI subcommands, config, setup, commands
│ ├── commands.py # Slash command registry (CommandDef)
│ ├── config.py # DEFAULT_CONFIG, env var definitions
│ └── main.py # CLI entry point and argparse
├── tools/ # One file per tool
│ └── registry.py # Central tool registry
├── gateway/ # Messaging gateway
│ └── platforms/ # Platform adapters (telegram, discord, etc.)
├── cron/ # Job scheduler
├── tests/ # ~3000 pytest tests
└── website/ # Docusaurus docs site
Config: ~/.{{AGENT_NAME_LOWER}}/config.yaml (settings), ~/.{{AGENT_NAME_LOWER}}/.env (API keys).
Adding a Tool (3 files)
1. Create tools/your_tool.py:
import json, os
from tools.registry import registry
def check_requirements() -> bool:
return bool(os.getenv("EXAMPLE_API_KEY"))
def example_tool(param: str, task_id: str = None) -> str:
return json.dumps({"success": True, "data": "..."})
registry.register(
name="example_tool",
toolset="example",
schema={"name": "example_tool", "description": "...", "parameters": {...}},
handler=lambda args, **kw: example_tool(
param=args.get("param", ""), task_id=kw.get("task_id")),
check_fn=check_requirements,
requires_env=["EXAMPLE_API_KEY"],
)
2. Add import in model_tools.py → _discover_tools() list.
3. Add to toolsets.py → _HERMES_CORE_TOOLS list.
All handlers must return JSON strings. Use get_{{AGENT_NAME_LOWER}}_home() for paths, never hardcode ~/.{{AGENT_NAME_LOWER}}.
Adding a Slash Command
- Add
CommandDef to COMMAND_REGISTRY in {{AGENT_NAME_LOWER}}_cli/commands.py
- Add handler in
cli.py → process_command()
- (Optional) Add gateway handler in
gateway/run.py
All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.
Agent Loop (High Level)
run_conversation():
1. Build system prompt
2. Loop while iterations < max:
a. Call LLM (OpenAI-format messages + tool schemas)
b. If tool_calls → dispatch each via handle_function_call() → append results → continue
c. If text response → return
3. Context compression triggers automatically near token limit
Testing
source venv/bin/activate
python -m pytest tests/ -o 'addopts=' -q
python -m pytest tests/tools/ -q
- Tests auto-redirect
DREW_HOME to temp dirs — never touch real ~/.{{AGENT_NAME_LOWER}}/
- Run full suite before pushing any change
- Use
-o 'addopts=' to clear any baked-in pytest flags
Commit Conventions
type: concise subject line
Optional body.
Types: fix:, feat:, refactor:, docs:, chore:
Key Rules
- Never break prompt caching — don't change context, tools, or system prompt mid-conversation
- Message role alternation — never two assistant or two user messages in a row
- Use
get_{{AGENT_NAME_LOWER}}_home() from {{AGENT_NAME_LOWER}}_constants for all paths (profile-safe)
- Config values go in
config.yaml, secrets go in .env
- New tools need a
check_fn so they only appear when requirements are met
