muffintui

muffintui is the crates.io package for a Rust terminal workspace that runs as the muffin command. It is designed to keep file navigation, shell work, and AI-assisted workflows in one terminal UI.

It gives you four panes inside a project directory:

• Files
• File Viewer / Diff Viewer
• Terminal
• Shell / Codex / Claude

The right pane can also enter a dedicated focus mode that expands that live session to the full terminal while keeping the same embedded shell, Codex, or Claude process.

It starts in the current working directory and uses that directory as:

• the root of the file tree
• the working directory for shell commands
• the working directory for the right-hand interactive session

Requirements

• Rust and Cargo
• codex on PATH if you want --codex
• claude on PATH if you want --claude
• ngrok on PATH if you want remote share

Setup Prerequisites

1. Install Rust and Cargo

If rustc and cargo are not installed yet, install them with rustup:

curl https://sh.rustup.rs -sSf | sh

After installation, restart your shell or load Cargo's environment:

source "$HOME/.cargo/env"

Verify the installation:

rustc --version
cargo --version

2. Install optional right-pane CLIs

By default, muffin starts a shell in the right pane.

If you want to start directly in Codex mode, verify that codex is available:

codex --version

If needed, authenticate it:

codex login

If you want to start directly in Claude mode, verify that claude is available:

claude --version

3. Set up ngrok for remote share

Remote share uses ngrok to publish a temporary HTTPS URL for the local remote-control page.

Install ngrok first. On macOS with Homebrew:

brew install ngrok/ngrok/ngrok

Then authenticate it with your ngrok account authtoken:

ngrok config add-authtoken YOUR_AUTHTOKEN

Verify that the CLI is installed and the config is valid:

ngrok version
ngrok config check

Notes:

• muffin starts ngrok http 127.0.0.1:<port> when you enable remote share.
• The app also reads the local ngrok API on 127.0.0.1:4040 to discover the public URL.
• If ngrok is installed but not authenticated, remote share will fail to start.

4. Sanity check

Before installing or running muffin, this should work:

cargo --version

Install

Install from crates.io:

cargo install muffintui

This installs the executable as:

muffin

Install from the local checkout:

cargo install --path .

That local install also provides the muffin executable.

Run

Launch in the current directory:

muffin

Use muffin --help to list available startup flags.

Launch with Codex in the right pane:

muffin --codex

Launch with Claude in the right pane:

muffin --claude

Launch against another project:

cd /path/to/project
muffin

Run without installing during local development:

cargo run

Pass startup flags through Cargo with an extra --:

cargo run -- --codex
cargo run -- --claude

What It Does

• Shows a navigable file tree rooted at the current directory
• Highlights updated files and changed directories in the Files pane using the active theme
• Opens the selected file in a read-only file viewer
• Highlights source code in normal file view with theme-aware colors
• Toggles a diff viewer against HEAD~1
• Runs shell commands inside the built-in terminal pane with sh -lc
• Starts the right pane as a shell by default
• Can start the right pane with codex or claude
• Can toggle the right pane into a full-screen focus mode with Ctrl+F
• Can expose the right pane through a temporary ngrok URL for phone viewing and limited remote control
• Cycles between three built-in themes
• Ships with integration tests under tests/

Notes:

• .git and target are intentionally hidden from the file tree
• The built-in terminal pane starts empty
• Diff mode falls back to a message when the repository has no HEAD~1
• If the initial right-pane launch fails, pressing Enter in that pane retries the same mode
• If a codex or claude session exits, the app automatically switches that pane back to a shell
• If codex or claude is not installed, the rest of the TUI still works and the right pane shows the startup error
• Remote share mirrors only the right pane session, not the full TUI
• Focus mode only changes the layout; it does not start a separate session
• Remote share depends on ngrok being installed, logged in, and able to publish a tunnel

Remote Share

Remote share lets you open the active right pane on your phone through a temporary ngrok URL. It is intended for lightweight approval and interruption flows while a shell, Codex, or Claude session is running.

How to start it

1. Launch muffin.
2. Move focus to the right pane.
3. Press Ctrl+R.
4. Scan the QR code overlay, or open the printed ngrok URL manually.

When remote share starts, muffin:

• starts a local HTTP server on an ephemeral port
• starts ngrok http 127.0.0.1:<port>
• prints the public URL in the terminal pane
• shows a QR overlay in the TUI
• writes a QR SVG to your temp directory

The overlay can be dismissed with Esc. This only closes the overlay. The remote share session keeps running until you press Ctrl+R again in the right pane.

What the phone page can do

The mobile page polls the active right pane and shows:

• the current session mode
• the current right-pane status line
• a recent text snapshot of the right pane output

It also exposes four actions:

• Approve / Enter: sends Enter
• Send y: sends y
• Send n: sends n
• Ctrl+C: interrupts the active right-pane session

This is enough for common remote approval prompts, continuing a command, rejecting a prompt, or interrupting a long-running session.

Limits and behavior

• Remote share only works while there is a live right-pane session to control.
• If no live session exists, remote actions are ignored.
• The shared page is text-only and optimized for phone-sized screens.
• The page refreshes automatically on an interval, so it is a near-live mirror rather than a full interactive terminal.
• The shared URL includes a random token and is scoped to the current app session.
• Stopping remote share kills the ngrok tunnel.

Troubleshooting

If Ctrl+R fails to start remote share, check the terminal pane for the exact error. Common causes:

• ngrok is not installed
• ngrok is installed but not authenticated
• ngrok could not publish a public URL within the startup timeout
• local access to the ngrok API on 127.0.0.1:4040 is unavailable

Keybindings

Global

• Tab: move focus to the next pane
• Shift+Tab: cycle the theme
• Ctrl+Q: quit
• Ctrl+C: quit when focus is not in the Codex pane

Files Pane

• Up or k: move selection up
• Down or j: move selection down
• Enter on a directory: expand or collapse it
• Enter on a file: open it in the file viewer

Notes:

• Files with git changes are highlighted
• Directories are highlighted when they contain changed files

File Viewer / Diff Viewer

• Ctrl+D: toggle between file view and diff view
• PageUp: scroll up
• PageDown: scroll down

Terminal Pane

• Type directly into the prompt
• Enter: run the current command
• Backspace: delete one character
• PageUp: scroll back
• PageDown: scroll forward
• Home: jump to the oldest visible terminal history
• End: jump back to the live prompt

Right Pane

• Regular typing: send input to the active shell, Codex, or Claude session
• Enter: submit input, or retry the session if startup failed
• Ctrl+C: send interrupt to the active right-pane session
• Ctrl+F: toggle right-pane focus mode
• Ctrl+R: start or stop remote share
• Arrow keys, PageUp, PageDown, Home, End, Tab, Backspace: forwarded to the embedded session

Notes:

• While focus mode is off, Tab leaves the right pane and moves focus to the next pane
• While focus mode is on, Tab is sent directly to the embedded session and the right pane fills the screen

Publish

Before publishing:

cargo package

Push the release commit first:

git push

Then publish the crate:

cargo publish

Contributions and issue reports are welcome.

Test

Run the integration test suite with:

cargo test