croft

A VS Code style three pane workspace that runs entirely inside your terminal. Written in Rust, shipped as a single static binary.

Tenets

The non-negotiables behind every decision in croft:

1. Speed is a must. Every feature is weighed against its cost on the hot path before it lands.
2. Low latency is non-negotiable. Keystrokes and clicks register instantly; rendering is coalesced so a noisy shell can never starve input.
3. Local and remote parity always binds. Behaviour on your Mac and on a Linux box over SSH is identical. There is no second-class remote mode.
4. The gap between terminal and GUI stays minimal. croft should look and feel like VS Code, down to the icons and motion.
5. Everything has a shortcut. Every action is reachable from the keyboard, and no menu item ships without an accelerator.
6. Correctness beats workarounds. Bugs are fixed at the root, never papered over with a fallback or a downgrade.
7. One binary, no ceremony. Features are emulated in process rather than bolted on, so there is nothing to wire up after you install.

Layout

Three panes in the VS Code arrangement: an Explorer sidebar on the left, a code editor top right, and a panel bottom right with PROBLEMS, OUTPUT, TERMINAL, CAPTURES, and PORTS tabs. An activity bar down the far left switches the sidebar between Explorer, Search, Source Control, Remote (SSH), Run and Debug, Extensions, and Testing, and holds the theme picker. Every seam drags to resize, and a Customize Layout popup mirrors VS Code's title-bar controls.

The essentials are all there: full LSP editing (completion, hover, go-to-definition, rename, quick fixes, inlay hints) with tree-sitter highlighting, multi-cursor, minimap, git gutter, inline blame, and an optional vim mode; a real terminal with shell integration, splits, triggers, copy mode, and durable command history; Source Control with hunk staging and a commit graph; a Test Explorer; a zero-config task runner; Live Run, which re-runs a Python file as you type and shows every line's values inline; and debugging for Python, JavaScript/TypeScript, Rust, C, and C++ over DAP.

See LAYOUT.md for the pane-by-pane reference: every editor, terminal, Source Control, Testing, and status-bar feature, the debugging workflow, and language-server setup.

Requirements

Requirement	Why
macOS, Linux, or Android (Termux)	The PTY layer is POSIX. On Windows, run the Linux build inside WSL2; see WINDOWS.md.
Rust 1.93+ stable and a C compiler	Only to build from source (edition 2024; the tree-sitter grammars compile C). See Install Rust.
A Nerd Font as your terminal font	File and activity-bar icons are Nerd Font glyphs; without one they render as [?] boxes.
A 256 color or truecolor terminal	Terminal.app, iTerm2, Alacritty, kitty, WezTerm, and Ghostty all qualify.
iTerm2, WezTerm, Ghostty, kitty, or a sixel terminal (optional)	Inline image / PDF / spreadsheet previews. Elsewhere croft shows a metadata header line.
pdftoppm from poppler-utils (optional)	Multi-page PDF preview with clickable links. Without it, page 1 only on macOS via sips.
Node.js + npm (optional)	TypeScript / JavaScript LSP; croft auto-installs the vtsls server on first use.

Per-platform setup (Nerd Font, terminal keybindings, optional dependencies) lives in the platform guides.

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then open a new terminal — or run . "$HOME/.cargo/env" in the current one — so cargo is on PATH.

