Skip to content

fix(doctor): flag ollama launch claude proxy bypass instead of misdirecting - #2566

Merged
JerrettDavis merged 1 commit into
headroomlabs-ai:mainfrom
tenderdeve:feat/2199-ollama-claude-coexist
Aug 12, 2026
Merged

JerrettDavis merged 1 commit into
headroomlabs-ai:mainfrom
tenderdeve:feat/2199-ollama-claude-coexist

Conversation

@tenderdeve

@tenderdeve tenderdeve commented Jul 26, 2026 •

Copy link
Copy Markdown
Contributor

Description

Addresses the diagnostic half of #2199.

ollama launch claude sets ANTHROPIC_BASE_URL=http://127.0.0.1:11434 in the launched Claude Code child. That process env outranks the env block a persistent Headroom install writes to ~/.claude/settings.json, so Claude Code talks to Ollama and never reaches the proxy — 0% savings, nothing on the dashboard, no error.

headroom doctor's routing classifier made it worse: seeing a loopback :11434, it reported routed to port 11434, but doctor probed port 8787 and hinted re-run with: headroom doctor --port 11434 — sending the user to re-probe Ollama's endpoint as if it were their proxy.

Closes #2199

Type of Change

  • Bug fix (non-breaking change that fixes an issue)

Changes Made

  • _classify_routing_url now recognizes Ollama's fixed default port: the check names the ollama launch claude bypass and points at the proxy-chaining path instead of the red-herring --port 11434 re-probe hint.
  • Fires for both the shell-env and settings-file routing checks that share the classifier.

Testing

  • Unit tests pass (pytest)
  • Linting passes (ruff check .)
  • Type checking passes (mypy headroom)
  • New tests added for new functionality
  • Manual testing performed

Test Output

$ pytest tests/test_cli_doctor.py -q
1 failed, 68 passed in 3.05s
# The lone failure is test_remote_control_warning_exits_1 — pre-existing and
# unrelated: it reads real ~/.headroom stats and fails on a clean tree with or
# without this change (does not exist / does not pass on main either).

$ pytest tests/test_cli_doctor.py -k ollama -q
1 passed, 68 deselected

$ ruff check headroom/cli/doctor.py tests/test_cli_doctor.py
All checks passed!

$ mypy headroom
Success: no issues found in 509 source files

Real Behavior Proof

  • Environment: local checkout, Python venv, pytest/ruff/mypy as above.
  • Exact command / steps: tests/test_cli_doctor.py pins the Ollama-aware message + hint emitted by _classify_routing_url for a loopback :11434 routing URL.
  • Observed result: doctor now reports the ollama launch claude bypass and the proxy-chaining fix instead of re-run with: headroom doctor --port 11434.
  • Not tested: no live ollama launch claude run; verified at the classifier boundary.

Review Readiness

  • I have performed a self-review
  • This PR is ready for human review

Checklist

  • My code follows the project's style guidelines
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I did not edit CHANGELOG.md — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

Additional Notes

