From 3ed13cd661cd84debc8ef7fdec3bd9aa45ef30c7 Mon Sep 17 00:00:00 2001 From: archdex-art Date: Fri, 17 Jul 2026 13:53:53 +0530 Subject: [PATCH] docs: explain how to actually get a CLAUDE_CODE_OAUTH_TOKEN Follow-up to the subscription-credential-check fix: the warning correctly told users to "configure CLAUDE_CODE_OAUTH_TOKEN" but never explained how to obtain one, leaving subscription-mode users stuck with no path forward -- despite the feature being fully implemented and working once that one env var is set. Verified live: `claude setup-token` is a real, documented subcommand of the official `@anthropic-ai/claude-code` CLI ("Set up a long-lived authentication token (requires Claude subscription)", confirmed via `npx @anthropic-ai/claude-code setup-token --help`). It runs on the user's own machine (interactive browser login to their Claude Pro/Max/ Team account, with a manual URL/code fallback for headless/SSH use), mints a token valid for 1 year, and instructs setting it as CLAUDE_CODE_OAUTH_TOKEN -- exactly the env var CodeGraph's existing claudeSubscriptionCredentialsAvailable() check already looks for. No code change: the feature was already correct. This closes the actual gap -- a user with a real Claude subscription had no way to discover the one command that makes it work. Changes: - Settings page: the "no usable Claude Code login" warning now includes the exact command (`npx @anthropic-ai/claude-code setup-token`) and a concrete explanation of where the resulting token goes. - DEPLOY.md: full 5-step walkthrough (run setup-token locally -> browser login -> copy the 1-year token -> set CLAUDE_CODE_OAUTH_TOKEN on the deployment -> redeploy) added to the Claude Agent SDK setup section. Verification: full suite 232/232, tsc --noEmit clean, lint baseline unchanged, next build clean. --- app/DEPLOY.md | 7 ++++++- app/src/app/settings/page.tsx | 29 ++++++++++++++++++----------- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/app/DEPLOY.md b/app/DEPLOY.md index c286412..46345c3 100644 --- a/app/DEPLOY.md +++ b/app/DEPLOY.md @@ -94,7 +94,12 @@ Runs in-process against the repo's live workspace directory. 1. Set `ANTHROPIC_API_KEY=` on the deployment (and/or in a local `.env.local` for dev). Restart/redeploy. 2. `npm install` already pulls the correct platform binary via `@anthropic-ai/claude-agent-sdk`'s `optionalDependencies` (Linux glibc/musl x64+arm64, macOS, Windows), so this works in the Docker image with no extra install step. -3. **Subscription mode (`CLAUDE_CODE_OAUTH_TOKEN` / "Use my Claude subscription" toggle) requires real evidence of a working login on this exact server process** — either `CLAUDE_CODE_OAUTH_TOKEN` set as an env var, or a `~/.claude/.credentials.json` file from having run `claude login` on that same host. On Render (and most container hosts), the home directory is NOT on the persistent disk and there's no interactive terminal to run `claude login` in the first place, so a credentials file can never exist there — `CLAUDE_CODE_OAUTH_TOKEN` is the only way subscription mode can work on this deployment model. CodeGraph checks for this evidence server-side (`claudeSubscriptionCredentialsAvailable()` in `lib/settings.ts`) before ever offering Claude via the subscription path — toggling the Settings checkbox alone, with no real credentials, correctly leaves the Claude tab unavailable instead of producing a broken chat session ("Not logged in — Please run /login", followed by "/login isn't available in this environment", since the SDK session is headless and can't prompt interactively). +3. **To use your Claude Pro/Max/Team subscription instead of an API key** (the "Use my Claude subscription" toggle on the Settings page), CodeGraph requires real evidence this exact server process can authenticate — an `ANTHROPIC_API_KEY`-free login. On a hosted/container deployment (Render, Docker, etc.) there's no persistent home directory and no interactive terminal to ever run `claude login` directly on the server, so the only way this works is a portable long-lived token: + 1. On **your own computer** (not the server) — run `npx @anthropic-ai/claude-code setup-token` (or `claude setup-token` if you already have Claude Code installed globally). This is a real subcommand of the official CLI: `Set up a long-lived authentication token (requires Claude subscription)`. + 2. It opens a browser to sign in with your Claude.ai account (Pro/Max/Team) — or prints a URL/code to paste manually if a browser can't open (e.g. over SSH). + 3. On success it prints a token valid for **1 year**: `Your OAuth token (valid for 1 year): ... Use this token by setting: export CLAUDE_CODE_OAUTH_TOKEN=`. Copy it now — you won't be able to see it again. + 4. Set `CLAUDE_CODE_OAUTH_TOKEN=` on the deployment (Render dashboard → your service → Environment → Add Environment Variable) and redeploy/restart. + 5. CodeGraph checks for this evidence server-side (`claudeSubscriptionCredentialsAvailable()` in `lib/settings.ts`) before ever offering Claude via the subscription path, so the toggle only "just works" once the token is actually set — no server-side login needed beyond this one env var. ### Local model (any OpenAI-compatible server) Talks over plain HTTP to a model server running on your own hardware — no data leaves the machine running CodeGraph. Tested against the OpenAI-compatible `/v1/chat/completions` shape that Ollama, LM Studio, llama.cpp's `server`, vLLM, and text-generation-webui all implement; tool-calling quality (and therefore how well the assistant can actually edit files) depends entirely on the model you pick — recent tool-calling-tuned models (e.g. Qwen2.5-Coder, Llama 3.1+) work noticeably better than older/small ones. diff --git a/app/src/app/settings/page.tsx b/app/src/app/settings/page.tsx index bfe4be1..b18b7eb 100644 --- a/app/src/app/settings/page.tsx +++ b/app/src/app/settings/page.tsx @@ -314,19 +314,26 @@ export default function SettingsPage() {

- Only works if the machine running CodeGraph already has Claude Code logged in - (run claude login in a terminal there once), or has{" "} - CLAUDE_CODE_OAUTH_TOKEN set in its environment. - Uses your subscription's included usage instead of per-token API billing. - An API Key above, if set, always takes priority over this. + Uses your subscription's included usage instead of per-token API billing. An API Key above, if set, always + takes priority over this.

{useSubscription && settings && !settings.claudeSubscriptionUsable && ( -

- ⚠ This server has no usable Claude Code login right now (no CLAUDE_CODE_OAUTH_TOKEN{" "} - and no local claude login session) — starting a chat with this toggle on and no - API Key set above will fail. Set an Anthropic API Key above instead, or ask the site operator to configure{" "} - CLAUDE_CODE_OAUTH_TOKEN. -

+
+

⚠ This server has no usable Claude Code login right now — starting a chat with this toggle on and no API Key set above will fail.

+

+ To actually use your subscription instead of an API key, on your own computer{" "} + (not this server) run: +

+ 
+                    npx @anthropic-ai/claude-code setup-token
+
+

+ This opens a browser to sign in with your Claude Pro/Max/Team account and prints a long-lived (1 year) + token. Set that as CLAUDE_CODE_OAUTH_TOKEN in this deployment's + environment (e.g. the Render dashboard's Environment tab) and redeploy — the server itself never needs + an interactive login, only that one token. +

+
)}