hermes-code-bridge

name	hermes-code-bridge
description	Use when connecting Hermes Agent to local coding CLIs such as Codex, Kimi Code, Claude Code, OpenCode, Gemini CLI, or other terminal-based coding assistants. Provides session-first routing, tracked dispatch, evidence-based verification, and honest reporting without pretending Hermes did delegated work.
version	1.1.0
author	Hermes Agent
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["hermes","coding-agents","cli","codex","kimi-code","claude-code","opencode","orchestration","tmux","dispatch"],"related_skills":["hermes-agent","cli-agent-orchestrator","codex","claude-code","opencode"]}}

Hermes Code Bridge

Overview

Hermes Code Bridge turns Hermes Agent into a control layer for local terminal-based coding agents. The goal is not to replace Codex, Kimi Code, Claude Code, OpenCode, Gemini CLI, or similar tools. The goal is to let Hermes coordinate them safely: choose the right tool, reuse the right session, send a precise task prompt, monitor the run, collect raw evidence, and report what actually happened.

Use this skill when the user wants Hermes to connect to one or more local coding CLIs and make them do implementation, review, debugging, research, experiment management, documentation, or repository maintenance work.

The bridge pattern is:

User request
  -> Hermes clarifies scope and chooses an existing local coding agent/session
  -> Hermes sends a structured prompt through the real CLI
  -> Local coding CLI executes in its own workspace/session
  -> Hermes monitors output, verifies artifacts, and reports evidence

Hermes is the control plane. Local coding CLIs are execution backends. The terminal, tmux, session archives, and output files are the transport and evidence layer.

This is intentionally lighter than a full multi-agent workspace manager. Projects such as CCB (claude_codex_bridge) create visible tmux workspaces with configured panes, sidebars, team topology, worktrees, and inter-agent communication. Hermes Code Bridge is a Hermes skill: it does not require a new workspace system. It teaches Hermes how to drive whichever local coding CLIs are already installed, while preserving real sessions and verifiable outputs.

When to Use

Use this skill when:

• The user asks Hermes to make Codex, Kimi Code, Claude Code, OpenCode, Gemini CLI, or another local coding agent do work.
• The user wants Hermes to coordinate several coding agents without manually copying prompts between terminals.
• A task should be executed inside an existing coding-agent session instead of by Hermes directly.
• The user needs background monitoring and a concise evidence-based report after a long agent run.
• The user wants a general workflow for experiments, coding, debugging, documentation, review, or repository operations through local coding CLIs.

Do not use this skill when:

• The user only wants Hermes to answer a normal question directly.
• The task can be handled by Hermes tools and the user did not ask for a specific coding CLI.
• The user wants a full tmux workspace product with persistent pane layout, sidebar UI, and project team config; in that case consider using or configuring a dedicated tool such as CCB.
• The requested CLI is not installed or not authenticated; report that honestly instead of substituting Hermes work.

Core Principles

1. Use the real CLI. If the user asks for Codex, run Codex. If the user asks for Kimi Code, run Kimi Code. Do not use delegate_task, execute_code, or a Hermes subagent and claim that a different tool did the work.

2. Route session-first. Existing coding-agent sessions contain context, decisions, tool history, and project assumptions. Reuse a session only after jointly matching the repository working directory, full session ID or thread name, role, and relevant history. Do not treat --last or another recent-session shortcut as the default correct answer. If no reliable match exists, use an intentional one-shot run instead of pretending to resume.

3. Hermes coordinates; workers execute. Hermes can inspect, route, prompt, monitor, verify, and summarize. While a worker runs, Hermes should continue non-conflicting repository inspection, constraint checks, and evidence collection. Hermes must not edit the same working tree concurrently with a worker.

4. Confirm before dispatch when side effects matter. If the task may edit files, run expensive jobs, change git state, call external APIs, or resume an ambiguous session, show the chosen agent/session and prompt draft before sending it.

5. Use an evidence ladder. A worker final message or self-report is only a lead. Before success, verify real artifacts, git diff and git status, and original command or test output. For remote side effects, also read back the remote URL, ID, or state.

6. Track bounded long runs. Use a traceable background process and completion notification when the host provides one. Check startup failure, final output, and exit code. Exit code 0 alone is not proof that the requested work completed.

