Filesystem Agent + Local Ops

What's in this pack

Most "AI on your filesystem" demos look great until you realize the agent is one bad rename away from clobbering a folder you actually cared about. This pack is the safe, opinionated stack for letting an agent do real local-files work — the kind of janitor tasks every developer has on a backlog and never gets to: an unsorted ~/Downloads going back to 2022, four near-duplicate copies of every screenshot, invoices named Scan_001.pdf through Scan_417.pdf, an ~/old-projects/ you keep meaning to archive.

The target user is a developer (not a sysadmin and not an end-user with a GUI mindset): comfortable in a terminal, willing to write a 30-line AGENTS.md, has already touched at least one CLI agent (Claude Code, Codex CLI, Aider, gptme). What they want from this pack is a layered design — a safe API surface for the agent (MCP), human-side tools for verification (ripgrep, fzf, Yazi), guardrails (AGENTS.md, Hooks), and one fallback autonomous agent for scripting (gptme). Nothing here is a magic "AI organizer" app. It's the infrastructure that makes filesystem agents trustworthy enough to let run.

This pack does not include cloud-sync tools (rclone, Syncthing) — that's a separate set of problems. It also doesn't replace the Modern CLI Toolbelt (fd, delta, bat, eza, hyperfine) — install that first; this pack is the agent-augmented layer on top. For agent-as-pair-programmer flow, see Aider Pair Programming Essentials. For terminal workflow patterns, see Terminal-First Workflow with AI.

Install in this order (safe API → human tools → guardrails → autonomous loop)

