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):

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:

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

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.