docs(setup): add a Claude subscription (claude setup-token) credential path by jiejingzhangamd · Pull Request #1940 · AMD-AGI/Hyperloom

jiejingzhangamd · 2026-10-16T07:13:27Z

Description: hyperloom-setup now asks how Hyperloom authenticates to Claude before anything else: Anthropic API key (unchanged flow: base URL question, ANTHROPIC_API_KEY placeholder, AMD APIM header) or Claude subscription (Pro/Max). The subscription path:
- tells the user to run claude setup-token in their own terminal (it needs a browser round-trip, so the agent must not run it from a non-interactive shell) and paste the sk-ant-oat01-… token into .env, never chat;
- writes CLAUDE_CODE_OAUTH_TOKEN=<PLEASE_FILL_IN> instead of the ANTHROPIC_API_KEY placeholder;
- writes ANTHROPIC_BASE_URL=https://api.anthropic.com without asking (the token is valid nowhere else; never paired with the AMD gateway);
- validates that neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set, since either outranks the token (ANTHROPIC_SYNTHESIZABLE_KEY_ENVS), and asks before removing an existing non-placeholder key.
Linked issue(s): Fixes hyperloom-setup has no Claude subscription (CLAUDE_CODE_OAUTH_TOKEN / claude setup-token) path #1935
Tests: added test_setup_skill_offers_the_claude_subscription_token_path in test_dotenv_precedence_recipes.py (the file that already pins the setup skill's recipes). It derives the shadowing variables from llm_config.ANTHROPIC_SYNTHESIZABLE_KEY_ENVS, so the skill cannot drift from the runtime's precedence. Fails without the skill change; file: 101 passed. ruff clean; code-metrics PASSED.
End-to-end: this exact path (token-only .env, official URL, docker mode) was used for an 8 h GLM-5.2 MXFP4 session; with the OAuth-only (CLAUDE_CODE_OAUTH_TOKEN) launch always fails: critic preflight calls ClaudeOneShotClient.messages inside asyncio.run #1929 fix (fix(cli): run model preflight off the event loop so an OAuth-only launch starts #1937) it ran to completion on subscription auth.
Size/complexity triggers crossed: none.
If this simplifies or refactors: n/a.
Observable effect: an operator on a Claude Pro/Max plan is now offered a subscription option in setup and told how to get the token. Before, setup only wrote an API-key placeholder; a subscription user either had no path, or filled the token beside the placeholder key, which outranks it (API billing, or a failed placeholder key).
Breaking changes: no; the API-key flow and its option labels are unchanged.
PR addresses single concern: yes
Root cause is upstream, ticket filed: no

🤖 Generated with Claude Code

…l path hyperloom-setup only ever wrote ANTHROPIC_API_KEY, although the runtime accepts CLAUDE_CODE_OAUTH_TOKEN and its own error text points subscription users at `claude setup-token`. A subscription user had no documented path, and the obvious one (fill the token next to the API-key placeholder) made the key outrank the token. Setup now asks first whether to use an API key or a Claude subscription. The subscription path tells the user to run `claude setup-token` in their own terminal, writes CLAUDE_CODE_OAUTH_TOKEN instead of the API-key placeholder, pins the official endpoint the token is valid for, and validates that no ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN shadows it. Fixes #1935 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HktBcjPwjE7QgkA8MgKH6q

github-actions · 2026-10-16T07:14:31Z

Code metrics gate: PASSED

Judged: the 2 files this change touches. Files it does not touch never fail it; anything found there is listed under Outside this change for information.

Dimension	Limit	Baseline entries	vs base
Cyclomatic complexity	fails > 20	72	+0
Cognitive complexity	fails > 30	284	+0
Function length (lines)	fails > 80	449	+0
Nested block depth	fails > 5	27	+0
Module length (lines)	warns > 800, fails > 1200	53	+0
Duplicated lines per file	fails > 0	118	+0
Dead code (vulture)	fails > 0	2	+0

Check	Findings	Effect
Comments	0
English only	0
Production code imports test code	0
Repeated literals	0
A1 Private name of another package	0
A8 Flag argument	0
A9 Tuple return	0
A10 Raw vocabulary comparison	0
A11 Hidden global write	0
A12 Pure forwarder	0
A12 Single-implementation abstraction	0

97 findings in files this change does not touch

Outside this change (informational): 97

Unit	Dimension	Baseline	Now
`src/hyperloom/orchestrator/enablement/recipe/projections.py` `project_launch_evidence`	Cognitive complexity	absent	36
`src/hyperloom/orchestrator/state/shared_state.py` `resolve_graded_comparison`	Cognitive complexity	absent	34
`src/hyperloom_kb/collect/mapping.py` `_experience`	Cognitive complexity	absent	31
`src/hyperloom_kb/schema.py` `FieldDeclaration.__post_init__`	Cognitive complexity	absent	32
`src/kernelforge/cli/forge_loop_command.py` `_prepare_measurement_driver`	Cognitive complexity	absent	36
`src/kernelforge/cli/forge_loop_command.py` `_read_kb_warm_start`	Cognitive complexity	absent	40
`src/kernelforge/loop/runner.py` `IterationLoop._collect_session_candidate`	Cognitive complexity	absent	44
`src/kernelforge/loop/runner.py` `IterationLoop._rule_on_attempt`	Cognitive complexity	absent	38
`src/hyperloom_kb/tests/test_cli.py`	Duplicated lines per file	absent	18
`src/hyperloom_kb/tests/test_global_identity_and_pull.py`	Duplicated lines per file	absent	13
`src/hyperloom_kb/tests/test_local_state.py`	Duplicated lines per file	absent	18
`src/hyperloom/inference_optimizer/cli/__init__.py` `_reexport_session_environment`	Function length (lines)	absent	112
`src/hyperloom/inference_optimizer/cli/__init__.py` `_resolve_agent_lineup`	Function length (lines)	absent	89
`src/hyperloom/inference_optimizer/cli/__init__.py` `_resolve_run_topology`	Function length (lines)	absent	92
`src/hyperloom/inference_optimizer/cli/__init__.py` `_resume_session`	Function length (lines)	absent	171
`src/hyperloom/inference_optimizer/cli/__init__.py` `_seed_fresh_session`	Function length (lines)	absent	183
`src/hyperloom/inference_optimizer/multi_node/cli.py` `_restart_multinode`	Function length (lines)	absent	107
`src/hyperloom/inference_optimizer/multi_node/scripts/launch_multinode.py` `_build_parser`	Function length (lines)	absent	84
`src/hyperloom/inference_optimizer/multi_node/scripts/launch_multinode.py` `_spawn_rank_actors`	Function length (lines)	absent	90
`src/hyperloom_kb/http_service.py` `RequestHandler._dispatch`	Function length (lines)	absent	91
`src/hyperloom_kb/sync.py` `GlobalSync.pull`	Function length (lines)	absent	86
`src/kernelforge/cli/forge_loop_command.py` `_RunReporter.build_result`	Function length (lines)	absent	91
`src/kernelforge/cli/forge_loop_command.py` `_prepare_measurement_driver`	Function length (lines)	absent	140
`src/kernelforge/cli/forge_loop_command.py` `_read_kb_warm_start`	Function length (lines)	absent	154
`src/kernelforge/loop/knowledge_integration.py` `_measure_warmstart_field`	Function length (lines)	absent	83

...and 72 more; the job log lists every row.

Verdict computed by the gate scripts in /home/runner/work/_temp/code-metrics-gate, not by this tree's copy.

_{Thresholds and sources: [tool.hyperloom.code_metrics] in pyproject.toml. Tools: complexipy 8.0.1, jscpd 5.4.1, ruff 0.16.2, vulture 2.16.}

chaojhou · 2026-10-16T15:12:32Z

PR #1940 -- docs(setup): add a Claude subscription (claude setup-token) credential path

What it does: the hyperloom-setup skill now asks first how Hyperloom authenticates to Claude. Anthropic API key keeps the existing flow. Claude subscription (Pro/Max) tells the user to run claude setup-token in their own terminal and paste the token into .env, writes CLAUDE_CODE_OAUTH_TOKEN=<PLEASE_FILL_IN> instead of the ANTHROPIC_API_KEY placeholder and ANTHROPIC_BASE_URL=https://api.anthropic.com without asking, and checks that no ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN is left to outrank the token. A test pins the new path and derives the shadowing variables from llm_config. The launch this path leads to depends on #1937 (model preflight off the event loop), which the description cites; #1937 should land first.

Blocking issues: none

Checked: skills/hyperloom-setup/SKILL.md (both paths, the .env write list and the read-back checks); common/llm_config.py credential precedence (ANTHROPIC_CREDENTIAL_ENV_ORDER, ANTHROPIC_SYNTHESIZABLE_KEY_ENVS, anthropic_transport); common/claude_oneshot.py; env forwarding in common/env_safety.py; cli preflight credential checks; docs/reference/environment-variables.md and docs/reference/experience-kb.md; the new test and the description | Ran: CI at 0977183 (green) | Base: a3fc0ba | Head: 0977183

LGTM

jiejingzhangamd requested a review from a team as a code owner October 16, 2026 07:13

jiejingzhangamd mentioned this pull request Oct 16, 2026

docs(setup): let setup configure the Codex (OpenAI) backend #1942

Open

chaojhou merged commit 016de1c into main Oct 16, 2026
40 checks passed

chaojhou deleted the docs/setup-claude-subscription-token branch October 16, 2026 15:12

chaojhou mentioned this pull request Oct 17, 2026

Default model 'claude-opus-5' is stale and scattered; setup offers no Codex backend despite README support #1936

Open

Navigation Menu

Repository navigation

docs(setup): add a Claude subscription (claude setup-token) credential path - #1940

docs(setup): add a Claude subscription (claude setup-token) credential path#1940
chaojhou merged 1 commit into
mainfrom
docs/setup-claude-subscription-token

jiejingzhangamd commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Outside this change (informational): 97

Uh oh!

chaojhou commented Oct 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jiejingzhangamd commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Code metrics gate: PASSED

Outside this change (informational): 97

Uh oh!

chaojhou commented Oct 16, 2026

PR #1940 -- docs(setup): add a Claude subscription (claude setup-token) credential path

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants