better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md

@@ -1,230 +0,0 @@
----
-title: "Hermes Agent — Use, configure, theme, extend, and orchestrate Hermes Agent"
-sidebar_label: "Hermes Agent"
-description: "Use, configure, theme, extend, and orchestrate Hermes Agent"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Hermes Agent
-
-Use, configure, theme, extend, and orchestrate Hermes Agent.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/autonomous-ai-agents\hermes-agent` |
-| Version | `3.2.0` |
-| Author | Hermes Agent + Teknium |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Hermes Agent
-
-Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.
-
-What makes Hermes different:
-
-- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
-- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
-- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
-- **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
-- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
-- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
-- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
-
-**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.
-
-**Docs:** https://hermes-agent.nousresearch.com/docs/
-
-## Scope & Verification
-
-This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
-
-Good verification targets, cheapest first:
-
-- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.
-- CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`
-- Source tree: https://github.com/NousResearch/hermes-agent
-
-Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable.
-
-## Quick Start
-
-```bash
-# Install (shell installer — sets up uv, Python, the venv, and the launcher)
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-
-# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
-hermes
-
-# Single query
-hermes chat -q "What is the capital of France?"
-
-# Setup wizard  /  pick model+provider  /  health check
-hermes setup
-hermes model
-hermes doctor
-
-# Other surfaces
-hermes desktop                 # launch the native desktop app (alias: hermes gui)
-hermes dashboard               # web admin panel + embedded chat
-hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider
-```
-
-## Key Paths
-
-```
-~/.hermes/config.yaml       Main configuration (settings — never secrets)
-~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
-$HERMES_HOME/skills/        Installed skills
-~/.hermes/skins/            Custom themes (see references/themes.md)
-~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
-~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
-~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
-~/.hermes/state.db          Canonical session store (SQLite + FTS5)
-~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
-~/.hermes/logs/             Gateway and error logs
-~/.hermes/auth.json         OAuth tokens and credential pools
-~/.hermes/hermes-agent/     Source code (if git-installed)
-```
-
-Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.
-
-## Routing Table — load the reference for the task
-
-| User wants... | Load |
-|---|---|
-| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** |
-| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |
-| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
-| In-session slash commands | `references/slash-commands.md` |
-| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
-| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
-| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |
-| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
-| Delegation, cron, curator, kanban | `references/background-systems.md` |
-| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |
-| Webhook routes and event-driven runs | `references/webhooks.md` |
-| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
-| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
-| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
-| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
-| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
-| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
-| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
-| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
-| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
-| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |
-
-The reference list above is not the feature list — it is the set of topics that
-need more than their docs page. For everything else Hermes ships, fetch
-`llms.txt` and it maps the question to the page that answers it.
-
-Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
-
-## Spawning Additional Hermes Instances
-
-Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.
-
-### When to Use This vs delegate_task
-
-| | `delegate_task` | Spawning `hermes` process |
-|-|-----------------|--------------------------|
-| Isolation | Separate conversation, shared process | Fully independent process |
-| Duration | Minutes (bounded by parent loop) | Hours/days |
-| Tool access | Subset of parent's tools | Full tool access |
-| Interactive | No | Yes (PTY mode) |
-| Use case | Quick parallel subtasks | Long autonomous missions |
-
-### One-Shot Mode
-
-```
-terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)
-
-# Background for long tasks:
-terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
-```
-
-### Interactive PTY Mode (via tmux)
-
-Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
-
-```
-# Start
-terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)
-
-# Wait for startup, then send a message
-terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)
-
-# Read output
-terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)
-
-# Send follow-up
-terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)
-
-# Exit
-terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
-```
-
-### Multi-Agent Coordination
-
-```
-# Agent A: backend
-terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
-terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)
-
-# Agent B: frontend
-terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
-terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)
-
-# Check progress, relay context between them
-terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
-terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
-```
-
-### Session Resume
-
-```
-# Resume most recent session
-terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)
-
-# Resume specific session
-terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)
-```
-
-### Tips
-
-- **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process
-- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
-- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
-- **Use `hermes chat -q` for fire-and-forget** — no PTY needed
-- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
-- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
-- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
-- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
-
-## Surfaces (quick orientation)
-
-- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
-- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
-- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
-- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
-
-## Hard Invariants (never violate, regardless of what you loaded)
-
-- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
-- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
-- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
-- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.
-- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md

