# cursor-eff

Token-efficiency toolkit for Cursor: a local MCP server + steering rules that cut how much context Cursor's agent burns, regardless of which model you use.

## Why

On a Cursor subscription, quota drains through three habits: the agent reading whole files to find things, re-exploring the repo every chat, and long conversations re-sending their entire history each turn. cursor-eff attacks all three at the source by giving the agent cheaper primitives and rules that make it prefer them.

## What the agent gets

| Tool | Replaces | Typical saving |
|---|---|---|
| `search_code` | reading whole files to find something | ~10–50x |
| `outline_file` | full file reads for orientation | ~10x |
| `read_snippet` | full file reads for a known region | proportional |
| `project_map` | recursive directory exploration, re-done every chat | cached, 10 min TTL |
| `handoff` | continuing a bloated 100-message chat | fresh chat seeded with ~1 page |

Plus a rules file (`.cursor/rules/efficiency.mdc`) that steers the agent to use them, avoid re-reads, stay terse, and suggest fresh chats.

## Setup

Requires Node.js 18+. Works on Windows, macOS, and Linux (ripgrep binaries ship with the install).

**From npm (once published):**

```bash
npm install -g cursor-eff
cursor-eff register        # once — adds the MCP server to ~/.cursor/mcp.json
cursor-eff init <project>  # per project — installs rules + .cursorignore entries
```

**From source:**

```bash
git clone https://github.com/aclermont318-sys/cursor-eff.git && cd cursor-eff
npm install && npm run build
node dist/cli.js register
node dist/cli.js init <project>
```

Restart Cursor afterwards. Verify under **Settings → MCP** that `cursor-eff` shows 5 tools.

`init` never overwrites an existing `efficiency.mdc` (so your project-specific edits survive); pass `--force` to reset it to the stock template.

## Daily use

Nothing changes — the agent uses the tools on its own. Two habits multiply the savings:

- When the agent says "state saved, start a fresh chat", do it: open a new chat and say *"read .cursor/handoffs/latest.md and continue"*.
- Keep one chat per task, not one chat per day.

## Development

```bash
npm run build   # compile
npm run smoke   # end-to-end MCP stdio test (10 checks)
```

## Limits (by design)

Cursor's prompt pipeline is closed — this tool cannot rewrite what Cursor sends for its subscription models. It reduces what the agent *asks for*, which is where most waste is. Savings depend on the model following the rules; frontier models follow tool-preference rules well.