tidybot CLI
CLI that sorts a messy folder such as Downloads into places with natural-language rules, while an agent judges the files.
- 109 ★ on the repository
- Last commit
Extended access
Why this level
- Moves and renames files after you confirm the plan, and the agent reads file contents.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/tidybotDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Moves and renames files after you confirm the plan, and the agent reads file contents.
This is third-party code. Review the repository files before installing.
What it does
tidybot has no model inside. The agent (Claude Code or any agent that can run commands) decides, while the CLI supplies facts, caches file summaries, turns decisions into a plan and performs moves with undo history. It works through places: destination folders that each carry a rule in plain words. The loop is this. `tidybot summary todo` lists files without a summary, the agent reads them and saves summaries, `tidybot scan --json` returns a compact list with duplicates, and `tidybot propose` builds a plan without moving anything. You edit the plan with `plan show` and `plan set`, then `tidybot apply` moves files, and `tidybot undo --last` brings them back under their original names. For files named like `scan0001.pdf`, the CLI helps pick names from content, and `tidybot find` searches summaries.
Who it is for. People whose downloads or scans folder is buried in files and who will hand sorting to an agent but want to review the plan before any moves.
Good fit when
- A Downloads folder is full of scans, photos and PDFs named with UUIDs.
- An agent prepares a move plan and you review and edit it before running.
- You need content search, such as the 2025 lease.
- You need to read PDF, DOCX, PPTX and XLSX files that `cat` cannot open.
Not a fit when
- You want one-off deletion; tidybot never deletes permanently and sends files to the Trash.
- No agent is available; the CLI makes no decisions without one.
- You need cloud sync or processing outside local folders.
Example request
Sort my ~/Downloads folder with tidybot: summarize files, propose a plan and move nothing until I review it.Limitations
There is no model inside, so sorting quality depends on the agent and the plan it uses. File summaries, especially for images, are prepared by the agent or its subagents on a cheap model, and file contents go to that model. Moves never overwrite existing files, the CLI recovers interrupted moves, and deletion goes to the Trash or to a folder you choose. It reads PDFs with CJK fonts, DOCX, PPTX, XLSX and UTF-16 and Windows-1252 text. For HEIC, WebP and the first pages of PDFs it makes JPEG previews. Node.js is required, and a source build needs pnpm.
How to disable. Remove the package with `npm uninstall -g tidybot`. History and places live in local configuration, which you clear separately.
FAQ
How do I install tidybot?
Run `npm install -g tidybot`. From source: `pnpm install`, `pnpm build` and `pnpm link --global`.
Does the agent move files itself?
No. The agent writes a plan with `tidybot propose`, and only `tidybot apply` performs moves after your review.
How do I put files back?
With `tidybot undo --last`: it returns moved files and restores their original names.
Does tidybot delete files?
Not permanently. Files go to the Trash or to a folder you choose.
How do I find a file later?
With a command like `tidybot find lease 2025`: search runs over saved summaries and keywords.
Discussion
No questions or reviews yet.
Related
CLI toolsorganize is a CLI for Downloads and photo archives, selecting files by document text and EXIF information from photos.
A Rust CLI for macOS that inspects and changes default apps for files and links, with an MCP server and an agent skill
A CLI that builds a local notes index with catalyst questions so the agent finds material faster than plain grep search
tasks-axi gives an agent short commands for a Markdown backlog: add, start, finish, block and find ready work
Set up Claude Code and Codex in one conversation: global instructions, rules, plugins, skills, a status line and correction memory
The CLI repeats a selected command, highlights output changes and retains history for users and agents to compare.
README in short
tidybot sorts files through rule-based places, caches summaries and provides a reviewable plan with undo history.