# Cane

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

Cane is a local [MCP](https://modelcontextprotocol.io) 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. |

> **Tested off-substrate.** Cane's payload was run past a non-Claude model (GPT-4o) against a Claude (Opus) baseline across 8 real file families. The payload proved legible — the generic model grasped what Cane was for and produced verdicts unaided — but without the creed it pruned more aggressively than is safe. Paired with Cane's shipped `cane://creed`, its recycle calls converged with Claude's. That's the design, not a patch: the evidence informs, the creed governs, which is why they ship together.

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

```json
{
  "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 — and spends the context window doing it. Cane runs the deterministic reduction *before* the handoff, so the agent spends its context reasoning about the evidence instead of ingesting the pile.

## 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.

## Attribution & Licensing

Cane is open-source under the **MIT License** — © 2026 Indifferencer LLC. The license permits broad modification and commercial use.

Cane was built to support human creators. If you build on it, integrate it into a commercial agent platform, or use it to scaffold your own operations, engineering attribution is requested (though never required). Please cite it as:

> **Cane MCP Server** — © 2026 Indifferencer LLC. An open-source, diagnose-only MCP server for reconciling near-duplicate files. https://github.com/kellyorkin/cane-mcp

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