# ContextSlim

**Save 50%+ AI context tokens without losing critical code semantics.**

Code: [github.com/lilite572-cyber/context-slim](https://github.com/lilite572-cyber/context-slim) · install: [`@idmxgne/context-slim`](https://www.npmjs.com/package/@idmxgne/context-slim) (npm account `idmxgne`). Not Jagganu’s [`context-slim`](https://www.npmjs.com/package/context-slim) (CLI output trimmer).

Cursor, Claude, and other coding agents re-read whole files on every turn. Most of that budget is JSDoc, unused imports, and DTO mappers. ContextSlim parses JS/TS (Babel) and PHP (php-parser), hollows the noise, and **keeps** try/catch, auth methods, `env()` / `process.env`, and markers like `FIXME` / `SECURITY` / `В ПРОД НЕ ГНАТЬ`.

## Before / after

Measured on the real-world billing controller in `tests/fixtures/real_world_controller.ts` (`--signatures-only`):

| | Tokens | What you keep |
|---|---:|---|
| **Before** | 3,522 | comments, mappers, unused imports, every method body |
| **After** | 1,408 | signatures + critical bodies + protected comments |
| **Savings** | **60%** (10 labels kept) | try/catch, `authorize` / `login`, `FIXME`, `В ПРОД НЕ ГНАТЬ` |

CLI stats use **gpt-tokenizer** (`o200k_base`, GPT-4o / GPT-5 family) and print to **stderr**. Slim source goes to **stdout**.

```bash
npx -y --package=@idmxgne/context-slim context-slim .
# Исходный размер: 3,522 токенов -> Сжатый: 1,408 токенов. Экономия: 60% ...
```

The binary is `context-slim`, not `@idmxgne/context-slim`. Scoped `npx @idmxgne/context-slim .` fails with `command not found`.

## Quick start

```bash
npx -y --package=@idmxgne/context-slim context-slim .
npx -y --package=@idmxgne/context-slim context-slim ./src --signatures-only
npx -y --package=@idmxgne/context-slim context-slim ./src --out slim.txt
npx -y --package=@idmxgne/context-slim context-slim-mcp
```

From a clone:

```bash
npm i && npm run build
node dist/cli.js ./src
```

## MCP server (Cursor, Windsurf, Claude Code)

Bin: `context-slim-mcp` → `dist/mcp.js`. Official `@modelcontextprotocol/sdk` `Server` + `StdioServerTransport`. **Do not write logs to stdout.**

Prompt `use-slim-context`:

> Always prioritize using `read_slim_file` tool when reading source code files to optimize context window.

Tools:

| Tool | Args | Result |
|---|---|---|
| `read_slim_file` | `path` (string), `signaturesOnly` (boolean, default `true`) | compressed source |
| `get_slim_stats` | none | last run: tokens before / after, `%` saved, protected label count |

### Cursor

Merge into `~/.cursor/mcp.json` (ready-made copy: `examples/cursor-mcp.json`):

```json
{
  "mcpServers": {
    "context-slim": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/context-slim/dist/mcp.js"]
    }
  }
}
```

After `npm publish`:

```json
{
  "mcpServers": {
    "context-slim": {
      "command": "npx",
      "args": ["-y", "--package=@idmxgne/context-slim", "context-slim-mcp"]
    }
  }
}
```

Restart Cursor and ask the agent to `read_slim_file` on a fat controller.

### Windsurf

Same `mcpServers` block in Windsurf's MCP config (`~/.codeium/windsurf/mcp_config.json`, or the MCP panel in settings). Point `command` at `node` + `dist/mcp.js`, or at `npx` as above.

### Claude Code / Claude Desktop

**Claude Desktop** — merge `examples/claude_desktop_config.json` into `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "context-slim": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/context-slim/dist/mcp.js"]
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add context-slim -- node /ABSOLUTE/PATH/TO/context-slim/dist/mcp.js
```

## Safe labels (`.contextslimrc` + `isCriticalNode`)

A node is never hollowed when `isCriticalNode` says so:

- comments matching **CRITICAL**, **FIXME**, **TODO**, **SECURITY**, **DONT TOUCH**, **`В ПРОД НЕ ГНАТЬ`**, **`@keep`**
- `try` / `catch`
- methods whose names look like auth (`authorize`, `login`, `jwt`, `csrf`, …)
- `env()`, `getenv()`, `process.env`
- PHP/Laravel: `$this->hasMany` / `$this->belongsTo` (and other Eloquent relations) and `scope*` methods

Repo: https://github.com/lilite572-cyber/context-slim

Put extra phrases in `.contextslimrc` at the project root:

```json
{
  "keep_patterns": ["HACK", "LEGACY"]
}
```

`entry_patterns` (defaults: `index` / `cli` / `main` / `app` / `server`) keep ordinary function bodies even without `--signatures-only`. Dependency files are hollowed; pass `--signatures-only` (or MCP `signaturesOnly: true`) to hollow everything that is not critical.

## Install / publish

```bash
npm i
npm test
npm run build
```

Bins: `context-slim` → `./dist/cli.js`, `context-slim-mcp` → `./dist/mcp.js`. npm: `@idmxgne/context-slim`. GitHub: `lilite572-cyber/context-slim`. License: MIT.

## License

MIT