Journey: Proxy & Power Integrations

You’ve mastered daily use and want the plumbing layer: compress the LLM API stream itself, serve the engine over HTTP for multi-repo setups, pull GitHub/GitLab/Jira/Postgres into context, and package curated context for others. This journey covers the power-user wiring — the parts that sit between your AI client and everything else.

1. The proxy — compress the LLM stream itself

What it does: Everything so far compresses before your AI calls a tool. The proxy goes one level deeper: it sits between your AI client and the LLM API and compresses tool_results in-flight, before they reach the model.

lean-ctx proxy enable        # set up env + autostart (writes RC + LaunchAgent)
lean-ctx proxy status
lean-ctx proxy start         # start now
lean-ctx proxy stop
lean-ctx proxy disable       # remove env + autostart
lean-ctx proxy cleanup       # clear proxy state

Golden output — lean-ctx proxy status tells you, at a glance, whether the proxy is configured, on which port, and whether the process is currently up:

lean-ctx proxy:
  Config:  enabled
  Port:    4444
  Process: not running

Config: enabled with Process: not running means it is wired up but not started, run lean-ctx proxy start (or rely on the LaunchAgent/systemd unit).

Under the hood: runs on LEAN_CTX_PROXY_PORT (default 4444), auth via session_token. proxy enable writes *_BASE_URL exports into your shell RC and Codex config.toml (OPENAI_BASE_URL), and installs com.leanctx.proxy.plist (macOS) or a systemd user unit (Linux). For Claude it sets ANTHROPIC_BASE_URL (shell RC + ~/.claude/settings.json) only when an Anthropic API key is detectable, see the Pro/Max note below. Upstreams are configurable in [proxy].

Claude Pro/Max subscription? The proxy forwards your upstream credential but never injects one, and a Pro/Max plan authenticates via OAuth directly against api.anthropic.com — a custom ANTHROPIC_BASE_URL is rejected (login loop / 401). So proxy enable deliberately leaves Claude on api.anthropic.com whenever no ANTHROPIC_API_KEY is set (it even repairs a stale local redirect), while OpenAI and Gemini still route through the proxy. On a subscription, get your savings from the lean-ctx MCP tools (ctx_read, ctx_search, ctx_shell) instead. Pay-as-you-go? Set ANTHROPIC_API_KEY and re-run lean-ctx proxy enable (or --force). lean-ctx doctor flags a conflicting redirect.

Codex & Pi/forge wiring. proxy enable also wires Pi and forge, which resolve their endpoint from ~/.pi/agent/models.json rather than *_BASE_URL (Anthropic gets the bare origin, OpenAI the /v1 suffix), and disable reverts only the endpoints it set. For Codex, the proxy speaks the OpenAI Responses WebSocket protocol natively (GET /responses upgrades; each response.create turn is bridged to the HTTP/SSE upstream with compression applied), so Codex is a drop-in without setting supports_websockets = false. If a client sits in front of the proxy and needs a plaintext upstream (e.g. http://host.docker.internal:2455), opt in with allow_insecure_http_upstream / LEAN_CTX_ALLOW_INSECURE_HTTP_UPSTREAM — see Configuration → Proxy.

Heads-up (community-reported): proxy enable modifies your shell RC. If a base URL “defaults to the wrong provider,” check the exported *_BASE_URL values in your RC and lean-ctx proxy status. The unmodified RC is preserved as a *.lean-ctx.bak backup.

2. HTTP MCP & multi-repo — lean-ctx serve

For clients that speak Streamable HTTP instead of stdio, or to serve several repos at once:

lean-ctx serve --daemon                       # background HTTP MCP server
lean-ctx serve --root ~/work/api:api \
               --root ~/work/web:web           # multi-repo, with aliases
lean-ctx serve --status
lean-ctx serve --stop

Multi-repo search fuses results across roots with Reciprocal Rank Fusion (--rrf-k). The MCP equivalent is ctx_multi_repo (add_root, list_roots, search, save_config).

The daemon (lean-ctx daemon) is the local IPC service (Unix socket in ~/.local/share/lean-ctx/); most users never touch it directly.

3. External context providers — ctx_provider

What it does: Brings issues, PRs/MRs, pipelines, tickets, and DB schema into context so ctx_semantic_search and ctx_knowledge can find them.

Supported: GitHub, GitLab, Jira, Postgres, and arbitrary MCP bridges.

ctx_provider action=list
ctx_provider action=gitlab_issues state=opened labels=bug
ctx_provider action=gitlab_mrs
ctx_provider action=query provider=jira resource=PROJ-123

Auth: via env tokens — GITHUB_TOKEN/GH_TOKEN, GITLAB_TOKEN/CI_JOB_TOKEN, JIRA_URL+JIRA_EMAIL+JIRA_TOKEN, DATABASE_URL. Jira also supports OAuth via lean-ctx provider auth jira. Configure under [providers] in config.toml.

The pipeline: provider data flows through the same consolidation path as everything else, the raw provider results are consolidated into BM25 chunks, graph edges, and knowledge facts. That’s why a GitHub issue can show up as a cross-source hint when you read a related file.

4. Packaging & sharing context — lean-ctx pack / ctx_pack

Context packages bundle curated context (and PR-specific “PR packs”) so it can be installed elsewhere or shared with teammates.

lean-ctx pack pr                         # build a PR pack for the current diff
lean-ctx pack create --name my-context
lean-ctx pack list
lean-ctx pack install <name>
lean-ctx pack export / import

Packages live under packages/ with a package-index.json. ctx_pack exposes the same actions to your AI.

5. Governing rules — lean-ctx rules / ctx_rules

Keeps the LeanCTX rule blocks in sync across every agent’s rule file (.cursor/rules, AGENTS.md, CLAUDE.md, …).

lean-ctx rules status        # what's installed where
lean-ctx rules sync          # re-sync all agents
lean-ctx rules diff          # show drift
lean-ctx rules lint          # validate

Scope via rules_scope (both/global/project). Promote high-confidence knowledge into rules with lean-ctx export-rules.

6. Client integration internals — instructions & hook

These are the low-level building blocks setup/init (Setup & Onboarding) wire up for you. You rarely call them by hand, but they’re documented for anyone integrating a new client or debugging an integration:

lean-ctx instructions --client cursor          # compile guidance for one client
lean-ctx instructions --client claude --profile standard --crp tdd
lean-ctx instructions --client codex --json --include-rules
lean-ctx instructions --list-clients           # which client IDs are supported

instructions renders the system-prompt/tool-instruction block a given client should receive, useful when adding support for an editor setup doesn’t know yet, or to inspect exactly what guidance LeanCTX injects. --client <id> selects the target (see --list-clients); --profile and --crp off|compact|tdd tune the tool surface and output style; --unified emits one combined block; --json adds metadata and, with --include-rules, the rules-file contents. Output is deterministic for the same inputs, which is what lets the docs-drift CI gate diff it reliably.

lean-ctx hook <rewrite|redirect|observe|copilot|codex-pretooluse|codex-session-start|rewrite-inline>

hook exposes the agent hook entry points that editors call automatically (Cursor/Claude/Copilot/Codex). They are invoked by the editor’s hook mechanism, not typed manually, listed here so the integration surface is fully accounted for.

Where the neighbouring topics live

Topic	Journey
Context profiles & tool profiles	Customization & Governance
Several agents on one project	Multi-Agent Collaboration
Writing your own plugins / WASM	Extend Without Forking
Team server & self-hosting	Team, Cloud & Self-Hosting
Unlimited MCP servers, flat cost	MCP Tool-Catalog Gateway