GitHub - Tripstack-Corp/spyc: A Rust TUI file commander where the AI agent in the side pane can query the file commander itself

The file commander built for collaborating with your coding agents.

Keyboard-driven · MCP-native · Rust · macOS and Linux

Why spyc?

Put an AI coding agent in your terminal and you get a chat window. You still describe your working tree to it, paste paths back and forth, and lose track of what it's looking at.

spyc runs the agent in a pane beside a keyboard-driven file commander and gives it live, structured access to what you're looking at over a local MCP socket. The agent asks spyc what is the cursor on, what is staged, what is picked — no copy-paste, no path description. Pick three files, ask a question, and it sees your selection. When it names a path in its answer, gf jumps you there.

The file manager is the shared workspace where you and your agents actually work — not a file list bolted onto a chat window.

What it is

A two-pane terminal program. The top pane is a vim-flavoured file commander with git-aware listings; the bottom pane is a child process — Claude Code by default (Codex, Antigravity and zot are first-class too), in practice anything. They share focus through a screen-style ^a chord prefix.

Everything else — vi motions, marks, picks, inventory, pager, shell integration — is what you'd expect from a keyboard-driven file manager. The MCP bridge is what sets spyc apart from Yazi, Broot, or Ranger.

A real session, mid-task: two columns on one worktree (^s n), three agent tabs on the divider each carrying its own activity dot, and the A monitor top-right reporting draws per second, throughput, and every MCP tool the agents have called. Two bands are blurred — the agent's own status line, and one command echo carrying an absolute home path.

The name. Say it "spy-see" — near enough to spicy, which is where the chili comes from. It carries a lineage too: spy and the keyboard-driven file commanders before it, rebuilt from scratch in Rust for the age of coding agents.

_{spyc is an independent project, not affiliated with or endorsed by Side Effects Software Inc. or Anthropic.}

A tour

Read anything, one key

Markdown renders, source arrives syntax-highlighted, a binary falls back to a hex dump — same key every time, no editor, file list still there. Images open as actual pictures on a terminal with a graphics protocol.

Keep a file open beside the list

^s | opens a live preview column on the cursor file; press it on another file to swap, again to close. It re-renders when the file changes on disk, so it doubles as a watch window while something else writes.

Review it where you are

The gutter marks what changed; gd diffs against HEAD, | toggles side-by-side/unified, gb blames. All in-process through gix — spyc never shells out to git.

Script it in Lua

map T lua todos binds a key to a script. This one runs spyc's own gitignore-aware search and picks every file with a TODO left in it. Scripts run off the main thread behind a kill switch; init.lua can register : commands and event hooks too.

See which agent needs you

Each tab carries a live dot — pulsing while the agent works, settling to a hot-red square the moment it blocks — and that transition fires a border pulse and a desktop notification, so you get pulled back from another window. Driven by the agent reporting its own status over MCP, not by scraping the screen.

Install

Pre-built, signed binaries — no Rust toolchain needed:

brew install Tripstack-Corp/tap/spyc          # macOS & Linux
cargo install spyc                            # any platform, with Rust

Debian/Ubuntu users get a signed apt repo, and every release ships verified tarballs. Full install guide — apt, tarballs, terminal, font, clipboard and MCP setup — is in INSTALL.md; building from source and running the rolling CURRENT stream are in BUILD.md.

You'll want a coding agent for the pane (npm install -g @anthropic-ai/claude-code) and a Nerd Font for the powerline status bar — press C inside spyc for a mono fallback if you'd rather not install one.

Your first 5 minutes

spyc            # opens in the current directory
spyc -r         # resume a session (tabs + each agent's conversation)

Move with hjkl, Enter opens, e edits, ? shows the full help overlay. Then try the part that makes spyc spyc, in a git repo:

1. Press t on two or three files to pick them.
2. Press ^\ to open the agent pane — it launches claude by default.
3. Ask: "How do these files interact?" The agent reads your picks over MCP, with no pasting of paths.
4. When it names a file, press gf to jump straight to it.

^a j / ^a k switch focus between the list and the pane.

The MCP bridge

On startup spyc runs a local MCP server and writes the agent's config automatically — no flags, no setup. The agent can then ask spyc:

• What you're looking at — get_spyc_context: cwd, cursor file, picks, inventory, active filter, git branch.
• Where things are — search_paths / search_content (gitignore-aware), plus search_picks and search_inventory for state generic filesystem tools can't see.
• Git and worktrees — status, log and diff in-process, plus worktree create/open/remove without ever shelling out to git worktree.

The handshake has to stay short, so the depth ships as an installable skill:

spyc --install-skill      # → Claude Code, codex, and agy skill dirs

spyc offers a [Y/n] update when its copy moves ahead of yours, never overwrites edits you've made, and is managed in-app with :skill. Multiple spyc instances coexist, one owning MCP for a directory at a time, and enterprise managed-mcp.json policies are respected — see INSTALL.md.

Running multiple agents

Each tab's activity dot answers which one needs me — hot pulse while working, settled square when blocked or done, with a desktop notification on the transition. An advisory scope registry (register_scope / list_scopes / wait_for_scope_clear) keeps parallel agents off each other's files. Sessions auto-save within seconds of any change, so a crash loses almost nothing and spyc -r resumes every tab and conversation. Design: docs/AGENT_ORCHESTRATION.md.

Keybindings

The essentials. Press ? in spyc for the full overlay, or see docs/KEYBINDINGS.md for the complete map.

Configuration

spyc reads .spycrc.toml from ~/.spycrc.toml (user) and ./.spycrc.toml (project), applying changes live. Bootstrap a fully-commented file with every default:

spyc --print-config > ~/.spycrc.toml

Rebind keys, set colors and layout, tune agent notifications, script in Lua. Note that ^a and ^w are reserved as chord prefixes, and a project-local config can't bind executing verbs — full reference, including both rules, in CONFIGURATION.md.

More docs

License

BSD-3-Clause. Logo uses Twemoji pepper artwork (CC-BY 4.0).