main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-ai-agents description: >- Install, sign in, sign out and check quota for the AIs in a Hydrogen workspace (Claude Code, Codex, Kimi Code, Antigravity) through the /agents API. Use when asked to install antigravity or kimi, sign in to codex, which AIs are signed in, how much usage is left, or why an AI button is missing.

Hydrogen AI agents: install and sign in from a session

Hydrogen owns AI installs and sign-ins. Do not run curl … | bash installers, npm install -g, pip install kimi-cli or claude update by hand: each of those puts a SECOND copy of a CLI the VS Code extension already ships into the user's container (see the no-duplicates rule below). Call Hydrogen's /agents API instead. It installs the extension and the CLI together, signs in the right way for each AI, and keeps the VS Code toolbar and the Manage AIs dialog in step.

Reach the API from inside the workspace

Hydrogen writes its control URL into the workspace:

HD=$(cat ~/.adom/hydrogen-control-url)      # normally http://127.0.0.1:47084
curl -s "$HD/agents/catalog" | python3 -m json.tool

If the file is missing you are not inside a Hydrogen workspace (or Hydrogen is not running); tell the user to open Hydrogen rather than improvising an install.

The four AIs and their keys

key AI extension CLI / TUI one sign-in covers both?
claude Claude Code anthropic.claude-code (baked into the golden image) claude, a wrapper onto the extension's bundled binary yes, ~/.claude/.credentials.json
codex Codex openai.chatgpt (baked in) codex, a wrapper onto the extension's bundled binary yes, ~/.codex/auth.json
kimi Kimi Code moonshot-ai.kimi-code (user installs) kimi 2.x, standalone (the extension ships no CLI) yes, ~/.kimi-code/credentials
antigravity Antigravity google.google-antigravity (user installs) agy, the copy the extension downloads to ~/.gemini/bin/agy yes, by Hydrogen: it copies the Google token between ~/.gemini/jetski-standalone-oauth-token (extension) and ~/.gemini/antigravity-cli/antigravity-oauth-token (CLI)

grok is Grok Bot, a desktop app reached through Adom Bridge's grok_* verbs, not an extension or a CLI. On this computer the catalog reports Grok as not installed with "Grok Bot needs Adom Bridge, which is not running" until Adom Bridge runs here (Hydrogen installs it when a Linux build is published for the user's account). A Grok Bot on another of the user's machines is reached with adom-bridge --target <machine> grok_* (the grok-account skill in adom/grok-bridge). No toolbar button.

What each call does

HD=$(cat ~/.adom/hydrogen-control-url)

# Who is installed and signed in (installed = extension or CLI present; authed = the AI's own oracle)
curl -s "$HD/agents/catalog"

# Sizes, where each piece lives, and any DUPLICATE copies (what the ? in Manage AIs shows)
curl -s "$HD/agents/facts"            # add ?fresh=1 to re-measure

# Install: extension + CLI together (Kimi, Antigravity). cli_only:true skips the extension.
curl -s -X POST "$HD/agents/install" -H 'content-type: application/json' -d '{"key":"antigravity"}'

# Sign in (CLI-driven for claude, codex, kimi; the shared credentials sign the extension in too)
curl -s -X POST "$HD/agents/login" -H 'content-type: application/json' -d '{"key":"kimi"}'
curl -s "$HD/agents/login-url?key=kimi"       # poll: {authed, url, device_code?, needs_input?, detail}
#   - url: hand it to the user as a tappable link (Hydrogen also opens it in their browser)
#   - device_code: the user types it on the page (Codex)
#   - needs_input: the page ends on a "copy this code" screen; paste it back:
curl -s -X POST "$HD/agents/login-input" -H 'content-type: application/json' -d "{\"key\":\"antigravity\",\"value\":\"$(printf %s "$CODE" | base64 -w0)\"}"
curl -s -X POST "$HD/agents/login-stop" -H 'content-type: application/json' -d '{"key":"kimi"}'   # cancel

# Antigravity's EXTENSION sign-in happens inside its VS Code panel; open it for the user:
curl -s -X POST "$HD/agents/open-panel" -H 'content-type: application/json' -d '{"key":"antigravity"}'

# API key instead of OAuth where the AI supports it (base64 on the wire)
curl -s -X POST "$HD/agents/apikey" -H 'content-type: application/json' -d "{\"key\":\"kimi\",\"value\":\"$(printf %s "$KEY" | base64 -w0)\"}"

