Initial commit: Hermes Agent skills collection
- Trading skills (OKX, dividend, lottery, quantitative) - Creative skills (ASCII art, diagrams, video) - Development skills (GitHub, debugging, TDD) - Research skills (arXiv, blog monitoring) - Productivity skills (email, documents, notes) - MCP integration skills - Custom user skills
This commit is contained in:
Hermes Skills Manager
@@ -0,0 +1,3 @@
|
||||
---
|
||||
description: Skills for spawning and orchestrating autonomous AI coding agents and multi-agent workflows — running independent agent processes, delegating tasks, and coordinating parallel workstreams.
|
||||
---
|
||||
@@ -0,0 +1,745 @@
|
||||
---
|
||||
name: claude-code
|
||||
description: "Delegate coding to Claude Code CLI (features, PRs)."
|
||||
version: 2.2.0
|
||||
author: Hermes Agent + Teknium
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Coding-Agent, Claude, Anthropic, Code-Review, Refactoring, PTY, Automation]
|
||||
related_skills: [codex, hermes-agent, opencode]
|
||||
---
|
||||
|
||||
# Claude Code — Hermes Orchestration Guide
|
||||
|
||||
Delegate coding tasks to [Claude Code](https://code.claude.com/docs/en/cli-reference) (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Install:** `npm install -g @anthropic-ai/claude-code`
|
||||
- **Auth:** run `claude` once to log in (browser OAuth for Pro/Max, or set `ANTHROPIC_API_KEY`)
|
||||
- **Console auth:** `claude auth login --console` for API key billing
|
||||
- **SSO auth:** `claude auth login --sso` for Enterprise
|
||||
- **Check status:** `claude auth status` (JSON) or `claude auth status --text` (human-readable)
|
||||
- **Health check:** `claude doctor` — checks auto-updater and installation health
|
||||
- **Version check:** `claude --version` (requires v2.x+)
|
||||
- **Update:** `claude update` or `claude upgrade`
|
||||
|
||||
## Two Orchestration Modes
|
||||
|
||||
Hermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.
|
||||
|
||||
### Mode 1: Print Mode (`-p`) — Non-Interactive (PREFERRED for most tasks)
|
||||
|
||||
Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
|
||||
|
||||
```
|
||||
terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)
|
||||
```
|
||||
|
||||
**When to use print mode:**
|
||||
- One-shot coding tasks (fix a bug, add a feature, refactor)
|
||||
- CI/CD automation and scripting
|
||||
- Structured data extraction with `--json-schema`
|
||||
- Piped input processing (`cat file | claude -p "analyze this"`)
|
||||
- Any task where you don't need multi-turn conversation
|
||||
|
||||
**Print mode skips ALL interactive dialogs** — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.
|
||||
|
||||
### Mode 2: Interactive PTY via tmux — Multi-Turn Sessions
|
||||
|
||||
Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. **Requires tmux orchestration.**
|
||||
|
||||
```
|
||||
# Start a tmux session
|
||||
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")
|
||||
|
||||
# Launch Claude Code inside it
|
||||
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")
|
||||
|
||||
# Wait for startup, then send your task
|
||||
# (after ~3-5 seconds for the welcome screen)
|
||||
terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")
|
||||
|
||||
# Monitor progress by capturing the pane
|
||||
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")
|
||||
|
||||
# Send follow-up tasks
|
||||
terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")
|
||||
|
||||
# Exit when done
|
||||
terminal(command="tmux send-keys -t claude-work '/exit' Enter")
|
||||
```
|
||||
|
||||
**When to use interactive mode:**
|
||||
- Multi-turn iterative work (refactor → review → fix → test cycle)
|
||||
- Tasks requiring human-in-the-loop decisions
|
||||
- Exploratory coding sessions
|
||||
- When you need to use Claude's slash commands (`/compact`, `/review`, `/model`)
|
||||
|
||||
## PTY Dialog Handling (CRITICAL for Interactive Mode)
|
||||
|
||||
Claude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:
|
||||
|
||||
### Dialog 1: Workspace Trust (first visit to a directory)
|
||||
```
|
||||
❯ 1. Yes, I trust this folder ← DEFAULT (just press Enter)
|
||||
2. No, exit
|
||||
```
|
||||
**Handling:** `tmux send-keys -t <session> Enter` — default selection is correct.
|
||||
|
||||
### Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
|
||||
```
|
||||
❯ 1. No, exit ← DEFAULT (WRONG choice!)
|
||||
2. Yes, I accept
|
||||
```
|
||||
**Handling:** Must navigate DOWN first, then Enter:
|
||||
```
|
||||
tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
|
||||
```
|
||||
|
||||
### Robust Dialog Handling Pattern
|
||||
```
|
||||
# Launch with permissions bypass
|
||||
terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions \"your task\"' Enter")
|
||||
|
||||
# Handle trust dialog (Enter for default "Yes")
|
||||
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")
|
||||
|
||||
# Handle permissions dialog (Down then Enter for "Yes, I accept")
|
||||
terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")
|
||||
|
||||
# Now wait for Claude to work
|
||||
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")
|
||||
```
|
||||
|
||||
**Note:** After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use `--dangerously-skip-permissions`.
|
||||
|
||||
## CLI Subcommands
|
||||
|
||||
| Subcommand | Purpose |
|
||||
|------------|---------|
|
||||
| `claude` | Start interactive REPL |
|
||||
| `claude "query"` | Start REPL with initial prompt |
|
||||
| `claude -p "query"` | Print mode (non-interactive, exits when done) |
|
||||
| `cat file \| claude -p "query"` | Pipe content as stdin context |
|
||||
| `claude -c` | Continue the most recent conversation in this directory |
|
||||
| `claude -r "id"` | Resume a specific session by ID or name |
|
||||
| `claude auth login` | Sign in (add `--console` for API billing, `--sso` for Enterprise) |
|
||||
| `claude auth status` | Check login status (returns JSON; `--text` for human-readable) |
|
||||
| `claude mcp add <name> -- <cmd>` | Add an MCP server |
|
||||
| `claude mcp list` | List configured MCP servers |
|
||||
| `claude mcp remove <name>` | Remove an MCP server |
|
||||
| `claude agents` | List configured agents |
|
||||
| `claude doctor` | Run health checks on installation and auto-updater |
|
||||
| `claude update` / `claude upgrade` | Update Claude Code to latest version |
|
||||
| `claude remote-control` | Start server to control Claude from claude.ai or mobile app |
|
||||
| `claude install [target]` | Install native build (stable, latest, or specific version) |
|
||||
| `claude setup-token` | Set up long-lived auth token (requires subscription) |
|
||||
| `claude plugin` / `claude plugins` | Manage Claude Code plugins |
|
||||
| `claude auto-mode` | Inspect auto mode classifier configuration |
|
||||
|
||||
## Print Mode Deep Dive
|
||||
|
||||
### Structured JSON Output
|
||||
```
|
||||
terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)
|
||||
```
|
||||
|
||||
Returns a JSON object with:
|
||||
```json
|
||||
{
|
||||
"type": "result",
|
||||
"subtype": "success",
|
||||
"result": "The analysis text...",
|
||||
"session_id": "75e2167f-...",
|
||||
"num_turns": 3,
|
||||
"total_cost_usd": 0.0787,
|
||||
"duration_ms": 10276,
|
||||
"stop_reason": "end_turn",
|
||||
"terminal_reason": "completed",
|
||||
"usage": { "input_tokens": 5, "output_tokens": 603, ... },
|
||||
"modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
|
||||
}
|
||||
```
|
||||
|
||||
**Key fields:** `session_id` for resumption, `num_turns` for agentic loop count, `total_cost_usd` for spend tracking, `subtype` for success/error detection (`success`, `error_max_turns`, `error_budget`).
|
||||
|
||||
### Streaming JSON Output
|
||||
For real-time token streaming, use `stream-json` with `--verbose`:
|
||||
```
|
||||
terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)
|
||||
```
|
||||
|
||||
Returns newline-delimited JSON events. Filter with jq for live text:
|
||||
```
|
||||
claude -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
|
||||
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
|
||||
```
|
||||
|
||||
Stream events include `system/api_retry` with `attempt`, `max_retries`, and `error` fields (e.g., `rate_limit`, `billing_error`).
|
||||
|
||||
### Bidirectional Streaming
|
||||
For real-time input AND output streaming:
|
||||
```
|
||||
claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages
|
||||
```
|
||||
`--replay-user-messages` re-emits user messages on stdout for acknowledgment.
|
||||
|
||||
### Piped Input
|
||||
```
|
||||
# Pipe a file for analysis
|
||||
terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)
|
||||
|
||||
# Pipe multiple files
|
||||
terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)
|
||||
|
||||
# Pipe command output
|
||||
terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)
|
||||
```
|
||||
|
||||
### JSON Schema for Structured Extraction
|
||||
```
|
||||
terminal(command="claude -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)
|
||||
```
|
||||
|
||||
Parse `structured_output` from the JSON result. Claude validates output against the schema before returning.
|
||||
|
||||
### Session Continuation
|
||||
```
|
||||
# Start a task
|
||||
terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)
|
||||
|
||||
# Resume with session ID
|
||||
terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)
|
||||
|
||||
# Or resume the most recent session in the same directory
|
||||
terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)
|
||||
|
||||
# Fork a session (new ID, keeps history)
|
||||
terminal(command="claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)
|
||||
```
|
||||
|
||||
### Bare Mode for CI/Scripting
|
||||
```
|
||||
terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)
|
||||
```
|
||||
|
||||
`--bare` skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires `ANTHROPIC_API_KEY` (skips OAuth).
|
||||
|
||||
To selectively load context in bare mode:
|
||||
| To load | Flag |
|
||||
|---------|------|
|
||||
| System prompt additions | `--append-system-prompt "text"` or `--append-system-prompt-file path` |
|
||||
| Settings | `--settings <file-or-json>` |
|
||||
| MCP servers | `--mcp-config <file-or-json>` |
|
||||
| Custom agents | `--agents '<json>'` |
|
||||
|
||||
### Fallback Model for Overload
|
||||
```
|
||||
terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)
|
||||
```
|
||||
Automatically falls back to the specified model when the default is overloaded (print mode only).
|
||||
|
||||
## Complete CLI Flags Reference
|
||||
|
||||
### Session & Environment
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `-p, --print` | Non-interactive one-shot mode (exits when done) |
|
||||
| `-c, --continue` | Resume most recent conversation in current directory |
|
||||
| `-r, --resume <id>` | Resume specific session by ID or name (interactive picker if no ID) |
|
||||
| `--fork-session` | When resuming, create new session ID instead of reusing original |
|
||||
| `--session-id <uuid>` | Use a specific UUID for the conversation |
|
||||
| `--no-session-persistence` | Don't save session to disk (print mode only) |
|
||||
| `--add-dir <paths...>` | Grant Claude access to additional working directories |
|
||||
| `-w, --worktree [name]` | Run in an isolated git worktree at `.claude/worktrees/<name>` |
|
||||
| `--tmux` | Create a tmux session for the worktree (requires `--worktree`) |
|
||||
| `--ide` | Auto-connect to a valid IDE on startup |
|
||||
| `--chrome` / `--no-chrome` | Enable/disable Chrome browser integration for web testing |
|
||||
| `--from-pr [number]` | Resume session linked to a specific GitHub PR |
|
||||
| `--file <specs...>` | File resources to download at startup (format: `file_id:relative_path`) |
|
||||
|
||||
### Model & Performance
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--model <alias>` | Model selection: `sonnet`, `opus`, `haiku`, or full name like `claude-sonnet-4-6` |
|
||||
| `--effort <level>` | Reasoning depth: `low`, `medium`, `high`, `max`, `auto` | Both |
|
||||
| `--max-turns <n>` | Limit agentic loops (print mode only; prevents runaway) |
|
||||
| `--max-budget-usd <n>` | Cap API spend in dollars (print mode only) |
|
||||
| `--fallback-model <model>` | Auto-fallback when default model is overloaded (print mode only) |
|
||||
| `--betas <betas...>` | Beta headers to include in API requests (API key users only) |
|
||||
|
||||
### Permission & Safety
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--dangerously-skip-permissions` | Auto-approve ALL tool use (file writes, bash, network, etc.) |
|
||||
| `--allow-dangerously-skip-permissions` | Enable bypass as an *option* without enabling it by default |
|
||||
| `--permission-mode <mode>` | `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions` |
|
||||
| `--allowedTools <tools...>` | Whitelist specific tools (comma or space-separated) |
|
||||
| `--disallowedTools <tools...>` | Blacklist specific tools |
|
||||
| `--tools <tools...>` | Override built-in tool set (`""` = none, `"default"` = all, or tool names) |
|
||||
|
||||
### Output & Input Format
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--output-format <fmt>` | `text` (default), `json` (single result object), `stream-json` (newline-delimited) |
|
||||
| `--input-format <fmt>` | `text` (default) or `stream-json` (real-time streaming input) |
|
||||
| `--json-schema <schema>` | Force structured JSON output matching a schema |
|
||||
| `--verbose` | Full turn-by-turn output |
|
||||
| `--include-partial-messages` | Include partial message chunks as they arrive (stream-json + print) |
|
||||
| `--replay-user-messages` | Re-emit user messages on stdout (stream-json bidirectional) |
|
||||
|
||||
### System Prompt & Context
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--append-system-prompt <text>` | **Add** to the default system prompt (preserves built-in capabilities) |
|
||||
| `--append-system-prompt-file <path>` | **Add** file contents to the default system prompt |
|
||||
| `--system-prompt <text>` | **Replace** the entire system prompt (use --append instead usually) |
|
||||
| `--system-prompt-file <path>` | **Replace** the system prompt with file contents |
|
||||
| `--bare` | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |
|
||||
| `--agents '<json>'` | Define custom subagents dynamically as JSON |
|
||||
| `--mcp-config <path>` | Load MCP servers from JSON file (repeatable) |
|
||||
| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configs |
|
||||
| `--settings <file-or-json>` | Load additional settings from a JSON file or inline JSON |
|
||||
| `--setting-sources <sources>` | Comma-separated sources to load: `user`, `project`, `local` |
|
||||
| `--plugin-dir <paths...>` | Load plugins from directories for this session only |
|
||||
| `--disable-slash-commands` | Disable all skills/slash commands |
|
||||
|
||||
### Debugging
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `-d, --debug [filter]` | Enable debug logging with optional category filter (e.g., `"api,hooks"`, `"!1p,!file"`) |
|
||||
| `--debug-file <path>` | Write debug logs to file (implicitly enables debug mode) |
|
||||
|
||||
### Agent Teams
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--teammate-mode <mode>` | How agent teams display: `auto`, `in-process`, or `tmux` |
|
||||
| `--brief` | Enable `SendUserMessage` tool for agent-to-user communication |
|
||||
|
||||
### Tool Name Syntax for --allowedTools / --disallowedTools
|
||||
```
|
||||
Read # All file reading
|
||||
Edit # File editing (existing files)
|
||||
Write # File creation (new files)
|
||||
Bash # All shell commands
|
||||
Bash(git *) # Only git commands
|
||||
Bash(git commit *) # Only git commit commands
|
||||
Bash(npm run lint:*) # Pattern matching with wildcards
|
||||
WebSearch # Web search capability
|
||||
WebFetch # Web page fetching
|
||||
mcp__<server>__<tool> # Specific MCP tool
|
||||
```
|
||||
|
||||
## Settings & Configuration
|
||||
|
||||
### Settings Hierarchy (highest to lowest priority)
|
||||
1. **CLI flags** — override everything
|
||||
2. **Local project:** `.claude/settings.local.json` (personal, gitignored)
|
||||
3. **Project:** `.claude/settings.json` (shared, git-tracked)
|
||||
4. **User:** `~/.claude/settings.json` (global)
|
||||
|
||||
### Permissions in Settings
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
|
||||
"ask": ["Write(*.ts)", "Bash(git push*)"],
|
||||
"deny": ["Read(.env)", "Bash(rm -rf *)"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Files (CLAUDE.md) Hierarchy
|
||||
1. **Global:** `~/.claude/CLAUDE.md` — applies to all projects
|
||||
2. **Project:** `./CLAUDE.md` — project-specific context (git-tracked)
|
||||
3. **Local:** `.claude/CLAUDE.local.md` — personal project overrides (gitignored)
|
||||
|
||||
Use the `#` prefix in interactive mode to quickly add to memory: `# Always use 2-space indentation`.
|
||||
|
||||
## Interactive Session: Slash Commands
|
||||
|
||||
### Session & Context
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/help` | Show all commands (including custom and MCP commands) |
|
||||
| `/compact [focus]` | Compress context to save tokens; CLAUDE.md survives compaction. E.g., `/compact focus on auth logic` |
|
||||
| `/clear` | Wipe conversation history for a fresh start |
|
||||
| `/context` | Visualize context usage as a colored grid with optimization tips |
|
||||
| `/cost` | View token usage with per-model and cache-hit breakdowns |
|
||||
| `/resume` | Switch to or resume a different session |
|
||||
| `/rewind` | Revert to a previous checkpoint in conversation or code |
|
||||
| `/btw <question>` | Ask a side question without adding to context cost |
|
||||
| `/status` | Show version, connectivity, and session info |
|
||||
| `/todos` | List tracked action items from the conversation |
|
||||
| `/exit` or `Ctrl+D` | End session |
|
||||
|
||||
### Development & Review
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/review` | Request code review of current changes |
|
||||
| `/security-review` | Perform security analysis of current changes |
|
||||
| `/plan [description]` | Enter Plan mode with auto-start for task planning |
|
||||
| `/loop [interval]` | Schedule recurring tasks within the session |
|
||||
| `/batch` | Auto-create worktrees for large parallel changes (5-30 worktrees) |
|
||||
|
||||
### Configuration & Tools
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/model [model]` | Switch models mid-session (use arrow keys to adjust effort) |
|
||||
| `/effort [level]` | Set reasoning effort: `low`, `medium`, `high`, `max`, or `auto` |
|
||||
| `/init` | Create a CLAUDE.md file for project memory |
|
||||
| `/memory` | Open CLAUDE.md for editing |
|
||||
| `/config` | Open interactive settings configuration |
|
||||
| `/permissions` | View/update tool permissions |
|
||||
| `/agents` | Manage specialized subagents |
|
||||
| `/mcp` | Interactive UI to manage MCP servers |
|
||||
| `/add-dir` | Add additional working directories (useful for monorepos) |
|
||||
| `/usage` | Show plan limits and rate limit status |
|
||||
| `/voice` | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |
|
||||
| `/release-notes` | Interactive picker for version release notes |
|
||||
|
||||
### Custom Slash Commands
|
||||
Create `.claude/commands/<name>.md` (project-shared) or `~/.claude/commands/<name>.md` (personal):
|
||||
|
||||
```markdown
|
||||
# .claude/commands/deploy.md
|
||||
Run the deploy pipeline:
|
||||
1. Run all tests
|
||||
2. Build the Docker image
|
||||
3. Push to registry
|
||||
4. Update the $ARGUMENTS environment (default: staging)
|
||||
```
|
||||
|
||||
Usage: `/deploy production` — `$ARGUMENTS` is replaced with the user's input.
|
||||
|
||||
### Skills (Natural Language Invocation)
|
||||
Unlike slash commands (manually invoked), skills in `.claude/skills/` are markdown guides that Claude invokes automatically via natural language when the task matches:
|
||||
|
||||
```markdown
|
||||
# .claude/skills/database-migration.md
|
||||
When asked to create or modify database migrations:
|
||||
1. Use Alembic for migration generation
|
||||
2. Always create a rollback function
|
||||
3. Test migrations against a local database copy
|
||||
```
|
||||
|
||||
## Interactive Session: Keyboard Shortcuts
|
||||
|
||||
### General Controls
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Ctrl+C` | Cancel current input or generation |
|
||||
| `Ctrl+D` | Exit session |
|
||||
| `Ctrl+R` | Reverse search command history |
|
||||
| `Ctrl+B` | Background a running task |
|
||||
| `Ctrl+V` | Paste image into conversation |
|
||||
| `Ctrl+O` | Transcript mode — see Claude's thinking process |
|
||||
| `Ctrl+G` or `Ctrl+X Ctrl+E` | Open prompt in external editor |
|
||||
| `Esc Esc` | Rewind conversation or code state / summarize |
|
||||
|
||||
### Mode Toggles
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Shift+Tab` | Cycle permission modes (Normal → Auto-Accept → Plan) |
|
||||
| `Alt+P` | Switch model |
|
||||
| `Alt+T` | Toggle thinking mode |
|
||||
| `Alt+O` | Toggle Fast Mode |
|
||||
|
||||
### Multiline Input
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `\` + `Enter` | Quick newline |
|
||||
| `Shift+Enter` | Newline (alternative) |
|
||||
| `Ctrl+J` | Newline (alternative) |
|
||||
|
||||
### Input Prefixes
|
||||
| Prefix | Action |
|
||||
|--------|--------|
|
||||
| `!` | Execute bash directly, bypassing AI (e.g., `!npm test`). Use `!` alone to toggle shell mode. |
|
||||
| `@` | Reference files/directories with autocomplete (e.g., `@./src/api/`) |
|
||||
| `#` | Quick add to CLAUDE.md memory (e.g., `# Use 2-space indentation`) |
|
||||
| `/` | Slash commands |
|
||||
|
||||
### Pro Tip: "ultrathink"
|
||||
Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current `/effort` setting.
|
||||
|
||||
## PR Review Pattern
|
||||
|
||||
### Quick Review (Print Mode)
|
||||
```
|
||||
terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)
|
||||
```
|
||||
|
||||
### Deep Review (Interactive + Worktree)
|
||||
```
|
||||
terminal(command="tmux new-session -d -s review -x 140 -y 40")
|
||||
terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
|
||||
terminal(command="sleep 5 && tmux send-keys -t review Enter") # Trust dialog
|
||||
terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
|
||||
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")
|
||||
```
|
||||
|
||||
### PR Review from Number
|
||||
```
|
||||
terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)
|
||||
```
|
||||
|
||||
### Claude Worktree with tmux
|
||||
```
|
||||
terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")
|
||||
```
|
||||
Creates an isolated git worktree at `.claude/worktrees/feature-x` AND a tmux session for it. Uses iTerm2 native panes when available; add `--tmux=classic` for traditional tmux.
|
||||
|
||||
## Parallel Claude Instances
|
||||
|
||||
Run multiple independent Claude tasks simultaneously:
|
||||
|
||||
```
|
||||
# Task 1: Fix backend
|
||||
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")
|
||||
|
||||
# Task 2: Write tests
|
||||
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")
|
||||
|
||||
# Task 3: Update docs
|
||||
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")
|
||||
|
||||
# Monitor all
|
||||
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")
|
||||
```
|
||||
|
||||
## CLAUDE.md — Project Context File
|
||||
|
||||
Claude Code auto-loads `CLAUDE.md` from the project root. Use it to persist project context:
|
||||
|
||||
```markdown
|
||||
# Project: My API
|
||||
|
||||
## Architecture
|
||||
- FastAPI backend with SQLAlchemy ORM
|
||||
- PostgreSQL database, Redis cache
|
||||
- pytest for testing with 90% coverage target
|
||||
|
||||
## Key Commands
|
||||
- `make test` — run full test suite
|
||||
- `make lint` — ruff + mypy
|
||||
- `make dev` — start dev server on :8000
|
||||
|
||||
## Code Standards
|
||||
- Type hints on all public functions
|
||||
- Docstrings in Google style
|
||||
- 2-space indentation for YAML, 4-space for Python
|
||||
- No wildcard imports
|
||||
```
|
||||
|
||||
**Be specific.** Instead of "Write good code", use "Use 2-space indentation for JS" or "Name test files with `.test.ts` suffix." Specific instructions save correction cycles.
|
||||
|
||||
### Rules Directory (Modular CLAUDE.md)
|
||||
For projects with many rules, use the rules directory instead of one massive CLAUDE.md:
|
||||
- **Project rules:** `.claude/rules/*.md` — team-shared, git-tracked
|
||||
- **User rules:** `~/.claude/rules/*.md` — personal, global
|
||||
|
||||
Each `.md` file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.
|
||||
|
||||
### Auto-Memory
|
||||
Claude automatically stores learned project context in `~/.claude/projects/<project>/memory/`.
|
||||
- **Limit:** 25KB or 200 lines per project
|
||||
- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions
|
||||
|
||||
## Custom Subagents
|
||||
|
||||
Define specialized agents in `.claude/agents/` (project), `~/.claude/agents/` (personal), or via `--agents` CLI flag (session):
|
||||
|
||||
### Agent Location Priority
|
||||
1. `.claude/agents/` — project-level, team-shared
|
||||
2. `--agents` CLI flag — session-specific, dynamic
|
||||
3. `~/.claude/agents/` — user-level, personal
|
||||
|
||||
### Creating an Agent
|
||||
```markdown
|
||||
# .claude/agents/security-reviewer.md
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Security-focused code review
|
||||
model: opus
|
||||
tools: [Read, Bash]
|
||||
---
|
||||
You are a senior security engineer. Review code for:
|
||||
- Injection vulnerabilities (SQL, XSS, command injection)
|
||||
- Authentication/authorization flaws
|
||||
- Secrets in code
|
||||
- Unsafe deserialization
|
||||
```
|
||||
|
||||
Invoke via: `@security-reviewer review the auth module`
|
||||
|
||||
### Dynamic Agents via CLI
|
||||
```
|
||||
terminal(command="claude --agents '{\"reviewer\": {\"description\": \"Reviews code\", \"prompt\": \"You are a code reviewer focused on performance\"}}' -p 'Use @reviewer to check auth.py'", timeout=120)
|
||||
```
|
||||
|
||||
Claude can orchestrate multiple agents: "Use @db-expert to optimize queries, then @security to audit the changes."
|
||||
|
||||
## Hooks — Automation on Events
|
||||
|
||||
Configure in `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [{
|
||||
"matcher": "Write(*.py)",
|
||||
"hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
|
||||
}],
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
|
||||
}],
|
||||
"Stop": [{
|
||||
"hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> /tmp/claude-activity.log"}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### All 8 Hook Types
|
||||
| Hook | When it fires | Common use |
|
||||
|------|--------------|------------|
|
||||
| `UserPromptSubmit` | Before Claude processes a user prompt | Input validation, logging |
|
||||
| `PreToolUse` | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |
|
||||
| `PostToolUse` | After a tool finishes | Auto-format code, run linters |
|
||||
| `Notification` | On permission requests or input waits | Desktop notifications, alerts |
|
||||
| `Stop` | When Claude finishes a response | Completion logging, status updates |
|
||||
| `SubagentStop` | When a subagent completes | Agent orchestration |
|
||||
| `PreCompact` | Before context memory is cleared | Backup session transcripts |
|
||||
| `SessionStart` | When a session begins | Load dev context (e.g., `git status`) |
|
||||
|
||||
### Hook Environment Variables
|
||||
| Variable | Content |
|
||||
|----------|---------|
|
||||
| `CLAUDE_PROJECT_DIR` | Current project path |
|
||||
| `CLAUDE_FILE_PATHS` | Files being modified |
|
||||
| `CLAUDE_TOOL_INPUT` | Tool parameters as JSON |
|
||||
|
||||
### Security Hook Examples
|
||||
```json
|
||||
{
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## MCP Integration
|
||||
|
||||
Add external tool servers for databases, APIs, and services:
|
||||
|
||||
```
|
||||
# GitHub integration
|
||||
terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)
|
||||
|
||||
# PostgreSQL queries
|
||||
terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)
|
||||
|
||||
# Puppeteer for web testing
|
||||
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)
|
||||
```
|
||||
|
||||
### MCP Scopes
|
||||
| Flag | Scope | Storage |
|
||||
|------|-------|---------|
|
||||
| `-s user` | Global (all projects) | `~/.claude.json` |
|
||||
| `-s local` | This project (personal) | `.claude/settings.local.json` (gitignored) |
|
||||
| `-s project` | This project (team-shared) | `.claude/settings.json` (git-tracked) |
|
||||
|
||||
### MCP in Print/CI Mode
|
||||
```
|
||||
terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)
|
||||
```
|
||||
`--strict-mcp-config` ignores all MCP servers except those from `--mcp-config`.
|
||||
|
||||
Reference MCP resources in chat: `@github:issue://123`
|
||||
|
||||
### MCP Limits & Tuning
|
||||
- **Tool descriptions:** 2KB cap per server for tool descriptions and server instructions
|
||||
- **Result size:** Default capped; use `maxResultSizeChars` annotation to allow up to **500K** characters for large outputs
|
||||
- **Output tokens:** `export MAX_MCP_OUTPUT_TOKENS=50000` — cap output from MCP servers to prevent context flooding
|
||||
- **Transports:** `stdio` (local process), `http` (remote), `sse` (server-sent events)
|
||||
|
||||
## Monitoring Interactive Sessions
|
||||
|
||||
### Reading the TUI Status
|
||||
```
|
||||
# Periodic capture to check if Claude is still working or waiting for input
|
||||
terminal(command="tmux capture-pane -t dev -p -S -10")
|
||||
```
|
||||
|
||||
Look for these indicators:
|
||||
- `❯` at bottom = waiting for your input (Claude is done or asking a question)
|
||||
- `●` lines = Claude is actively using tools (reading, writing, running commands)
|
||||
- `⏵⏵ bypass permissions on` = status bar showing permissions mode
|
||||
- `◐ medium · /effort` = current effort level in status bar
|
||||
- `ctrl+o to expand` = tool output was truncated (can be expanded interactively)
|
||||
|
||||
### Context Window Health
|
||||
Use `/context` in interactive mode to see a colored grid of context usage. Key thresholds:
|
||||
- **< 70%** — Normal operation, full precision
|
||||
- **70-85%** — Precision starts dropping, consider `/compact`
|
||||
- **> 85%** — Hallucination risk spikes significantly, use `/compact` or `/clear`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Effect |
|
||||
|----------|--------|
|
||||
| `ANTHROPIC_API_KEY` | API key for authentication (alternative to OAuth) |
|
||||
| `CLAUDE_CODE_EFFORT_LEVEL` | Default effort: `low`, `medium`, `high`, `max`, or `auto` |
|
||||
| `MAX_THINKING_TOKENS` | Cap thinking tokens (set to `0` to disable thinking entirely) |
|
||||
| `MAX_MCP_OUTPUT_TOKENS` | Cap output from MCP servers (default varies; set e.g., `50000`) |
|
||||
| `CLAUDE_CODE_NO_FLICKER=1` | Enable alt-screen rendering to eliminate terminal flicker |
|
||||
| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from sub-processes for security |
|
||||
|
||||
## Cost & Performance Tips
|
||||
|
||||
1. **Use `--max-turns`** in print mode to prevent runaway loops. Start with 5-10 for most tasks.
|
||||
2. **Use `--max-budget-usd`** for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
|
||||
3. **Use `--effort low`** for simple tasks (faster, cheaper). `high` or `max` for complex reasoning.
|
||||
4. **Use `--bare`** for CI/scripting to skip plugin/hook discovery overhead.
|
||||
5. **Use `--allowedTools`** to restrict to only what's needed (e.g., `Read` only for reviews).
|
||||
6. **Use `/compact`** in interactive sessions when context gets large.
|
||||
7. **Pipe input** instead of having Claude read files when you just need analysis of known content.
|
||||
8. **Use `--model haiku`** for simple tasks (cheaper) and `--model opus` for complex multi-step work.
|
||||
9. **Use `--fallback-model haiku`** in print mode to gracefully handle model overload.
|
||||
10. **Start new sessions for distinct tasks** — sessions last 5 hours; fresh context is more efficient.
|
||||
11. **Use `--no-session-persistence`** in CI to avoid accumulating saved sessions on disk.
|
||||
|
||||
## Pitfalls & Gotchas
|
||||
|
||||
1. **Interactive mode REQUIRES tmux** — Claude Code is a full TUI app. Using `pty=true` alone in Hermes terminal works but tmux gives you `capture-pane` for monitoring and `send-keys` for input, which is essential for orchestration.
|
||||
2. **`--dangerously-skip-permissions` dialog defaults to "No, exit"** — you must send Down then Enter to accept. Print mode (`-p`) skips this entirely.
|
||||
3. **`--max-budget-usd` minimum is ~$0.05** — system prompt cache creation alone costs this much. Setting lower will error immediately.
|
||||
4. **`--max-turns` is print-mode only** — ignored in interactive sessions.
|
||||
5. **Claude may use `python` instead of `python3`** — on systems without a `python` symlink, Claude's bash commands will fail on first try but it self-corrects.
|
||||
6. **Session resumption requires same directory** — `--continue` finds the most recent session for the current working directory.
|
||||
7. **`--json-schema` needs enough `--max-turns`** — Claude must read files before producing structured output, which takes multiple turns.
|
||||
8. **Trust dialog only appears once per directory** — first-time only, then cached.
|
||||
9. **Background tmux sessions persist** — always clean up with `tmux kill-session -t <name>` when done.
|
||||
10. **Slash commands (like `/commit`) only work in interactive mode** — in `-p` mode, describe the task in natural language instead.
|
||||
11. **`--bare` skips OAuth** — requires `ANTHROPIC_API_KEY` env var or an `apiKeyHelper` in settings.
|
||||
12. **Context degradation is real** — AI output quality measurably degrades above 70% context window usage. Monitor with `/context` and proactively `/compact`.
|
||||
|
||||
## Rules for Hermes Agents
|
||||
|
||||
1. **Prefer print mode (`-p`) for single tasks** — cleaner, no dialog handling, structured output
|
||||
2. **Use tmux for multi-turn interactive work** — the only reliable way to orchestrate the TUI
|
||||
3. **Always set `workdir`** — keep Claude focused on the right project directory
|
||||
4. **Set `--max-turns` in print mode** — prevents infinite loops and runaway costs
|
||||
5. **Monitor tmux sessions** — use `tmux capture-pane -t <session> -p -S -50` to check progress
|
||||
6. **Look for the `❯` prompt** — indicates Claude is waiting for input (done or asking a question)
|
||||
7. **Clean up tmux sessions** — kill them when done to avoid resource leaks
|
||||
8. **Report results to user** — after completion, summarize what Claude did and what changed
|
||||
9. **Don't kill slow sessions** — Claude may be doing multi-step work; check progress instead
|
||||
10. **Use `--allowedTools`** — restrict capabilities to what the task actually needs
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: codex
|
||||
description: "Delegate coding to OpenAI Codex CLI (features, PRs)."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Coding-Agent, Codex, OpenAI, Code-Review, Refactoring]
|
||||
related_skills: [claude-code, hermes-agent]
|
||||
---
|
||||
|
||||
# Codex CLI
|
||||
|
||||
Delegate coding tasks to [Codex](https://github.com/openai/codex) via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.
|
||||
|
||||
## When to use
|
||||
|
||||
- Building features
|
||||
- Refactoring
|
||||
- PR reviews
|
||||
- Batch issue fixing
|
||||
|
||||
Requires the codex CLI and a git repository.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Codex installed: `npm install -g @openai/codex`
|
||||
- OpenAI auth configured: either `OPENAI_API_KEY` or Codex OAuth credentials
|
||||
from the Codex CLI login flow
|
||||
- **Must run inside a git repository** — Codex refuses to run outside one
|
||||
- Use `pty=true` in terminal calls — Codex is an interactive terminal app
|
||||
|
||||
For Hermes itself, `model.provider: openai-codex` uses Hermes-managed Codex
|
||||
OAuth from `~/.hermes/auth.json` after `hermes auth add openai-codex`. For the
|
||||
standalone Codex CLI, a valid CLI OAuth session may live under
|
||||
`~/.codex/auth.json`; do not treat a missing `OPENAI_API_KEY` alone as proof
|
||||
that Codex auth is missing.
|
||||
|
||||
## One-Shot Tasks
|
||||
|
||||
```
|
||||
terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
|
||||
```
|
||||
|
||||
For scratch work (Codex needs a git repo):
|
||||
```
|
||||
terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)
|
||||
```
|
||||
|
||||
## Background Mode (Long Tasks)
|
||||
|
||||
```
|
||||
# Start in background with PTY
|
||||
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
|
||||
# Returns session_id
|
||||
|
||||
# Monitor progress
|
||||
process(action="poll", session_id="<id>")
|
||||
process(action="log", session_id="<id>")
|
||||
|
||||
# Send input if Codex asks a question
|
||||
process(action="submit", session_id="<id>", data="yes")
|
||||
|
||||
# Kill if needed
|
||||
process(action="kill", session_id="<id>")
|
||||
```
|
||||
|
||||
## Key Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `exec "prompt"` | One-shot execution, exits when done |
|
||||
| `--full-auto` | Sandboxed but auto-approves file changes in workspace |
|
||||
| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
|
||||
| `--sandbox danger-full-access` | No Codex sandbox; useful when the host service context breaks bubblewrap |
|
||||
|
||||
## Hermes Gateway Caveat
|
||||
|
||||
When invoking the Codex CLI from a Hermes gateway/service context (for example,
|
||||
Telegram-driven agent sessions), Codex `workspace-write` sandboxing may fail even
|
||||
when the same command works in the user's interactive shell. A typical symptom is
|
||||
bubblewrap/user-namespace errors such as `setting up uid map: Permission denied`
|
||||
or `loopback: Failed RTM_NEWADDR: Operation not permitted`.
|
||||
|
||||
In that context, prefer:
|
||||
|
||||
```
|
||||
codex exec --sandbox danger-full-access "<task>"
|
||||
```
|
||||
|
||||
Use process boundaries as the safety layer instead: explicit `workdir`, clean git
|
||||
status before launch, narrow task prompts, `git diff` review, targeted tests, and
|
||||
human/agent confirmation before committing broad changes.
|
||||
|
||||
## PR Reviews
|
||||
|
||||
Clone to a temp directory for safe review:
|
||||
|
||||
```
|
||||
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)
|
||||
```
|
||||
|
||||
## Parallel Issue Fixing with Worktrees
|
||||
|
||||
```
|
||||
# Create worktrees
|
||||
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
|
||||
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
|
||||
|
||||
# Launch Codex in each
|
||||
terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
|
||||
terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)
|
||||
|
||||
# Monitor
|
||||
process(action="list")
|
||||
|
||||
# After completion, push and create PRs
|
||||
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
|
||||
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
|
||||
|
||||
# Cleanup
|
||||
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
|
||||
```
|
||||
|
||||
## Batch PR Reviews
|
||||
|
||||
```
|
||||
# Fetch all PR refs
|
||||
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")
|
||||
|
||||
# Review multiple PRs in parallel
|
||||
terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
|
||||
terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)
|
||||
|
||||
# Post results
|
||||
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Always use `pty=true`** — Codex is an interactive terminal app and hangs without a PTY
|
||||
2. **Git repo required** — Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch
|
||||
3. **Use `exec` for one-shots** — `codex exec "prompt"` runs and exits cleanly
|
||||
4. **`--full-auto` for building** — auto-approves changes within the sandbox
|
||||
5. **Background for long tasks** — use `background=true` and monitor with `process` tool
|
||||
6. **Don't interfere** — monitor with `poll`/`log`, be patient with long-running tasks
|
||||
7. **Parallel is fine** — run multiple Codex processes at once for batch work
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,344 @@
|
||||
# Native MCP Client
|
||||
|
||||
Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this whenever you want to:
|
||||
- Connect to MCP servers and use their tools from within Hermes Agent
|
||||
- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
|
||||
- Run local stdio-based MCP servers (npx, uvx, or any command)
|
||||
- Connect to remote HTTP/StreamableHTTP MCP servers
|
||||
- Have MCP tools auto-discovered and available in every conversation
|
||||
|
||||
For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
|
||||
- **Node.js** -- required for `npx`-based MCP servers (most community servers)
|
||||
- **uv** -- required for `uvx`-based MCP servers (Python-based servers)
|
||||
|
||||
Install the MCP SDK:
|
||||
|
||||
```bash
|
||||
pip install mcp
|
||||
# or, if using uv:
|
||||
uv pip install mcp
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
```
|
||||
|
||||
Restart Hermes Agent. On startup it will:
|
||||
1. Connect to the server
|
||||
2. Discover available tools
|
||||
3. Register them with the prefix `mcp_time_*`
|
||||
4. Inject them into all platform toolsets
|
||||
|
||||
You can then use the tools naturally -- just ask the agent to get the current time.
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).
|
||||
|
||||
### Stdio Transport (command + args)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
server_name:
|
||||
command: "npx" # (required) executable to run
|
||||
args: ["-y", "pkg-name"] # (optional) command arguments, default: []
|
||||
env: # (optional) environment variables for the subprocess
|
||||
SOME_API_KEY: "value"
|
||||
timeout: 120 # (optional) per-tool-call timeout in seconds, default: 120
|
||||
connect_timeout: 60 # (optional) initial connection timeout in seconds, default: 60
|
||||
```
|
||||
|
||||
### HTTP Transport (url)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
server_name:
|
||||
url: "https://my-server.example.com/mcp" # (required) server URL
|
||||
headers: # (optional) HTTP headers
|
||||
Authorization: "Bearer sk-..."
|
||||
timeout: 180 # (optional) per-tool-call timeout in seconds, default: 120
|
||||
connect_timeout: 60 # (optional) initial connection timeout in seconds, default: 60
|
||||
```
|
||||
|
||||
### All Config Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|-------------------|--------|---------|---------------------------------------------------|
|
||||
| `command` | string | -- | Executable to run (stdio transport, required) |
|
||||
| `args` | list | `[]` | Arguments passed to the command |
|
||||
| `env` | dict | `{}` | Extra environment variables for the subprocess |
|
||||
| `url` | string | -- | Server URL (HTTP transport, required) |
|
||||
| `headers` | dict | `{}` | HTTP headers sent with every request |
|
||||
| `timeout` | int | `120` | Per-tool-call timeout in seconds |
|
||||
| `connect_timeout` | int | `60` | Timeout for initial connection and discovery |
|
||||
|
||||
Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Startup Discovery
|
||||
|
||||
When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:
|
||||
|
||||
1. Reads `mcp_servers` from `~/.hermes/config.yaml`
|
||||
2. For each server, spawns a connection in a dedicated background event loop
|
||||
3. Initializes the MCP session and calls `list_tools()` to discover available tools
|
||||
4. Registers each tool in the Hermes tool registry
|
||||
|
||||
### Tool Naming Convention
|
||||
|
||||
MCP tools are registered with the naming pattern:
|
||||
|
||||
```
|
||||
mcp_{server_name}_{tool_name}
|
||||
```
|
||||
|
||||
Hyphens and dots in names are replaced with underscores for LLM API compatibility.
|
||||
|
||||
Examples:
|
||||
- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
|
||||
- Server `github`, tool `list-issues` → `mcp_github_list_issues`
|
||||
- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
|
||||
|
||||
### Auto-Injection
|
||||
|
||||
After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
|
||||
|
||||
### Connection Lifecycle
|
||||
|
||||
- Each server runs as a long-lived asyncio Task in a background daemon thread
|
||||
- Connections persist for the lifetime of the agent process
|
||||
- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
|
||||
- On agent shutdown, all connections are gracefully closed
|
||||
|
||||
### Idempotency
|
||||
|
||||
`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
|
||||
|
||||
## Transport Types
|
||||
|
||||
### Stdio Transport
|
||||
|
||||
The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||||
```
|
||||
|
||||
The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.
|
||||
|
||||
### HTTP / StreamableHTTP Transport
|
||||
|
||||
For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
remote_api:
|
||||
url: "https://mcp.example.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-..."
|
||||
```
|
||||
|
||||
If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
|
||||
|
||||
## Security
|
||||
|
||||
### Environment Variable Filtering
|
||||
|
||||
For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
|
||||
|
||||
- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
|
||||
- Any `XDG_*` variables
|
||||
|
||||
All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
# Only this token is passed to the subprocess
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
|
||||
```
|
||||
|
||||
### Credential Stripping in Error Messages
|
||||
|
||||
If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
|
||||
|
||||
- GitHub PATs (`ghp_...`)
|
||||
- OpenAI-style keys (`sk-...`)
|
||||
- Bearer tokens
|
||||
- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "MCP SDK not available -- skipping MCP tool discovery"
|
||||
|
||||
The `mcp` Python package is not installed. Install it:
|
||||
|
||||
```bash
|
||||
pip install mcp
|
||||
```
|
||||
|
||||
### "No MCP servers configured"
|
||||
|
||||
No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
|
||||
|
||||
### "Failed to connect to MCP server 'X'"
|
||||
|
||||
Common causes:
|
||||
- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
|
||||
- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
|
||||
- **Timeout**: The server took too long to start. Increase `connect_timeout`.
|
||||
- **Port conflict**: For HTTP servers, the URL may be unreachable.
|
||||
|
||||
### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
|
||||
|
||||
Your `mcp` package version doesn't include HTTP client support. Upgrade:
|
||||
|
||||
```bash
|
||||
pip install --upgrade mcp
|
||||
```
|
||||
|
||||
### Tools not appearing
|
||||
|
||||
- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
|
||||
- Ensure the YAML indentation is correct
|
||||
- Look at Hermes Agent startup logs for connection messages
|
||||
- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
|
||||
|
||||
### Connection keeps dropping
|
||||
|
||||
The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
|
||||
|
||||
## Examples
|
||||
|
||||
### Time Server (uvx)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
```
|
||||
|
||||
Registers tools like `mcp_time_get_current_time`.
|
||||
|
||||
### Filesystem Server (npx)
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
|
||||
|
||||
### GitHub Server with Authentication
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||
timeout: 60
|
||||
```
|
||||
|
||||
Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
|
||||
|
||||
### Remote HTTP Server
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
company_api:
|
||||
url: "https://mcp.mycompany.com/v1/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
|
||||
X-Team-Id: "engineering"
|
||||
timeout: 180
|
||||
connect_timeout: 30
|
||||
```
|
||||
|
||||
### Multiple Servers
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
time:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-time"]
|
||||
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
||||
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||
|
||||
company_api:
|
||||
url: "https://mcp.internal.company.com/mcp"
|
||||
headers:
|
||||
Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
|
||||
timeout: 300
|
||||
```
|
||||
|
||||
All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
|
||||
|
||||
## Sampling (Server-Initiated LLM Requests)
|
||||
|
||||
Hermes supports MCP's `sampling/createMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).
|
||||
|
||||
Sampling is **enabled by default**. Configure per server:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
my_server:
|
||||
command: "npx"
|
||||
args: ["-y", "my-mcp-server"]
|
||||
sampling:
|
||||
enabled: true # default: true
|
||||
model: "gemini-3-flash" # model override (optional)
|
||||
max_tokens_cap: 4096 # max tokens per request
|
||||
timeout: 30 # LLM call timeout (seconds)
|
||||
max_rpm: 10 # max requests per minute
|
||||
allowed_models: [] # model whitelist (empty = all)
|
||||
max_tool_rounds: 5 # tool loop limit (0 = disable)
|
||||
log_level: "info" # audit verbosity
|
||||
```
|
||||
|
||||
Servers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.
|
||||
|
||||
Disable sampling for untrusted servers with `sampling: { enabled: false }`.
|
||||
|
||||
## Notes
|
||||
|
||||
- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
|
||||
- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
|
||||
- The native MCP client is independent of `mcporter` -- you can use both simultaneously
|
||||
- Server connections are persistent and shared across all conversations in the same agent process
|
||||
- Adding or removing servers requires restarting the agent (no hot-reload currently)
|
||||
@@ -0,0 +1,194 @@
|
||||
# Webhook Subscriptions
|
||||
|
||||
Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Hermes agent runs by POSTing events to a URL.
|
||||
|
||||
## Setup (Required First)
|
||||
|
||||
The webhook platform must be enabled before subscriptions can be created. Check with:
|
||||
```bash
|
||||
hermes webhook list
|
||||
```
|
||||
|
||||
If it says "Webhook platform is not enabled", set it up:
|
||||
|
||||
### Option 1: Setup wizard
|
||||
```bash
|
||||
hermes gateway setup
|
||||
```
|
||||
Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.
|
||||
|
||||
### Option 2: Manual config
|
||||
Add to `~/.hermes/config.yaml`:
|
||||
```yaml
|
||||
platforms:
|
||||
webhook:
|
||||
enabled: true
|
||||
extra:
|
||||
host: "0.0.0.0"
|
||||
port: 8644
|
||||
secret: "generate-a-strong-secret-here"
|
||||
```
|
||||
|
||||
### Option 3: Environment variables
|
||||
Add to `${HERMES_HOME:-~/.hermes}/.env`:
|
||||
```bash
|
||||
WEBHOOK_ENABLED=true
|
||||
WEBHOOK_PORT=8644
|
||||
WEBHOOK_SECRET=generate-a-strong-secret-here
|
||||
```
|
||||
|
||||
After configuration, start (or restart) the gateway:
|
||||
```bash
|
||||
hermes gateway run
|
||||
# Or if using systemd:
|
||||
systemctl --user restart hermes-gateway
|
||||
```
|
||||
|
||||
Verify it's running:
|
||||
```bash
|
||||
curl http://localhost:8644/health
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
All management is via the `hermes webhook` CLI command:
|
||||
|
||||
### Create a subscription
|
||||
```bash
|
||||
hermes webhook subscribe <name> \
|
||||
--prompt "Prompt template with {payload.fields}" \
|
||||
--events "event1,event2" \
|
||||
--description "What this does" \
|
||||
--skills "skill1,skill2" \
|
||||
--deliver telegram \
|
||||
--deliver-chat-id "12345" \
|
||||
--secret "optional-custom-secret"
|
||||
```
|
||||
|
||||
Returns the webhook URL and HMAC secret. The user configures their service to POST to that URL.
|
||||
|
||||
### List subscriptions
|
||||
```bash
|
||||
hermes webhook list
|
||||
```
|
||||
|
||||
### Remove a subscription
|
||||
```bash
|
||||
hermes webhook remove <name>
|
||||
```
|
||||
|
||||
### Test a subscription
|
||||
```bash
|
||||
hermes webhook test <name>
|
||||
hermes webhook test <name> --payload '{"key": "value"}'
|
||||
```
|
||||
|
||||
## Prompt Templates
|
||||
|
||||
Prompts support `{dot.notation}` for accessing nested payload fields:
|
||||
|
||||
- `{issue.title}` — GitHub issue title
|
||||
- `{pull_request.user.login}` — PR author
|
||||
- `{data.object.amount}` — Stripe payment amount
|
||||
- `{sensor.temperature}` — IoT sensor reading
|
||||
|
||||
If no prompt is specified, the full JSON payload is dumped into the agent prompt.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### GitHub: new issues
|
||||
```bash
|
||||
hermes webhook subscribe github-issues \
|
||||
--events "issues" \
|
||||
--prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
|
||||
--deliver telegram \
|
||||
--deliver-chat-id "-100123456789"
|
||||
```
|
||||
|
||||
Then in GitHub repo Settings → Webhooks → Add webhook:
|
||||
- Payload URL: the returned webhook_url
|
||||
- Content type: application/json
|
||||
- Secret: the returned secret
|
||||
- Events: "Issues"
|
||||
|
||||
### GitHub: PR reviews
|
||||
```bash
|
||||
hermes webhook subscribe github-prs \
|
||||
--events "pull_request" \
|
||||
--prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
|
||||
--skills "github-code-review" \
|
||||
--deliver github_comment
|
||||
```
|
||||
|
||||
### Stripe: payment events
|
||||
```bash
|
||||
hermes webhook subscribe stripe-payments \
|
||||
--events "payment_intent.succeeded,payment_intent.payment_failed" \
|
||||
--prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
|
||||
--deliver telegram \
|
||||
--deliver-chat-id "-100123456789"
|
||||
```
|
||||
|
||||
### CI/CD: build notifications
|
||||
```bash
|
||||
hermes webhook subscribe ci-builds \
|
||||
--events "pipeline" \
|
||||
--prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
|
||||
--deliver discord \
|
||||
--deliver-chat-id "1234567890"
|
||||
```
|
||||
|
||||
### Generic monitoring alert
|
||||
```bash
|
||||
hermes webhook subscribe alerts \
|
||||
--prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
|
||||
--deliver origin
|
||||
```
|
||||
|
||||
### Direct delivery (no agent, zero LLM cost)
|
||||
|
||||
For use cases where you just want to push a notification through to a user's chat — no reasoning, no agent loop — add `--deliver-only`. The rendered `--prompt` template becomes the literal message body and is dispatched directly to the target adapter.
|
||||
|
||||
Use this for:
|
||||
- External service push notifications (Supabase/Firebase webhooks → Telegram)
|
||||
- Monitoring alerts that should forward verbatim
|
||||
- Inter-agent pings where one agent is telling another agent's user something
|
||||
- Any webhook where an LLM round trip would be wasted effort
|
||||
|
||||
```bash
|
||||
hermes webhook subscribe antenna-matches \
|
||||
--deliver telegram \
|
||||
--deliver-chat-id "123456789" \
|
||||
--deliver-only \
|
||||
--prompt "🎉 New match: {match.user_name} matched with you!" \
|
||||
--description "Antenna match notifications"
|
||||
```
|
||||
|
||||
The POST returns `200 OK` on successful delivery, `502` on target failure — so upstream services can retry intelligently. HMAC auth, rate limits, and idempotency still apply.
|
||||
|
||||
Requires `--deliver` to be a real target (telegram, discord, slack, github_comment, etc.) — `--deliver log` is rejected because log-only direct delivery is pointless.
|
||||
|
||||
## Security
|
||||
|
||||
- Each subscription gets an auto-generated HMAC-SHA256 secret (or provide your own with `--secret`)
|
||||
- The webhook adapter validates signatures on every incoming POST
|
||||
- Static routes from config.yaml cannot be overwritten by dynamic subscriptions
|
||||
- Subscriptions persist to `~/.hermes/webhook_subscriptions.json`
|
||||
|
||||
## How It Works
|
||||
|
||||
1. `hermes webhook subscribe` writes to `~/.hermes/webhook_subscriptions.json`
|
||||
2. The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
|
||||
3. When a POST arrives matching a route, the adapter formats the prompt and triggers an agent run
|
||||
4. The agent's response is delivered to the configured target (Telegram, Discord, GitHub comment, etc.)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If webhooks aren't working:
|
||||
|
||||
1. **Is the gateway running?** Check with `systemctl --user status hermes-gateway` or `ps aux | grep gateway`
|
||||
2. **Is the webhook server listening?** `curl http://localhost:8644/health` should return `{"status": "ok"}`
|
||||
3. **Check gateway logs:** `grep webhook ~/.hermes/logs/gateway.log | tail -20`
|
||||
4. **Signature mismatch?** Verify the secret in your service matches the one from `hermes webhook list`. GitHub sends `X-Hub-Signature-256`, GitLab sends `X-Gitlab-Token`.
|
||||
5. **Firewall/NAT?** The webhook URL must be reachable from the service. For local development, use a tunnel (ngrok, cloudflared).
|
||||
6. **Wrong event type?** Check `--events` filter matches what the service sends. Use `hermes webhook test <name>` to verify the route works.
|
||||
@@ -0,0 +1,277 @@
|
||||
---
|
||||
name: kanban-codex-lane
|
||||
description: Use when a Hermes Kanban worker wants to run Codex CLI as an isolated implementation lane while Hermes keeps ownership of task lifecycle, reconciliation, testing, and handoff.
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [kanban, codex, worktrees, autonomous-agents, prediction-market-bot]
|
||||
related_skills: [kanban-worker, codex, hermes-agent]
|
||||
---
|
||||
|
||||
# Kanban Codex Lane
|
||||
|
||||
## Overview
|
||||
|
||||
This skill defines the lightweight Hermes+Codex dual-lane convention for Kanban workers. Hermes is always the task owner: it calls `kanban_show`, decides whether Codex is appropriate, creates or selects an isolated workspace, starts and monitors Codex, reconciles any diff, runs verification, and writes the final `kanban_complete` or `kanban_block` handoff. Codex is an input lane only. Codex output is not a task completion signal, not a trusted reviewer, and not allowed to write durable Kanban state directly.
|
||||
|
||||
The convention exists so a Hermes worker can use Codex for bounded implementation help without changing the dispatcher. The dispatcher must still spawn Hermes workers. A worker may optionally spawn Codex inside its own run, then accept, partially accept, or reject the lane after independent review and tests.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use the Codex lane when all of these are true:
|
||||
|
||||
- The Kanban task is a coding, refactor, documentation, test, or mechanical migration task with clear acceptance criteria.
|
||||
- A bounded diff can be evaluated by Hermes in one run.
|
||||
- The repo can be copied or checked out in an isolated git worktree/branch.
|
||||
- Hermes can run the relevant tests itself after Codex exits.
|
||||
- The prompt can state all safety constraints and files that must not change.
|
||||
|
||||
Do not use the Codex lane when any of these are true:
|
||||
|
||||
- The task requires human judgment that is not already captured in the Kanban body.
|
||||
- The worker lacks repo access, Codex auth, or time to reconcile the result.
|
||||
- The change touches secrets, credential stores, private user data, or production order-entry systems.
|
||||
- A small direct edit is faster and safer than spawning another agent.
|
||||
- The task is research-only and should produce a written handoff rather than a diff.
|
||||
- The worker would be tempted to mark Done based only on Codex self-report.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
1. Hermes owns the Kanban lifecycle. Codex must never call `kanban_complete`, `kanban_block`, `kanban_create`, gateway messaging, or any Hermes board CLI as a substitute for the worker.
|
||||
2. Hermes owns final acceptance. Treat Codex commits/diffs as untrusted patches until reviewed and verified.
|
||||
3. Hermes owns test execution. Codex may run tests, but those runs are advisory; repeat required verification from Hermes with the repo's canonical wrapper.
|
||||
4. Hermes owns safety. If Codex changes safety boundaries, risk gates, live trading behavior, or secrets handling, reject the lane even if tests pass.
|
||||
5. Hermes owns cleanup. Kill stuck Codex processes and remove temporary worktrees when they are no longer needed.
|
||||
|
||||
## Required Worktree and Branch Pattern
|
||||
|
||||
Never run Codex directly in a shared dirty checkout. Use a branch/worktree name that ties the lane to the Kanban task and keeps untrusted edits isolated.
|
||||
|
||||
Recommended variables:
|
||||
|
||||
```bash
|
||||
TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
|
||||
REPO="/path/to/repo"
|
||||
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
|
||||
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
|
||||
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
|
||||
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
|
||||
```
|
||||
|
||||
Create the isolated lane:
|
||||
|
||||
```bash
|
||||
git -C "$REPO" fetch --all --prune
|
||||
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
|
||||
git -C "$WORKTREE" status --short --branch
|
||||
```
|
||||
|
||||
If the current Kanban workspace is already an isolated git worktree created for this task, you may create a sibling Codex branch inside it only if `git status --short` is clean except for intentional Hermes edits. Otherwise create a separate temporary worktree and cherry-pick or copy accepted commits back after reconciliation.
|
||||
|
||||
Cleanup after reconciliation:
|
||||
|
||||
```bash
|
||||
git -C "$REPO" worktree remove "$WORKTREE"
|
||||
git -C "$REPO" branch -D "$BRANCH" # only after accepted commits were copied/cherry-picked or intentionally rejected
|
||||
```
|
||||
|
||||
Keep the worktree if it is needed as an artifact for review; record it in `codex_lane.artifacts` and mention it in the handoff.
|
||||
|
||||
## Codex Capability Checks
|
||||
|
||||
Run these before spawning Codex. Missing Codex is a normal reason to skip the lane, not a task blocker if Hermes can do the task directly.
|
||||
|
||||
```bash
|
||||
command -v codex
|
||||
codex --version
|
||||
codex features list | grep -i goals || true
|
||||
```
|
||||
|
||||
If `/goal` support is required, enable or launch with the feature flag only after checking availability:
|
||||
|
||||
```bash
|
||||
codex features enable goals || true
|
||||
codex --enable goals --version
|
||||
```
|
||||
|
||||
Authentication can be via `OPENAI_API_KEY` or the Codex CLI OAuth state (often `~/.codex/auth.json`). Do not print token files. A missing `OPENAI_API_KEY` is not proof that auth is unavailable.
|
||||
|
||||
## Mode Selection
|
||||
|
||||
Use `codex exec` for bounded one-shot edits where Codex should exit on its own:
|
||||
|
||||
```python
|
||||
terminal(
|
||||
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
|
||||
workdir=WORKTREE,
|
||||
background=True,
|
||||
pty=True,
|
||||
notify_on_complete=True,
|
||||
)
|
||||
```
|
||||
|
||||
Use Codex `/goal` only for broader multi-step work that benefits from durable objective tracking. Launch interactively in a PTY/tmux session or with `codex --enable goals` if the feature is disabled by default. Keep the goal objective self-contained: repo path, task id, safety constraints, allowed scope, acceptance criteria, tests, and commit expectations.
|
||||
|
||||
Example `/goal` objective text to paste into Codex:
|
||||
|
||||
```text
|
||||
/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
|
||||
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
|
||||
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
|
||||
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.
|
||||
```
|
||||
|
||||
Do not use `--yolo` for prediction-market-bot or safety-sensitive repos. Prefer `--full-auto` inside the isolated worktree, then rely on Hermes reconciliation.
|
||||
|
||||
## Prompt Construction
|
||||
|
||||
Use the linked template at `templates/pmb-codex-lane-prompt.md` for prediction-market-bot work. For other repos, keep the same structure and replace the PMB-specific safety block with repo-specific invariants.
|
||||
|
||||
Every Codex prompt must include:
|
||||
|
||||
- `task_id`, title, and full Kanban acceptance criteria.
|
||||
- Repo path, worktree path, branch name, and allowed file scope.
|
||||
- Explicit statement: Hermes owns Kanban lifecycle; Codex is an input lane only.
|
||||
- Required output: concise summary, files changed, commits, tests run, and known risks.
|
||||
- Prohibited actions: secrets access, external messaging, board mutation, unrelated refactors, dependency upgrades unless required.
|
||||
- Verification commands Codex may run and commands Hermes will run afterward.
|
||||
|
||||
For PMB, include these mandatory safety constraints verbatim:
|
||||
|
||||
```text
|
||||
PMB safety constraints:
|
||||
- live-SIM is paper-only; do not add or enable live REST order entry.
|
||||
- Never use market orders.
|
||||
- Do not add execution crossing or bypass price/risk checks.
|
||||
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
|
||||
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
|
||||
- Keep research/selection outside the C++ hot path unless explicitly requested.
|
||||
- Do not read, print, write, or require secrets/tokens/credentials.
|
||||
```
|
||||
|
||||
## Monitoring, Timeout, and Kill Behavior
|
||||
|
||||
Start long Codex lanes in the background with PTY and completion notification:
|
||||
|
||||
```python
|
||||
result = terminal(
|
||||
command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
|
||||
workdir=WORKTREE,
|
||||
background=True,
|
||||
pty=True,
|
||||
notify_on_complete=True,
|
||||
)
|
||||
session_id = result["session_id"]
|
||||
```
|
||||
|
||||
Monitor without interfering:
|
||||
|
||||
```python
|
||||
process(action="poll", session_id=session_id)
|
||||
process(action="log", session_id=session_id, limit=200)
|
||||
process(action="wait", session_id=session_id, timeout=300)
|
||||
```
|
||||
|
||||
Send a Kanban heartbeat every few minutes for lanes longer than two minutes, e.g. `kanban_heartbeat(note="Codex lane running in <WORKTREE>; waiting for tests/diff")`.
|
||||
|
||||
Kill conditions:
|
||||
|
||||
- No useful output for the task's remaining runtime budget.
|
||||
- Codex requests secrets, production credentials, or external permissions.
|
||||
- Codex attempts to modify files outside the worktree.
|
||||
- Codex starts unrelated rewrites or dependency churn.
|
||||
- Codex is still running near the worker timeout and no safe partial artifact exists.
|
||||
|
||||
Kill command:
|
||||
|
||||
```python
|
||||
process(action="kill", session_id=session_id)
|
||||
```
|
||||
|
||||
After kill, inspect `git status --short`, preserve useful patches only if safe, and record `codex_lane.result: timed_out` or `rejected` with a concrete `rejected_reason`.
|
||||
|
||||
## Reconciliation Checklist
|
||||
|
||||
Hermes must perform this checklist before accepting any Codex lane result:
|
||||
|
||||
- [ ] `git -C <WORKTREE> status --short --branch` shows only expected files.
|
||||
- [ ] `git -C <WORKTREE> diff --stat` and `git diff` were reviewed by Hermes.
|
||||
- [ ] No secrets, credentials, generated caches, unrelated data, or local artifacts are included.
|
||||
- [ ] PMB safety constraints were preserved: no live REST order entry, no market orders, no execution crossing, no fake passive fills/PnL, no risk-gate weakening, no secrets.
|
||||
- [ ] Codex commits are small enough to cherry-pick or squash cleanly.
|
||||
- [ ] Hermes ran the canonical tests itself, using `scripts/run_tests.sh` for Hermes Agent or the repo's documented wrapper for other repos.
|
||||
- [ ] Any Codex-run tests are listed separately from Hermes-run tests.
|
||||
- [ ] Accepted commits/diffs were applied to the Hermes-owned workspace/branch.
|
||||
- [ ] Rejected or partial work has a concrete reason and artifact path if useful.
|
||||
|
||||
Acceptance outcomes:
|
||||
|
||||
- `accepted`: Codex diff/commits were reviewed, applied, and verified.
|
||||
- `partial`: Some Codex work was accepted after edits or cherry-picks; rejected parts are documented.
|
||||
- `rejected`: No Codex changes were accepted; reason is documented.
|
||||
- `timed_out`: Codex exceeded the lane budget; useful artifacts may or may not exist.
|
||||
|
||||
## kanban_complete Metadata Schema
|
||||
|
||||
Include this object under `metadata.codex_lane` for every task where the lane was considered. If Codex was not used, set `used: false` and explain why in `rejected_reason` or a sibling `notes` field.
|
||||
|
||||
```json
|
||||
{
|
||||
"codex_lane": {
|
||||
"used": true,
|
||||
"mode": "exec | goal | skipped",
|
||||
"worktree": "/absolute/path/to/codex/worktree",
|
||||
"branch": "codex/t_caa69668/20260508100000",
|
||||
"command": "codex exec --full-auto ...",
|
||||
"result": "accepted | rejected | partial | timed_out",
|
||||
"accepted_commits": ["<sha1>", "<sha2>"],
|
||||
"rejected_reason": "empty when fully accepted; otherwise concrete reason",
|
||||
"tests_run": [
|
||||
{"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
|
||||
{"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
|
||||
],
|
||||
"artifacts": ["/absolute/path/to/log-or-patch"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For tasks that intentionally skip Codex:
|
||||
|
||||
```json
|
||||
{
|
||||
"codex_lane": {
|
||||
"used": false,
|
||||
"mode": "skipped",
|
||||
"worktree": null,
|
||||
"branch": null,
|
||||
"command": null,
|
||||
"result": "rejected",
|
||||
"accepted_commits": [],
|
||||
"rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
|
||||
"tests_run": [],
|
||||
"artifacts": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. Treating Codex self-report as verification. Always inspect the diff and rerun tests from Hermes.
|
||||
2. Running Codex in the user's dirty main checkout. Always isolate in a worktree/branch.
|
||||
3. Letting Codex own Kanban. Codex may summarize progress, but Hermes writes board state.
|
||||
4. Forgetting PMB safety invariants in the prompt. Missing safety text is a lane setup failure.
|
||||
5. Using `/goal` for quick edits. Prefer `codex exec` unless durable multi-step continuation is needed.
|
||||
6. Killing a stuck lane without recording why. `rejected_reason` must explain the decision.
|
||||
7. Accepting broad unrelated cleanup because tests pass. Reject or cherry-pick only the scoped changes.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Codex was skipped or started only after `command -v codex`, `codex --version`, and optional goals feature checks.
|
||||
- [ ] Codex ran only in an isolated worktree/branch.
|
||||
- [ ] Prompt included task scope, ownership rules, PMB safety constraints when applicable, and verification commands.
|
||||
- [ ] Hermes reviewed `git diff` and safety-sensitive files.
|
||||
- [ ] Hermes ran canonical tests independently.
|
||||
- [ ] `kanban_complete.metadata.codex_lane` follows the schema above.
|
||||
- [ ] Temporary processes and unnecessary worktrees were cleaned up.
|
||||
@@ -0,0 +1,57 @@
|
||||
# PMB Codex Lane Prompt Template
|
||||
|
||||
Use this template when a Hermes Kanban worker chooses to run Codex as an implementation lane for prediction-market-bot. Fill every bracketed field before launching Codex. Do not include secrets.
|
||||
|
||||
```text
|
||||
You are Codex CLI running as an input lane for a Hermes Kanban worker.
|
||||
|
||||
Ownership:
|
||||
- Hermes owns the Kanban task lifecycle, final review, test verification, and handoff.
|
||||
- You are an implementation lane only. Do not call Hermes kanban tools, Hermes CLI board commands, messaging gateways, or external notification tools.
|
||||
- Produce a scoped diff/commits and a concise report; do not mark any task complete.
|
||||
|
||||
Task:
|
||||
- task_id: [KANBAN_TASK_ID]
|
||||
- title: [KANBAN_TITLE]
|
||||
- acceptance criteria:
|
||||
[PASTE_ACCEPTANCE_CRITERIA]
|
||||
|
||||
Repository and isolation:
|
||||
- repo: [REPO_PATH]
|
||||
- worktree: [CODEX_WORKTREE_PATH]
|
||||
- branch: [CODEX_BRANCH]
|
||||
- allowed files/scope: [ALLOWED_FILES_OR_DIRECTORIES]
|
||||
- forbidden files/scope: [FORBIDDEN_FILES_OR_DIRECTORIES]
|
||||
|
||||
PMB safety constraints:
|
||||
- live-SIM is paper-only; do not add or enable live REST order entry.
|
||||
- Never use market orders.
|
||||
- Do not add execution crossing or bypass price/risk checks.
|
||||
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
|
||||
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
|
||||
- Keep research/selection outside the C++ hot path unless explicitly requested.
|
||||
- Do not read, print, write, or require secrets/tokens/credentials.
|
||||
|
||||
Implementation constraints:
|
||||
- Follow existing project conventions and style.
|
||||
- Keep diffs small and reviewable.
|
||||
- Do not perform unrelated refactors, dependency upgrades, formatting sweeps, or generated-file churn.
|
||||
- If a requirement is unsafe or ambiguous, stop and report the blocker instead of guessing.
|
||||
- Commit only if asked by the Hermes worker; if committing, use small commits with clear subjects.
|
||||
|
||||
Verification you may run:
|
||||
- [COMMAND_1]
|
||||
- [COMMAND_2]
|
||||
|
||||
Verification Hermes will rerun independently:
|
||||
- [HERMES_COMMAND_1]
|
||||
- [HERMES_COMMAND_2]
|
||||
|
||||
Required final report:
|
||||
- Summary of changes.
|
||||
- Files changed.
|
||||
- Commit SHAs, if any.
|
||||
- Tests/commands run with exit codes.
|
||||
- Safety constraints checked.
|
||||
- Known risks or incomplete items.
|
||||
```
|
||||
@@ -0,0 +1,219 @@
|
||||
---
|
||||
name: opencode
|
||||
description: "Delegate coding to OpenCode CLI (features, PR review)."
|
||||
version: 1.2.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Coding-Agent, OpenCode, Autonomous, Refactoring, Code-Review]
|
||||
related_skills: [claude-code, codex, hermes-agent]
|
||||
---
|
||||
|
||||
# OpenCode CLI
|
||||
|
||||
Use [OpenCode](https://opencode.ai) as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User explicitly asks to use OpenCode
|
||||
- You want an external coding agent to implement/refactor/review code
|
||||
- You need long-running coding sessions with progress checks
|
||||
- You want parallel task execution in isolated workdirs/worktrees
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- OpenCode installed: `npm i -g opencode-ai@latest` or `brew install anomalyco/tap/opencode`
|
||||
- Auth configured: `opencode auth login` or set provider env vars (OPENROUTER_API_KEY, etc.)
|
||||
- Verify: `opencode auth list` should show at least one provider
|
||||
- Git repository for code tasks (recommended)
|
||||
- `pty=true` for interactive TUI sessions
|
||||
|
||||
## Binary Resolution (Important)
|
||||
|
||||
Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check:
|
||||
|
||||
```
|
||||
terminal(command="which -a opencode")
|
||||
terminal(command="opencode --version")
|
||||
```
|
||||
|
||||
If needed, pin an explicit binary path:
|
||||
|
||||
```
|
||||
terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)
|
||||
```
|
||||
|
||||
## One-Shot Tasks
|
||||
|
||||
Use `opencode run` for bounded, non-interactive tasks:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")
|
||||
```
|
||||
|
||||
Attach context files with `-f`:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")
|
||||
```
|
||||
|
||||
Show model thinking with `--thinking`:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")
|
||||
```
|
||||
|
||||
Force a specific model:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")
|
||||
```
|
||||
|
||||
## Interactive Sessions (Background)
|
||||
|
||||
For iterative work requiring multiple exchanges, start the TUI in background:
|
||||
|
||||
```
|
||||
terminal(command="opencode", workdir="~/project", background=true, pty=true)
|
||||
# Returns session_id
|
||||
|
||||
# Send a prompt
|
||||
process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")
|
||||
|
||||
# Monitor progress
|
||||
process(action="poll", session_id="<id>")
|
||||
process(action="log", session_id="<id>")
|
||||
|
||||
# Send follow-up input
|
||||
process(action="submit", session_id="<id>", data="Now add error handling for token expiry")
|
||||
|
||||
# Exit cleanly — Ctrl+C
|
||||
process(action="write", session_id="<id>", data="\x03")
|
||||
# Or just kill the process
|
||||
process(action="kill", session_id="<id>")
|
||||
```
|
||||
|
||||
**Important:** Do NOT use `/exit` — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (`\x03`) or `process(action="kill")` to exit.
|
||||
|
||||
### TUI Keybindings
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Enter` | Submit message (press twice if needed) |
|
||||
| `Tab` | Switch between agents (build/plan) |
|
||||
| `Ctrl+P` | Open command palette |
|
||||
| `Ctrl+X L` | Switch session |
|
||||
| `Ctrl+X M` | Switch model |
|
||||
| `Ctrl+X N` | New session |
|
||||
| `Ctrl+X E` | Open editor |
|
||||
| `Ctrl+C` | Exit OpenCode |
|
||||
|
||||
### Resuming Sessions
|
||||
|
||||
After exiting, OpenCode prints a session ID. Resume with:
|
||||
|
||||
```
|
||||
terminal(command="opencode -c", workdir="~/project", background=true, pty=true) # Continue last session
|
||||
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true) # Specific session
|
||||
```
|
||||
|
||||
## Common Flags
|
||||
|
||||
| Flag | Use |
|
||||
|------|-----|
|
||||
| `run 'prompt'` | One-shot execution and exit |
|
||||
| `--continue` / `-c` | Continue the last OpenCode session |
|
||||
| `--session <id>` / `-s` | Continue a specific session |
|
||||
| `--agent <name>` | Choose OpenCode agent (build or plan) |
|
||||
| `--model provider/model` | Force specific model |
|
||||
| `--format json` | Machine-readable output/events |
|
||||
| `--file <path>` / `-f` | Attach file(s) to the message |
|
||||
| `--thinking` | Show model thinking blocks |
|
||||
| `--variant <level>` | Reasoning effort (high, max, minimal) |
|
||||
| `--title <name>` | Name the session |
|
||||
| `--attach <url>` | Connect to a running opencode server |
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Verify tool readiness:
|
||||
- `terminal(command="opencode --version")`
|
||||
- `terminal(command="opencode auth list")`
|
||||
2. For bounded tasks, use `opencode run '...'` (no pty needed).
|
||||
3. For iterative tasks, start `opencode` with `background=true, pty=true`.
|
||||
4. Monitor long tasks with `process(action="poll"|"log")`.
|
||||
5. If OpenCode asks for input, respond via `process(action="submit", ...)`.
|
||||
6. Exit with `process(action="write", data="\x03")` or `process(action="kill")`.
|
||||
7. Summarize file changes, test results, and next steps back to user.
|
||||
|
||||
## PR Review Workflow
|
||||
|
||||
OpenCode has a built-in PR command:
|
||||
|
||||
```
|
||||
terminal(command="opencode pr 42", workdir="~/project", pty=true)
|
||||
```
|
||||
|
||||
Or review in a temporary clone for isolation:
|
||||
|
||||
```
|
||||
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)
|
||||
```
|
||||
|
||||
## Parallel Work Pattern
|
||||
|
||||
Use separate workdirs/worktrees to avoid collisions:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
|
||||
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
|
||||
process(action="list")
|
||||
```
|
||||
|
||||
## Session & Cost Management
|
||||
|
||||
List past sessions:
|
||||
|
||||
```
|
||||
terminal(command="opencode session list")
|
||||
```
|
||||
|
||||
Check token usage and costs:
|
||||
|
||||
```
|
||||
terminal(command="opencode stats")
|
||||
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Interactive `opencode` (TUI) sessions require `pty=true`. The `opencode run` command does NOT need pty.
|
||||
- `/exit` is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
|
||||
- PATH mismatch can select the wrong OpenCode binary/model config.
|
||||
- If OpenCode appears stuck, inspect logs before killing:
|
||||
- `process(action="log", session_id="<id>")`
|
||||
- Avoid sharing one working directory across parallel OpenCode sessions.
|
||||
- Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).
|
||||
|
||||
## Verification
|
||||
|
||||
Smoke test:
|
||||
|
||||
```
|
||||
terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")
|
||||
```
|
||||
|
||||
Success criteria:
|
||||
- Output includes `OPENCODE_SMOKE_OK`
|
||||
- Command exits without provider/model errors
|
||||
- For code tasks: expected files changed and tests pass
|
||||
|
||||
## Rules
|
||||
|
||||
1. Prefer `opencode run` for one-shot automation — it's simpler and doesn't need pty.
|
||||
2. Use interactive background mode only when iteration is needed.
|
||||
3. Always scope OpenCode sessions to a single repo/workdir.
|
||||
4. For long tasks, provide progress updates from `process` logs.
|
||||
5. Report concrete outcomes (files changed, tests, remaining risks).
|
||||
6. Exit interactive sessions with Ctrl+C or kill, never `/exit`.
|
||||
Reference in New Issue
Block a user