quickstart-proxy.md

Quickstart: proxy

Run context-guru in front of your provider and point an agent at it. One port serves both the OpenAI and Anthropic dialects.

You need no toolchain at all to run it. The shipped binary is statically linked pure Go — no C compiler, no Go install, no runtime dependencies. Grab it from Releases:

# Pick your platform: linux/darwin × amd64/arm64. The archive unpacks into its own
# directory, so this is safe to run from anywhere — including a project checkout.
tar xzf context-guru_*_darwin_arm64.tar.gz
install -m 755 context-guru_*/context-guru-proxy ~/.local/bin/

To build from source instead you need Go 1.26 — and still no C toolchain: make build builds with cgo disabled and produces the same statically linked binary. CI asserts that natively for linux/amd64 (the purego job), and the release workflow asserts it again before publishing.

A C compiler is needed for exactly two things: make test (the race detector requires cgo) and the optional skeleton component's cg_skeleton build tag.

Steps

1. Build (source path only — skip if you downloaded a release):

   make build                     # → bin/context-guru-proxy
   make build-static              # the pure-Go build releases ship (CGO_ENABLED=0)

2. Run it. It listens on :4000; set LISTEN_ADDR to change that.

   ./bin/context-guru-proxy       # default preset: house

3. Point your agent at it:

   ANTHROPIC_BASE_URL=http://localhost:4000/anthropic      # Anthropic dialect
   OPENAI_BASE_URL=http://localhost:4000/openai/v1         # OpenAI dialect

   Set ANTHROPIC_API_KEY / OPENAI_API_KEY on the proxy and it injects the real key on forward; leave them unset to pass the client's own auth through.

4. Check the savings:

   curl -s localhost:4000/stats | jq

Send one request by hand

curl -s -XPOST localhost:4000/openai/v1/chat/completions \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $YOUR_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "list users"},
      {"role": "tool", "tool_call_id": "c1",
       "content": "[{\"id\":1,\"name\":\"Alice\"},{\"id\":2,\"name\":\"Bob\"}]"}
    ]
  }'

The same request on the Anthropic dialect

curl -s localhost:4000/anthropic/v1/messages \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $YOUR_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 64,
    "messages": [
      {"role": "user", "content": "read the config"},
      {"role": "assistant", "content": [
        {"type": "tool_use", "id": "t1", "name": "Bash", "input": {}}]},
      {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": "t1",
         "content": "[{\"id\":1,\"name\":\"Alice\"},{\"id\":2,\"name\":\"Bob\"}]"}]}
    ]
  }'

Tool outputs on the Anthropic dialect ride in tool_result blocks inside a user message; apply normalizes them so every component sees them the same way.

Per-request headers

Header	Effect
x-context-guru-session: <id>	Set the session key explicitly (otherwise a content hash).
x-context-guru-bypass: true	Skip the pipeline entirely for this request.

Troubleshooting

The proxy exits with components: unknown component "skeleton". The skeleton component needs the cg_skeleton build tag, and make build does not pass it. Build it explicitly:

CGO_ENABLED=1 go build -tags cg_skeleton -o bin/context-guru-proxy ./cmd/context-guru-proxy

The coding preset, and any pipeline listing skeleton, needs that binary. Without the tag the component is not registered, and the proxy refuses to start rather than quietly running a pipeline that is missing a component you asked for. Every other component is unaffected.

/stats shows zero requests. The agent is not reaching the proxy. Confirm the base URL includes the dialect path (/anthropic, or /openai/v1), and note that Claude Code's ~/.claude/settings.json env block overrides an exported ANTHROPIC_BASE_URL — see Use with Claude Code.

I need a container instead. docker build -t context-guru:local .

I want to recover an offloaded original by hand. A lossy Offload leaves a <<cg:HASH>> marker; curl -s 'localhost:4000/expand?id=<HASH>' returns the stashed original. In normal operation the model recovers it automatically — see Reversibility & recovery.

See also: Config & environment · Choose a preset · Routes & headers · Measure savings