Using siftr from AI agents

Coding agents spend a lot of their tokens finding things: opening files to see if they're the right ones, reading whole files for one function, scrolling through long test output. siftr's four tools do those jobs in a second or two and return only what matters.

The quick way

siftr agents install

finds every supported agent on your machine and adds siftr to its MCP config — Claude Code, Codex, Cursor, Claude Desktop, Gemini CLI, Windsurf, Kiro, opencode, pi and omp. It backs each file up first (<file>.bak-siftr-<timestamp>), keeps your other servers, removes any entry left by siftr's old name (jgrep), and is safe to run again. siftr agents lists what it found; siftr agents remove undoes it.

The agent needs your API key too: run siftr setup once, or set OPENROUTER_API_KEY in the environment the agent starts tools with.

The four tools

MCP tool	What it does	Use it when
semantic_search(query, path?, top?, files_only?, glob?, include_tests?)	Ranked file:line ranges for a plain-words query	the agent doesn't know the names of what it's looking for
focused_read(path, question, max_lines?)	The sections of one file that matter, with real line numbers, plus a map of what was left out	it needs one area of a large file, not all of it
filter_output(path, question)	The blocks of a long text file that matter (experimental)	a log or saved output on disk is too long to read whole
pick_relevant(task, items, top?)	Every item ranked by relevance to a task	it has a long list (tests, docs, tools) and needs the few that matter

Every tool is read-only and returns suggestions. Each description tells the agent to fall back to grep or a full read if nothing fits, rather than concluding something doesn't exist.

filter_output takes a file, not a command. An MCP tool that runs shell commands could skip the approval an agent normally asks for before running one, so for command output the agent pipes through the CLI instead, which goes through its usual shell permissions:

pytest -x 2>&1 | siftr filter "why does test_login fail"

Setting it up by hand

If siftr isn't on the agent's PATH, use the full path to the executable (the output of siftr agents shows it).

Claude Code

claude mcp add -s user siftr -- siftr mcp

Codex CLI — ~/.codex/config.toml

[mcp_servers.siftr]
command = "siftr"
args = ["mcp"]

Cursor, Claude Desktop, Windsurf, Gemini CLI, Kiro

In that client's MCP config (~/.cursor/mcp.json, claude_desktop_config.json, ~/.codeium/windsurf/mcp_config.json, ~/.gemini/settings.json, ~/.kiro/settings/mcp.json):

{ "mcpServers": { "siftr": { "command": "siftr", "args": ["mcp"] } } }

pi and omp — ~/.pi/agent/mcp.json, ~/.omp/agent/mcp.json

{ "mcpServers": { "siftr": { "type": "stdio", "command": "siftr", "args": ["mcp"] } } }

omp also takes "enabled": true.

opencode — ~/.config/opencode/opencode.json

{ "mcp": { "siftr": { "type": "local", "command": ["siftr", "mcp"], "enabled": true } } }

VS Code (Copilot agent mode) — .vscode/mcp.json

{ "servers": { "siftr": { "type": "stdio", "command": "siftr", "args": ["mcp"] } } }

Config locations move between client versions; if one of these doesn't work, check that client's MCP docs. siftr agents snippet <name> prints the right snippet for any agent it knows.

Agents without MCP

Every command has --json:

siftr search --json "where are users charged credits" .
siftr read --json src/billing.py "where is the refund calculated"
git ls-files 'tests/*.py' | siftr pick --json "fix the login redirect bug"

Telling the agent when to use it

Agents use tools they're told about. Add something like this to your CLAUDE.md, AGENTS.md, .cursorrules or system prompt:

## Finding things cheaply (siftr)
- Don't know the names of what you're looking for? Use `semantic_search` before opening files.
- Need one part of a large file? Use `focused_read` instead of reading the whole file.
- Choosing which tests to run or docs to open? Use `pick_relevant` on the list first.
- Use grep / a normal read when you already know the exact string or need the whole file.
These return suggestions: if nothing fits, fall back to grep or a full read.

Cost and privacy

Each call sends file paths, symbol names and relevant snippets to OpenRouter, which routes them to TypeSafe. A search over a few thousand files costs one to two cents; read and pick cost well under a cent. Don't point it at code you can't send to a third-party API.