Scope: this is only the diagnostic ask (#2199 part 3, requested as the minimum). The launcher-composition and model-aware routing halves depend on #1279's direction and are left for a maintainer steer. Documentation item is N/A (diagnostic message change, no docs surface). The pre-existing test_remote_control_warning_exits_1 failure is unrelated as noted above.

…ecting

`ollama launch claude` writes ANTHROPIC_BASE_URL=http://127.0.0.1:11434
into the launched Claude Code child, which outranks the persistent-install
env block and silently bypasses the Headroom proxy (0% savings, no dashboard
requests). `headroom doctor` treated :11434 as a mis-probed Headroom port
and suggested `--port 11434` — a red herring that hid the real collision.

Recognize Ollama's fixed default port in the routing classifier: the check
now names the `ollama launch claude` bypass and points at the proxy-chaining
path instead of telling the user to re-probe Ollama's endpoint.

Addresses the diagnostic half of headroomlabs-ai#2199.
@github-actions

github-actions Bot commented Jul 26, 2026 •

Copy link
Copy Markdown
Contributor

PR governance

This PR follows the template and is marked ready for human review.

@github-actions github-actions Bot added the status: needs author action Pull request body or readiness checklist still needs author updates label Jul 26, 2026
@codecov-commenter

codecov-commenter commented Jul 26, 2026 •

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions github-actions Bot added status: ready for review Pull request body is complete and the author marked it ready for human review and removed status: needs author action Pull request body or readiness checklist still needs author updates labels Jul 26, 2026

@JerrettDavis JerrettDavis left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Narrow diagnostic fix looks correct. I verified the shared routing classifier is used by both shell-env and settings-file checks, and the Ollama :11434 special case avoids the bad --port 11434 hint. Local verification passed: pytest tests/test_cli_doctor.py -q (69 passed), pytest tests/test_cli_doctor.py -k ollama -q, and ruff on the touched files. CI is green.

@JerrettDavis
JerrettDavis merged commit 7f24d69 into headroomlabs-ai:main Aug 12, 2026
33 checks passed
nangsontay pushed a commit to nangsontay/headroom that referenced this pull request Aug 12, 2026
…irecting (headroomlabs-ai#2566)

## Description

Addresses the diagnostic half of headroomlabs-ai#2199.

`ollama launch claude` sets `ANTHROPIC_BASE_URL=http://127.0.0.1:11434`
in the launched Claude Code child. That process env outranks the `env`
block a persistent Headroom install writes to `~/.claude/settings.json`,
so Claude Code talks to Ollama and never reaches the proxy — 0% savings,
nothing on the dashboard, no error.

`headroom doctor`'s routing classifier made it worse: seeing a loopback
`:11434`, it reported `routed to port 11434, but doctor probed port
8787` and hinted `re-run with: headroom doctor --port 11434` — sending
the user to re-probe Ollama's endpoint as if it were their proxy.

Closes headroomlabs-ai#2199

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `_classify_routing_url` now recognizes Ollama's fixed default port:
the check names the `ollama launch claude` bypass and points at the
proxy-chaining path instead of the red-herring `--port 11434` re-probe
hint.
- Fires for both the shell-env and settings-file routing checks that
share the classifier.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest tests/test_cli_doctor.py -q
1 failed, 68 passed in 3.05s
# The lone failure is test_remote_control_warning_exits_1 — pre-existing and
# unrelated: it reads real ~/.headroom stats and fails on a clean tree with or
# without this change (does not exist / does not pass on main either).

$ pytest tests/test_cli_doctor.py -k ollama -q
1 passed, 68 deselected

$ ruff check headroom/cli/doctor.py tests/test_cli_doctor.py
All checks passed!

$ mypy headroom
Success: no issues found in 509 source files
```

## Real Behavior Proof

- Environment: local checkout, Python venv, `pytest`/`ruff`/`mypy` as
above.
- Exact command / steps: `tests/test_cli_doctor.py` pins the
Ollama-aware message + hint emitted by `_classify_routing_url` for a
loopback `:11434` routing URL.
- Observed result: doctor now reports the `ollama launch claude` bypass
and the proxy-chaining fix instead of `re-run with: headroom doctor
--port 11434`.
- Not tested: no live `ollama launch claude` run; verified at the
classifier boundary.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Scope: this is only the *diagnostic* ask (headroomlabs-ai#2199 part 3, requested as the
minimum). The launcher-composition and model-aware routing halves depend
on headroomlabs-ai#1279's direction and are left for a maintainer steer. Documentation
item is N/A (diagnostic message change, no docs surface). The
pre-existing `test_remote_control_warning_exits_1` failure is unrelated
as noted above.
JerrettDavis added a commit that referenced this pull request Aug 13, 2026
🤖 I have created a release *beep* *boop*
---


<details><summary>0.35.0</summary>

##
[0.35.0](v0.34.0...v0.35.0)
(2026-08-12)


### Features

* **beacon:** allowlist the routing summary key
([#2818](#2818))
([7940c05](7940c05))
* **beacon:** hourly R2 compaction, per-strategy savings, and a stack
that reports
([#2853](#2853))
([e0870ef](e0870ef))
* **cli,pricing:** add CLI extension seam and prompt-cache TTL pricing
([#2802](#2802))
([6ec3e34](6ec3e34))


### Bug Fixes

* **anthropic:** strip first-party tool search on custom upstreams
([#2539](#2539))
([7f6950b](7f6950b))
* **backends/anyllm:** convert Anthropic tools and tool_choice to OpenAI
shape
([0d6866b](0d6866b))
* **backends/anyllm:** stream tool_use blocks and map finish_reason on
the streaming path
([e4904e2](e4904e2))
* **backends/litellm:** None-guard core token counts in OpenAI usage
block ([#2324](#2324))
([12f9f58](12f9f58))
* **beacon:** report all-layers savings, not context-compression only
([#2796](#2796))
([e9a24f3](e9a24f3))
* **beacon:** split session failures by status code
([#2815](#2815))
([2954e37](2954e37))
* **cache:** bound compression cache bookkeeping
([0ae948c](0ae948c))
* **cache:** enforce Anthropic's 1h-before-5m cache_control ordering
before forwarding
([#2941](#2941))
([3752458](3752458))
* **cache:** mirror client cache_control positions instead of
single-marker consolidation
([def3d76](def3d76))
* **cache:** stabilize Anthropic block-growing lineages
([#2917](#2917))
([1a04c95](1a04c95))
* **ccr:** avoid injecting tool on chat streaming
([d0c1f5b](d0c1f5b))
* **ccr:** preserve exact SQLite TTL boundary
([#2669](#2669))
([d0a86d4](d0a86d4))
* **ccr:** report embedded hashes from compress endpoint
([#717](#717))
([685ebe4](685ebe4))
* **ccr:** resolve &lt;&lt;ccr:...&gt;&gt; markers inline when no
retrieve-tool path exists
([#2512](#2512))
([ce8ce83](ce8ce83))
* **ccr:** tolerate null/malformed OpenAI data in response handling
([#2467](#2467))
([e583e08](e583e08))
* **ci:** publish latest from the root Docker manifest
([#2252](#2252))
([5568d73](5568d73))
* **claude:** stop forcing tool search on Foundry
([#2477](#2477))
([7981396](7981396))
* **cli/update:** let install ownership win over bare /.dockerenv so
venv installs self-update
([#2830](#2830))
([7092b53](7092b53))
* **codex:** route alpha search through the Codex backend
([#2538](#2538))
([a540eb2](a540eb2))
* **content-router:** protect custom-tag blocks before mixed-content
section split
([d7bc1e2](d7bc1e2))
* **deps:** bump h2 to 4.4.1 for CVE-2026-71554
([#2839](#2839))
([564e0a8](564e0a8))
* **deps:** enforce audited transitive dependency floors
([#2791](#2791))
([64e2039](64e2039))
* **doctor:** flag `ollama launch claude` proxy bypass instead of
misdirecting
([#2566](#2566))
([7f24d69](7f24d69))
* emit SSE ping before message_start on Bedrock streaming path (issue
[#902](#902))
([#1080](#1080))
([4dab254](4dab254))
* **gemini:** resolve native CCR retrieval calls
([#2253](#2253))
([2483f57](2483f57))
* **health:** label kompress as degraded/optional when not yet loaded
([#2865](#2865))
([8949371](8949371))
* **image:** decouple routing types from trained_router so importing the
compressor doesn't import torch
([#2513](#2513))
([#2537](#2537))
([d7cf981](d7cf981))
* **install/windows:** register persistent-task from S4U hidden XML
([#2453](#2453))
([#2459](#2459))
([1edaeb8](1edaeb8))
* **install:** don't crash the PowerShell installer when $PROFILE is
unset ([#2469](#2469))
([fc5c4e2](fc5c4e2))
* **install:** trust Docker bridge for dashboard metadata
([e044139](e044139))
* **install:** use --userns=keep-id under Podman so bind-mount writes
don't fail
([#2846](#2846))
([3488f8d](3488f8d))
* **learn/gemini:** stop double-counting session tokens
([#2230](#2230))
([29d8a5e](29d8a5e))
* **learn/grok:** detect a Windows absolute project path
([#2283](#2283))
([e240df2](e240df2))
* **learn:** stop classifying a successful exit code 0 as an error
([#2289](#2289))
([a24fe7d](a24fe7d))
* **litellm:** add async_post_call_success_hook to HeadroomCallback
([#1322](#1322))
([3107994](3107994))
* **litellm:** don't forward a caller key the target cannot accept
([#2883](#2883))
([2f2950a](2f2950a))
* **memory:** bound the TrafficLearner pending-pattern accumulator
(memory leak)
([#2579](#2579))
([1f5feff](1f5feff))
* **memory:** close DirectMem0 resources
([6596182](6596182))
* **memory:** close MCP backend on shutdown
([4bd8ecd](4bd8ecd))
* **memory:** don't crash inline memory extraction on a non-object
&lt;memory&gt; block
([#2470](#2470))
([e00c6ff](e00c6ff))
* **memory:** keep vector metadata in sync
([#2295](#2295))
([c471800](c471800))
* **memory:** make explicit-project and user store keys
collision-resistant
([#2231](#2231))
([f840d5f](f840d5f))
* **memory:** skip &lt;system-reminder&gt; blocks when building the
retrieval query
([#2195](#2195))
([#2541](#2541))
([4e5a67a](4e5a67a))
* **memory:** sync FTS5 and vector indexes on CLI
delete/edit/prune/purge
([fd4628d](fd4628d))
* **oauth2:** make repository lint checks pass
([c85abf7](c85abf7))
* **observability:** aggregate tool savings in OTEL
([#2936](#2936))
([941c25d](941c25d))
* **onnx:** stop ONNX thread pools from spinning idle cores
([#2495](#2495))
([#2540](#2540))
([5c561bd](5c561bd))
* **openai:** skip Responses tool-search deferral for clients that
cannot execute it
([#2696](#2696))
([54ea28d](54ea28d))
* **opencode:** ship the transport hook-shim so wheel installs route
Node child traffic
([702dbc5](702dbc5))
* **providers/anthropic:** don't crash token estimation on null
tool_calls
([#2472](#2472))
([08466f3](08466f3))
* **providers/openai:** bound tiktoken vocab loads with the guarded
loader
([#2554](#2554))
([0805e8e](0805e8e))
* **proxy/anthropic:** inject headroom_retrieve whenever a CCR marker is
present, not only for new markers
([#2848](#2848))
([3808f60](3808f60))
* **proxy/anthropic:** None-guard usage token counts on the direct
buffered path
([#2434](#2434))
([2b5ee7c](2b5ee7c))
* **proxy/anthropic:** run tool-search history repair after turn hooks
([c6f9948](c6f9948))
* **proxy/batch:** don't crash an OpenAI batch on a valid-JSON
non-object line
([#2316](#2316))
([1f2c681](1f2c681))
* **proxy/bedrock:** report uncached input tokens from backend usage,
not the live-zone count
([#2318](#2318))
([c19e412](c19e412))
* **proxy/gemini:** keep streaming-parity baseline so eligible_pct can't
exceed 100
([#2824](#2824))
([b97c7c6](b97c7c6))
* **proxy/metrics:** cap client-supplied model label cardinality
([#2480](#2480))
([e24a7e6](e24a7e6))
* **proxy/metrics:** escape label values in the Prometheus export
([#2463](#2463))
([6a53861](6a53861))
* **proxy/openai:** don't crash the Responses memory tool loops on null
arguments
([#2273](#2273))
([a30db2c](a30db2c))
* **proxy/openai:** feed Codex WS traffic into the traffic learner
([#2334](#2334))
([f669149](f669149))
* **proxy/openai:** run response hooks on Responses, and bill their
re-drives
([#2872](#2872))
([675d13f](675d13f))
* **proxy:** allow settings routes for trusted gateway/dashboard clients
([#2491](#2491))
([a5b0a8f](a5b0a8f))
* **proxy:** cache litellm model resolution to stop repeated Provider
List spam
([99f07e7](99f07e7))
* **proxy:** cancel periodic TOIN task on shutdown
([739fdef](739fdef))
* **proxy:** close the upstream stream when a streaming body is never
consumed
([0951663](0951663))
* **proxy:** compress cache-mode cold starts and tag prefix-mismatch
passthrough
([#2365](#2365))
([aaeba0a](aaeba0a))
* **proxy:** emit request log timestamps in UTC
([620028f](620028f))
* **proxy:** enable tool search by default and repair poisoned
transcripts
([#2807](#2807))
([0237cbf](0237cbf))
* **proxy:** gate mid-turn message coalescing to Claude Code clients
([#1643](#1643))
([a4bd2e6](a4bd2e6))
* **proxy:** give each Codex /v1/responses WS turn a unique request_id
([#2164](#2164))
([d02df10](d02df10))
* **proxy:** graceful shutdown and reliable Ctrl+C exit
([#621](#621))
([17cdb18](17cdb18))
* **proxy:** guard telemetry and TOIN endpoints
([cde1513](cde1513))
* **proxy:** include tool_search_deferral savings in the savings ledger
([12149f7](12149f7))
* **proxy:** pass through cross-region prefixed Bedrock model IDs
directly
([#2330](#2330))
([64cb46e](64cb46e))
* **proxy:** port session-sticky beta headers to the Rust proxy
([#2381](#2381))
([f6398a6](f6398a6))
* **proxy:** preserve merged session and quarantine contracts
([#2943](#2943))
([039cd24](039cd24))
* **proxy:** preserve signed Anthropic thinking blocks on outbound
re-serialize
([#2254](#2254))
([dc163bc](dc163bc))
* **proxy:** stop discarding compressed Codex WS later-frame payloads
([#2823](#2823))
([4ec416d](4ec416d))
* **proxy:** time-cap the compression timeout-debt quarantine
([#2360](#2360))
([#2412](#2412))
([c5a08d2](c5a08d2))
* **proxy:** unwrap Hermes tool_call bridge in tool name map
([#2717](#2717))
([a97b824](a97b824))
* publish headroom-opencode in release workflow
([#2372](#2372))
([7859154](7859154))
* **settings:** accept documented HEADROOM_* env names as settings keys
([#2833](#2833))
([de9e052](de9e052))
* **subscription:** dedup transcript usage by message id
([#2340](#2340) token
inflation)
([#2408](#2408))
([74275b7](74275b7))
* **toin:** bound private query and pattern retention
([8cd1380](8cd1380))
* **tokenizer:** coerce non-string tool_call fields before counting
([#2801](#2801))
([b6f9877](b6f9877))
* **tokenizer:** price CJK in the Rust fixed-ratio estimator (Python
parity)
([#2260](#2260))
([6840153](6840153))
* **transforms/adaptive-sizer:** honor max_k on small-input fast path
([#2319](#2319))
([8a90523](8a90523))
* **transforms/smart_crusher:** don't crash on a tool call with a null
function
([#2232](#2232))
([3bb02f8](3bb02f8))
* Vertex model pricing shows $0.00 for versioned model names and
vertex:anthropic provider
([#2517](#2517))
([eb5b5e4](eb5b5e4))
* **wrap/claude:** keep --1m effective when an explicit --model is
passed through
([c093bf1](c093bf1))
* **wrap/opencode:** verify the opencode binary before mutating config
([ae38486](ae38486))
* **wrap/serena:** install Serena from the serena-agent PyPI wheel, not
the git source
([d7b25ae](d7b25ae))
* **wrap:** honor Copilot OAuth wire-api override and model default
([#2387](#2387))
([1db6d88](1db6d88))
* **wrap:** serialize shared proxy startup
([#2946](#2946))
([e540d64](e540d64))
* **wrap:** stop the launch cwd from shadowing the installed package in
the proxy subprocess
([#2843](#2843))
([c49be26](c49be26))


### Performance Improvements

* cut hot-path latency 27% (token-count memo, startup preloads, JSON
scan memo)
([#2838](#2838))
([53af90d](53af90d))
* **proxy:** bound upstream calls and hot-path costs
([#2852](#2852))
([f624d3a](f624d3a))
* **subscription:** skip transcripts older than the window in
compute_window_tokens
([#2861](#2861))
([91d6bf3](91d6bf3))


### Dependencies

* bump brace-expansion from 5.0.7 to 5.0.9 in /docs
([#2751](#2751))
([56ee57b](56ee57b))
* bump bytesize from 1.3.3 to 2.4.2
([#2286](#2286))
([6448545](6448545))
* bump hf-hub from 0.4.3 to 0.5.0
([#2285](#2285))
([4925bf6](4925bf6))
* bump next from 16.2.10 to 16.3.0 in /docs
([#2750](#2750))
([0fd0b99](0fd0b99))
* bump postcss from 8.5.19 to 8.5.25 in /plugins/openclaw
([#2749](#2749))
([cd60ee9](cd60ee9))
* bump postcss from 8.5.19 to 8.5.25 in /plugins/opencode
([#2748](#2748))
([ff4e016](ff4e016))
* bump postcss from 8.5.19 to 8.5.25 in /sdk/typescript
([#2747](#2747))
([267c2bd](267c2bd))
* bump postcss from 8.5.19 to 8.5.26 in /docs
([#2881](#2881))
([e6e5826](e6e5826))
* bump ruff from 0.15.17 to 0.15.22 in the pip-minor-patch group
([#2501](#2501))
([ecf130d](ecf130d))
* bump rusqlite from 0.32.1 to 0.40.1
([#2287](#2287))
([522faa1](522faa1))
* bump the cargo-minor-patch group across 1 directory with 22 updates
([#2916](#2916))
([148d860](148d860))
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

---------

Co-authored-by: JD Davis <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
chopratejas pushed a commit that referenced this pull request Aug 16, 2026
…oxy (#2987)

## Description

`headroom doctor` reports the `claude` check as a pass whenever
`~/.claude/settings.json` carries an `ANTHROPIC_BASE_URL` pointing at
the proxy. That is correct for the terminal Claude Code CLI. But Claude
Desktop (`com.anthropic.claudefordesktop`) unconditionally overwrites
that variable when spawning agent sessions (#869), so on a
Desktop-primary machine `doctor` asserts routing that is in fact
discarded, and nothing in the output hints that Desktop sessions are
unrouted (#2925).

## Fix

Add a per-surface `claude desktop` check that warns about the bypass
when Claude Desktop's config directory is detected, pointing at #869.
Following the issue's suggestion, it models per-surface reporting like
the existing `wrap_marker` / `shell env` rows: it is a separate row
emitted only when Desktop is present, so it never contradicts a
genuinely routed CLI, and the existing `claude` check is left unchanged.

Detection uses Claude Desktop's per-user config directory (distinct from
the CLI's `~/.claude`):
- macOS: `~/Library/Application Support/Claude`
- Windows: `%APPDATA%\Claude`
- Linux: `$XDG_CONFIG_HOME/Claude` (or `~/.config/Claude`)

Fixes #2925

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/cli/doctor.py`: add `claude_desktop_config_dir()`
(cross-platform) and `check_claude_desktop()` (WARN when the dir exists,
`None` otherwise); append it to the `doctor()` check list when present.
- `tests/test_cli_doctor.py`: `TestClaudeDesktop` -- no row when absent;
WARN naming the bypass and #869 when present; the `doctor --json`
entrypoint appends the row only when Desktop is detected.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added

### Test Output

```text
tests/test_cli_doctor.py  78 passed
# uvx [email protected] check  -> All checks passed!
# uvx [email protected] headroom/cli/doctor.py -> Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.15.22 and mypy 1.20.2 via uvx.
- Exact command / steps: `uvx [email protected] check headroom/cli/doctor.py
tests/test_cli_doctor.py`; `uvx [email protected] headroom/cli/doctor.py`;
`python -m pytest tests/test_cli_doctor.py -q`; then drove the check
directly and through the `doctor --json` entrypoint with
`claude_desktop_config_dir` pointed at a tmp dir (created the dir, ran
`doctor --json`, then removed it and reran).
- Observed result: with the dir present, a `claude desktop` row appears
with status `warn` and a `#869` hint; with the dir absent, no such row
is emitted and the rest of the report is unchanged. A Desktop-primary
machine now gets an explicit warning that Desktop agent sessions bypass
the proxy, instead of a bare `claude: pass` that reads as though all
Claude routing is live.
- Not tested: a live Claude Desktop install (detection is
directory-existence, exercised against a tmp dir).

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This adds a read-only diagnostic row
to `headroom doctor`; it is not behind any rollout channel or feature
flag.
- Minimum rollout channel: N/A (no rollout-managed behavior).
- Stable/default behavior changed: no. The existing `claude` check and
all other rows are unchanged; the new `claude desktop` row is additive
and only appears when Claude Desktop's config directory is detected.
- Kill switch / disable path: N/A. The row self-suppresses (returns
`None`) on any machine without the Desktop config directory.
- Unsafe override required: no.
- Qualification impact: none. No proxy request path, routing, or token
accounting is touched; the change is confined to the doctor diagnostic
surface.
- Rollback path: revert this PR; the doctor output returns to its prior
set of rows with no state or migration to undo.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`: it is generated by
release-please from my Conventional Commit PR title

## Additional Notes

Scope: this warns whenever Claude Desktop is present, which is accurate
(Desktop agent sessions always bypass per #869) and matches the
precedent for doctor-accuracy fixes (#2618/#2614 Codex, #2566 ollama).
The issue's stronger refinement -- suppress the warning when a
`client=claude-code` request has recently reached the proxy -- would
need per-client traffic observation the doctor does not have today; I
left that as a follow-up rather than build new traffic-tracking infra
into this fix. Happy to add it if you'd prefer the conditional form.

Rebased onto current `main` to resolve an overlap with the newly merged
`check_claude_auth_conflict` in `doctor.py`; both checks now coexist.

Co-authored-by: JD Davis <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: ready for review Pull request body is complete and the author marked it ready for human review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Global/persistent Claude Code routing is bypassed by ollama launch claude (ANTHROPIC_BASE_URL collision) — support both from one install

3 participants