obsidian-hermes-plugin/README.md

# Hermes Chat — Obsidian Plugin

Chat with Hermes Agent directly from Obsidian via REST API.

## Prerequisites

- **Obsidian** 1.7.2 or later
- **Hermes Gateway** with the API Server adapter enabled and running

## Installation

1. Build the plugin:
   ```bash
   npm install
   npm run build
   ```

2. Copy the plugin folder into your Obsidian vault:
   ```
   <vault>/.obsidian/plugins/obsidian-hermes-plugin/
   ```

   Required files in the plugin folder:
   - `main.js` (built output)
   - `manifest.json`
   - `styles.css` (dark theme styling)

3. Restart Obsidian or reload plugins:
   - **Settings → Community plugins →** enable **Hermes Chat**

## Settings

After enabling the plugin, open **Settings → Hermes Chat**:

| Setting | Description | Default |
|---|---|---|
| **Gateway URL** | Base URL of your Hermes Gateway API server | `http://192.168.1.12:8642/v1` |
| **API Key** | API key for authenticating with the Hermes Gateway | (pre-filled) |
| **Show model info** | Display the current model name in the status bar | Enabled |
| **Enable context injection** | Automatically send the active note as context | Enabled |

## Usage

### Opening the Chat

- **Ribbon icon:** Click the message-square icon in the left ribbon
- **Keyboard:** `Ctrl+Shift+H` (customizable in **Settings → Hotkeys** → "Open Hermes Chat")
- **Command palette:** `Ctrl+P` → "Open Hermes Chat"

The chat opens as a sidebar panel on the right. You can resize it by dragging the edge.

### Sending Messages

Type in the input area at the bottom and press **Enter** to send. Press **Shift+Enter** for a newline. Responses stream in token-by-token — you'll see Hermes's reply appear in real time.

The status bar at the bottom of the chat shows the current model and session ID.

### Context Injection (Sharing Notes with Hermes)

Instead of sending your entire note content with every message (burning context tokens), the plugin sends a **vault-relative path reference**. Hermes reads the file on-demand from Helm using `mcp_obsidian_get_vault_document` — zero context wasted, same result.

This works seamlessly when you edit your vault via SMB from LPC. Hermes and Obsidian both see the same files at the same paths.

There are two ways to trigger context injection:

#### Automatic (recommended)

Enable **"Enable context injection"** in plugin settings and keep your active note open. When you send a message, the plugin prepends a system message like:

```
[Current note: obsidian-skt-revised/01 - Sessions/Session 67.md]
Use mcp_obsidian_get_vault_document(vault_name="obsidian-skt-revised", doc_path="01 - Sessions/Session 67.md") to read the full contents.
```

Hermes then reads the file on Helm and responds with full awareness of your note — no copy-paste, no wasted tokens.

**Toggle it off** when you want a clean chat without note context.

#### Manual (one-shot)

Use **"Send Current Note as Context"** from the command palette (`Ctrl+P`). This opens the chat sidebar with context queued for your next message.

#### Selection-only (embedded)

If you select text before sending, the plugin embeds your selection directly instead of sending a path reference. This is useful for quick questions about a specific passage — the selection is small and intentional, so embedding it costs few tokens.

### Session Continuity

The plugin maintains a persistent session with Hermes. Your conversation history is preserved across messages — Hermes remembers what you discussed earlier in the session, just like the CLI. The session ID is visible in the status bar.

### Status Bar

| Message | Meaning |
|---|---|
| `Hermes: connected` | Gateway is reachable and healthy |
| `Hermes: unreachable` | Gateway is down or unreachable — check that the API server is running on Helm |
| `Hermes: checking...` | Plugin is verifying connectivity on startup |
| `Model: hermes-agent \| Session: api-abc123` | Shown in the chat sidebar footer — current model and session |

## Settings

| Setting | Description | Default |
|---|---|---|
| **Gateway URL** | Base URL of your Hermes Gateway API server | `http://192.168.1.12:8642/v1` |
| **API Key** | API key for authenticating with the Hermes Gateway | (pre-configured) |
| **Show model info** | Display the current model name in the status bar | Enabled |
| **Enable context injection** | Automatically send the active note as context with each message | Enabled |

## Roadmap

- ~~**Multi-tab chat support**~~ — open multiple Hermes chat tabs simultaneously, each with its own isolated session, message history, and note context. *(shipped: each tab gets its own API client + session; use Ctrl+P → "Open Hermes Chat in New Tab")*
- ~~**Slash commands**~~ — `/prep-session`, `/sync-content`, `/lint-wiki`, and user-defined custom commands in plugin settings. *(shipped: built-in commands + JSON-configurable custom commands)*
- ~~**Slash command autocomplete**~~ — on `/` trigger in the chat input, show a suggestion dropdown with arrow-key navigation and click-to-select. *(shipped)*
- **Quick Actions button bar** — one-click buttons above the chat input for common workflows (Sync Content, Prep Session, Lint Wiki). Configurable in settings.
- **Hermes-side `/commands` endpoint** — server publishes a manifest of available slash commands; plugin fetches and merges with local commands on load.

## Development

```bash
npm install
npm run dev       # watch mode — rebuilds on changes
npm run build     # production build (minified, no sourcemap)
```