CLI Auth via Telegram

Use this skill whenever a user chatting over Telegram asks to connect, sign in, authenticate, or reconnect one of the CLI authentication flows covered here: Claude, Codex, Agy (Antigravity), or Grok Build. Do not use it for platform-account or billing login questions unrelated to these CLI credentials.

Before you start

1. Confirm which CLI the user means. If ambiguous, ask — do not guess.

2. Check whether it is already authenticated by testing for its credential file before doing anything else:

   • Claude: ~/.claude/.credentials.json
   • Codex: ~/.codex/auth.json
   • Agy: ~/.gemini/antigravity-cli/antigravity-oauth-token (fall back to ~/.gemini/oauth_creds.json only if the primary file is absent)
   • Grok Build: ~/.grok/auth.json (also accept ~/.config/grok/auth.json, which Agent Bridge retains as a compatibility path)

   If the file exists and is non-empty, treat that as credential presence rather than proof of usability. If Claude was explicitly reported as needing re-authentication, continue the re-auth flow instead of treating the file alone as connected. For the other file-backed account flows, tell the user it looks already connected and ask whether they want to re-authenticate anyway before proceeding.

   For Grok, a non-empty XAI_API_KEY is only a candidate automation credential, not proof that Grok is connected. Agent Bridge's shared API-key auth path verifies it with a bounded native headless request before routing. Never print the value. If the user asked to connect their own Grok account, continue with device authentication instead of substituting the operator key.

3. Resolve the CLI binary with command -v <cli> (claude, codex, agy, or grok) rather than assuming a hardcoded install path — it can vary by environment.

Running the login

Each CLI behaves differently. Do not send the same instructions for all four.

Claude

If the current owning Run is itself Claude, do not launch Claude re-authentication from inside that Run. Ordinary Claude execution holds the shared credential lock for its lifetime, so an exclusive login launched as its descendant would wait on its own parent. Switch the conversation to another authenticated provider first; if no other provider is available, the operator must run the provider-owned Claude login outside the Claude Run.

DISPLAY= <resolved-claude-bin> auth login

Prints an OAuth URL, then may prompt for a pasted code. Because this must run in the background while you keep chatting, run it detached with output captured to a log file and stdin wired through a named pipe you control:

mkdir -p "$RUNTIME_DIR" "$HOME/.agent-bridge/locks"
mkfifo "$RUNTIME_DIR/claude-auth.pipe" 2>/dev/null || true
FLOCK_BIN="$(command -v flock)"
CLAUDE_CREDENTIAL_LOCK="$HOME/.agent-bridge/locks/claude-credentials.lock"
( exec 3<>"$RUNTIME_DIR/claude-auth.pipe"; DISPLAY= "$FLOCK_BIN" --exclusive --no-fork "$CLAUDE_CREDENTIAL_LOCK" "$CLAUDE_BIN" auth login <&3 >"$RUNTIME_DIR/claude-auth.log" 2>&1 & )

Poll the log briefly for the URL line, then reply to the user with it as a Markdown link plus: "After approving, reply here with the code shown." When their next message arrives, write it to the pipe (printf '%s\n' "$CODE" > "$RUNTIME_DIR/claude-auth.pipe") and confirm the credential file now exists before telling them it worked.

Codex

<resolved-codex-bin> login --device-auth

Prints a URL and a device code. Codex polls the provider itself — no code needs relaying back through chat. Reply with the link and device code as a Markdown link + code, tell the user no further reply is needed, then poll for the credential file to appear before confirming.

Agy (Antigravity)

<resolved-agy-bin>

Starts Agy's own provider-owned browser OAuth flow and prints a temporary browser URL; the session stays alive until the callback completes. Reply with the link and poll for the credential file rather than expecting a pasted-back code, unless the CLI's own output explicitly asks for one — if it does, relay it the same way as the Claude flow via a dedicated pipe.

Grok Build

<resolved-grok-bin> login --device-auth

--device-code is an alias. The device flow prints a verification URL and short user code, then Grok polls xAI for completion. The command must remain alive while the user approves it, so run it in the background with output captured under the runtime directory:

mkdir -p "$RUNTIME_DIR"
( "$GROK_BIN" login --device-auth >"$RUNTIME_DIR/grok-auth.log" 2>&1 & echo $! >"$RUNTIME_DIR/grok-auth.pid" )

Poll the log briefly for the verification URL and code, reply with them as a Markdown link + code, and tell the user no further reply is needed. Then poll for either supported Grok credential path before confirming. On timeout, kill the PID recorded in grok-auth.pid if it is still running, then remove the Grok auth log/PID files.

Do not use plain grok login in a headless/Telegram context because its default flow tries to launch a local browser. XAI_API_KEY is a supported Grok automation credential and Agent Bridge can route with it after native verification, but do not substitute it when the user asked to connect their own Grok account; use an API key only when the operator explicitly requested or approved that authentication method.

Safety rules

• Never print the raw device/auth code or URL query secrets into anything other than the single chat reply meant for the user — do not echo them again in later messages, status updates, or error text.
• Set a bounded wait (15 minutes) for the user's code reply or for the credential file to appear. On timeout, kill the background login process, remove its pipe/log/PID files, and tell the user the attempt expired and how to retry.
• Only one login attempt per CLI at a time. If one is already in flight when asked again for the same CLI, tell the user and offer to cancel it rather than starting a second one silently.
• Claude login must keep the exclusive Agent Bridge credential lock shown above for the full provider-owned login. Do not delete or manipulate Claude's own .oauth_refresh.lock; ordinary Claude turns use the same Agent Bridge lock in shared mode and remain concurrent with each other.
• Clean up the log, pipe, and PID files once the flow finishes (success, failure, or timeout) — do not leave credential-adjacent artifacts on disk.
• Confirm success by checking the credential file actually appeared/updated, not merely that the login process exited zero.

Verification

After the credential file is confirmed present and updated by the login:

• For Claude, a refreshed non-empty ~/.claude/.credentials.json readmits the provider for interactive routing. A full npm run qualify:provider -- --provider claude run is no longer required solely to make Claude routable again; the next Claude execution verifies recovery and will re-degrade and trigger existing fallback if auth is still invalid. Full provider qualification can still be run when runtime identity or contract evidence needs refreshing.
• For the other covered CLIs, retain their provider-specific verification above.

Never repeat secret material from the exchange.