Cane

A support for thinking in a mess — not a tool for cleaning one up.

Cane is a local MCP server. It hands your AI assistant deterministic evidence about your files — which of your near-identical drafts is current, which lines exist in only one place, what actually changed between two versions — so the assistant can tell you what's safe to recycle by reading the bytes, never by trusting what you named things.

It diagnoses only. It never moves, renames, or deletes. Nothing leaves your machine, there's no account and no service, and there's no API key on Cane's side — your own assistant does the reasoning, on its own model access.

---

What it's for

Most tools that touch a pile of files are there to fix it — dedupers, organizers, "tidy your drive" utilities. They all say the same thing: be more disciplined. Name things consistently. Version them properly. Clean as you go. For a lot of people that advice reads as be less like yourself, and it fails for the same reason every time: the discipline it asks for is exactly the thing that's in short supply.

Cane is the opposite. Cane is the tool that lets the mess happen.

Keep twenty copies. Re-derive the same idea six times. Name them all final. Then point Cane at them and ask which one is the survivor and why the difference matters — and get an evidence-backed answer instead of a lecture.

The name is the whole idea. A cane doesn't cure anything; it bears your weight so you can keep moving. Cane doesn't fix your mess — it gives you the support to make it, because the reconciliation is handled after the fact. It's a support, not a cure.

Why not just diff, dedupe, or version control?

• diff tells you what changed and refuses to say whether it matters.
• Hash-based dedupe happily deletes the wrong copy. (Cane's own test case: the junk-looking …(1).md was the superseding file — naive dedup destroys it.)
• Version control works — and demands upfront discipline, which is precisely the faculty in short supply. It's a solution conditioned on not having the problem.

The missing piece is judgment, not another diff. Cane produces the deterministic evidence; your assistant, guided by a shipped judgment prompt, supplies the judgment. Neither half alone is enough — the evidence keeps the judgment honest, and the judgment is what a raw diff can't give you.

What you get

Three things register with your assistant:

cane_compare(a, b)	Everything measurable about two files: size, modified-time, md5, byte-identical?, a containment read (which file's lines exist nowhere else → keep; which is a full subset of the other → safe to recycle), and a unified diff. The "which of these two is current?" atom.
cane_cluster(folder)	Near-name families in a folder — files that are versions of each other despite different names (draft, final, v2, (1), dates). The "which of my twenty copies?" entry point.
cane://creed (resource)	The judgment law: read content not labels, sole-copy lines are a finding, name the missing fact when the evidence runs out. This is what lets any model reason over the evidence the way the tool's author does.

Install

Cane needs Python 3.10+ and the mcp package (pip install mcp). Then clone this repo:

git clone https://github.com/kellyorkin/cane-mcp.git

Claude Code

claude mcp add --scope user cane -- python /path/to/cane-mcp/server.py

--scope user makes it available in all your projects. Start a fresh session and you'll have the tools. Verify with claude mcp list (look for cane ✔ Connected).

Claude Desktop

Add this to your claude_desktop_config.json, then restart:

{
  "mcpServers": {
    "cane": {
      "command": "python",
      "args": ["/path/to/cane-mcp/server.py"]
    }
  }
}

On Windows, use the full path to your python.exe and double-backslash the paths. If it shows "connection timed out," the usual cause is a wrong Python path — point command at the exact interpreter that has mcp installed.

Then ask your assistant something like: "Use cane to compare these two files and tell me which is current and whether either is safe to recycle," and hand it two paths.

What it will not do (on purpose)

• No writes. It never moves, renames, or deletes. Not in v1, not ever. It proposes; your hand acts.
• No service, no account, no telemetry, no key. It's a local process. Your files never leave your machine except as whatever your assistant already sees.
• No whole-drive crawl. The tools take a bounded target — two files, or one folder. Scope is the feature: an unbounded pile just relocates the overwhelm onto the model. Cane's job is to remove it before the handoff, not move it downstream.

Honest limits

• The judgment holds while the deciding evidence fits Cane's 240-line diff cap; past that, the signal doesn't carry.
• Containment is a text-file signal (it reads lines). Binary files fall back to md5/size. It normalizes line-endings and trailing whitespace — so cosmetic churn matches — but not case or indentation, which stays deliberately conservative toward keeping.
• It reads inside compound documents (.docx/.pptx/.xlsx) as text, but doesn't OCR images.

License

MIT © 2026 Kelly Orkin Brady. Do what you like with it.

Diagnose, don't execute. Support the mess; don't punish it.