1. Desktop Commander MCP — Local Terminal + Files — Start here. This is the safe API surface any MCP-aware agent (Claude Code, Codex CLI, Cursor agent mode, Cline, gptme) plugs into to actually touch your filesystem. It exposes a curated set of tools — read file, write file, list directory, run shell, plus PDF/DOCX/Excel text extraction — all behind one audited interface instead of each agent reinventing its own bash wrapper. The win is one place to set permission scopes: you point it at ~/Downloads and ~/projects and the agent literally cannot read ~/.ssh because it's outside the configured roots. If you do nothing else from this pack, do this — it's the difference between "agent with shell access" (terrifying) and "agent with file access scoped to two directories" (a reasonable Tuesday).
2. ripgrep — Recursively Search Directories for a Regex Pattern — The fastest content-search primitive on the planet, period. When you tell the agent "find every PDF that mentions invoice number INV-2024", under the hood it's ripgrep doing the work (or it should be). Install it standalone too — you'll use it directly to verify what the agent claims to have found. rg -l 'INV-2024' ~/Downloads/*.pdf returns the paths in milliseconds; ask the agent for the same list and compare. If the agent's list doesn't match ripgrep's, the agent is hallucinating filenames and you stop the run.
3. fzf — Fuzzy Finder for the Command Line — The interactive counterpart to ripgrep. When the agent has narrowed things to 40 candidate files and you want to spot-check 5, fzf pipes the list and you arrow-key through them with preview. Also load-bearing for the agent indirectly: many shell helpers and Yazi (#4) use fzf under the hood, so installing it once unlocks fuzzy selection across the whole stack. Pair with --preview flags so you see file contents inline before committing to an action.
4. Yazi — Blazing Fast Terminal File Manager — The visual layer. When the agent says "I'll move these 200 files from ~/Downloads/screenshots/ to ~/Pictures/2024/", you open Yazi, navigate to both directories, and watch the move happen in real time. Async preview means a 50MB PDF previews without freezing the UI; image previews work over SSH with sixel/kitty. The mental model: agent does the bulk work, Yazi is your truth-checking window. Don't let an agent do destructive ops without a Yazi pane open somewhere — you want to see things appear and disappear.
5. AGENTS.md — Open Format for Coding Agent Instructions — Repo-root (or ~/.agents.md for personal-files context) Markdown file telling every modern CLI agent the rules. For a filesystem-ops use case the file looks different from a coding repo: "Downloads is the inbox, sort weekly. Pictures/YYYY/MM is the archive structure. NEVER touch ~/Documents/legal/. PDFs older than 1 year go to ~/Archive/PDFs/. Duplicates resolved by largest-file-wins." Codex CLI, Aider, Claude Code, Cursor agent mode, Gemini CLI all read it (most as fallback after their own native config). One source of truth instead of N copies of CLAUDE.md / .cursorrules / .windsurfrules. The single highest-leverage 50 lines of Markdown you can write before turning an agent loose on personal files.
6. Claude Code Hooks — Automate Your AI Workflow — Event-driven guardrails. PreToolUse hook to block writes outside allowlisted directories, PostToolUse hook to log every file the agent touched into a daily file (so you have a rollback trail), Notification hook to ping you on long-running ops. Hook config is just shell commands triggered by events — no plugin system. Even if you're not using Claude Code as your primary agent, the pattern translates: every modern CLI agent has some hook-equivalent (Codex CLI events, Aider commit hooks). Start with one: PreToolUse: Write → fail-if-path-outside-allowlist.sh "$file". That single hook prevents the worst class of accidents.
7. Jina Reader — Convert Any URL into LLM-Ready Markdown — The bridge between local files and remote content. When you want to download a 200-page PDF from a URL and have the agent index it locally, r.jina.ai/<url> gives you clean LLM-ready Markdown in one call — no pdftotext chain to build, no formatting noise. Save the output to a local file, point the agent at the directory, done. Specifically useful for the "organize my Downloads" use case where half the PDFs are scraped manuals/papers that no longer load at their original URL — Jina Reader fetches and converts once, then you have a permanent local Markdown copy the agent can search with ripgrep (#2).
8. gptme — Terminal AI Agent with Tools and MCP — Your scriptable autonomous agent. pipx install gptme, point at any model (Anthropic, OpenAI, local Ollama), and you have an agent that runs shell, edits files, supports MCP servers (including Desktop Commander MCP from #1) — and crucially, supports non-interactive mode for CI/cron scripts. The killer use case here: a weekly cron that runs gptme --non-interactive "sort everything in ~/Downloads older than 7 days into ~/Archive/$(date +%Y-%m)/, organize by file type". The agent runs, the cron logs the output, you review on Sunday morning. Use it when Claude Code/Codex CLI feel too heavy or you need automation in a script that has no interactive terminal.
9. tmux — Terminal Multiplexer for Sessions, Windows, Panes — The workspace that ties everything together. Layout: pane 1 = the agent (Claude Code / gptme), pane 2 = Yazi watching the directory the agent is operating on, pane 3 = a watch ls -la ~/Downloads or inotifywait tail so you see every change, pane 4 = the agent's hook log being tail -f'd. Detach the session over SSH, come back tomorrow, the agent run is either still going or has cleanly stopped. Without tmux you'd be alt-tabbing between four terminal windows and losing track. With tmux, the whole filesystem-agent operation is one named session you can attach/detach.

How they fit together

┌────────────────────────────────────────────────────────────────┐
│  tmux session: "file-ops" (#9)                                  │
│                                                                 │
│  ┌────────────────────────┐  ┌─────────────────────────────┐   │
│  │ pane 1: the agent      │  │ pane 2: Yazi (#4)           │   │
│  │  Claude Code / gptme   │  │   watching ~/Downloads      │   │
│  │  (#8)                  │  │   visual truth-check        │   │
│  │                        │  │                             │   │
│  │  reads AGENTS.md (#5)  │  └─────────────────────────────┘   │
│  │  uses Desktop Commander │                                   │
│  │   MCP (#1) for files   │  ┌─────────────────────────────┐   │
│  │  uses ripgrep (#2)     │  │ pane 3: change tail         │   │
│  │   under the hood       │  │   watch ls / inotifywait    │   │
│  │  uses fzf (#3) for     │  │                             │   │
│  │   user selection       │  └─────────────────────────────┘   │
│  │  Jina Reader (#7) for  │                                   │
│  │   URL → local Markdown │  ┌─────────────────────────────┐   │
│  │                        │  │ pane 4: hook log tail       │   │
│  │  every shell tool call │  │   tail -f ~/.agent-log.md   │   │
│  │  → Hooks (#6) → log    │  │                             │   │
│  └────────────────────────┘  └─────────────────────────────┘   │
└────────────────────────────────────────────────────────────────┘

Load-bearing trio: Desktop Commander MCP + AGENTS.md + Hooks. Without MCP, the agent has raw shell access and you have nothing to scope. Without AGENTS.md, the agent doesn't know your sorting rules and invents new ones every session. Without Hooks, you have no audit trail and no kill switch. Everything else is the operator's quality-of-life layer.

If you have one hour: install Desktop Commander MCP, point it at ~/Downloads and one project directory, write a 30-line ~/.agents.md with your sort rules and three "never touch" paths, add one PreToolUse hook that blocks writes outside the allowlist. That's enough to safely run an agent against your files. The remaining picks are weekend two.

Tradeoffs you'll hit (filesystem agent vs cloud sync vs manual)

• Agent on files vs cloud-sync rules (Hazel / Maid) — Hazel (macOS) and Maid (cross-platform) are rule engines: "if filename matches Scan_*.pdf and older than 30 days, move to ~/Documents/Scans/". They're great for stable rules. Agents win where rules don't work: "sort these 400 mixed downloads using the categories you can infer from filenames and file contents." Rule of thumb: if you can describe the sort in 5 lines of Hazel rules, use Hazel; if you'd need 50 lines and exceptions, use the agent. Both can coexist — Hazel handles the deterministic 80%, the agent handles the messy long tail.
• MCP filesystem vs giving the agent bare shell — Bare shell (Bash tool, bash MCP server, --dangerously-skip-permissions) is faster to set up and capable of anything. Desktop Commander MCP is the constrained-but-audited alternative: scoped roots, structured tool calls, easier to log. The right answer depends on the task — bare shell for one-off creative file gymnastics you'll watch closely; MCP for any recurring or unattended op. Hard rule: never give an agent --dangerously-skip-permissions access to your home directory.
• ripgrep + fzf vs an LLM-based semantic file search — Tools like Personal Knowledge Base RAG embed your files into a vector DB and search by meaning. ripgrep searches by exact regex. For "find the invoice from Acme Corp in March 2024," ripgrep finds it in 200ms and costs nothing; semantic search costs a model call and might miss a typo'd company name. For "find that note where I argued against using Postgres for time-series data," semantic wins. Run both. Ripgrep is the primary; semantic search is the fallback when you don't remember keywords.
• Yazi vs ranger vs nnn vs lf — All four are TUI file managers. Yazi is the youngest, fastest, and has the best async preview (50MB PDFs preview without freezing). Ranger has the largest plugin ecosystem and most mature config. nnn is the most minimal. lf is the middle ground. For agent-watching specifically, Yazi's preview speed matters more than ranger's plugins — you'll be flipping through files fast, you don't want to wait. Switch to ranger if you already know it and don't want to relearn keybinds.
• gptme vs Claude Code for non-interactive ops — Claude Code is excellent interactively, less ergonomic in cron-style scripts. gptme is built for both — same agent loop in interactive REPL or piped from a script. Use Claude Code when you're watching; use gptme when you're not. Both can share the same Desktop Commander MCP and AGENTS.md, so the agent behavior is consistent across modes.

Common pitfalls

• No allowlist = eventually a deleted directory — The classic failure mode is configuring Desktop Commander MCP without scoping roots, or skipping the PreToolUse Hook. The agent will eventually do something surprising — write a file in a place you didn't expect, or rm a directory because it misread your prompt. The allowlist is not optional. Treat "agent has access to entire $HOME" as a config bug to fix, not a state to live in.
• Trusting the agent's own count — Agents will confidently say "I sorted 247 files." Verify with find ~/Archive/2024-01 -type f | wc -l or a quick eza -la | wc -l. The number of times "agent claimed X, reality was X-15 (or X+15)" is non-zero in any extended run. Build verification into the loop: every batch op ends with the agent printing a count and you running the equivalent shell count and comparing.
• Letting an agent run rename without dry-run — Batch renames are the highest-regret class of filesystem op because they're not obviously reversible. Always two-pass: first prompt the agent to print the proposed renames as a mv old new list (no execution), eyeball it, then execute. Many tools (f2, rename, mmv) have a --dry-run flag — instruct the agent in AGENTS.md to use it by default and require explicit confirmation before the real run.
• Dedupe by name vs by content hash — If your dedupe rule is "same filename = same file," you'll merge ~/Downloads/report.pdf and ~/Downloads/january/report.pdf when they're actually different documents. The right rule is content hash (sha256 or BLAKE3). Tools like fclones / czkawka / rmlint do this natively; if you're prompting the agent to dedupe, the prompt must say "hash file contents, not filenames." One sentence in AGENTS.md prevents a lot of pain.
• Archive without verification — "Move everything older than 1 year to ~/Archive/" sounds safe until you realize the archive volume is a network drive that's currently disconnected, or the path doesn't exist and the agent just created ~/Archive as a regular directory. Archive ops should always: (a) verify destination exists and is writable, (b) copy first then delete (never mv across volumes for important files), (c) leave a _INDEX.txt in the archive with the original paths. Bake this into AGENTS.md.
• No diff between "agent will do X" and "agent did X" — Without the hook log tail (pane 4 in the tmux diagram), you have no record of what actually happened. Six months from now when you can't find a file, you want a ~/.agent-log.md you can grep for the filename to see when and why it moved. The cost of the hook is one line; the cost of not having it is a 30-minute git-style archaeology session per missing file. Set it up the day you install Desktop Commander MCP.