# Sign out (removes that AI's credentials; for Kimi also the extension's, they are shared)
curl -s -X POST "$HD/agents/logout" -H 'content-type: application/json' -d '{"key":"kimi"}'

# Raise the Manage AIs dialog in Hydrogen for the human to click through
curl -s -X POST "$HD/agents/present" -H 'content-type: application/json' -d '{"manage":true}'

A sign-in is done when GET /agents/catalog reports authed: true for that key. Poll every few seconds; the human has minutes, not seconds, to click through Google or OpenAI.

What to tell the user

  • "Install antigravity" / "install kimi": call /agents/install, wait for installed: true in the catalog, then start the sign-in. Say what got installed: the extension and the CLI.
  • Sign-in for claude, codex, kimi: one sign-in covers the extension and the CLI. Give the URL as a link. For Codex give the device code too.
  • Sign-in for antigravity: either side works and Hydrogen syncs the token to the other within seconds. Prefer the panel (/agents/open-panel): the user clicks Continue with Google there and the CLI is signed in right after. The CLI flow (/agents/login) ends on a page that shows a code; ask them to paste it and send it with /agents/login-input. After a CLI-side sign-in the VS Code panel keeps its Welcome screen until the window reloads; the dialog offers "Reload VS Code now", or call POST $HD/reload-vscode?confirm=1 (it hard reloads the editor; ask first if the user may have unsaved editor state).
  • Kimi 403 "subscription does not have access to Kimi Code" from the CLI while the extension works: that is the legacy pip Kimi 1.x (kimi --version says 1.x). Its upgrade also kills the TUI. Hydrogen's install (or hydrogen-bootstrap on its next run) replaces it with the 2.x binary in ~/.kimi-code/bin, which uses the same credentials without error.
  • Kimi region: Kimi's installer defaults to mainland China (kimi.com, WeChat). Hydrogen's install writes global into ~/.kimi-code/region so sign-in goes to kimi.ai. If a user lands on a WeChat page, that file is wrong.
  • Quota is not "signed out": an AI that answers 429 (Antigravity: "Individual quota reached, resets in Nh") is still signed in. Hydrogen's sign-in check reads the token, not a live prompt, so it stays green; explain the quota instead of re-authenticating.

Quota: how much of each plan is left

None of these calls runs a model, so reading quota costs nothing. Each one reads the sign-in the AI already keeps in the workspace; never print the tokens, print only the numbers.

AI where the numbers come from what comes back
Claude Code ~/.claude/.credentials.json (claudeAiOauth.accessToken), GET https://api.anthropic.com/api/oauth/usage with anthropic-beta: oauth-2025-04-20; GET .../api/oauth/profile gives the account email five_hour.utilization, seven_day.utilization (percent used) with resets_at; limits is the list /usage draws, including weekly limits scoped to one model
Codex ~/.codex/auth.json (tokens.access_token, tokens.account_id), GET https://chatgpt.com/backend-api/wham/usage with ChatGPT-Account-Id rate_limit.primary_window.used_percent and reset_at (epoch), limit_reached; also credits.balance and rate_limit_reset_credits.available_count (what /status shows)
Antigravity the running hub agy --hub (port and CSRF token on its command line), POST http://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary with x-codeium-csrf-token, body {} response.groups[].buckets[]: window (weekly or 5h), remainingFraction, resetTime, for the Gemini group and the Claude and GPT group; GetLoadCodeAssist gives the plan name and GetUserStatus the signed-in email
Grok Bot a desktop app on a machine running Adom Bridge, no file in the workspace: adom-bridge --target <machine> grok_settings {"page":"usage"} then grok_screenshot (the grok-account skill ships in adom/grok-bridge) the plan, weekly percent and reset, the on-demand cap
Kimi Code not mapped yet

The Title Bar widgets claude-usage, codex-usage and antigravity-usage (wiki widget packages, when installed) show the same numbers for this workspace.

python3 - <<'PY'
import json, os, re, subprocess, urllib.request
def get(url, h, data=None):
    return json.loads(urllib.request.urlopen(urllib.request.Request(url, data=data, headers=h), timeout=20).read())
try:
    c = json.load(open(os.path.expanduser('~/.claude/.credentials.json')))['claudeAiOauth']
    h = {'Authorization': 'Bearer ' + c['accessToken'], 'anthropic-beta': 'oauth-2025-04-20'}
    u = get('https://api.anthropic.com/api/oauth/usage', h); who = get('https://api.anthropic.com/api/oauth/profile', h)['account']['email']
    print('claude', who, '5h', u['five_hour']['utilization'], 'week', u['seven_day']['utilization'], 'resets', u['seven_day']['resets_at'])
