akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/docs
History
Tejas Chopra f4bd2fe68f
docs(vertex): Claude Code + Vertex via Headroom guide (validated) (#1180) 
## Description

Documents the **validated** way to run **Claude Code** against **Claude
models on Google Vertex AI** with **Headroom compressing the context**.
Corrects the prior review's assumption that the "Vertex-mode redirect"
approach would work — Claude Code's client-side `probeVertexModel`
blocks it — and documents the working **Anthropic-mode + LiteLLM
`vertex_ai`** path, verified end-to-end against live Vertex quota (~22%
context compression observed).

Closes # <!-- n/a -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- **`docs/claude-code-vertex-headroom.md`** (new) — copy-paste runbook:
prerequisites (GCP ADC, `google-cloud-aiplatform`, Vertex quota),
two-terminal setup (proxy `--backend litellm-vertex_ai --region <loc>
--code-aware`; Claude Code in normal Anthropic mode via
`ANTHROPIC_BASE_URL`), verification, a troubleshooting table, and a
section on what `--code-aware` does and what it never touches (local
files / protected `Read`/`Glob`/`Grep`/`Write`/`Edit` output).
- **`wiki/vertex.md`** — new "Claude Code with Headroom compression"
section pointing at the runbook, with the two ⚠️ caveats (Vertex-mode
probe rejects custom URLs; `vertexai` dep + `--code-aware` required).
- **`docs/proposals/vertex-claude-compression-review.md`** — corrected
TL;DR: Setup A is blocked by Claude Code's probe; Setup B is the
validated path.

## Testing

- [ ] Unit tests pass (`pytest`) — **N/A (docs-only, no code changed)**
- [ ] Linting passes (`ruff check .`) — **N/A (no Python changed)**
- [ ] Type checking passes (`mypy headroom`) — **N/A (no Python
changed)**
- [ ] New tests added for new functionality — **N/A (docs)**
- [x] Manual testing performed (live Vertex validation — see below)

### Test Output

```text
# 1) Direct Vertex quota check (global)
POST .../locations/global/publishers/anthropic/models/claude-sonnet-4-6:rawPredict
  -> HTTP 200  {"content":[{"text":"VERTEX OK"}], "model":"claude-sonnet-4-6"}

# 2) Headroom in Anthropic mode -> LiteLLM(vertex_ai) -> Vertex global
POST http://127.0.0.1:8787/v1/messages  (model=claude-sonnet-4-6)
  -> HTTP 200  {"content":[{"text":"LITELLM VERTEX OK"}], "model":"claude-sonnet-4-6"}

# 3) Real Claude Code session (normal mode) through Headroom, --code-aware ON
claude -p "...run two Bash source dumps + summarize..."  (ANTHROPIC_BASE_URL=proxy)
  -> is_error: False, modelUsage: ['claude-sonnet-4-6']
  request_log: orig=9353  saved=2029 (21.7%)  transforms=['router:tool_result:mixed']

# 4) Compressors loaded (GET /debug/warmup)
{'kompress':'loaded', 'code_aware':'loaded', 'tree_sitter':'loaded', 'smart_crusher':'loaded'}
```

## Real Behavior Proof

- **Environment:** macOS (arm64); Claude Code 2.1.181; Headroom 0.27.0;
venv Python 3.12; LiteLLM `vertex_ai` via `google-cloud-aiplatform`
1.158.0; GCP project `eternal-sunset-495505-t0`; Vertex location
`global`; model `claude-sonnet-4-6` (only model with quota on this
project); auth via `gcloud auth application-default login` (ADC).
- **Exact command / steps:** the two-terminal setup in
`docs/claude-code-vertex-headroom.md` — proxy `headroom proxy --port
8787 --backend litellm-vertex_ai --region global --code-aware`; client
`ANTHROPIC_BASE_URL=http://127.0.0.1:8787` +
`ANTHROPIC_MODEL=claude-sonnet-4-6` in normal mode (no
`CLAUDE_CODE_USE_VERTEX`).
- **Observed result:** Claude Code answered via Vertex (`modelUsage:
claude-sonnet-4-6`); ~22% context compression
(`router:tool_result:mixed`) on a code-heavy request forwarded to Vertex
`global`; all compressors loaded.
- **Not tested:** cumulative savings over long multi-turn sessions;
non-global regions (no quota on this project); Opus 4.8 (not enabled in
this project — 404); automated tests for the LiteLLM-vertex path (still
absent — pre-existing gap).

## 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 (docs)
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
(N/A — docs)
- [x] I have made corresponding changes to the documentation (this *is*
the documentation)
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works — **N/A (docs-only)**
- [ ] New and existing unit tests pass locally with my changes — **N/A
(no code changed)**
- [ ] I have updated the CHANGELOG.md if applicable — **N/A
(docs-only)**

## Additional Notes

- **Docs-only PR** — no Python changed, so `ruff` / `mypy` / `pytest`
are N/A.
- **Base:** branched from latest `origin/main`; clean 3-file diff (the
prerequisite review doc and Vertex wiki content are already on `main`).
- **Follow-ups:** optional `headroom wrap claude` Vertex turnkey; add
automated tests for the LiteLLM-vertex path; consider defaulting
`--code-aware` (or warning when code content is detected but code-aware
is off), since its default-off state makes compression silently no-op on
coding sessions.
2026-06-19 18:14:14 -07:00
..
app docs: improve discoverability for AI agents and search crawlers 2026-05-13 17:36:06 -07:00
components tokens saved grid 2026-04-12 13:42:20 +06:00
content/docs feat(vertex): turnkey Claude Code + Vertex compression (+ fixes from the Vertex review) (#1113) 2026-06-18 00:56:23 -07:00
lib docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
overrides fix: repair release and docs pipelines 2026-04-16 12:53:51 -05:00
proposals docs(vertex): Claude Code + Vertex via Headroom guide (validated) (#1180) 2026-06-19 18:14:14 -07:00
screenshots Merge pull request #147 from JerrettDavis/feat/anthropic-usage-insights 2026-04-12 10:54:22 -07:00
spec docs: align MCP proxy docs with implemented API (#614) 2026-06-10 21:14:23 -05:00
.gitignore new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
auth-modes.md fix: PR-F1 classify_auth_mode helper (Phase F kickoff) 2026-05-03 17:20:14 -07:00
bedrock.md feat(bedrock): cross-region + Converse compression; bundle proxy binary in images (#999) 2026-06-16 09:45:24 -05:00
bun.lock fix(docs): update bun.lock to next 16.2.6 for GHSA-h64f-5h5j-jqjh (CVE-2026-44577) 2026-06-02 04:25:21 +00:00
claude-code-vertex-headroom.md docs(vertex): Claude Code + Vertex via Headroom guide (validated) (#1180) 2026-06-19 18:14:14 -07:00
next.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
observability.md fix(observability): G3 remediation — bound cardinality + wire dead metrics 2026-05-24 10:41:56 -07:00
output-token-reduction-guide.md feat(proxy): hot-reload live env knobs so a reused proxy picks them up without a restart (#1090) 2026-06-18 09:50:50 -07:00
package-lock.json ci: bump the npm_and_yarn group across 3 directories with 3 updates (#1056) 2026-06-16 23:07:34 -07:00
package.json ci: bump the npm_and_yarn group across 3 directories with 3 updates (#1056) 2026-06-16 23:07:34 -07:00
postcss.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
proxy.ts new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
README.md new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
rtk-architecture.md fix(observability): wire Phase G PR-G3 RTK + proxy metrics (H-blocker) 2026-05-22 13:18:42 -07:00
source.config.ts docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
tsconfig.json new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00

README.md

docs

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Explore

In the project, you can see:

  • lib/source.ts: Code for content source adapter, loader() provides the interface to access your content.
  • lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
Route Description
app/(home) The route group for your landing page and other pages.
app/docs The documentation layout and pages.
app/api/search/route.ts The Route Handler for search.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: