# Use Gotcontext

> Route large context through gotcontext.ai MCP compression before sending to a model — pre-flight, ingest, skeleton reads, PR diffs, remote docs. Use when about to paste a large file, verbose CLI output, git diff, or remote URL into context. Pair with tg for local code reads. Triggers include "compress this", "shrink context", "gc_pre_flight", "ingest_context", "gotcontext MCP", "token savings".

- Skill: `oimiragieo/use-gotcontext` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/use-gotcontext`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/use-gotcontext/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/use-gotcontext

---


# use-gotcontext

gotcontext-saddle is the **behavior harness**; gotcontext.ai is the **compression
engine**. This skill routes you to the right layer.

## Install (once per machine)

1. **API key** — sign in at [gotcontext.ai/dashboard/settings](https://gotcontext.ai/dashboard/settings),
   create a `gc_`-prefixed key.
2. **Export before every session** (MCP reads the shell, not `.env.local`):
   ```bash
   export GOTCONTEXT_API_KEY="gc_..."
   ```
3. **Wire MCP without replacing existing config** — pick one:
   - Saddle installer (additive merge): `./install.sh claude` (or `codex`, `cursor`, `agy`)
   - Official CLI: `npx --yes gotcontext@1.0.1 wrap claude` (or `codex` / `gemini`)
   Do not copy a template over an existing user configuration.
4. **Restart and verify**:
   - Claude / Codex / Gemini CLI: `npx --yes gotcontext@1.0.1 doctor`
   - Cursor: open **Settings → MCP** and confirm `gotcontext` is enabled
   - agy: run `/mcp` and confirm `gotcontext` is connected
5. **Optional plugin** (outcome-shaped compression skills):
   ```text
   /plugin marketplace add oimiragieo/gotcontext-sdk
   /plugin install gotcontext
   ```
   Plugin skills: `shrink-for-claude`, `pre-flight`, `review-pr-diff`,
   `compress-mcp-manifest`, `ingest-docs`, `batch-compress`, `extract-api-surface`,
   `session-summary`. Read `SETUP.md` in the plugin on first run.

## Routing table

| Task | Tool | Notes |
|------|------|-------|
| Large pasted doc / handoff | `ingest_context` → `read_skeleton` | `profile=core`; give a unique `file_id` |
| Remote URL / docs page | `ingest_context(file_url=…)` → `read_skeleton` | `profile=core`; avoid raw full-page fetches |
| Find a section in ingested doc | `search_semantic` → `modulate_region` | `profile=core`; evidence-aware reads |
| `git diff`, pytest -v, CI logs | `filter_cli_output` | `profile=full`; use when output is genuinely verbose |
| Route a large payload | `gc_pre_flight` or plugin `pre-flight` | `profile=full`, Pro+ |
| PR review / changed symbol context | `gc_blast_radius` or plugin `review-pr-diff` | `profile=full`, Pro+; submit snippets |
| MCP tools/list bloat | `gc_compress_manifest` or plugin `compress-mcp-manifest` | `profile=full`; shrink tool descriptions |
| **Local repo search** | **`tg search PATTERN PATH`** | Scoped; broad scans refused |
| **Local symbol before edit** | **`tg callers PATH SYM`** / **`tg blast-radius`** | Disk primitive |
| Server-side code navigation | `gc_callers`, `gc_blast_radius`, … | `profile=full`, Pro+; submit snippets |

**PreToolUse hooks enforce this** (installed with `./install.sh claude`):
- `Read` ≥20 KB full-file → **blocked** → use MCP, scoped Read, or `tg`
- `WebFetch` → nudge ingest+skeleton
- `Grep` / shell `grep`/`rg` → nudge `tg search`
- `PreCompact` → core compression path; `gc_pre_flight` only when `profile=full` is enabled

Emergency: `export SADDLE_GOTCONTEXT_BYPASS=1`

## MCP profiles

- `?profile=core` (installed default) — compact core compression profile with a
  small tool-list footprint. It does **not** expose `gc_pre_flight` or the
  server-side code-navigation suite.
- `?profile=full` — complete catalog, including Pro+ routing, code navigation,
  security, KB, and batch tools. Your account plan still controls access.

Change the `url` in your MCP config or pass the profile query param.

## When NOT to use

- Secrets, tokens, credentials, raw auth output
- Prompts under ~200 tokens (send them as-is; compression overhead is not worthwhile)
- Already-compact green test output
- Sources you must reproduce character-for-character

## Full discipline write-up

`core/prompts/principles/08-gotcontext-dogfood.md`

## Docs

- [gotcontext.ai/docs#mcp-server](https://gotcontext.ai/docs#mcp-server)
- [gotcontext-sdk plugin](https://github.com/oimiragieo/gotcontext-sdk/tree/main/plugins/gotcontext)