7. Report blockers honestly. If work is incomplete, state what completed, what did not, why it is blocked, and the next concrete step. Do not invent output that merely looks plausible.

8. Keep it general and private. Public skills must not contain personal paths, private project names, private session IDs, credentials, private endpoints, or organization-specific assumptions.

Architecture Model

Think of the bridge as four layers:

Layer	Responsibility
Hermes control layer	Interpret user intent, choose backend, write prompt, monitor, verify, report.
Coding CLI backend	Codex, Kimi Code, Claude Code, OpenCode, Gemini CLI, or another terminal coding assistant.
Session/state layer	Existing CLI sessions, project directories, tmux panes, logs, JSONL archives, or CLI history files.
Evidence layer	Terminal output, final messages, diffs, generated files, test logs, screenshots, benchmark outputs.

The skill should work with two operating styles:

• Direct non-interactive dispatch: Hermes runs a single CLI command with a prompt and waits or monitors in the background.
• Interactive workspace dispatch: Hermes sends prompts into an existing tmux pane or resumes a CLI session that the user also can observe manually.

Pre-flight Checks

Before dispatching work to a local coding CLI, gather enough context to avoid sending the wrong task to the wrong backend.

1. Identify the requested backend

Map user language to a backend:

User wording	Backend
Codex, OpenAI Codex	codex
Kimi Code, Kimi CLI	kimi or the user's configured Kimi command
Claude Code	claude
OpenCode	opencode
Gemini CLI	gemini or the user's configured Gemini command
coding agent, local agent, worker	Ask or infer from project/session context

If the user names a backend, do not silently substitute another backend.

2. Check installation

command -v codex || true
command -v kimi || true
command -v claude || true
command -v opencode || true
command -v gemini || true

If a command is missing, report it and suggest installation/configuration. Do not pretend dispatch succeeded.

3. Confirm the working directory

Prefer the project root, not the user's home directory.

pwd
git rev-parse --show-toplevel 2>/dev/null || true
git status --short 2>/dev/null || true

For repository tasks, include the absolute working directory in the dispatch prompt and command.

4. Discover existing sessions

Use the backend's session list, history files, or project metadata. The exact storage paths and commands vary by tool version, so treat the examples below as patterns, not immutable API contracts.

Codex examples:

# If supported by the installed CLI
codex --help
codex exec --help
codex resume --help

# Common local archive patterns; inspect read-only
find ~/.codex -maxdepth 4 -type f \( -name '*.jsonl' -o -name '*.json' -o -name '*.toml' \) 2>/dev/null | head -50

Kimi Code examples:

kimi --help
find ~/.kimi -maxdepth 4 -type f \( -name '*.jsonl' -o -name '*.json' -o -name '*.toml' \) 2>/dev/null | head -50

Claude Code examples:

claude --help
find ~/.claude -maxdepth 4 -type f 2>/dev/null | head -50

OpenCode examples:

opencode --help
find ~/.opencode ~/.config/opencode -maxdepth 4 -type f 2>/dev/null | head -50

5. Decide whether confirmation is required

Require confirmation before dispatch when any of these are true:

• The target session is ambiguous.
• The command may modify files, run long experiments, spend money, push commits, open PRs, deploy, or delete data.
• The prompt includes assumptions not explicitly stated by the user.
• The requested backend is unavailable and an alternative is being proposed.
• The work is public-facing or could expose private information.

For read-only inspection or tiny status checks, it is usually acceptable to proceed directly and report results.

Session Selection Protocol

When multiple sessions exist, use session-first routing. A session is reusable only when the available evidence gives a reliable match. Do not choose it by recency alone.

Match these signals together, in this order:

1. Current project directory or repository root.
2. User-provided full session ID or thread name, when available.
3. Session title, first user prompt, or declared role.
4. Recent conversation summary or archive content that matches the requested work.
5. Files or artifacts the session has touched, when that evidence is available.

Common session roles:

Role	Use for
main / lead / controller	Planning, high-level coordination, final integration.
implementation / worker	Code edits, scripts, feature implementation.
reviewer	Code review, risk analysis, PR feedback.
debugger	Reproducing bugs, reading logs, root-cause analysis.
research	Literature, library, API, or benchmark research.
data / experiments	Dataset processing, experiment runs, result aggregation.
docs / writer	README, docs, release notes, design docs.