rustup does not install the C compiler and linker the build needs. On macOS run xcode-select --install; on Debian or Ubuntu, sudo apt install build-essential (or your distribution's equivalent).

Install

With Homebrew on macOS or Linux, no toolchain and no compile:

brew install vitali87/croft/croft

Upgrade with brew upgrade croft; croft's own updater (Ctrl+Shift+F9) leaves a Homebrew install to brew. Each release updates the formula, and it installs the same prebuilt archives as below.

Or prebuilt binaries through cargo:

cargo binstall croft-software

cargo binstall itself needs installing once (cargo install cargo-binstall, or a prebuilt from its releases).

That downloads the tagged release for your platform (macOS arm64/x86_64, Linux musl arm64/x86_64) and puts croft on PATH in seconds.

Or straight from the latest release, with nothing but curl and tar:

os=$([ "$(uname -s)" = Darwin ] && echo apple-darwin || echo unknown-linux-musl)
arch=$(uname -m | sed 's/arm64/aarch64/')
curl -fsSL "https://github.com/vitali87/croft/releases/latest/download/croft-$arch-$os.tar.gz" | tar xz
sudo mkdir -p /usr/local/bin
sudo mv "croft-$arch-$os/croft" /usr/local/bin/

/usr/local/bin is on the default PATH but may not exist yet on a fresh Mac, hence the mkdir. On Android in Termux there is no sudo and no /usr/local/bin: move it to "$PREFIX/bin/" instead.

To verify the archive before installing it, download it to a file instead of piping it into tar, together with the release's SHA256SUMS and that file's signature. SHA256SUMS lists all four archives, so check only the one you fetched rather than running it whole:

os=$([ "$(uname -s)" = Darwin ] && echo apple-darwin || echo unknown-linux-musl)
arch=$(uname -m | sed 's/arm64/aarch64/')
tag=$(curl -fsSLo /dev/null -w '%{url_effective}' https://github.com/vitali87/croft/releases/latest | sed 's|.*/||')
for f in "croft-$arch-$os.tar.gz" SHA256SUMS SHA256SUMS.sigstore.json; do
  curl -fsSLO "https://github.com/vitali87/croft/releases/download/$tag/$f"
done
grep "croft-$arch-$os.tar.gz" SHA256SUMS | sha256sum -c -
# macOS: grep "croft-$arch-$os.tar.gz" SHA256SUMS | shasum -a 256 -c -

SHA256SUMS is itself signed with Sigstore by the release workflow, keyless, so the signature proves the file came from this repository's release.yml run for that tag. Check it with cosign before trusting the sums, then install the archive you verified:

cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/vitali87/croft/.github/workflows/release.yml@refs/tags/$tag" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
tar xzf "croft-$arch-$os.tar.gz"
sudo mkdir -p /usr/local/bin
sudo mv "croft-$arch-$os/croft" /usr/local/bin/

To build from source instead:

cargo install croft-software --locked

This compiles the latest crates.io release into ~/.cargo/bin/croft. Re-run to upgrade. To track main instead:

cargo install --git https://github.com/vitali87/croft.git --locked

Or to build from a source checkout:

git clone https://github.com/vitali87/croft.git
cd croft
cargo install --path . --locked

macOS: the build directory churns the Spotlight index and can spike your CPU and fans. Before building, point Cargo at a .noindex directory Spotlight ignores; see MACOS.md.

Run

croft                            # opens the current directory
croft ~/projects                 # opens a specific folder
croft ~/proj --open-file a.rs    # opens a folder with a file already open
croft ~/proj --open-file a.rs --zen  # ...focused on just the file (no sidebar/terminal)
croft remote <host>              # launch croft over SSH on a Linux server (host from ~/.ssh/config)
croft devcontainer [folder]      # open a folder inside its dev container (.devcontainer/devcontainer.json)
croft open-link 'croft://attach?host=devbox&path=/srv/app'  # what a croft:// link runs (croft install-link-handler registers them)
croft open-link 'croft://decide?host=devbox&path=/srv/app&token=…&decision=allow'  # a notification's Approve: answers the agent's edit without attaching
croft attach                     # open the current folder as a persistent session (survives closing the window)
croft attach ~/projects          # ...for a specific folder
croft attach --solo ~/projects   # join a shared folder in your own viewport (live co-editing)
croft ls                         # list running persistent sessions
croft sync-config devbox         # push your keybindings, snippets, triggers to a host now (never over its own edits)
croft demo                       # a guided tour in a throwaway sample project (--tour my.json runs your own steps)
croft view report.pdf            # from any pane: open a file in the croft you are sitting in
cat data.csv | croft view -      # ...or pipe it in (staged to ~/.cache/croft, 0600, swept at the next launch once a day old)
croft theme-import theme.json    # use a VS Code colour theme in croft
croft locale-template fr --write # start or update a translation of croft's UI (see docs/SETTINGS.md)
croft theme-import dracula-theme.theme-dracula   # ...or fetch one from the marketplace
croft --help

croft remote <host> installs itself on the box on first connect with no manual prep, and a stock cloud image works as-is. See LINUX.md for how the cross-compile and host provisioning work.

croft devcontainer builds or pulls the image in devcontainer.json, starts the container with the folder mounted, runs postCreateCommand once, installs croft into it the same way, and runs it there. It supports image, build, mounts, forwardPorts, postCreateCommand, workspaceFolder, containerEnv, remoteUser and runArgs. The next run reuses the container, and an edited config (or --rebuild) replaces it.

Collaboration

croft attach keeps a session alive after you close the window, and lets other people join it. Add --solo and each participant gets an independent viewport on the same files, live. An AI can take a seat too, either as an MCP guest or as a resident pair-programming navigator croft hosts itself (croft pair), local open-weight models included.

See COLLABORATION.md for the full guide.

Platform setup

croft runs on macOS, Linux, Android, and Windows (via WSL2). The cross-platform basics are above; each platform has a short guide for its Nerd Font, terminal keybindings, and optional dependencies:

• macOS — Nerd Font for Terminal.app, and croft setup-iterm2 / croft setup-ghostty to deliver the Cmd chords that macOS otherwise reserves for menus.
• Linux — Ctrl as the command modifier, Nerd Font and poppler-utils, language servers, and the croft remote <host> cross-compile / provisioning flow.
• Android (Termux) — Ctrl as the command modifier, pkg-based dependencies, the auto-installed activity-bar font, and the built-in on-screen keyboard for touch.
• Windows (WSL2) — run the Linux build inside WSL2, hosted in WezTerm for the full icon/image UI; why native PowerShell / conhost is not supported.

Keybindings

Every action is reachable from the keyboard; press F1 inside croft for the full reference. The complete tables (global, Explorer, Search, editor, vim mode, previews, terminal) live in KEYBINDINGS.md. The command modifier is Cmd on macOS and Ctrl on Linux / Android, where Ctrl+K is also the Cmd+K chord leader; the platform guides cover getting Cmd chords through your terminal and the few Linux chords that need Super.

Goal

A complete VS Code replacement in the terminal: the full IDE experience as a single fast Rust binary. Everything VS Code does, croft will do, without leaving the TUI.

Maintainers and developers: see ARCHITECTURE.md for the project layout and internals, and CONTRIBUTING.md for the developer workflow (including keeping target/ from filling your disk).

License

MIT.