hermes-claude-code-tmux

Files (8)

• SKILL.md
• alternative-multiplexer-runtimes.md · references/
• permissions-and-mcp-grants.md · references/
• tracker-writes-via-mcp.md · references/
• verifying-a-delegated-run.md · references/
• cc-drive.py · scripts/
• cc-live.py · scripts/
• trust_cloned_repos.py · scripts/

SKILL.md (first lines)

# hermes-claude-code-tmux

How a Hermes agent invokes Claude Code. Read this **before** the first `claude` call
of a task, not after one fails.

## Precedence

Where this skill and the bundled `autonomous-ai-agents/claude-code` skill disagree,
**this skill wins**. The bundled skill assumes a foreground call; that assumption is
wrong here.

## Authentication: subscription, not API key

Claude Code is authenticated with a **Claude subscription (OAuth)**, not an
`ANTHROPIC_API_KEY`. Two consequences:

- **Never pass `--max-budget-usd`.** It expresses an API-billing cap, which does not
  apply to subscription auth.
- **Never pass `--bare`.** It skips auto-discovery of skills, hooks, MCP servers,
  subagents and `CLAUDE.md` — exactly the context that should be loaded.

If a `claude` call fails on authentication, do **not** reach for an API key. Re-check
the OAuth session instead; a fresh box needs one interactive `claude` login on the
desktop, because print mode cannot prompt.

## MCP servers are live — scope and word prompts accordingly

Claude Code here inherits the account's claude.ai MCP servers. **Do not assume a
roster — read it:**

```bash
claude mcp list        # every server, and whether it is authenticated
```

Authentication state is the one fact in this area guaranteed to change: a server gets
connected, a token expires, a new one is added. A roster written into this file is
therefore wrong shortly after it is written, and wrong in the most misleading
direction — it reads as authoritative. Run the command while preparing the dispatch and
word the prompt against what it actually returns.

Consequences for a dispatch:

- **Never tell CC it has "no network access"**, and never write that a tracker it has
  an MCP for is out of its reach. The claim is false, and CC will faithfully report
  back "could not verify — no access" for something it could have checked itself. A
  delegated agent's self-report about its own capabilities is not evidence: run
  `claude mcp list`, don't believe it.
- **Name the systems to cross-check** in the prompt ("verify the release against
  Sentry via MCP", "read the issue's current body via Linear") and require each claim
  to be labelled *verified via MCP* or *taken on trust*.
- **Not everything is covered.** A self-hosted GitLab and a Kubernetes cluster are not
  in that roster, so those claims stay yours to verify with `glab`/`kubectl`. State
  that explicitly rather than letting CC guess which facts it owns.
- **A read-only run needs the restriction spelled out.** MCP tools can write to
  external systems — an audit must say "read only, change nothing in Linear/Sentry"
  and keep the `--settings` deny list, or a review can end in a mutated issue.
- **Do not pass `--bare` or `--strict-mcp-config`** on a task that needs those
  servers; both cut MCP discovery off.
- **"Connected" does not mean "callable".** A server listed as connected can still
  refuse an individual tool call for want of a granted permission, and print mode
  cannot run an authorization flow — CC comes back "permission not granted" and stops.
  Ask it to *name* any refused call rather than work around it, then read that system
  with your own connector tools and fold the answer into the deliverable. Deliver the
  fact, not the caveat: a review handed over as "could not check the ticket" is worse
  than one you closed out yourself before reporting.
- **A refused call and an invented one read the same in prose.** CC reports a tool as
  absent — "not available in this environment" — without having attempted any call, and
  does it repeatedly. Only the `tool_use` / `tool_result` events of
  `--output-format stream-json` are evidence about what it could and could not call.
- **Separate auth from permission when a connector is dark.** `claude mcp list` shows
  `✔ Connected` or `! Needs authentication`; a server in the second state needs a
  sign-in and no permission rule will help until then. Permission questions are settled
  by the probes in `references/permissions-and-mcp-grants.md`.

### MCP tools need an explicit grant in a headless run

Print mode cannot prompt, so an MCP tool with no allow rule is denied — and the denial
comes back as prose ("access not authorized", or worse "tool not available in this
environment" with no call attempted), not as an error you can catch. Grant it one of two
ways:

- **Name the tools in `--allowedTools`** (`--allowedTools "Read,mcp__claude_ai_Linear__get_issue"`).
  Verified sufficient with no settings file anywhere on the machine — this is the default
  for a one-off review.
- **Rely on an allow rule.** An interactive "Yes, and don't ask again" writes
  `mcp__<server>__<tool>` into `.claude/settings.local.json` at the git repository root,
  resolved *through worktrees* to the main checkout, so a worktree of that repo inherits
  it while a scratch directory does not. A `--settings` file merges with the lower levels
  instead of replacing them, so a run-level deny list does not wipe the project's grants.
- **Or write the rule once in the user settings file.** `permissions.allow` in
  `~/.claude/settings.json` applies in every project on the machine, scratch directories
  included — the way to stop re-granting the same read tools on every dispatch.
- **When the delegated task *is* a tracker write** (create the issue, post the comment), grant the
  server-wide glob deliberately — `mcp__claude_ai_Linear__*` — and constrain it in prose to the one
  object it may create. Then read that object back with your own connector: a write reported
  without an identifier, URL or read-back is not evidence it happened. House shape, language, label
  and assignee rules: `references/tracker-writes-via-mcp.md`.

Rule syntax (permissions docs): allow globs are accepted only after a literal
`mcp__<server>__` prefix (`mcp__claude_ai_Linear__get_*`); a bare `mcp__<server>` or
`mcp__<server>__*` matches every tool of that server — which also grants its write tools
in unattended runs, so prefer per-tool read globs. There is **no wildcard for a family of
servers**: the server segment must be literal, so `mcp__claude_ai_*` grants nothing and
"every connector on the account" is one entry per connector. Evaluation order is deny,
ask, allow, and a deny cannot be carved out by a narrower allow.

`references/permissions-and-mcp-grants.md` — where each kind of rule lives, the
precedence order, the mode semantics, and the probes that prove a rule grants.

Never accept a delegated run's word that an MCP tool is out of reach: force the call
("Call the MCP tool `<exact name>` with no arguments; you must attempt it; quote the
failure verbatim") and read the events it produced, then grant and re-run.

### Answering a permission dialog yourself, in a live session

A run that hits a wall can be reproduced **interactively** in tmux and driven: start
`claude` with no `-p`, send the prompt, read the dialog with `tmux capture-pane -p`, move
the selection with `send-keys … Down` (confirm with `capture-pane` that the `❯` marker
moved — do not assume), and commit with `Enter`. Send the text and the `Enter` as separate

From Clovel/custom-ai-skills, MIT.

More from Clovel/custom-ai-skills