Selection rules:

• A full session ID or thread name is stronger than a display label or a recent-session shortcut.
• A matching project alone is insufficient when several sessions exist for that project. Use role and history to disambiguate.
• --last means only "the most recent session." Do not use it as the session-first default.
• If the signals conflict or no reliable match exists, explain the ambiguity and use a one-shot run when the user allows it. Do not silently create or misrepresent a persistent session.

Dispatch Prompt Template

Use this template for non-trivial tasks:

You are the <ROLE> coding agent for this project.

Working directory:
<ABSOLUTE_PROJECT_DIR>

Background:
- <Relevant project context>
- <Relevant prior decisions or files>
- <What the user wants and why>

Task:
1. <Concrete step 1>
2. <Concrete step 2>
3. <Concrete step 3>

Constraints:
- Do not make unrelated changes.
- Do not add new abstractions, dependencies, configs, or features unless required for this task.
- Do not silently guess important missing requirements. If blocked, state the ambiguity and propose the smallest safe default.
- Preserve existing style and project conventions.
- If you find unrelated issues, mention them in the final report but do not fix them unless necessary for this task.

Success criteria:
- <Measurable criterion 1>
- <Measurable criterion 2>
- <Expected artifact path or command output>

Verification:
- Run or explain: <test command / lint command / manual check>
- Report exact commands run and whether they passed.

Final report format:
- Summary
- Files changed or artifacts created
- Commands run
- Verification results
- Remaining risks or blockers

For read-only research or review tasks, replace file-edit constraints with scope and evidence requirements:

Do not modify files. Read only the relevant files/logs/docs. Quote file paths, line numbers when possible, commands run, and confidence level for each conclusion.

Confirmation Template

When confirmation is required, show a concise confirmation block:

I understand the task as: <one-sentence summary>.

Proposed backend: <Codex/Kimi Code/Claude Code/OpenCode/...>
Working directory: <absolute path>
Session: <session name/id or "one-shot new run">
Reason: <why this backend/session fits>

Prompt draft:
---
<prompt>
---

Please confirm before I dispatch this to the local coding CLI.

Do not dispatch until the user confirms. If the user edits the prompt or selects a different backend, update the command accordingly.

Command Recipes

CLI flags change over time. Always check <command> --help when a command fails or when using a new version.

Codex

Common patterns:

# One-shot non-interactive
codex exec "<PROMPT>"

# One-shot with automatic approval if supported by the installed version
codex exec --ask-for-approval never "<PROMPT>"

# Run from a project directory if supported
codex exec -C <PROJECT_DIR> "<PROMPT>"

# Resume an explicit session or thread name if supported
codex exec resume <SESSION_ID_OR_THREAD_NAME> "<PROMPT>"

# JSON output for easier parsing if supported
codex exec --json -o <OUTPUT_JSONL> "<PROMPT>"

Automation notes:

• Prefer an explicit full session ID or thread name that reliably matches the repo, role, and history.
• Treat --last, where the installed CLI provides it, as a recent-session shortcut only. It is not the session-first default.
• Prefer non-interactive exec modes for Hermes terminal calls.
• If the CLI refuses due to repository trust or git checks, stop and report the exact error unless the user has already approved bypassing that guard.
• Use background execution for long tasks and monitor with Hermes process tools.

Kimi Code

Common patterns:

# One-shot non-interactive
kimi --print -p "<PROMPT>"

# Automatic approval if supported and appropriate
kimi --print --yolo -p "<PROMPT>"

# Resume an explicit session if supported
kimi -S <SESSION_ID> --print -p "<PROMPT>"

# Continue the latest session for the current directory if supported
kimi --continue --print -p "<PROMPT>"

# Specify working directory if supported
kimi -w <PROJECT_DIR> --print -p "<PROMPT>"

Automation notes:

• Use --print or equivalent non-interactive output mode when calling from Hermes.
• Do not rely on interactive session pickers unless running inside a tracked PTY/tmux pane.
• Use --yolo or AFK-style modes only when the user has approved the risk.

