Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
d8a45ab
name: hydrogen-claude-management description: >- API for the Claude Code conversations inside Hydrogen: list, open, close and switch tabs, read a conversation's state, type into a specific one, and Remote Control for a claude.ai URL. Use when asked to open a new Claude tab, type into a conversation, list conversations, or view this chat on mobile.
Hydrogen Claude Conversation Management
Hydrogen runs Claude Code as webview tabs inside VS Code. This skill is the first-class API for managing those conversations programmatically: from Hydrogen's control API, from the user's AI inside the workspace machine, or from setup steps.
All endpoints are on the Hydrogen control API (a dynamic localhost port; the workspace
shares the host's network). Examples use $Hydrogen:
Hydrogen="$(cat ~/.adom/hydrogen-control-url)"
From a cloud container, call the same endpoints with
adom-bridge --target <machine> hd_api '{"path":"/claude/...","method":"POST","body":{...}}',
which needs Adom Bridge on this computer (Hydrogen for Linux does not set it up). Everything here
works in the background: no window focus, no keystroke stealing.
On Linux these endpoints read and type into the chat through Hydrogen's frame bus (WebKitGTK
has no DevTools protocol). Context ids are the frame agent's ids: large numbers, stable for the
frame's life, never reused after a reload. Typing into a signed-in Claude over the frame bus is
new on Linux: do a dry run (submit:false, then read compose_text) before relying on it.
The core idea: address conversations by CONTEXT ID, list from the TAB BAR
Each Claude conversation is its own webview execution context with a stable integer id. That id — not the tab index, not the title, not visibility — is how you reliably target one conversation (type into it, remote-control it). VS Code keeps multiple webviews "visible" at once, so visibility/tab-index are NOT reliable addresses; the context id is.
But VS Code also disposes the webview of a background tab, so a context id only exists for
loaded tabs. That's why GET /claude/conversations merges three sources into one view:
the tab bar (every open conversation + which is active — what you see), the live webview
contexts (rich data for loaded tabs), and the on-disk session logs (the GUIDs). Each row
carries a loaded flag; loaded:false means activate the tab first to read its live details.
GET /claude/conversations — everything in one call
curl -s $Hydrogen/claude/conversations
{
"ok": true,
"count": 4,
"conversations": [
{
"ordinal": 3, // its position in the tab bar
"active": true, // the currently-focused tab
"loaded": true, // webview is live → rich fields are populated
"context_id": 7, // STABLE address for inject/remote-control (null if not loaded)
"title": "Calculate 10 times 10", // authoritative title (from the session log when matched)
"tab_label": "Calculate 10 times 10", // raw tab label (may be ellipsis-truncated)
"compose_text": "", // what's typed but not yet sent (null if not loaded)
"msg_count": 16, // null if not loaded
"session_id": "566cec21-…", // on-disk log GUID (read ~/.claude/projects/*/<id>.jsonl)
"rc_active": false, // Remote Control on? (null if not loaded)
"remote_control_url": null // claude.ai cloud URL when rc_active
},
{ "ordinal": 1, "active": false, "loaded": false, "context_id": null,
"title": "Find the capital of France", "tab_label": "Find the capital of Fran…",
"compose_text": null, "msg_count": null, "session_id": "b352055b-…", "rc_active": null, "remote_control_url": null }
]
}
- Merged view: every tab is listed (from the tab bar).
loaded:truerows have live fields (context_id,compose_text,msg_count,rc_active);loaded:falserows are background tabs VS Code disposed — activate them (/claude/tabs/activate) to read those. Even a disposed tab resolves itssession_idwhen its title matches the on-disk log. - A conversation is
Untitledwithsession_id: nulluntil its first message is submitted — then Claude names it and writes the session log. ?with_session=falseskips the disk read (faster; omitssession_id).
GET /claude/contexts is the lighter version (just the loaded contexts: context_id + compose_text).
Open / close / switch tabs
# Open a fresh conversation (new tab)
curl -s -X POST $Hydrogen/claude/new-conversation
# Open the Claude panel if it isn't open
curl -s -X POST $Hydrogen/claude/open
# List raw editor tabs (label/active/dirty)
curl -s $Hydrogen/claude/tabs
# Close ALL conversation tabs (also removes the leftover empty editor group)
curl -s -X POST $Hydrogen/claude/tabs/close-all
# Switch the visible tab by index or label substring (background)
curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"index":1}'
curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"label":"Eiffel"}'
# Remove a stale EMPTY editor group (the dead blank panel) WITHOUT collapsing a
# real 2-group left/right layout. (merge-groups is a back-compat alias.)
curl -s -X POST $Hydrogen/claude/tabs/close-empty-groups
Type a message into a SPECIFIC conversation
POST /claude/inject types into the conversation you name with context_index. Two speeds:
# INSTANT paste (fast) — no typing animation. Best for slash commands and scripted input.
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"summarize this repo","context_index":16,"typed":false,"submit":true}'
# SLOW human typing animation (the "watch the AI type" effect), then submit.
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"hello there","context_index":16,"typed":true,"delay_ms":50,"submit":true}'
# Type but DON'T send (leave it sitting in the compose box):
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"draft…","context_index":16,"typed":false,"submit":false}'
typed:true= char-by-char with ±50% jitter (avgdelay_ms);false= instant paste.submit:true= press Enter;false= leave in the box.- Omit
context_indexONLY when a single conversation is open. With more than one conversation open, omitting it can type your text into several compose boxes at once (it falls back to a visibility heuristic that isn't reliable when the window isn't foreground). When in doubt, pass it. - Targeting by
context_indexis deterministic — it lands in exactly that tab even when it's not the foreground one and even with many tabs open (no fan-out into other tabs). This is the safe default: list/claude/conversations, take the row withactive:true(or the tab you want), use itscontext_id, then inject.
Typical "open a new tab and ask a question":
curl -s -X POST $Hydrogen/claude/new-conversation
CTX=$(curl -s $Hydrogen/claude/contexts | jq '.contexts[-1].context_id')
curl -s -X POST $Hydrogen/claude/inject -d "{\"text\":\"what does this project do?\",\"context_index\":$CTX,\"typed\":true,\"submit\":true}"
⭐ Remote Control → view the conversation on claude.ai / mobile
This is the big one. Turn on Remote Control for a conversation and Hydrogen returns a claude.ai cloud URL. Open it on claude.ai in any browser or in the Claude mobile app to see and drive that exact conversation in the cloud — not tied to Hydrogen. The user can be on their phone editing the same conversation.
curl -s -X POST $Hydrogen/claude/remote-control -d '{"context_index":7}'
{
"ok": true,
"rc_active": true,
"toggled": true, // false + already_in_desired_state:true if it was already on
"context_id": 7,
"remote_control_url": "https://claude.ai/code/session_014koKPJxmjYpnX2SjRRqrD3"
}
- ⚠️
/remote-controlis a TOGGLE. This endpoint detects the current state first and only toggles when needed — re-calling it on an already-on session is a no-op that returns the existing URL (it will NOT turn it off; doing that blindly archives the cloud session). {enable:false}turns Remote Control off.- The
session_…id in the URL is the cloud session id — distinct from the local on-disksession_idGUID. The cloud URL is the shareable one for claude.ai / mobile. {name}→/remote-control <name>to label the remote session.- Each conversation's current state is also reported as
rc_activein/claude/conversations. - Opening it for the user:
POST $Hydrogen/open-url {"url":"<remote_control_url>"}sends it through the Browser Picker to their browser. Never blind-type into the claude.ai page.
How a live conversation maps to its on-disk log (JSONL)
Claude Code stores each conversation as ~/.claude/projects/<cwd>/<uuid>.jsonl containing
sessionId, aiTitle (the generated title), and every message. The session GUID is NOT
exposed in the conversation's webview DOM, so Hydrogen correlates a live conversation to its log by
matching the first user message (exact + unique; present in both the DOM and the JSONL).
On a match, /claude/conversations fills in session_id and uses the log's aiTitle as the
authoritative title. (Matching on the title alone is unreliable — the rendered title and the
persisted aiTitle can differ.)
Read a conversation's full transcript from the workspace:
cat ~/.claude/projects/*/<session_id>.jsonl
Why this is valuable
- Multi-conversation orchestration: open N conversations, drive each independently by context id, read each one's state — all from a script or an agent, in the background.
- Cloud + mobile continuity: Remote Control hands you a claude.ai URL so a conversation started in Hydrogen continues on the phone / web. Huge for working away from the desk.
- Deterministic + safe: context-id addressing never types into the wrong tab; the empty blank panel is cleaned up automatically; a real 2-group left/right layout is preserved.
- Auditable: every conversation maps to an on-disk JSONL you can read, diff, or archive.
Endpoint quick reference
| Endpoint | Method | What it does |
|---|---|---|
/claude/conversations |
GET | Full per-conversation data incl. session_id (the canonical list) |
/claude/contexts |
GET | Light list: context_id + compose_text |
/claude/tabs |
GET | Raw editor tabs (label/active/dirty) |
/claude/new-conversation |
POST | Open a fresh conversation tab |
/claude/open |
POST | Open the Claude panel if closed |
/claude/tabs/close-all |
POST | Close all tabs + remove the leftover empty group |
/claude/tabs/activate |
POST | Switch visible tab by {index} or {label} |
/claude/tabs/close-empty-groups |
POST | Remove stale empty editor groups (preserves populated) |
/claude/inject |
POST | Type into {context_index} — {typed,submit,delay_ms} |
/claude/remote-control |
POST | Turn on RC for {context_index} → returns remote_control_url |
/claude/cross-eval |
POST | (Diagnostic) run JS across all workbench/webview contexts |
These are the same endpoints Hydrogen's own setup steps use to open Claude and inject the first prompt — so behavior is identical whether a human, setup, or the workspace AI drives them.
---
name: hydrogen-claude-management
description: >-
API for the Claude Code conversations inside Hydrogen: list, open, close and switch
tabs, read a conversation's state, type into a specific one, and Remote Control for a
claude.ai URL. Use when asked to open a new Claude tab, type into a conversation, list
conversations, or view this chat on mobile.
---
# Hydrogen Claude Conversation Management
Hydrogen runs Claude Code as webview tabs inside VS Code. This skill is the
**first-class API** for managing those conversations programmatically: from Hydrogen's control
API, from the user's AI inside the workspace machine, or from setup steps.
All endpoints are on the **Hydrogen control API** (a dynamic localhost port; the workspace
shares the host's network). Examples use `$Hydrogen`:
```bash
Hydrogen="$(cat ~/.adom/hydrogen-control-url)"
```
From a cloud container, call the same endpoints with
`adom-bridge --target <machine> hd_api '{"path":"/claude/...","method":"POST","body":{...}}'`,
which needs Adom Bridge on this computer (Hydrogen for Linux does not set it up). Everything here
works in the **background**: no window focus, no keystroke stealing.
**On Linux** these endpoints read and type into the chat through Hydrogen's frame bus (WebKitGTK
has no DevTools protocol). Context ids are the frame agent's ids: large numbers, stable for the
frame's life, never reused after a reload. Typing into a signed-in Claude over the frame bus is
new on Linux: do a dry run (`submit:false`, then read `compose_text`) before relying on it.
## The core idea: address conversations by CONTEXT ID, list from the TAB BAR
Each Claude conversation is its own webview **execution context** with a **stable integer id**.
That id — not the tab index, not the title, not visibility — is how you reliably *target* one
conversation (type into it, remote-control it). VS Code keeps multiple webviews "visible" at
once, so visibility/tab-index are NOT reliable addresses; the context id is.
But VS Code also **disposes the webview of a background tab**, so a context id only exists for
*loaded* tabs. That's why `GET /claude/conversations` **merges three sources** into one view:
the **tab bar** (every open conversation + which is active — what you see), the **live webview
contexts** (rich data for loaded tabs), and the **on-disk session logs** (the GUIDs). Each row
carries a `loaded` flag; `loaded:false` means activate the tab first to read its live details.
## GET /claude/conversations — everything in one call
```bash
curl -s $Hydrogen/claude/conversations
```
```jsonc
{
"ok": true,
"count": 4,
"conversations": [
{
"ordinal": 3, // its position in the tab bar
"active": true, // the currently-focused tab
"loaded": true, // webview is live → rich fields are populated
"context_id": 7, // STABLE address for inject/remote-control (null if not loaded)
"title": "Calculate 10 times 10", // authoritative title (from the session log when matched)
"tab_label": "Calculate 10 times 10", // raw tab label (may be ellipsis-truncated)
"compose_text": "", // what's typed but not yet sent (null if not loaded)
"msg_count": 16, // null if not loaded
"session_id": "566cec21-…", // on-disk log GUID (read ~/.claude/projects/*/<id>.jsonl)
"rc_active": false, // Remote Control on? (null if not loaded)
"remote_control_url": null // claude.ai cloud URL when rc_active
},
{ "ordinal": 1, "active": false, "loaded": false, "context_id": null,
"title": "Find the capital of France", "tab_label": "Find the capital of Fran…",
"compose_text": null, "msg_count": null, "session_id": "b352055b-…", "rc_active": null, "remote_control_url": null }
]
}
```
- **Merged view:** every tab is listed (from the tab bar). `loaded:true` rows have live fields
(`context_id`, `compose_text`, `msg_count`, `rc_active`); `loaded:false` rows are background tabs
VS Code disposed — **activate them** (`/claude/tabs/activate`) to read those. Even a disposed tab
resolves its `session_id` when its title matches the on-disk log.
- A conversation is **`Untitled`** with **`session_id: null`** until its first message is submitted —
then Claude names it and writes the session log.
- `?with_session=false` skips the disk read (faster; omits `session_id`).
`GET /claude/contexts` is the lighter version (just the *loaded* contexts: `context_id` + `compose_text`).
## Open / close / switch tabs
```bash
# Open a fresh conversation (new tab)
curl -s -X POST $Hydrogen/claude/new-conversation
# Open the Claude panel if it isn't open
curl -s -X POST $Hydrogen/claude/open
# List raw editor tabs (label/active/dirty)
curl -s $Hydrogen/claude/tabs
# Close ALL conversation tabs (also removes the leftover empty editor group)
curl -s -X POST $Hydrogen/claude/tabs/close-all
# Switch the visible tab by index or label substring (background)
curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"index":1}'
curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"label":"Eiffel"}'
# Remove a stale EMPTY editor group (the dead blank panel) WITHOUT collapsing a
# real 2-group left/right layout. (merge-groups is a back-compat alias.)
curl -s -X POST $Hydrogen/claude/tabs/close-empty-groups
```
## Type a message into a SPECIFIC conversation
`POST /claude/inject` types into the conversation you name with `context_index`. Two speeds:
```bash
# INSTANT paste (fast) — no typing animation. Best for slash commands and scripted input.
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"summarize this repo","context_index":16,"typed":false,"submit":true}'
# SLOW human typing animation (the "watch the AI type" effect), then submit.
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"hello there","context_index":16,"typed":true,"delay_ms":50,"submit":true}'
# Type but DON'T send (leave it sitting in the compose box):
curl -s -X POST $Hydrogen/claude/inject -d '{"text":"draft…","context_index":16,"typed":false,"submit":false}'
```
- `typed`: `true` = char-by-char with ±50% jitter (avg `delay_ms`); `false` = instant paste.
- `submit`: `true` = press Enter; `false` = leave in the box.
- Omit `context_index` ONLY when a single conversation is open. With **more than one** conversation
open, omitting it can type your text into **several compose boxes at once** (it falls back to a
visibility heuristic that isn't reliable when the window isn't foreground). When in doubt, pass it.
- Targeting by `context_index` is deterministic — it lands in exactly that tab even when it's
not the foreground one and even with many tabs open (no fan-out into other tabs). **This is the
safe default: list `/claude/conversations`, take the row with `active:true` (or the tab you want),
use its `context_id`, then inject.**
Typical "open a new tab and ask a question":
```bash
curl -s -X POST $Hydrogen/claude/new-conversation
CTX=$(curl -s $Hydrogen/claude/contexts | jq '.contexts[-1].context_id')
curl -s -X POST $Hydrogen/claude/inject -d "{\"text\":\"what does this project do?\",\"context_index\":$CTX,\"typed\":true,\"submit\":true}"
```
## ⭐ Remote Control → view the conversation on claude.ai / mobile
This is the big one. Turn on Remote Control for a conversation and Hydrogen returns a **claude.ai
cloud URL**. Open it on claude.ai in any browser or in the Claude **mobile app** to see and
drive that exact conversation in the cloud — not tied to Hydrogen. The user can be on their phone
editing the same conversation.
```bash
curl -s -X POST $Hydrogen/claude/remote-control -d '{"context_index":7}'
```
```jsonc
{
"ok": true,
"rc_active": true,
"toggled": true, // false + already_in_desired_state:true if it was already on
"context_id": 7,
"remote_control_url": "https://claude.ai/code/session_014koKPJxmjYpnX2SjRRqrD3"
}
```
- ⚠️ **`/remote-control` is a TOGGLE.** This endpoint **detects** the current state first and only
toggles when needed — re-calling it on an already-on session is a **no-op** that returns the
existing URL (it will NOT turn it off; doing that blindly archives the cloud session).
- `{enable:false}` turns Remote Control **off**.
- The `session_…` id in the URL is the **cloud** session id — distinct from the local on-disk
`session_id` GUID. The cloud URL is the shareable one for claude.ai / mobile.
- `{name}` → `/remote-control <name>` to label the remote session.
- Each conversation's current state is also reported as `rc_active` in `/claude/conversations`.
- **Opening it for the user:** `POST $Hydrogen/open-url {"url":"<remote_control_url>"}` sends it
through the Browser Picker to their browser. Never blind-type into the claude.ai page.
## How a live conversation maps to its on-disk log (JSONL)
Claude Code stores each conversation as `~/.claude/projects/<cwd>/<uuid>.jsonl` containing
`sessionId`, `aiTitle` (the generated title), and every message. **The session GUID is NOT
exposed in the conversation's webview DOM**, so Hydrogen correlates a live conversation to its log by
matching the **first user message** (exact + unique; present in both the DOM and the JSONL).
On a match, `/claude/conversations` fills in `session_id` and uses the log's `aiTitle` as the
authoritative `title`. (Matching on the title alone is unreliable — the rendered title and the
persisted `aiTitle` can differ.)
Read a conversation's full transcript from the workspace:
```bash
cat ~/.claude/projects/*/<session_id>.jsonl
```
## Why this is valuable
- **Multi-conversation orchestration:** open N conversations, drive each independently by
context id, read each one's state — all from a script or an agent, in the background.
- **Cloud + mobile continuity:** Remote Control hands you a claude.ai URL so a conversation
started in Hydrogen continues on the phone / web. Huge for working away from the desk.
- **Deterministic + safe:** context-id addressing never types into the wrong tab; the empty
blank panel is cleaned up automatically; a real 2-group left/right layout is preserved.
- **Auditable:** every conversation maps to an on-disk JSONL you can read, diff, or archive.
## Endpoint quick reference
| Endpoint | Method | What it does |
|---|---|---|
| `/claude/conversations` | GET | Full per-conversation data incl. `session_id` (the canonical list) |
| `/claude/contexts` | GET | Light list: `context_id` + `compose_text` |
| `/claude/tabs` | GET | Raw editor tabs (label/active/dirty) |
| `/claude/new-conversation` | POST | Open a fresh conversation tab |
| `/claude/open` | POST | Open the Claude panel if closed |
| `/claude/tabs/close-all` | POST | Close all tabs + remove the leftover empty group |
| `/claude/tabs/activate` | POST | Switch visible tab by `{index}` or `{label}` |
| `/claude/tabs/close-empty-groups` | POST | Remove stale empty editor groups (preserves populated) |
| `/claude/inject` | POST | Type into `{context_index}` — `{typed,submit,delay_ms}` |
| `/claude/remote-control` | POST | Turn on RC for `{context_index}` → returns `remote_control_url` |
| `/claude/cross-eval` | POST | (Diagnostic) run JS across all workbench/webview contexts |
These are the same endpoints Hydrogen's own setup steps use to open Claude and inject the first
prompt — so behavior is identical whether a human, setup, or the workspace AI drives them.