light-tools replaces the file and shell tools your AI coding agent ships with. One Go binary, speaks MCP over stdio, no daemon and no database. Read less, write less, waste fewer turns.
An MCP server that replaces your agent’s file and shell tools.
light-tools is an open-source MCP server that replaces the built-in file and shell tools used by
AI coding agents with versions designed for token efficiency. It ships as a single Go binary,
speaks the Model Context Protocol over stdio, and needs no daemon or database. It provides five
tools: light_file, light_bash, light_ssh,
light_scp and light_ops.
Anyone paying for context their agent didn’t need.
Anyone running an MCP-capable coding agent — Claude Code, Antigravity, or any client that
can start a stdio MCP server — who is paying for context they did not need. It is most
useful on large repositories, long sessions, and noisy build or test output. Install it with
npm install --global @factor-i-o/light-tools.
Not a code-search replacement, and not a sandbox.
light-tools is not a replacement for code search, indexing, language servers or repository intelligence — keep whichever code-intelligence layer you already use. It solves a different part of the problem: how the agent reads, writes and operates on the machine after it already knows what it wants to do. It is also not a shell sandbox; see Safety before treating its confinement as a security boundary.
Ask for parts of many files in one call.
When an agent needs code from several files, light-tools lets it request the relevant parts of all of them in a single tool call instead of fetching them one at a time. That removes tool round trips and puts the related code in front of the model together. Large files are paged rather than dumped, and the agent receives an exact continuation cursor when more content exists.
Send the new code, not the old code too.
Many old/new replacement tools make the model emit both the code being replaced and its replacement. light-tools can edit by span instead: point at the lines or symbol to change and send only the new content. When the old and new blocks are about the same size, that roughly halves the edit payload — on output tokens, usually the more expensive side of model usage.
Re-reading an unchanged file costs nothing.
If the agent re-reads a file whose content has not changed, light-tools returns a short dedup notice instead of pushing identical bytes back into context. If the file did change, it is sent normally.
Build noise stays out of the context window.
Builds, tests and logs can produce thousands of lines. light-tools keeps the useful part inline and spills oversized output to an indexed file that stays searchable and addressable by line range. The goal is not to hide information — it is to stop paying the context cost before the agent knows whether it needs that information.
| Tool | What it does |
|---|---|
light_file | Read, search, inspect symbols and edit files without unnecessary full-file traffic |
light_bash | Run local commands with bounded, searchable output |
light_ssh | Run commands on a remote host through a named profile |
light_scp | Copy files to or from a remote host through a named profile |
light_ops | Read-only service, port and log inspection |
Any tool can be withheld entirely. A disabled tool is not registered, so the model cannot call it:
light-tools --disable-tool light_ssh --disable-tool light_scpFrom npm, which requires Node 18.17 or later and npm 10 or later:
npm install --global @factor-i-o/light-toolsOr build it directly from source:
go install -tags treesitter github.com/icediceice/light-tools/cmd/light-tools@latestChecksum-verifying installers are also published with each GitHub release:
curl -fsSL https://raw.githubusercontent.com/icediceice/light-tools/main/install.sh | shFor a known client:
light-tools init --client claude
--client antigravity is also supported, and --client print emits the MCP
configuration without changing anything, for any other MCP-capable agent. Then restart the coding
agent — light-tools is a stdio server, so the client starts it with the session and there is no
background daemon to manage.
84% less of the corpus reached model context.
Across 319K tool calls in the broader Light stack's telemetry, 2,190.9M tokens were considered and 345.0M delivered — about 84% less of the considered corpus reaching model context in that dataset, measured with partial instrumentation (corpus size on 36.8% of calls, delivered size on 15.2%, with uninstrumented stages falling back to the previous measured point) and published deliberately as a lower bound.
That is a lower bound, not a per-call rate.
That is a Light-stack measurement of the same targeting and output-reduction primitive that light-tools uses — it is not a claim that every individual light-tools call saves 84%. Other aggregate figures from that same 319K-call dataset carry the same partial-instrumentation limits and are lower bounds too: 37.0M tokens in, 6.7 GB of exec bytes saved, a 12.0× raw-to-compacted ratio, and 3.2s average latency across all tools.
A separate 45-call local sample, not a benchmark.
Separately, a local measurement over 45 tool calls in three throwaway sessions on the light-tools repository itself recorded 12,194 tokens saved by terse output, 164,087 bytes by read dedup, and 116,363 bytes by span writes rather than full rewrites — a small sample, not a benchmark and not an extrapolated rate.
Mistakes are made cheap; dangerous ones are refused.
Coding agents make ordinary mistakes: wrong field names, misspelled verbs, malformed values, overly broad shell commands. light-tools tries to make those mistakes cheap without silently guessing about dangerous mutations:
allowed_rootsallowed_roots bounds
light_file paths, local SCP endpoints and caller-supplied light_ops paths.
light_bash has its working directory bounded, but the commands it runs can still reach
outside that directory. Read
SECURITY.md
before treating confinement as a security boundary.
| OS | amd64 | arm64 | Symbol extraction |
|---|---|---|---|
| Linux | native | native | tree-sitter |
| macOS | native | native | tree-sitter |
| Windows | native | native | tree-sitter on amd64; no-symbol fallback on arm64 |
Windows arm64 is built without CGo. All five tools still work there; only symbol and outline extraction degrade.
light-tools is an open-source MCP server that replaces the built-in file and shell tools used by AI coding agents with versions designed for token efficiency. It ships as a single Go binary, speaks the Model Context Protocol over stdio, and needs no daemon or database. It provides five tools: light_file, light_bash, light_ssh, light_scp and light_ops.
Yes. Running light-tools init --client claude registers light-tools with Claude Code. An --client antigravity option exists for Antigravity, and light-tools init --client print emits the MCP configuration for any other MCP-capable agent without changing anything. Because light-tools is a stdio server, the client starts it with the session and there is no background daemon to manage.
No. light-tools is explicitly not a replacement for code search, indexing, language servers or repository intelligence, and it is designed to sit alongside whichever code-intelligence layer you already use. light-tools handles a different part of the problem: how the agent reads, writes and operates on the machine after it already knows what it wants to do.
Across 319K tool calls in the broader Light stack's telemetry, 2,190.9M tokens were considered and 345.0M delivered, which is roughly 84% less of the considered corpus reaching model context in that dataset — a lower bound from partial instrumentation, with corpus size measured on 36.8% of calls and delivered size on 15.2%. It is a Light-stack measurement of the same targeting primitive, not a claim that every individual light-tools call saves 84%.
light-tools snapshots every file mutation before it happens so a bad edit can be restored, refuses ambiguous or dangerous mutations rather than guessing, inspects destructive wildcard operations before execution when their surface can be determined safely, and does not register disabled tools at all. Filesystem access can be bounded with allowed_roots. However, confinement is not a shell sandbox: allowed_roots bounds light_file paths, local SCP endpoints and caller-supplied light_ops paths, and while light_bash has its working directory bounded, the commands it runs can still reach outside that directory. Read SECURITY.md before treating confinement as a security boundary.
No. light-tools is a single Go binary that speaks MCP over stdio. The coding agent starts it with the session, so there is no background process, no database and nothing to keep running between sessions.
Install globally from npm with npm install --global @factor-i-o/light-tools, which requires Node 18.17 or later and npm 10 or later. Alternatively build from source with go install -tags treesitter github.com/icediceice/light-tools/cmd/light-tools@latest, or use the checksum-verifying install.sh and install.ps1 scripts published with GitHub releases.
Yes. Passing --disable-tool, for example light-tools --disable-tool light_ssh --disable-tool light_scp, means those tools are never registered, so the model cannot call them at all. This is a registration-time exclusion rather than a runtime permission check.
Nothing. light-tools is free and open source under GPL-3.0-or-later, published by Factor I O Co., Ltd. at github.com/icediceice/light-tools.
Local telemetry is aggregate-only: no paths, arguments, commands, hostnames or usernames are sent anywhere. It can be disabled entirely by setting DO_NOT_TRACK=1 or a non-empty LIGHT_NO_TELEMETRY.
light-tools ships native builds for Linux, macOS and Windows on both amd64 and arm64. Symbol and outline extraction uses tree-sitter everywhere except Windows arm64, which is built without CGo and falls back to a no-symbol mode; all five tools still work there.