Skip to content

docs: document Hermes local start support #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tumberger wants to merge 1 commit into
base: 05-17-feat_agent_add_hermes_shell_hook_adapter
Choose a base branch
from
Open

docs: document Hermes local start support #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ brew install kontext-security/tap/kontext
kontext start
```

This starts the currently supported adapter, Claude Code, with a local Kontext runtime. No hosted login is required.
By default, this starts Claude Code with a local Kontext runtime. Use `kontext start --agent hermes` to start Hermes Agent instead. No hosted login is required for local sessions.

By default, Kontext runs in observe mode: the agent keeps running, while Kontext records `would allow`, `would ask`, and `would deny` decisions in the local dashboard. The dashboard is served on loopback, with the URL printed at startup.

Expand Down Expand Up @@ -100,6 +100,7 @@ For enterprise identity, audit retention, organization controls, deployment plan
| Agent | Status | Start command | Support level |
| --- | --- | --- | --- |
| Claude Code | Active | `kontext start` or `kontext start --agent claude` | Local observe/enforce, dashboard diagnostics, managed sessions. |
| Hermes Agent | Beta | `kontext start --agent hermes` | Local observe/enforce for `pre_tool_call` and `post_tool_call`; no managed sessions or native approval prompts yet. |
| Goose | Planned | Coming soon | Adapter not shipped yet. |
| Codex | Planned | Coming soon | Adapter not shipped yet. |
| Cursor | Planned | Coming soon | Adapter not shipped yet. |
Expand All @@ -111,9 +112,11 @@ Additional agents can be added through adapters that send compatible tool events
```text
kontext start
|
|-- Agent hook adapter (Claude Code today)
|-- Agent hook adapter
| |-- PreToolUse -> kontext hook --agent claude --mode observe --socket /tmp/kontext/.../kontext.sock
| |-- PostToolUse -> kontext hook --agent claude --mode observe --socket /tmp/kontext/.../kontext.sock
| |-- pre_tool_call -> kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock
| |-- post_tool_call -> kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock
|
|-- Local runtime: Unix socket service + RuntimeCore
|-- Local dashboard: 127.0.0.1:4765
Expand Down
32 changes: 31 additions & 1 deletion docs/guard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,36 @@ go run ./cmd/kontext guard start
claude
```

## Hermes Agent

Hermes Agent can run under the local Kontext runtime with the Hermes shell-hook adapter:

```bash
kontext start --agent hermes
KONTEXT_MODE=enforce kontext start --agent hermes
```

Kontext creates a per-session temporary Hermes home shaped as a Hermes profile, snapshots the required Hermes config/auth/env state, and writes temporary shell-hook config that points back to the local Kontext socket. It does not edit `~/.hermes/config.yaml`, does not preserve user-defined shell hooks in the generated session config, and pre-approves only the generated Kontext hook commands in the temporary allowlist.

In observe mode, the generated Hermes hook config uses this shape. Enforce sessions use `--mode enforce` in the same command positions:

```yaml
hooks:
pre_tool_call:
- command: "kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock"
timeout: 20
post_tool_call:
- command: "kontext hook --agent hermes --mode observe --socket /tmp/kontext/.../kontext.sock"
timeout: 20
```

Current limitations:

- `ask` approval is not supported through Hermes shell hooks. In observe mode, Kontext records would-ask decisions. In enforce mode, Kontext maps `ask` and `deny` decisions to a Hermes block response.
- `updatedInput` is not supported through Hermes shell hooks.
- Managed sessions remain Claude-only.
- If Hermes cannot run the hook subprocess, the hook times out, or the hook emits malformed output, Hermes logs the problem and continues the agent loop.

## Runtime boundary

Guard mode is local-first by default:
Expand All @@ -34,7 +64,7 @@ Guard mode is local-first by default:
Hosted mode remains separate:

```bash
kontext start --agent claude
kontext start --managed
```

Hosted mode owns login, provider connection, short-lived scoped credentials, hosted traces, and team governance.
Expand Down
Loading