except Exception as e: print('claude', e)
try:
    a = json.load(open(os.path.expanduser('~/.codex/auth.json')))['tokens']
    d = get('https://chatgpt.com/backend-api/wham/usage', {'Authorization': 'Bearer ' + a['access_token'], 'ChatGPT-Account-Id': a['account_id'], 'User-Agent': 'codex_cli_rs'})
    w = d['rate_limit']['primary_window']
    print('codex', d['email'], d['plan_type'], 'week', w['used_percent'], 'reset', w['reset_at'], 'credits', d['credits']['balance'])
except Exception as e: print('codex', e)
try:
    l = next(l for l in subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True).stdout.splitlines() if re.search(r'(^|/)agy\s.*--hub', l))
    port, csrf = re.search(r'--hub-port[= ](\d+)', l).group(1), re.search(r'--csrf_token[= ](\S+)', l).group(1)
    q = get(f'http://127.0.0.1:{port}/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary',
            {'Content-Type': 'application/json', 'x-codeium-csrf-token': csrf}, b'{}')['response']
    for g in q['groups']:
        for b in g['buckets']: print('antigravity', g['displayName'], b['window'], 'used', round((1 - b['remainingFraction']) * 100), 'reset', b['resetTime'])
except StopIteration: print('antigravity: hub not running (open the Antigravity panel once)')
except Exception as e: print('antigravity', e)
PY

Across machines. Each machine's workspace has its own sign-ins, and two machines can be on different accounts. On another machine that runs Adom Bridge and Hydrogen, run the same script in its workspace through the bridge (adom-bridge --target <machine> --ai-thread "<thread>" run_script ...; see adom-bridge-multi-machine). Group the rows by account email, not by machine: machines signed in to the same account share one pool.

Reading the answers.

  • Codex at 100 percent (limit_reached: true) still has two ways on before the reset: the credits balance (pay-as-you-go, if the user turns it on) and rate_limit_reset_credits (one-shot window resets). Both spend money or a scarce reset: tell the user, never use one on your own.
  • Antigravity reports separate pools for Gemini and for its Claude and GPT models. One pool can be empty while the other is full.
  • Grok Bot sitting on its "Update ready, Restart to update" screen shows no Settings page and runs no bots. Restarting it stops whatever its bots are doing: leave that to the user.

Codex and Claude Code's shell sandbox on Ubuntu

Both sandbox their shell commands with bubblewrap. Ubuntu 23.10 and later restrict unprivileged user namespaces, which breaks bwrap ("Codex's Linux sandbox uses bubblewrap and needs access to create user namespaces"). Hydrogen's workspace helper loads an AppArmor profile (/etc/apparmor.d/adom-hydrogen-bwrap) at every machine start that lets bwrap set the namespace up with no extra capabilities. If the error appears anyway, restart the workspace once; on Debian and Fedora there is no such restriction.

The VS Code toolbar and the Manage AIs dialog

Hydrogen publishes ~/.adom/agent-bar.json ({"authed":[…],"agents":[{key, cli, extension, extension_id, authed}]}) every time an oracle changes. adom-vscode watches that file and draws one toolbar button per INSTALLED AI (extension first; a TUI button only if the user adds it in the icon chooser and the CLI exists). So after an install or sign-in the button appears on its own; nothing to reload. The Manage AIs dialog (Hydrogen: Adom menu, profile menu; VS Code: the AI menu's "Manage AIs" row) reads /agents/catalog and /agents/facts live.

The no-duplicates rule

The extension is the source of the CLI wherever it ships one. claude and codex on PATH are 719- and 830-byte wrappers that exec the extension's bundled binary; agy links to the copy the Antigravity extension downloads; only kimi is a standalone binary because its extension ships none. A second copy (an npm @openai/codex, a claude update native install under ~/.local/share/claude/versions, a second agy from the public installer) is a regression: Manage AIs flags it under "Duplicate" with the bytes it would free, and hydrogen-bootstrap removes it and restores the wrapper on its next run. If a user asks for the npm or native channel on purpose, say that the extension then carries the same binary twice.

For the design behind all of this, Read ~/.claude/skills/hydrogen-ai-agents-dev/SKILL.md.