# FanBox: a local cockpit for Claude Code and Codex sessions

> FanBox is a macOS Electron app that puts a file browser, a real embedded terminal and a live change dashboard in one window. It is for people who run coding agents locally and keep losing track of what those agents touched.

**alchaincyf/fanbox** — vibe coding 的驾驶舱：左边文件，右边/下边终端，中间看清每一次改动。 / The cockpit for vibe coding: browse files on the left, command agents on the right, watch every change in between.

- Repository: https://github.com/alchaincyf/fanbox
- Website: https://github.com/alchaincyf/fanbox/releases/latest
- Stars: 1,018 · Forks: 148
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/alchaincyf-fanbox

## The problem FanBox was built around

The README opens with a complaint rather than a feature list: an AI helps you start ten projects in an afternoon, and then they scatter, the names stop making sense, and you cannot see what changed. The described daily loop is three windows in rotation. Dig through Finder, switch to iTerm to launch an agent, switch to the browser to check the result.

FanBox targets that specific loop. Its stated scope is find, preview, light edits, command the agent. The README is explicit about what it is not: it does not compete with Finder on file operations, and it does not compete with VS Code on editing. If your problem is that a coding agent rewrote eleven files across two directories and you have no idea which ones, that is the problem this app claims to solve. If your problem is that you need a full language server and a debugger, this is the wrong window.

The audience is narrow and identifiable: someone on a Mac who runs Claude Code or Codex locally, often across many small generated projects, and who wants the file view, the terminal and the diff in one place. The README's own framing is local-first, zero config, zero runtime dependencies, with no cloud, no remote and no accounts.

## How the file view, terminal and change dashboard fit together

The layout is the mechanism. Files sit on the left, the terminal sits on the right or the bottom, and preview happens in place. The repository confirms a two-process shape: package.json declares `"main": "electron/main.js"` for the Electron shell and a `bin` entry pointing at `server.js`, with `npm start` running the Node server and `npm run app` launching Electron. The terminal is not a simulation; the build scripts reference `node-pty` and an `electron-rebuild` step for it, which is what a real PTY inside Electron requires.

The change tracking is the part worth understanding before you install. The README describes a live dashboard where every file the agent writes makes its card ripple and glow according to change frequency, so the light follows the agent. Follow mode makes the file view and preview track whatever file the agent is editing, with code scrolling and freshly written lines flashing, HTML rendering live with double buffering, and Markdown rendering as it is written. Any manual browsing hands control back.

The This round panel is the audit surface: which files the agent changed in the round, which terminal and which agent did it, grouped by attribution, with plus and minus line counts per file. Clicking a row opens a side-by-side diff in Monaco. You can restore a single file, roll back the whole round, or scrub a replay timeline at the bottom. Markdown is compared as rendered reader view by default, and images get a before/after slider, which suggests the review target is the artifact and not only the source.

One design decision stands out. Comments written on the diff are pasted into the agent's terminal as `file:lines` plus a fenced code block plus your note, using bracketed paste, without pressing enter. The final submit is yours. That is a deliberate refusal to let the app drive the agent, and it is the right call for an audit tool.

## Installing FanBox and running your first agent session

The README points at the releases page for the dmg, and the platform badge lists macOS on Apple Silicon. Windows appears only as a community port in the badges, not as a supported build in the install path. There is no Homebrew instruction and no npm install instruction in the README, so treat the dmg as the distribution channel.

If you want to run the source instead, package.json gives the entry points. The server runs on its own:

```bash
npm start
```

That executes `node server.js`, the `bin` target named `fanbox`. The Electron shell is a separate script:

```bash
npm run app
```

Because the terminal depends on a native module, a fresh checkout on a new Electron version will need the rebuild step the project ships:

```bash
npm run rebuild
```

That script is `electron-rebuild -f -w node-pty`, and there is a narrower variant, `npm run rebuild:pty`, that rebuilds node-pty directly through node-gyp against the Electron headers. If the embedded terminal fails to spawn after an upgrade, this is the first thing to check.

Once the app is open, the workflow the README describes is: use `⌘K` for global fuzzy search to find the project folder, then `⌘↵` to open that project in your editor if you want a full IDE, or start an agent in the embedded terminal instead. Typing `content:keyword` in the same search box switches to full-text search. Folder cards carry node, web, py, rs or go badges, so a directory of half-finished afternoons is at least sortable at a glance. When the agent starts writing, watch the cards light up, then open This round to see the file list and the diff.

## Where FanBox stops being the right tool

The README's own boundary is the honest one. It does not compete with Finder on file operations, and it does not compete with VS Code on editing. If your day is mostly moving, renaming and bulk-organizing files, or if you need refactoring across a large codebase with a language server, an Electron window with a preview pane is not going to replace your editor.

The second constraint is the platform. The install path is a macOS dmg for Apple Silicon. Windows is labeled a community port in the badge, and the README's install anchor does not document a Windows build. On Linux there is nothing documented at all. The architecture also assumes a native PTY through node-pty, which is the kind of dependency that breaks on Electron upgrades and needs the rebuild scripts above. That is a real maintenance surface, not a theoretical one.

