Integrates with Ollama to run local text and vision models for analyzing files, suggesting names, and categorizing them into folders, all offline.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tidy clean up my Downloads folder — show me the plan before moving anything"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your Downloads folder, cleaned by a local AI. Private. Undoable.
Point tidy at a messy folder. A local model looks at every file, gives it a real name and sorts it into folders. Nothing leaves your machine, and every run can be undone.
🚧 Early release. Feedback welcome.
IMG_2931.png → Receipts/2026-06-12_Amazon_receipt.png
Screenshot 11.04.12.png → Screenshots/Code/python_KeyError_traceback.png
final_v3_real.pdf → Documents/Housing/Lease_Agreement_Bangalore_2025.pdf
IMG_2931 (1).png → _tidy_trash/ (duplicate)
Docker.dmg → _tidy_trash/ (installer older than 30 days)scan → plan (dry run) → preview → apply → undoRuns on Ollama, fully offline
Never deletes anything. Duplicates and old installers go to _tidy_trash/
Every applied plan can be undone
Only touches the top level of the folder you give it. Hidden files and symlinks are skipped
Works as a CLI (tidy) and as an MCP server for Claude, Cursor and other clients
Related MCP server: mcp-document-intelligence
Install Ollama and pull the models:
ollama pull qwen2.5:7b
ollama pull qwen2.5vl:7bInstall tidy (needs Python 3.12+):
uv tool install tidy-mcp # or: pipx install tidy-mcptidy plan ~/Downloads # dry run: shows every change, moves nothing
tidy apply last # asks before moving (or pass a plan ID)
tidy undo last # puts everything back
tidy dupes ~/Downloads # list duplicate filesAdd tidy to your MCP client. For Claude Desktop, edit claude_desktop_config.json:
{
"mcpServers": {
"tidy": {
"command": "uvx",
"args": ["tidy-mcp"]
}
}
}For Claude Code:
claude mcp add tidy -- uvx tidy-mcpFor Cursor, add the same command and args under mcpServers in ~/.cursor/mcp.json.
Then ask: "Tidy my Downloads folder." The assistant shows the plan and only applies it after you agree.
Tool | What it does |
| List the files tidy would look at |
| Suggested name and folder for one file |
| Build a dry-run plan |
| Apply an approved plan |
| Reverse an applied plan |
| Groups of identical files |
Optional. Create ~/.tidy/config.toml:
text_model = "qwen2.5:7b"
vision_model = "qwen2.5vl:7b"
limit = 500 # max files per run
ignore = ["*.part", "keep-*"] # file name patterns to leave alone
[[rules]] # send matching files to a fixed folder
match = "invoice"
folder = "~/Finance/Invoices"workers (default 4) sets how many files are described at once. Answers are cached, so re-running on the same files is instant.
Any setting can also come from an environment variable such as TIDY_TEXT_MODEL. Plans and undo logs live in ~/.tidy (or $TIDY_HOME).
uv sync
uv run python scripts/make_fixtures.py # builds a fake messy folder
uv run pytest # includes property-based safety tests
uv run python scripts/eval_quality.py # scores naming on 30 varied files (needs Ollama)Current score with qwen2.5:7b + qwen2.5vl:7b: 29/30 folders correct, 30/30 names contain the key words.
Issues labeled good first issue are a good place to start. See CONTRIBUTING.md.
Move the Unreleased notes in CHANGELOG.md under a new version heading.
uv version --bump minor (or patch / major) and commit.
git tag v$(uv version --short) && git push --tags
The Release workflow tests, builds, publishes to PyPI and creates the GitHub release.
MIT
Apply a plan the user has approved. Files are moved, never deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
| moves | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, and the description usefully explains the mutation semantics that justify that profile: 'Files are moved, never deleted.' That tells the agent the operation relocates rather than removes data, which is meaningful context beyond the hints. It still omits idempotency and partial-failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the action and the key safety guarantee front-loaded. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema and annotations exist, so return values and safety profile are covered. For a mutating one-parameter tool, though, it neglects idempotency, error/partial-application behavior, and the undo sibling that governs recovery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A single plan_id parameter with 0% schema description coverage, so the description carries the burden. It implies the plan came from user approval but never says where plan_id originates (presumably a plan_tidy result) or its format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (apply) plus resource (plan), and the qualifier 'the user has approved' scopes it to a post-review stage. It implicitly separates this from plan_tidy (which produces the plan), though it never names that sibling directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a plan the user has approved' implies a prerequisite step and ordering, which is real if implicit guidance. It never states when not to use it, nor points to undo as the reversal path when the result is unwanted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the local model for a better name and folder for one file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| name | Yes | New file name without extension, e.g. 2026-06-12_Amazon_receipt |
| summary | Yes | One short sentence about the file |
| category | Yes | Folder to put it in, e.g. Receipts or Screenshots/Code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the valuable detail that a local model is invoked (implying latency and non-deterministic output), but it does not clarify that the result is only a suggestion and that nothing is renamed or moved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; every word contributes to the meaning and nothing is repeated from structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the tool is low complexity with one parameter. However, in a workflow with siblings like plan_tidy, apply_plan and undo, the definition omits where this step fits and that its output is advisory rather than applied, leaving the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single 'path' property has no description, so the description must carry the load. 'One file' does imply the path points to a single file rather than a directory, but it adds no format, relative-vs-absolute, or error semantics beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (ask the local model) and a specific output (a better name and folder) scoped to 'one file', which an agent can distinguish from folder-level siblings like scan_folder and plan_tidy. It is clear but never explicitly contrasts itself with those siblings or explains how its per-file suggestion relates to plan_tidy/apply_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus scan_folder or plan_tidy, nor any mention of prerequisites or ordering within the tidy workflow. The only hint is the phrase 'one file', which implies per-file scope but leaves the agent to infer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Groups of identical files. The first in each group is the original and is kept.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| groups | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral convention: files within each group are ordered such that the first is the 'original' kept by downstream steps. However, it leaves other behavior (ordering of groups, how identity is determined, whether it recurses) unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the key grouping convention is front-loaded. It is efficient, though arguably undersized given how much is left unspecified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, but for a tool with an undocumented required parameter and no usage guidance, the description is too thin. It omits the scan scope, recursion behavior, and how it fits with plan_tidy/apply_plan.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single required parameter 'path' is completely undocumented in both schema and description. The description does not say what the path points to (root folder to scan?), whether it recurses, or what format it takes, so it fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (groups of identical files) but uses a noun phrase with no verb, so the action is only inferable from the tool name. It does add one meaningful semantic detail (the first file in each group is treated as the original), which distinguishes it somewhat, but there is no differentiation from siblings like scan_folder or plan_tidy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool versus scan_folder, plan_tidy, or apply_plan, and no statement of prerequisites or typical workflow position. The agent must guess that this is a read step feeding into plan_tidy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a dry-run plan for a folder. Nothing is moved. Show the plan to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| root | Yes | |
| moves | No | |
| created | Yes | |
| extra_roots | No | Folders outside root that config rules may move files into |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false and openWorldHint=false, and the description usefully reinforces this with 'Nothing is moved.' telling the agent the call is a safe dry run. It adds no information about whether a plan artifact is persisted or how long a plan stays valid, which is the remaining behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and followed by the safety and UX constraints. Nothing is padded, though the final directive is terse enough that it reads as a fragment rather than a complete instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the tool is structurally simple with one required parameter. The unresolved gap is the unexplained 'limit' parameter and the absence of any note on plan persistence or how the plan connects to apply_plan, leaving the workflow slightly under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions 'path' or 'limit'. The one required parameter and the pagination default are left entirely for the agent to infer from bare titles, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource (build a dry-run plan for a folder) and clarifies scope with 'Nothing is moved', which implicitly separates it from apply_plan. It never names the sibling explicitly, so an agent must infer the planning-vs-execution distinction rather than being routed to it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Build a dry-run plan' and 'Show the plan to the user' imply this is the pre-execution step and that the plan should be surfaced rather than acted on. However, it never states when to prefer this over apply_plan or what must happen between planning and applying, so usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the files tidy would look at in a folder (top level only, no hidden files).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| files | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds genuinely non-obvious behavior: only top-level entries are returned and hidden files are excluded, which is tidy's own filtering rule. It still omits anything about the 500-item cap or what happens when a folder exceeds it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the scope constraint front-loaded in the parenthetical, zero filler and no redundancy with the title or schema. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description covers the filtering scope adequately. However, for a scan-like tool it leaves the limit/pagination behavior and the relationship to plan_tidy unaddressed, so it is only minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description explains neither parameter. 'path' is only obliquely implied by 'folder,' and the 'limit' parameter (default 500), which materially changes results, is never mentioned. With two undocumented parameters, the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb (list) and resource (files in a folder) plus the exact scope tidy applies, which is specific enough for an agent to recognize it without opening the schema. It does not name or contrast itself with siblings like describe_file or find_duplicates, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the phrase 'files tidy would look at' suggests this is a reconnaissance step preceding plan_tidy, but the description never says when to call it, when not to, or which sibling handles the alternative (e.g., finding duplicates or describing a single file). An agent must infer the workflow position.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put every file from an applied plan back where it was.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes |
| Name | Required | Description |
|---|---|---|
| moves | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is partly covered. The description adds the meaningful behavioral fact that it restores every file, but omits failure modes (partial undo, files changed since apply, conflicts) that matter for a mutating file operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, and the scope qualifier ('from an applied plan') is placed where it matters. Nothing is padded or restated from the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and annotations cover the safety flags. Still, for a mutating undo operation the description is thin: it does not indicate whether the undo is all-or-nothing, what happens on partial failure, or whether it can be re-applied afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter with 0% schema description coverage, so the description must carry the burden. 'Applied plan' does clarify that plan_id must reference a plan that has already been applied, which is real added meaning, but format, source of the id, and validation are still unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete action (put files back) and its scope (every file from an applied plan), which clearly pairs it with the sibling apply_plan as its inverse. It stops short of naming apply_plan explicitly, but the phrase 'applied plan' makes the pairing inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from an applied plan' implies the tool is used after apply_plan has run, which is useful context. However, it gives no explicit when-to-use/when-not guidance, no mention of what to do if the plan was never applied or was already undone, and does not contrast with siblings like plan_tidy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0apply_plandescribe_filefind_duplicatesplan_tidyscan_folderundoScored across 6 tools
Each tool targets a distinct granularity and action: scan_folder (inventory), describe_file (single-file suggestion), plan_tidy (folder dry-run), apply_plan (execution), undo (reversal), find_duplicates (dedup). No two tools could plausibly be swapped for the same task.
Five of six tools follow a clean verb_noun pattern (scan_folder, describe_file, plan_tidy, apply_plan, find_duplicates). The lone outlier is 'undo', which breaks the pattern but is a universally understood primitive verb.
Six tools is well-scoped for a file-tidying assistant: one inventory, one per-file helper, one planning step, one apply step, one undo, and dedup detection. Each earns its place with no filler.
The surface covers the full safe lifecycle (scan, plan, apply, undo) plus duplicate handling, which is strong for the domain. Minor gaps remain: no way to list past plans or selectively roll back a single file, and no configuration of naming rules.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.