Claude Code

Common patterns:

# One-shot print mode
claude -p "<PROMPT>"

# With explicit working directory if supported
claude --cwd <PROJECT_DIR> -p "<PROMPT>"

# Inspect supported session/resume flags
claude --help

Automation notes:

• Claude Code often has rich interactive behavior. For Hermes automation, prefer print/non-interactive modes where possible.
• If using a persistent interactive Claude pane, use tmux send/capture rather than pretending the command is non-interactive.

OpenCode

Common patterns:

# Inspect installed CLI first because command syntax varies
opencode --help

# Typical one-shot pattern, if supported by installed version
opencode run "<PROMPT>"

# Project directory pattern, if supported
opencode run --cwd <PROJECT_DIR> "<PROMPT>"

Automation notes:

• OpenCode command syntax has changed across versions; verify with opencode --help before dispatch.
• Capture stdout/stderr and report the exact command form used.

Gemini CLI or other coding CLIs

Use the generic adapter pattern:

<AGENT_CMD> --help
<AGENT_CMD> <NON_INTERACTIVE_FLAGS> "<PROMPT>"

Record:

• command path from command -v <AGENT_CMD>
• version if available
• working directory
• exact prompt
• output file or terminal log

Interactive tmux Bridge

For long-running interactive CLIs, tmux can provide a visible bridge. This is useful when the user wants to observe the agent, intervene manually, or keep multiple agents alive.

Create or attach a project tmux session:

tmux new-session -d -s <SESSION_NAME> -c <PROJECT_DIR>
tmux send-keys -t <SESSION_NAME> "<AGENT_CMD>" Enter

Send a prompt:

tmux send-keys -t <SESSION_NAME> "<PROMPT>" Enter

Capture output:

tmux capture-pane -t <SESSION_NAME> -p -S -200

Safety notes:

• Escape quotes and newlines carefully. For large prompts, write the prompt to a temporary file and paste/send it in a controlled way.
• Prefer one tmux session per project or per agent group.
• Do not kill an existing tmux session unless the user confirms it is safe.
• If using a dedicated workspace manager such as CCB, follow that tool's config and command model instead of manually fighting its panes.

Background Monitoring

For bounded long-running tasks, run the CLI in the background with completion notification if available in the host environment.

Hermes tool pattern:

terminal(command="cd <PROJECT_DIR> && <AGENT_CMD> <FLAGS> '<PROMPT>'", background=True, notify_on_complete=True)
process(action="poll", session_id="<HERMES_PROCESS_ID>")
process(action="log", session_id="<HERMES_PROCESS_ID>", limit=80)
process(action="wait", session_id="<HERMES_PROCESS_ID>", timeout=180)

Monitoring checklist:

• Poll soon after start to catch immediate authentication or syntax failures.
• Record the process or job ID, working directory, start command, and output location so the run can be recovered and audited.
• Request completion notification when the host environment supports it. Do not silently lose a detached task.
• While the worker runs, Hermes should inspect independent repository facts, constraints, and verification targets. Do not wait idly, and do not edit the worker's working tree.
• For long jobs, report progress only when there is meaningful new output.
• If stuck at an interactive prompt, either answer only if the user already approved the choice, or ask the user.
• At the end, inspect final output, exit code, and expected artifacts. Exit code 0 is necessary evidence, not sufficient evidence of task completion.
• If the process fails, capture exit code and stderr. Do not hide failures behind a summary.

Evidence Collection

Collect evidence before reporting success. Follow this ladder in order; do not let a worker self-report skip later checks.

1. Worker report: capture the final message or self-report as a lead, including claimed files, tests, artifacts, and remote actions.
2. Real artifacts: verify each claimed file, generated output, screenshot, benchmark result, or other local artifact exists and is relevant.
3. Repository state: inspect git status, git diff, and relevant paths to confirm the actual working-tree changes.
4. Original verification output: run or inspect the raw output of tests, lint, build, benchmark, or other requested commands. Do not rely only on a worker summary.
5. Remote read-back: when a task has remote side effects, read back the remote URL, ID, or state through the relevant service or CLI before claiming success.

Minimum evidence:

