main
John Lauer Publish 0.1.0 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: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

# 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 (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":

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-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:

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.