muffintui 0.1.6

A terminal workspace that combines a file tree, editor, shell, and embedded Codex pane
Documentation

muffintui

muffintui is the crates.io package for a Rust terminal workspace that runs as the muffin command.

It gives you four panes inside a project directory:

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

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 embedded codex session

Requirements

  • Rust and Cargo
  • codex installed and available on PATH

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 and authenticate Codex CLI

muffin launches the codex command inside the Codex pane, so the CLI must already be installed and authenticated on your machine.

Verify that the command is available:

codex --version

If you still need to authenticate, run:

codex login

Then confirm the CLI is ready before starting muffin.

3. Sanity check

Before installing or running muffin, this should work:

cargo --version
codex --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

Launch against another project:

cd /path/to/project
muffin

Run without installing during local development:

cargo run

What It Does

  • Shows a navigable file tree rooted at the current directory
  • 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
  • Embeds a live codex terminal session in the right pane
  • 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 codex launch fails, pressing Enter in the Codex pane retries the session
  • If codex is not installed, the rest of the TUI still works and the Codex pane shows the startup error

Keybindings

Global

  • Tab: move focus to the next pane
  • Shift+Tab: cycle the theme
  • Esc: 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

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

Codex Pane

  • Regular typing: send input to the embedded codex session
  • Enter: submit input, or retry the session if startup failed
  • Ctrl+C: send interrupt to codex
  • Arrow keys, PageUp, PageDown, Home, End, Tab, Backspace: forwarded to the embedded session

Publish

Before publishing:

cargo package

Then publish:

cargo publish

Test

Run the integration test suite with:

cargo test