• Exact backend and command used.
• Working directory.
• Session id, tmux pane, or output file when relevant.
• Final CLI output or a concise excerpt from raw output.
• Changed files or created artifacts, if any.
• Verification commands and results.
• Remote read-back result when remote state was changed.

Useful commands:

# Git evidence
git status --short
git diff --stat
git diff -- <RELEVANT_PATHS>

# Artifact evidence
find <OUTPUT_DIR> -maxdepth 2 -type f -print
file <ARTIFACT_PATH>

# Test evidence
<TEST_COMMAND>

If the coding CLI claims it created a file, verify the file exists. If it claims tests passed, inspect the actual test command output. If the output is truncated, say so. If it claims a remote action completed, read back the relevant remote state. If a required rung is unavailable, report the result as unverified or incomplete.

Reporting Template

Use a report like this:

Dispatched to: <backend>
Working directory: <path>
Session/process: <session id / tmux pane / Hermes process id>
Command: <exact command, with secrets redacted>

Result:
- <What completed>
- <Files changed or artifacts created>
- <Verification result>

Evidence:
```text
<short raw output excerpt>
```

Incomplete / blocked:
- <What did not complete>
- <What completed so far>
- <Blocking reason and next concrete step>

Risks:
- <Anything unresolved, ambiguous, or not verified>

For user-facing summaries, keep the report concise, but do not omit failure state or verification gaps.

Safety Rules

Never do these:

• Do not claim a local coding CLI ran unless the actual CLI command was executed.
• Do not use Hermes delegate_task or execute_code as a fake substitute for Codex/Kimi/Claude/OpenCode.
• Do not directly edit the coding agent's session database, JSONL history, or internal state files.
• Do not modify project files directly when the user explicitly asked a coding CLI to own the work, unless the user separately authorizes Hermes to edit files.
• Do not create a new persistent session when an existing relevant session should be reused.
• Do not use a recent-session shortcut as proof that the chosen session matches the request.
• Do not edit the same working tree while a dispatched worker may edit it. Use a separate worktree or wait for the worker to finish.
• Do not bypass sandbox, approval, git safety, or destructive-command prompts unless the user approved that risk.
• Do not paste secrets, private endpoints, personal paths, or private project names into a public skill or shareable prompt.

Recommended defaults:

• Prefer read-only inspection before write-heavy dispatch.
• Prefer explicit working directories and session IDs.
• Prefer non-interactive CLI flags for automation.
• Prefer tmux for long-lived interactive agents.
• Prefer worktrees for parallel agents editing the same repository.
• Prefer small, scoped prompts with clear success criteria over vague broad prompts.

Open-source Sanitization

Before publishing or sharing this skill, inspect for private information.

Remove or replace:

• Personal names, usernames, organization names, lab names, and relationship details.
• Absolute paths such as /Users/<name>/... or /home/<name>/....
• Private project names, paper names, dataset names, internal codenames, or unreleased features.
• Real session IDs, API keys, tokens, private base URLs, and account identifiers.
• Private communication habits, schedules, or user-specific preferences.

Use placeholders instead:

<PROJECT_DIR>
<SESSION_ID>
<AGENT_CMD>
<PROMPT>
<OUTPUT_JSONL>
<TEST_COMMAND>
<ARTIFACT_PATH>

Run a quick privacy scan before release:

grep -RInE "(/Users/|/home/|API_KEY|TOKEN|SECRET|SESSION_ID_HERE|PRIVATE|@)" SKILL.md references templates scripts 2>/dev/null || true

A public skill should teach the workflow, not expose a particular user's workflow map.

Relationship to Multi-Agent Workspace Tools

Hermes Code Bridge can coexist with workspace tools such as CCB.

Use a dedicated workspace tool when the user wants:

• A persistent tmux UI with multiple visible panes.
• Project-level team topology in a config file.
• Sidebar/status UI and inter-agent /ask routing.
• Managed worktrees and pane recovery.

Use Hermes Code Bridge when the user wants:

• A lightweight Hermes skill for dispatching to installed CLIs.
• One-shot or session-resume routing from Hermes conversations.
• Evidence-based reports back through Hermes.
• A portable pattern that works even without a full workspace manager.

