CandyFiles
Dual-pane terminal file manager
Two panes side-by-side, Midnight Commander style. Tab to swap focus, multi-select, sort cycling, hidden-file toggle, delete-with-confirm. Pure-state transition layer — filesystem is injected, every transition is unit-testable.
Install
composer require sugarcraft/candy-files
While the release channel is dev-only the inline :@dev is required — Packagist carries just dev-master, and a fresh project's default stable minimum-refuses the bare command.
Quickstart
# 1. Composer consumer — the package bin (composer.json "bin"):
vendor/bin/candy-files [LEFT_DIR] [RIGHT_DIR]
# 2. Source checkout of this repo:
composer install
./bin/candy-files [LEFT_DIR] [RIGHT_DIR]
# 3. Rolling phar — published on GitHub Releases under the
# candy-files/latest tag (with .sha256/.sig verification sidecars and
# the .phar.commit build stamp + .phar.pins.json pin-map — quote
# the latter pair in bug reports):
php candy-files.phar [LEFT_DIR] [RIGHT_DIR]
# Flags (answered before the positional directory scan):
# --version build stamp — phar-aware via Support\Version
# --help/-h usage
# --print-cd cd-on-quit handshake: the interface rides /dev/tty
# and stdout carries ONLY the final active-pane
# directory at exit — capture it in a shell function
# (candy-files-cd, see the README handshake section)
# A missing/unreadable start directory refuses up front with exit 1
# ("left/right directory does not exist: ").
# Default: left = cwd, right = $HOME.
# Size honesty: each pane box measures (cols - 2) / 2 cells outer — the
# name column, header clip and separator all derive from the content
# width inside it, so the composed frame lands exactly on the live
# terminal width at any size. Rows are windowed: the listing scrolls a
# window that follows the cursor (↑/↓ fold hints mark hidden head/tail),
# and the status line and confirm prompts are always on screen.
# Keys
# Tab Swap focus
# ↑ / k Move up
# ↓ / j Move down
# Home / g Top
# End / G Bottom
# Enter / → Open: directory navigates, archive (.zip/.tar/.tgz/.tbz2) browses read-only, file launches $EDITOR
# l Page a file through $PAGER, or the built-in viewer when none is installed; on a dir it opens (vim-diamond right)
# o Open with the platform default (xdg-open / open / cmd start) — argv list, never a shell string
# x Run the entry under cursor when it carries the exec bit; inside an archive view, extract to the other pane
# ← / h Up one directory
# Space Toggle selection + advance
# Ctrl+a Select every listed entry (the .. sentinel is never marked)
# v Invert the selection — pressing it twice restores the set
# * Pattern-select: type a glob-lite pattern (fnmatch, never regex)
# s Cycle sort order (8 modes)
# e Direct-select extension sort
# . Toggle hidden files
# c Copy selection or cursor → inactive pane (confirm: y or the locale's affirmative)
# m Move selection or cursor → inactive pane (confirm: y or the locale's affirmative)
# R Rename cursor entry — type new name, Enter commits, Backspace edits, Esc cancels
# N Create directory in the active pane — same text-entry; u removes it while empty
# d Delete (selection or cursor) — confirm gate arms first
# y / Y Yank (copy / move) the selection or cursor entry into the yank register
# p Paste the register into the active pane's directory (existing confirm gate)
# w / W Copy the full path / bare name to the clipboard over OSC 52
# a Pin the active directory as a bookmark · B opens the bookmarks overlay (Enter jumps, d unpins)
# I Info overlay: path, type, size, permissions, owner, times, link target, free space
# r Refresh active pane
# q Quit (two presses while copy batches are in flight)
# ? Help overlay — every binding one per row, Esc or ? closes
# / Search mode — fuzzy filter by name of the active pane; arrows move the result cursor, Enter opens dirs / lands on files, Backspace-to-empty exits; Ctrl+R inside search toggles the bounded recursive walk (hits show their path relative to the pane)
# Escape Exit search mode · cancel armed gates and text-entry · clear selection (outside modes)
# t Duplicate current tab
# Ctrl+w Close current tab
# Ctrl+O Open a typed path in the active pane (~ expands, relative joins the pane cwd)
# 1-9 Switch to tab 1-9 (bare digit or Alt+n)
# Ctrl+Tab Cycle to next tab — terminals that report modified Tab
# Ctrl+Shift+Tab Previous tab
# Ctrl+PgUp Next tab · Ctrl+PgDn Previous tab — tmux/browser terminals may intercept modified Page keys
# u / Ctrl+z Undo last operation
# Ctrl+y Redo last undo
# Mouse Wheel scrolls the pane under the pointer · click activates + parks the cursor · Ctrl+click toggles the mark · double-click opens · tab-bar click switches tab
What's in the box
Dual panesLeft + right; Tab swaps focus. Each pane has its own cwd, cursor, selection, sort, hidden-flag.
Multi-selectSpace toggles + advances.
Ctrl+a marks every listed entry, v inverts, * pattern-selects with a glob-lite prompt. Selection survives r relist and sort; leaving a directory stashes its marks and re-entering re-adopts them for names that still exist (CF-31) — the stash is keyed by directory, so a mark can never act on a same-named entry elsewhere. Escape clears.Eight sort modesname / mtime / size / extension, asc / desc —
s cycles, e jumps straight to extension (CF-46).Hidden-file toggle
. hides / shows dotfiles.Copy / Move / Rename
c/m stage to the inactive pane, y commits. R opens a text-entry rename submode — type the new name, Enter commits, Esc cancels. Undo covers delete, move and rename (copy undo is informational).Delete-with-confirm
d arms the gate, y (or the prompt's taught localized affirmative) commits — protects against fat-finger deletes. Files move to a per-session ephemeral trash (mode 0700, wiped on exit; a cross-device delete is announced PERMANENT before you confirm).Injectable FS
FsLister closure — swap for a fixture lister in unit tests with no tmp dirs.RequirementsPHP
^8.3 with ext-intl and ext-mbstring — both hard-required transitively by sugar-core, whose cell-width math segments through ICU, so composer install is the step that refuses on a bare php-cli machine.Live search
/ fuzzy-filters the active pane's listing by name (dotfiles obey the . visibility law). Matching compares NFC-normalized names, so a composed query finds macOS's decomposed bytes and vice versa (CF-48). ↑/↓ move the result cursor, so k, j and every other printable type into the query (/ itself cannot). Enter opens a directory result; on a file result it exits search with the pane cursor landed on the hit. A Backspace that empties the query exits. Ctrl+R inside search arms a bounded recursive walk of the whole tree (CF-17) — depth, name-count, and hit budgets, with the status announcing "search partial" when any cap fires.MouseThe launcher requests SGR cell-motion reporting: the wheel scrolls the hovered pane, a click activates it and parks the cursor,
Ctrl+click toggles the mark, a double-click opens, and a tab label click switches tabs. Modal frames (confirm gate, help, info, bookmarks, search) swallow the pointer so a click can never answer a prompt (CF-55).MetadataTerminals of 100 columns or more add a modification-time column to every pane row;
I opens a stat overlay read fresh with lstat (type, bytes, drwxr-xr-x + octal, owner:group, times, link target, free space) (CF-52).Yank / paste & clipboard
y/Y stage a copy or move, p arms the ordinary confirm gate at the active pane's directory; w/W put the path or name on the clipboard over OSC 52, refusing a dumb/linux TERM and admitting the terminal may ignore the sequence (CF-32, CF-50).Bookmarks
a pins the directory, B lists the pins, Enter jumps through the typed-path door, d unpins; stored as atomic 0600 JSON under $XDG_DATA_HOME/candy-files/ (CF-30).ArchivesEnter on a
.zip, .tar, .tar.gz or .tar.bz2 browses it as a read-only directory; x extracts to the other pane through the copy gate on the event loop. Zip-slip names, links and devices are dropped, and 256 MiB scan / 512 MiB extract ceilings stop decompression bombs (CF-33).Built-in viewer & open-with-default
l falls back to a read-only in-app viewer (head 256 KiB, sanitized lines) when no pager exists; o opens the entry with xdg-open/open as an argv list (CF-03).Tab management
t duplicates the current tab, Ctrl+Tab/Ctrl+Shift+Tab cycle (needs a terminal that reports modified Tab; Ctrl+PgUp/Ctrl+PgDn are the alternative — tmux and browser terminals may intercept modified Page keys), Ctrl+w closes (refuses the last tab).Undo
u or Ctrl+z restores the last delete / move / rename; Ctrl+y redoes.Localized promptsThe executable activates a language detected from
$LC_ALL/$LANG (16 catalogs, English default). Confirmation gates honor the affirmative each locale's prompt teaches — a German (j/n) answers j, a Russian (д/н) answers д — and y works everywhere.Source & demos
- Source on GitHub
- Full README
- Originally inspired by superfile (Go); SugarCraft is developed as a native PHP project.
Key Classes
| Class | Method | Description |
|---|---|---|
| Manager | start(leftCwd, rightCwd, ?lister) | Factory — initializes two panes + first tab |
| Manager | update(Msg): [Model, ?Cmd] | Main event loop — key dispatch, confirm gate |
| Manager | view(): string | Renders two panes + tab bar + status line |
| Manager | copy(src, dst), move(src, dst), rename(src, newName) | Direct single-entry helpers — rename/move run synchronously; the deferred engine is copy-only, and the committed copy path goes through the async command, not these |
| Manager | search(query), exitSearch(), openSearchResult() | Live search mode |
| Manager | undo(), redo(), canUndo(), canRedo() | Delete / move / rename undo/redo stack (copy undo is informational); u/Ctrl+z undo, Ctrl+y redo |
| Manager | duplicateTab(), closeTab(), switchTab() | Tab management |
| Manager | openNewTab(path) | API tab push — path defaults to /; since CF-29 a key binding carries a path too: Ctrl+O opens the typed-path prompt in the active pane (t duplicates) |
| Manager | moveSearchCursor(delta) | Result-cursor motion in search mode (clamped to the result list) |
| Manager | builder(): ManagerBuilder | Fluent immutable construction of the eighteen founding fields — see README "Constructing Manager" |
| Pane | open(cwd, lister, sort, showHidden): self | Factory — reads and sorts directory |
| Pane | navigate(lister): self | Enter directory under cursor (no-op on files) |
| Pane | toggleSelection(): self | Add/remove cursor entry from selection set |
| Sort | apply(entries): list<Entry> | Sort entries (parent sentinel stays at index 0) |
| Sort | cycle(): self | Cycles: name → mtime → size → extension, each asc then desc, wrapping to name-asc (CF-46) |
| Entry | displaySize(): string | Returns "DIR" / "LINK" / compacted bytes |
Demos.
GIFs recorded against the live app — 7 tapes under .vhs/ drive ./bin/candy-files over real directories. Regenerated automatically on every push that touches the source.
Navigate
Tab-swap, multi-select, sort cycle, delete-with-confirm.
Search
Type "/" to fuzzy-filter the active directory by name, arrows move the result cursor, Enter lands on the hit.
Multi-select
Space toggles selection, d+y deletes all selected.
Tab management
t duplicates, Ctrl+Tab (or Ctrl+PgUp/PgDn) cycles, Ctrl+w closes.
Sort cycle
s cycles through all 8 sort modes: name/mtime/size/extension × asc/desc.
Undo delete
u or Ctrl+z restores the last deleted entry.