The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Sift listing page.
Runs your command, then gives the model only the lines that matter.
A test suite prints 4,000 lines and eleven of them are the failure. A build prints a progress bar that redraws 900 times. An install lists every package it touched. All of it lands in the context window, and — this is the part that costs — it is re-sent in full on every turn that follows.
sift is an MCP server and a command line for that problem. It runs the command
itself, keeps every byte on disk, and hands the model a view: the failures, the
summary, the lines a reader would actually stop on. The rest is marked, not
deleted.
Two numbers, both measured, both reproducible from this repository. Running this
project's own test suite prints 652 lines — 21,392 tokens, as the model's own
tokenizer counts them. What comes back is 8 lines and 208 tokens: 99% fewer
(python test/kazanc.py). Removing almost everything is the easy half. Over a
22-sample corpus of real build and test output, the default budget keeps 138
of the 140 lines a reader could not do without (python test/budget.py).
A file you did not produce — a log, a saved CI transcript, a crash dump — gets the same treatment without being run:
A list is not read in lines. A JSON array written for a machine often has no newlines at all, and there is nothing in a line of one worth choosing, so the record becomes the unit and the same rules hold:
The same question, asked about source code instead, is a table of contents:
And a command that does not end — a dev server, a log tail, a build you want to keep working during — is started and then read a slice at a time:
Nothing is shown twice, and the numbers are the run's own: line 247 stays line
247 in sift peek for as long as the capture exists.
A free model does. sift sends it the numbered lines and asks one question:
which numbers matter? It answers with numbers, and nothing else it says is
used — the text you read above is printed from the local capture, byte for byte.
That is the whole trick, and it is why this is not a summariser. A summariser
can be wrong about what a line said. sift cannot be: it never writes a line,
it only chooses one.
It also means language coverage is not a list. A model reads Turkish, Japanese, Arabic and Hindi; it reads Rust, COBOL, Mojo and a language released last week. Nothing here enumerates them, so nothing here can be missing one.
Nothing shown is invented. The judge returns line numbers. Text always comes from the local file.
Nothing is thrown away. sift peek <handle> returns the raw capture,
unchanged. Every gap in a view says how many lines it covers.
Nothing can break your command. No API key, no network, an overloaded endpoint, a nonsense reply, a bug in the distiller, or a decision that nothing may leave this machine — every one of these falls back to rules that need none of them. The command still runs; you still get its output; you get its exit code.
One thing: the text of a question. Before it is sent, anything credential-shaped is replaced — tokens with a known prefix, JWTs, authorization headers, passwords in connection strings, the body of a PEM block.
That costs you nothing to read. The model is only ever asked for line numbers, and the lines are printed from your own file, so a line masked on the way out is still shown to you in full.
Three switches:
Masking is not complete and does not claim to be: a bare secret shaped like
nothing in particular gets through. SIFT_NO_MODEL is the one that guarantees.
The fourth is a measured trade and is off by default. Asked which lines matter
in a 404-line build, the model writes about 900 tokens of reasoning to produce a
twelve-token answer, and you wait 15 seconds for it. At SIFT_EFFORT=low the
same question takes 2.4 seconds — and over the corpus it loses 7.8% of the lines
a reader could not do without, in exactly the places this tool exists for: a
mainframe job's return code, a crash loop's diagnosis. Speed is available; it is
not the default, and the price is written down.
The third is about not paying twice. An answer already given for exactly these
bytes and exactly this question is used again instead of bought again — and what
is kept is the numbers, never the view, so the text is still rendered from your
own file and the gap still names your own capture. A view that cost no request
says (remembered) where it would otherwise name the model.
Captured bytes never leave $SIFT_HOME (~/.cache/sift by default). Nothing is
uploaded, nothing is logged elsewhere, and removing a capture directory removes
everything that was ever kept about it.
One capture keeps at most a gigabyte. That is far past any real build log and
a few seconds of a command stuck in a loop, which is the case it exists for:
nothing is thrown away, and the disk somebody else needs is not filled either.
Reading never stops — a pipe nobody drains would stop the command, and that is
the one thing this will not do — so the command finishes, its exit code is its
own, and the footer says kept the first 1,073,741,824 bytes of it rather than
letting you believe you have the whole run. SIFT_MAX_CAPTURE=0 turns the
ceiling off for anyone who would rather have the disk.
They also never go away on their own. Nothing here sweeps, expires or tidies in
the background: sift gc [DAYS] is the only thing that deletes a capture, and
it deletes when you type it and not before. What it leaves is one line per
handle — when it went and how big it was, never the command — so that a gap
marker read a fortnight later gets "removed on the 8th" instead of the answer
it would give for a handle you made up.
A path of - reads standard input, which is the other way somebody else's
output turns up:
What arrives on a pipe has no path anybody could type again, so it is kept as a capture of its own and the gap marker names that instead. The second rule is why: a view that left lines out and pointed at a scratch file would be pointing at nothing by the time somebody read it.
Several paths given to digest are asked about at the same time, and --all
follows every running command in one go. Both are the same idea: the waiting is
the cost, so do it once. --wait N holds until a run actually says something
instead of answering that nothing has happened yet.
sift hook is the way to catch the shell commands a client runs on its own,
without a proxy: point the client's pre-tool hook at it and every shell command
comes here first. Everything is routed — nothing here guesses which commands
are worth catching, because a list of those is a list of tools in disguise and
how much a command prints is not knowable before it runs. Routing everything
costs nothing: a view of twelve lines is twelve lines. It fails open, so a bug
in it leaves your shell exactly as it was, and SIFT_HOOK=0 switches it off.
It is the part of this that pays most and the only part you have to turn on, so it offers itself rather than waiting to be found:
It writes one line into your client's settings, keeps a copy of the file as it
was, and touches nothing else that is in there. sift run mentions it once,
ever, and then stops.
sift tool runs one of three programs that answer a question without opening
the file — sg (ast-grep) for structural search, diff (difftastic) for a diff
that can tell a reindent from a change, loc (scc) for the size of a tree. Their
output is large by nature, which is exactly why they belong here. No binaries
ship with this package: sift tools says which of them this machine has and
what each is called, and installing one stays your decision.
sift memory asks no model at all. The question is counting — how often, how it
went, which command has never once worked here — and a model asked to count is
slower, costs a request and is sometimes wrong. The model decides what cannot be
computed, and nothing else.
sift stats says what the shortening saved and what it cost, and keeps those
apart because they are not the same kind of number. The share is this tool's own
arithmetic over bytes it holds, so it is exact. The cost is the endpoint's count
of its own tokens, so it is measured. And beside it now sits the number the
question is really about — what the output weighed, counted by the same
tokenizer at the moment it was sent:
That last line is a little more than the capture alone, because the lines went out numbered with a question in front of them, and it says so rather than subtracting a guess. It also lets the report be unflattering: on a small command the asking costs more than the output ever weighed, and this is where you would see that. A run the endpoint did not count is a dash, left out of both totals rather than filled in with bytes divided by four.
--keep PATTERN shows every line matching it whatever else was chosen and
whatever the budget says. It is your pattern, not one this tool guessed at —
the only place a pattern decides anything here, and it decides nothing until
you type it. --budget LINES is the ceiling for one view.
The same answers are available over MCP, and that is where they pay most: a tool result is re-sent on every turn that follows it, so a build log kept out of a transcript goes on staying out of it.
The key is read from ~/.config/nvidia/api_key, so it does not have to be in
the environment and does not have to be pasted anywhere. --scope user puts the
server in every project rather than the one you happen to be in.
Then restart the client. MCP servers are connected when a session starts, so the session you ran that command in will not see this one.
Without a key the server starts and every tool that would need a model declines with an explanation, so the agent falls back to its own shell rather than being handed a worse answer it cannot tell apart from a good one.
Any client that speaks stdio will do. The command is sift-mcp, and sift mcp
starts the same server — one word for a client that would rather run the package
by its own name (uvx --from "sift-cli[mcp]" sift-cli mcp, which is what the MCP
registry entry says). It offers
run, follow, outline, digest, digest_many, tool and peek. list
and stats are deliberately not offered: they would hand a model every command lately run on this machine,
including the ones it never asked about, and the person at a terminal already
has that access while a model connecting over a socket does not.
Because a client never sees stderr, the last line of every result says what you are looking at: which handle, how the command ended, and whether a model chose the lines or none could be reached.
pipx install does the same thing. Either puts sift and sift-mcp on your
PATH in an environment of their own, which is what you want for a command-line
tool: nothing here belongs in the Python you build with.
Plain pip install sift-cli works inside a virtualenv you have already
activated. It does not work against the system Python on Debian, Ubuntu, or
WSL — those ship a EXTERNALLY-MANAGED marker and pip refuses, by design:
That refusal is right and the answer is not --break-system-packages. Use uv tool or pipx.
The package is sift-cli and the commands are sift and sift-mcp. The names
differ because sift-mcp on PyPI belongs to somebody else's project — an
unrelated MCP server about authorising agent actions. Nothing here is theirs and
nothing there is this.
Python 3.12 or newer, and no dependencies for the command line.
sift asks a model which lines matter. There are two ways to give it one and
you need exactly one of them.
Not shipped, and not shareable. The key has to be yours. It is free, and it takes a minute:
sift looks:Point sift somewhere and it asks there instead. Nothing about the question
changes; the endpoint is asked the ordinary OpenAI-shaped way, and no
Authorization header is sent when there is no key to put in it.
The same two lines fit llama.cpp (--api), vLLM, LM Studio, LocalAI, a company
gateway, or any other endpoint that speaks POST /v1/chat/completions.
SIFT_MODELS takes a comma-separated ladder and is asked in order.
An address you typed is treated as a decision: nothing warns you about a missing key, and the MCP server does not decline. What that endpoint wants for credentials is between you and it.
No model is named above on purpose. Tested here as a shape rather than as a list: the suite proves that an endpoint of your own is asked, and asked without a key. Which local model answers well has not been measured here, and naming one would be a recommendation nobody earned — the corpus in
test/budget.pyis how you settle it for yours, on the output you actually run.
The two callers are answered differently, on purpose:
If you want to run without a model, say so with SIFT_NO_MODEL=1. That is a
decision rather than an oversight, everything works, and nothing lectures you.
CONTRIBUTING.md is the map: two languages on purpose, three rules that do not
bend, and a mutation for every rule. SECURITY.md says what runs, what leaves
the machine, and where to send a finding privately.
Twenty-four phases, each one closed before the next began, each with a note in
notlar/ saying what was decided and what it cost. notlar/00-PLAN.md is the
arc, including the things that were deliberately not built and why.
The tests are in test/. Beside them is test/mutations.py, which breaks each
rule the code follows — 162 of them, one at a time — and checks that the suite
notices. A green suite says the tests did not object to this version of the
code, not that they would object to a worse one.
It also says what happens when that battery is interrupted, because it was: a
break left on disk survived every ordinary test run and took the machine down
six times before anybody looked. test/conftest.py repairs one now, and the
rule it was breaking is kept twice over, so that no single edit anywhere can
turn sift stop into a signal to everything you own. That is notlar/19.
MIT.