NECO — Neural Commander

      ░█▄░█░█▀▀░█▀▀░█▀█
      ░█░▀█░█▀▀░█░░░█░█
      ░▀░░▀░▀▀▀░▀▀▀░▀▀▀

           (￣^￣)ゞ
      STANDING BY, SIR.

NECO wraps any CLI with a file explorer, file viewer, and hotkey macros. You run your tool inside it, and it stays out of your way until you need it.

If you ever used Norton Commander — you know.

The problem it solves

Modern CLI tools — AI assistants, code generators, dev servers — often need file paths as input. You find yourself typing /Users/you/projects/thing/src/components/SomeDeepFile.tsx from memory, or switching to Finder, copying a path, switching back, pasting. Repeatedly.

NECO intercepts your terminal input, listens for a hotkey, and overlays a file browser on top of whatever is running. You pick a file, it inserts the path at your cursor, and the overlay disappears. The underlying tool never knew anything happened.

It also lets you preview files (text or hex), record macros, and configure how paths are formatted — all from inside the overlay.

Installation

npm install -g @ittaigolde/neco

Requires Node.js 18+. Uses node-pty (native module — prebuilt binaries available for most platforms).

Usage

neco <command> [args...]

neco claude               # wrap Claude CLI
neco claude --resume      # flags pass through normally
neco npm run dev          # works with anything
neco                      # wraps your default shell ($SHELL)

NECO spawns the command in a PTY, proxies all input and output, and listens for its hotkeys. From the perspective of the wrapped tool, it is running in a normal terminal. From your perspective, you have a file browser, a file viewer, and macros.

Hotkeys

| Key | Action | |-----|--------| | Opt+1 | Open Commander (file explorer + macro editor) | | Opt+2..9 | Run macro |

Key naming: Throughout this document, Opt refers to the Option key on macOS. On Linux and Windows, this is the Alt key.

On macOS, NECO handles both Option-as-Meta terminals (\x1b2) and Option-as-character terminals (™, £, etc.) without requiring any terminal configuration changes.

The Commander

Press Opt+1 to open the overlay. Press Esc or q to close it.

┌─ Navigation ──────────┐ ┌─ Files ─────────────────────────────────┐
│ ┌─ Directories ──────┐│ │ Name               SIZE  CRE       UPD  │
│ │ ..                 ││ │ README.md           4K   Apr 12 26  ...  │
│ │ src                ││ │ package.json        1K   Mar 01 26  ...  │
│ │ node_modules       ││ │ dis-cli.js         12K   Mar 01 26  ...  │
│ └────────────────────┘│ │                                          │
│ ┌─ Favorites ────────┐│ │  N:Name  S:Size  C:CRE  U:UPD  O:Open  │
│ │ ~/Downloads        ││ └─────────────────────────────────────────┘
│ │ ~/projects         ││
│ └────────────────────┘│
└───────────────────────┘
┌─ Macros ──────────────────────────────────────────────────────────┐
│ Opt-2: (empty)   Opt-3: (empty)   Opt-4: @"~/projects/neco"  ... │
└───────────────────────────────────────────────────────────────────┘

Navigation

• D / F — jump to Directories or Favorites pane
• m — jump to Macros pane (when visible)
• Tab / Shift+Tab — cycle through panes forward / backward
• Arrow keys / j k — move selection
• Enter on a file — inserts the path into the wrapped CLI and closes the overlay
• Enter on a directory — navigates into it

Commander remembers your last navigated directory and focused pane between sessions.

File pane

Files are shown with size (B/K/M/G) and dates. When the file pane is focused:

• N / S / C / U — sort by name, size, creation date, or updated date
• Press the same key again to toggle ascending/descending
• O — open the file in Finder (macOS), Explorer (Windows), or your file manager (Linux) without closing Commander
• F3 — open the file in the built-in viewer; for archives, open the archive browser

Sort preference persists between sessions.

File viewer (F3)

Press F3 on a selected file to view it full-screen.

• Text files (.js, .md, .json, .py, and many more) — displayed as-is with scroll support
• Binary files — displayed in hex view (offset | hex bytes | ASCII), like a classic hex editor
• Archives (.zip, .tar, .tar.gz, .tgz) — opened in archive browser mode

Inside the viewer:

• ↑ / ↓ / PgUp / PgDn — scroll
• Ctrl+F — reactive search (highlights matches as you type)
• n / b — next / previous match (wraps around)
• Esc — close viewer

The list of text file extensions is stored in ~/.dis-cli-settings.json and can be edited.

Archive browser

Press F3 on a .zip, .tar, .tar.gz, or .tgz file to browse it without leaving Commander. Pressing Enter on the archive itself inserts the archive path, just like any other file.