If CCB is installed, Hermes can treat ccb as another bridge backend: inspect .ccb/ccb.config, start or attach the workspace, send prompts to the appropriate pane/agent, and capture output. By default Hermes remains an external orchestrator; this skill does not automatically make Hermes the CCB main-agent and does not ship a built-in CCB adapter. Follow the installed CCB command and workspace contract, and do not rewrite CCB configuration unless the user asked for that.

Common Pitfalls

1. Confusing Hermes with the worker. Hermes may be capable of doing the task, but if the user requested Codex/Kimi/Claude/OpenCode, run that real tool.

2. Using the wrong session. Recent is not always correct. Match by repository cwd, full session ID or thread name, role, and history. --last is not a session-first default.

3. Trusting summaries without evidence. A worker final message is a lead, not completion proof. Verify artifacts, repository state, original verification output, and remote state when applicable.

4. Idling or losing long jobs. Run bounded long jobs in the background with process tracking and completion notification when available. Inspect independent facts while they run, then check startup failure, final output, and exit code.

5. Interactive picker in non-TTY. Many CLIs fail when an interactive session picker runs without a terminal. Use explicit session IDs or tmux/PTY.

6. Over-broad prompts. Large vague prompts cause unnecessary rewrites. Use narrow tasks, constraints, and success criteria.

7. Unsafe approval bypass. Flags like --yolo, full-auto, or sandbox bypass are convenient but risky. Use only with user approval and appropriate repository state.

8. Publishing private workflow details. A reusable public skill should not include one user's project map, collaborators, filesystem paths, private endpoints, or real session IDs.

9. Hiding an incomplete result. Do not turn missing artifacts, failed verification, or an ambiguous session into a confident success summary. State the completed portion, blocker, and next step.

Verification Checklist

Before reporting completion:

• The requested backend was actually executed.
• The working directory was correct.
• The selected session reliably matched repo cwd, full session ID or thread name, role, and history, or the run was intentionally one-shot.
• The prompt contained role, task, constraints, success criteria, and output requirements.
• Side-effectful dispatch was confirmed by the user when needed.
• Background process startup, status, completion notification when available, final output, and exit code were checked.
• Hermes performed only non-conflicting work while the worker ran and did not edit the same working tree.
• Worker final output was treated as a lead and raw output or output file was inspected.
• Claimed artifacts/files were verified on disk.
• git status and relevant git diff evidence were inspected.
• Tests, lint, benchmarks, or manual checks have original output, or are explicitly marked not run.
• Remote effects were read back by URL, ID, or state, or are explicitly marked unverified.
• The final report includes command, evidence, result, unfinished work, blockers, next step, and unresolved risks.
• No secrets or private information appear in shareable output.

Minimal One-Shot Example

User asks: "Have Codex review this repository for risky changes."

Hermes should:

1. Confirm the repository root.
2. Check Codex is installed.
3. Decide whether this is read-only. If yes, dispatch without extra confirmation unless the user workflow requires it.
4. Run a real Codex command.
5. Capture and report evidence.

Example:

cd <PROJECT_DIR>
codex exec "Read-only review: inspect the current git diff and identify correctness, security, and maintainability risks. Do not modify files. Report file paths, line references when possible, severity, and recommended fixes."

Report:

Dispatched to: Codex
Working directory: <PROJECT_DIR>
Command: codex exec "Read-only review: ..."

Result:
- Found <N> issues / no blocking issues.
- No files modified.

Evidence:
<raw output excerpt>

Risks:
- Tests were not run because this was review-only.

Minimal Multi-Agent Example

User asks: "Ask one agent to implement and another to review."

Hermes should:

1. Choose separate sessions/backends, ideally separate worktrees if both may edit.
2. Confirm the plan and prompts.
3. Dispatch implementation first.
4. Verify diff/artifacts.
5. Dispatch review with the implementation context.
6. Report both outputs and any conflicts.

Implementation prompt should be scoped and surgical. Review prompt should be read-only unless the user asks for fixes.

Codex worker: implement the smallest change that satisfies <goal>; run <tests>; report files changed.
Claude reviewer: read the resulting diff only; do not modify files; list blockers, non-blockers, and test gaps.

If both agents need to edit concurrently, use git worktrees or isolated branches to avoid file conflicts.