The third constraint is scope of the review model. This round groups changes by terminal and by agent, and rollback works on a single file or on a whole round. The README does not document rollback across multiple rounds, or a way to undo a rollback. If you need version-control-grade history with branches and merges, use git; FanBox sits on top of the working tree, not in place of a VCS.

Finally, the README states no cloud, no remote and no accounts. That is a feature for a local workflow and a hard stop for anyone who needs to share a session with a teammate or review an agent's work from another machine.

## FanBox compared with staying in your editor and terminal

The real alternative is not another agent cockpit. It is the setup most people already have: a terminal multiplexer with an editor beside it, plus git diff for review. That approach wins on maturity. Git has history, branches and a well-understood undo model. A terminal emulator plus VS Code has years of extension support and no native rebuild step.

The difference in approach is what gets surfaced. In the terminal-plus-editor setup, an agent's writes are visible only if you run `git diff` or watch the file tree refresh. FanBox inverts that: the file cards themselves are the status display, and the This round panel aggregates per-round changes with attribution to a specific terminal and agent. That attribution is the genuinely different piece, because a plain diff cannot tell you which of your two running agents wrote a line.

The comment-and-feed-back path is the other divergence. In a normal terminal you copy a line reference by hand and paste it into the agent's prompt. FanBox formats the selection as `file:lines` with a fenced block and pastes it without submitting. Small difference, but it removes the transcription step that usually introduces the wrong line numbers.

Where the alternative wins is durability and portability. Git works everywhere, FanBox is a macOS Electron app with a native terminal dependency. If you already have a review loop that works, FanBox is a convenience layer, not a replacement.

## Maintenance, updates and the MIT licence

The last push to the repository was on 2026-09-03, and the most recent release is v2.16.1 on the same day. The release notes for that version describe fixing a race in the update button introduced in 2.16.0, and 2.16.0 itself added in-app one-click update: download in the background, restart and it is applied. A release shipped to fix a race in the updater from the same day is worth noting if you rely on that path; the fix exists, but the updater is young.

The repository is not archived. The version in package.json is 2.16.1, matching the latest release tag. The build configuration sets `appId` to `com.huashu.fanbox` and `productName` to FanBox, and the distribution script uses electron-builder with a notarization keychain profile, which tells you the macOS builds are signed and notarized rather than ad hoc.

Upgrade cost is mostly the native module. Any Electron version bump can invalidate the compiled node-pty binary, which is why `npm run rebuild` and `npm run rebuild:pty` exist as separate scripts. There are also two vendored bundle steps, `build:milkdown` and `build:hljs`, which esbuild the Markdown editor and the syntax highlighter into `public/vendor/`. If you build from source and change those dependencies, you have to rerun them.

The licence is MIT, stated in the README badge and present as a LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence text retained. It also means no warranty and no support obligation from the author. That is a statement about the licence terms, not legal advice; check your own obligations before shipping a modified build.

## Conclusion

Adopt FanBox if you run Claude Code or Codex on a Mac and regularly lose track of which file an agent just rewrote; the This round panel and the per-file restore are the parts worth trying first. Skip it if you need Windows or Linux support, since the README lists Windows only as a community port, or if you want a full IDE: the project says it does not compete with VS Code on editing. Before you commit, verify that your macOS build is Apple Silicon, that node-pty rebuilds cleanly for your Electron version, and that the in-app updater behaves on your machine, since v2.16.1 exists specifically to fix a race in the update button from 2.16.0.

## FAQ

### What is FanBox used for?

FanBox is described as the cockpit for coding agents: it browses, previews and edits local files on one side while running Claude Code or another coding agent in a real embedded terminal on the other, and it lights up each file card as the agent writes it.

### How do I install FanBox?

The README points to the releases page for the dmg, and the platform badge lists macOS on Apple Silicon, with Windows shown only as a community port. There is no Homebrew or npm install instruction in the README.

### How do I use FanBox with Claude Code or Codex?

Open the project folder, start the agent in the embedded terminal, and watch the file cards ripple as it writes. The This round panel then lists which files changed, which terminal and agent did it, and the plus and minus line counts, with a per-file diff you can restore from.

### Does FanBox need an account or a cloud service?

No. The README states no cloud, no remote and no accounts, and describes the app as local-first, zero config and zero runtime dependencies.

### Why does the embedded terminal stop working after an Electron upgrade?

The terminal depends on the native node-pty module, and package.json ships rebuild scripts for exactly this. Running npm run rebuild, which is electron-rebuild -f -w node-pty, is the documented path back.

### Can FanBox roll back an agent's changes?

The README describes restoring a single file from the diff, rolling back the whole round, and scrubbing a replay timeline. It does not document rollback across multiple rounds or undoing a rollback.

## Sources

- [alchaincyf/fanbox on GitHub](https://github.com/alchaincyf/fanbox)
- [License: MIT](https://github.com/alchaincyf/fanbox/blob/master/LICENSE)
- [Project website](https://github.com/alchaincyf/fanbox/releases/latest)
- [README](https://github.com/alchaincyf/fanbox/blob/master/README.md)
- [Releases](https://github.com/alchaincyf/fanbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alchaincyf-fanbox