• Enter on a folder — navigates into that folder
• Enter on a file — extracts it to the system temp directory, inserts the extracted file path, and closes Commander
• F3 on a file — opens it in the built-in viewer without leaving a persistent extracted file behind
• Esc — exits archive mode and returns to normal Commander

The first file extraction prompts for confirmation. Choosing "Always" stores autoExtractArchive: true in ~/.dis-cli-settings.json.

Extracted files are kept in temp instead of being deleted on archive exit, so paths inserted into the wrapped CLI remain valid.

Viewer-only archive reads avoid creating durable temp artifacts. If you only press F3 to inspect a file, NECO reads the file for display and cleans up any internal extraction work before returning to Commander.

Path format

Press P to cycle the path insertion format:

| Format | Output | |--------|--------| | @"$PATH" | @"/Users/you/file.txt" (default, for Claude CLI) | | "$PATH" | "/Users/you/file.txt" | | $PATH | /Users/you/file.txt |

The format applies to both file selection and macro path assignment. Persists between sessions.

Favorites

F2 toggles the current directory as a favorite. Useful for projects you navigate to often.

Macro pane

Press M to show or hide the macros pane. When hidden, macros still work via Opt+2..9 — only the UI is toggled. Visibility persists between sessions.

Indicator

Press I to toggle a 🫡 prefix in your terminal tab/window title while NECO is running. Helps when you have many terminal tabs open and forget which one has NECO in it. On by default. State persists.

Macros

A macro is a sequence of text and special tokens assigned to Opt+2 through Opt+9. Press the key combination to replay it.

Setting a macro

Inside Commander, navigate to a file or directory and press Opt+2..9 — this assigns the path (in your current path format) to that slot. Or go to the Macros pane and press Enter to edit one directly.

Macro syntax

Plain text is typed as-is. Special tokens:

| Token | Action | |-------|--------| | <enter> | Press Enter | | <tab> | Press Tab | | <esc> | Press Escape | | <up> <down> <left> <right> | Arrow keys | | <opt-2> .. <opt-9> | Run another macro (nestable, max depth 5) | | <wait 3> | Wait 3 seconds | | <typing-start> | Enable character-by-character typing at ~60ms/char | | <typing-end> | Disable typing simulation | | \<enter> | Type the literal text <enter> |

Macro edits are validated before saving. Invalid token names, stray <typing-end> tokens, nested typing blocks, and <typing-start> blocks without a matching <typing-end> are rejected in the editor. If you hand-edit the settings file, invalid macro entries are dropped during settings normalization.

Example macros

# Open a specific project in Claude and resume the last session
cd ~/projects/myapp<enter>claude --resume<enter>

# Type a common prompt slowly (looks more natural in some tools)
<typing-start>Please review the following file for issues:<typing-end><enter>

# Chain macros: macro 2 runs macro 3, then adds context
<opt-3>Here is the file I mentioned above.

Use cases

AI CLI assistants (Claude, Copilot CLI, etc.) — The primary motivation. Instead of typing or pasting file paths into your AI conversation, you navigate to the file and press Enter. The path appears at your cursor. No terminal switching required.

Long-running dev servers — Wrap npm run dev or similar. Your terminal is occupied, but you can still drop into the file browser or fire a macro without interrupting the process.

Repetitive workflows — If you find yourself typing the same sequence of commands with minor variations, record it as a macro with a path placeholder. One key combination, done.

Context switching — The 🫡 title indicator makes it easy to spot the NECO terminal among a stack of tabs, which matters more than it sounds once you have ten of them open at 11pm.

Settings

All settings are stored in ~/.dis-cli-settings.json and can be edited directly:

• favorites — bookmarked directories
• macros — macro definitions (keyed by slot number)
• pathFormat — path insertion template (@"$PATH", "$PATH", or $PATH)
• showMacros — macro pane visibility
• showIndicator — terminal title indicator
• fileSort — column and direction for file sorting
• textExtensions — file extensions treated as text in the viewer
• autoExtractArchive — extract archive files without asking every time

Settings are normalized on load and saved atomically. Unknown or malformed values fall back to defaults, and invalid hand-edited macros are removed instead of breaking startup.

Platform notes

• macOS — Full support. Works with both "Option as Meta" and "Option as character" terminal configurations.
• Linux — Full support. "Open in explorer" uses xdg-open.
• Windows — Full support via Win32 extended input mode. "Open in explorer" uses explorer /select,.

Technical notes

NECO uses node-pty to spawn the wrapped command in a pseudoterminal, which means the child process behaves exactly as it would in a real terminal — colors, cursor movement, raw mode, everything. The file browser overlay is rendered using blessed on the host terminal, switching to the alternate screen buffer and back.

Hotkeys are intercepted by watching raw stdin before it reaches the PTY. The wrapped process never sees Opt+1 — it only sees what NECO decides to forward.

License

MIT

Neural Commander. Because your terminal deserved a co-pilot.