@@ -1,176 +0,0 @@
----
-title: "Merge Reconciler — Neutral third-party resolution of agent merge conflicts"
-sidebar_label: "Merge Reconciler"
-description: "Neutral third-party resolution of agent merge conflicts"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Merge Reconciler
-
-Neutral third-party resolution of agent merge conflicts.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/autonomous-ai-agents\merge-reconciler` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Multi-Agent`, `Git`, `Merge-Conflict`, `Kanban`, `Arbitration` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Merge Reconciler
-
-Resolve a git merge conflict between two AGENTS' branches as an impartial third
-party. Agents resolving conflicts against a peer's work reliably either
-overwrite the peer or abandon their own change — they lack the peer's context
-and are biased toward their own side. This skill is the fix: a neutral
-reconciler that receives both diffs plus both sides' stated intents and
-produces a merged result, like a merge-queue arbiter.
-
-## When to Use
-
-- Two agent branches/worktrees collide during a parallel campaign (kanban
-  engineering pipeline, parallel-PR wave, multi-worktree refactor).
-- `git merge` or `git rebase` halts on conflicts between two agents' work and
-  neither original agent should self-adjudicate.
-- Do NOT use for conflicts within a single agent's own work, or for trivial
-  lockfile/generated-file conflicts (regenerate those instead).
-
-## Prerequisites
-
-- A repo checkout containing the halted merge, or the two branch names plus
-  permission to run the merge yourself.
-- Both sides' intent sources: kanban completion summaries (`terminal` running
-  `hermes kanban show <task-id>`), PR bodies, or at minimum each branch's
-  commit messages.
-- The project's build/test command, if one exists.
-
-## How to Run
-
-**Standalone** — a human (or agent) invokes this skill inside the conflicted
-repo: load the skill, then follow the Procedure top to bottom.
-
-**Spawned neutral agent** — the preferred shape in multi-agent campaigns:
-
-- `delegate_task`: spawn a subagent whose task message contains the repo path,
-  both branch names, and both sides' intent summaries verbatim, plus an
-  instruction to follow this skill.
-- Kanban-native: create a reconciliation card assigned to a **third profile**
-  (not either worker's profile) with BOTH conflicted cards linked as parents —
-  `kanban_create(title="reconcile branch-a x branch-b", assignee="reconciler",
-  parents=["t_a", "t_b"])`. The parent links carry both sides' completion
-  summaries into the reconciler's context automatically; the card body should
-  name the repo path and the two branches.
-
-## Quick Reference
-
-| Hunk class | Definition | Resolution |
-|---|---|---|
-| disjoint-intent | The two changes serve different goals and can coexist | Combine both |
-| same-question-different-answer | Both sides answered one design question differently | Pick ONE per stated intents; surface the decision |
-| superseded | One side's premise no longer holds after the other's change | Keep the surviving side; note why |
-
-Impartiality contract: never favor the side that spawned you; touch ONLY
-conflicted regions (no drive-by edits); every design-question pick must appear
-explicitly in the hand-back summary.
-
-## Procedure
-
-### 1. Gather both sides
-
-- Run via `terminal`: `git status` (confirm the conflicted state and list
-  conflicted files), `git merge-base <A> <B>`, then for each side
-  `git log --oneline <base>..<side>` and `git diff <base>..<side> -- <file>`
-  for every conflicted file. In a halted merge, `HEAD` is one side and
-  `MERGE_HEAD` is the other.
-- Collect each side's intent: `hermes kanban show <task-id>` for completion
-  summaries/metadata, or the PR body, or the commit messages from the log
-  above. Write down one sentence of intent per side before touching any file.
-- Done when: you can state both intents in your own words and have both diffs
-  for every conflicted file.
-
-### 2. Classify every conflicted hunk
-
-- Open each conflicted file with `read_file` and locate each
-  `<<<<<<<`/`=======`/`>>>>>>>` block.
-- Assign each hunk exactly one class from the Quick Reference table, judging
-  by the stated intents — not by which change looks nicer.
-- If a single hunk contains multiple independent decisions (e.g., new logic
-  that combines cleanly PLUS a styling/rounding choice both sides answered
-  differently), decompose it into sub-decisions and classify each one.
-- A single file often mixes classes: one hunk may be a design collision while
-  a neighboring hunk is disjoint. Classify per hunk, not per file.
-- Done when: every hunk has a written class and a one-line rationale.
-
-### 3. Resolve under the impartiality contract
-
-- Edit each hunk with `patch` (or `write_file` for whole-file rewrites):
-  - disjoint-intent → merge both changes so each intent is fully served.
-  - same-question-different-answer → pick the answer that best serves the
-    STATED intents (e.g., an intent of "strict validation" beats "quick
-    default" if the task required correctness). Never split the difference
-    into a hybrid neither side asked for.
-  - superseded → keep the surviving side; delete the dead premise.
-- Never favor the side that spawned you. If intents genuinely tie, escalate
-  (block the kanban card / report back) rather than guess.
-- Change nothing outside conflict markers — no formatting, renames, or
-  opportunistic fixes.
-- `git add` each resolved file via `terminal`.
-- Done when: `search_files` finds no `<<<<<<<` markers in the repo and every
-  resolved file is staged.
-
-### 4. Verify
-
-- Run the project's build/tests via `terminal`; at minimum import/execute the
-  touched modules. Both intents must be observable in the merged behavior
-  (e.g., side A's new semantics AND side B's disjoint addition both present).
-- Complete the merge: `git commit` (the default merge message plus a body
-  listing hunk decisions is fine).
-- Done when: verification passes and the merge commit exists.
-
-### 5. Hand back
-
-- Produce a completion summary naming EVERY hunk decision:
-  `file:lines — class — which side(s) kept — rationale`. For every
-  same-question-different-answer hunk, state the design question and the
-  answer you picked so a human can veto it — never bury a design call.
-- Kanban: `kanban_complete(summary=...)`. Standalone: print the summary.
-- Done when: the summary is delivered and lists all hunks.
-
-## Pitfalls
-
-- **Self-favoring**: if you were spawned by one of the conflicting agents,
-  you are structurally biased — state this and weigh the other side's intent
-  deliberately. Prefer the third-profile shape so this never arises.
-- **Splitting the difference** on a design collision produces a hybrid nobody
-  designed; pick one answer and surface it.
-- **Per-file classification**: files usually mix hunk classes; classifying a
-  whole file as one class silently drops a disjoint change.
-- **Drive-by edits** make the merge unreviewable and steal decisions from the
-  original agents.
-- **Missing intents**: commit messages alone can be thin; prefer kanban
-  completion summaries or PR bodies. If neither side's intent is recoverable,
-  escalate instead of guessing.
-- **Repeat offenders**: repeated conflicts on the SAME file across rounds are
-  a hotspot signal, not routine reconciliation work — flag it (e.g. a
-  `hotspot: <path> — <reason>` kanban comment) so the orchestrator decomposes
-  that file, rather than serially reconciling every new collision on it.
-
-## Verification
-
-- `git status` shows a clean tree on the target branch with a merge commit.
-- No conflict markers remain (`search_files` pattern `<<<<<<<`).
-- Build/tests pass; both sides' intents are demonstrably present or the
-  dropped one is explicitly named in the summary.
-- The hand-back summary enumerates every hunk with class and rationale.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md

@@ -1,237 +0,0 @@
----
-title: "Opencode — Delegate coding to OpenCode CLI (features, PR review)"
-sidebar_label: "Opencode"
-description: "Delegate coding to OpenCode CLI (features, PR review)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Opencode
-
-Delegate coding to OpenCode CLI (features, PR review).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/autonomous-ai-agents\opencode` |
-| Version | `1.2.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |
-| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# 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`.