red

red

The Vim-style terminal editor where your coding agent works through your editor.

Vim muscle memory, editor-aware Codex agents, focused inline assistance, and modern code intelligence in one self-contained Rust binary. Red works without configuration; optional agent support requires an installed, authenticated Codex CLI.

Website · Download · Getting started · Documentation · Community

The current documented release is v0.12.0.

Install

Homebrew

brew install codersauce/tap/red

Nix

Run Red directly from this repository:

nix run github:codersauce/red

To install the red-editor command in your profile, run nix profile add github:codersauce/red. The flake supports x86-64 Linux, ARM64 Linux, and Apple Silicon macOS.

Scoop

scoop bucket add codersauce https://github.com/codersauce/red
scoop install codersauce/red-editor

Run red-editor to open the editor. Use scoop update red-editor to upgrade.

macOS and Linux

curl --proto '=https' --tlsv1.2 -fsSL https://getred.dev/install.sh | sh

The installer selects the correct macOS or x86_64 glibc Linux archive, verifies its published SHA-256 checksum, installs to ~/.local/bin, and runs Red's built-in self-check.

For native x86-64 Linux packages, download the DEB or RPM from a Red release that includes it, then install the downloaded file with the command for your distribution:

sudo apt install ./red-editor_*_amd64.deb
# Fedora
sudo dnf install ./red-editor-*.x86_64.rpm

Both packages provide the red-editor command.

Windows

irm https://getred.dev/install.ps1 | iex

The PowerShell installer verifies the release checksum, installs to %LOCALAPPDATA%\Programs\Red\bin, and adds that directory to your user PATH.

To pin a release or choose another directory:

RED_VERSION=0.12.0 RED_INSTALL_DIR="$HOME/bin" \
  sh -c "$(curl --proto '=https' --tlsv1.2 -fsSL https://getred.dev/install.sh)"

You can also download a prebuilt archive or build from source. Red's editor, default configuration, themes, and plugins are bundled into the executable.

Official standalone installations can check or install the latest stable release:

red update --check
red update

Inside the editor, use :update or Update Red in the command palette. By default Red checks once per day and installs a newer stable release in the background after verifying its signed checksums; running sessions keep their version until restarted. Use your package manager to upgrade packaged installations. For Homebrew, run brew upgrade codersauce/tap/red. For source builds, use your existing build process. If you installed Red before v0.8.2 or extracted an archive manually, rerun the official installer once into the same directory to enable managed updates. See Updating Red for migration commands, restart behavior, and switching to notify-only or disabling automatic checks.

Agent support is optional. It requires Codex CLI 0.144.1 or newer and a completed codex login.

Why Red

• Keep your Vim muscle memory. Familiar modes, motions, operators, text objects, splits, and keyboard-first pickers work alongside Tree-sitter and LSP.
• Give your agent the real editor. Codex sees open buffers, unsaved changes, diagnostics, and selections. Its validated edits pass through Red's editor transactions and save paths instead of modifying files behind the editor.
• Ask right where you are. Inline assistance reviews, explains, or refactors an exact selection or enclosing function; code changes stay unsaved and undoable.
• Keep the whole workflow in your terminal. File search, language servers, a full Git workspace, plugins, themes, and sessions are bundled with Red.
• Reconnect without losing your work. On macOS and Linux, detachable sessions retain buffers, plugins, LSP state, and running agents across terminal or SSH disconnects.

New in v0.11.0

• Markdown that reads like the document. Tables draw as grids, link URLs and emphasis markers take no space, and images appear in the buffer at full resolution in terminals that support graphics. Move onto a line to edit its source. See the Markdown guide.
• Follow links and tick tasks. gx opens files, headings, and file:line references, Ctrl-w x keeps the document beside them, and gT toggles a task.
• Explore code without asking a model. Space e e opens a sidebar that follows names, dims a function to the calls that matter, and keeps a trail back. See Code explore. The error list moved to Space D.
• Change a setting for one launch. red -c theme=onedark.json sets any dotted key for a single run.

See the release notes for everything else.

First five minutes

Open a file:

red path/to/file

The first interactive launch offers a guided tour, release highlights, and an immediate exit into the editor. The tour uses a disposable practice buffer and safe Git/agent demonstrations; reopen it with :welcome or :tutorial. Starter configuration remains optional: embedded defaults, plugins, and themes are enough to begin editing.

Key	Action
Space ?	Discover commands and their effective keymaps
Space m	Browse notifications and recent messages
Ctrl-p	Find a file with fuzzy search and live preview
Ctrl-e, then /	Open the file tree and search files or directories
Space G	Open the Git status workspace
Space A	Ask the agent with editor context
Space i	Review, explain, or refactor the enclosing function or exact selection
Space t	Browse themes with live preview

See Getting started for editing, navigation, configuration, language servers, Git, CLI, and troubleshooting guidance. The Vim compatibility matrix is the precise, versioned behavior contract.

Agents that understand your editor

The full Agent workspace

1. Ask. Press Space A; Red provides a bounded source excerpt, current selection, relevant diagnostics, and authoritative unsaved buffer contents.
2. Work through the editor. Codex reads and changes files only through Red's workspace-confined, revision-checked editor tools. Agent edits are attributed to their conversation and saved to disk through Red.
3. Keep the conversation. Follow tool progress, queue another request, and resume the same conversation without losing editor context. Source-linked annotations turn explanations into navigable code walkthroughs.

File-tool playback is optional and disabled by default; set [agent] follow_tool_calls = true to reveal each target and pause before the operation. Full Agent writes still save to disk.

Focused inline assistance

Press Space i to review, explain, or refactor the enclosing function, falling back to the current line when syntax is unavailable. In Visual or Visual Line mode, the target is exactly the selected text. Requests use an ephemeral Codex thread with bounded read-only project context; visual-block targets are not supported. Inline code edits form one unsaved, undoable editor transaction.

An exact-target edit may apply immediately when its original popup is in the foreground; set [agent] auto_apply_inline_edits = false to review it first. Background results and wider same-file proposals always require an explicit review and approval. Use Space H to revisit inline history or A to prepare a full Agent follow-up without sending it automatically.

The agent workflow and safety contract explains prerequisites, path protections, exact boundaries, commands, and failure modes.

What Red ships today

The current release includes:

• Normal, Insert, Visual, Visual Line, Visual Block, and Command modes with expanding Vim motion and editing compatibility
• tree-sitter highlighting for Rust, Markdown, JavaScript, TypeScript/TSX, JSON, TOML, YAML, Bash, PowerShell, Lua, and Husk
• a first-party Husk language server plus built-in LSP defaults for Rust, TypeScript/JavaScript, Markdown, JSON, TOML, YAML, and Lua
• command and keymap discovery, fuzzy files, buffer navigation, symbols, references, project search, and diagnostics
• native Git gutter signs, hunk actions, and a full-screen workspace for staging, commits, Codex-generated commit messages, branches, remotes, stashes, logs, and rebases
• a persistent full Agent workspace and bounded inline assistance with source-anchored comments, retained history, and reviewable local edits
• an embedded Husk runtime with bundled file tree, search, Git, progress, inlay-hint, symbol, theme, and agent plugins
• a branded startup splash, the Red theme, accessible selection and cursor contrast, and optimized rendering hot paths
• atomic crash recovery on every platform and detachable sessions on macOS and Linux

See the latest release notes or the complete changelog for details.

After installing a new version, Red opens a themed What’s new panel once. Reopen it whenever you like with :whats-new, :changelog, or the command palette. Release notes are bundled for offline use and refreshed from the exact matching GitHub release in the background.

Configuration

Red layers your settings over embedded defaults, so a configuration file can contain only the values you want to change:

# ~/.config/red/config.toml
theme = "red.json"
scrolloff = 8
# Disable the automatic release panel or its optional GitHub refresh:
# show_whats_new = false
# fetch_release_notes = false

[updates]
# "auto" installs new stable releases in the background, "notify" only announces
# them, and "off" disables the daily check.
mode = "auto"

[search]
ignorecase = true
smartcase = true

[keys.normal]
"Ctrl-s" = "Save"

The commented default_config.toml documents every setting that ships with Red. Custom themes go in ~/.config/red/themes/, and custom Husk plugins go in ~/.config/red/plugins/. Run red --runtime-files to see every visible runtime asset and its source.

Override settings for a single launch with repeatable -c or --config flags. The key is a dotted path. The value is TOML, and a value that is not valid TOML is used as a plain string, so ordinary words do not need quotes. Later flags win. --config-override is the same flag and still accepts a TOML document.

red -c theme=onedark.json -c languages.rust.indent_width=2 src/main.rs
red -c 'disabled_plugins=["indent_guides"]' -c 'search={ignorecase=true}'
red --print-config -c scrolloff=8

Precedence, from lowest to highest:

1. Embedded defaults
2. config.toml ($XDG_CONFIG_HOME/red/config.toml, or ~/.config/red/config.toml)
3. -c / --config / --config-override

Red does not read configuration from an environment variable. XDG_CONFIG_HOME only chooses the directory that contains config.toml. red --print-config prints the merged result, and :config-diagnostics lists startup overrides next to any configuration problems. :set relativenumber still toggles that option for the current session after startup.

Markdown reads like the rendered document and edits as source. In Normal mode, pipe tables draw as aligned grids, link URLs and emphasis markers are hidden so paragraphs wrap on the words you see, and a line holding only an image shows the picture in the buffer, at full resolution in Kitty, Ghostty, WezTerm, iTerm2, and Sixel terminals. Move onto a line and its raw Markdown comes back. gx follows links to files, headings, and file:line references, Ctrl-w x keeps the document open beside what it links to, and gT toggles a task. See the Markdown guide.

Add new highlighting, exact filenames, comment syntax, indentation, and language servers through a unified [languages.<id>] configuration or an installable language pack. Native Tree-sitter grammars require explicit digest-bound trust; :languages reload applies validated changes without restarting the editor. See the language extensions guide.

Husk language

The source tree contains the extracted Husk embedding API, standalone CLI, local package resolver, and portable WebAssembly Component extension runtime. Start with the language and embedding guide. The research and implementation plan and card-by-card status explain the dynamic Rust-crate design, completed work, and remaining release-hardening tasks.

Plugins and themes

Bundled plugins and themes are embedded in the binary and upgrade with Red. They are parsed and typechecked against the versioned Husk host contract before activation; an incompatible plugin is quarantined without preventing editor startup.

You can disable bundled plugins, configure them in config.toml, or eject a copy for customization:

red --eject plugins/fidget.hk
red --eject themes/red.json

An ejected asset shadows the bundled copy until you delete it. See the plugin system guide, host API, and bundled plugin source for details and examples.

Sessions

On macOS and Linux:

red --detach path/to/file
red --detach=work path/to/project
red --attach work

Leave a detachable session with Ctrl-\. Read Detachable sessions and Session recovery for lifecycle, recovery, and platform details.

Documentation

Guide	Covers
Getting started	Editing, keymaps, LSP, Git, CLI, and troubleshooting
Markdown	Rendered tables, hidden markup, inline images, links, and tasks
Code explore	Reading mode: symbol follow, sidebar, skeleton dimming, review trail
Husk language server	Husk editor features, external crates, configuration, and safety boundaries
Language extensions	Custom syntax, trusted Tree-sitter grammars, language packs, LSP settings, and live reload
Vim compatibility	Supported behavior and intentional differences
Agent workflow	Codex prerequisites, review model, commands, and safety
Plugin system	Husk lifecycle, runtime architecture, and validation
Plugin API	Versioned host API for plugin authors
Detach and attach	Persistent Unix sessions
Session recovery	Atomic recovery and dirty-buffer restoration
Performance	Measurement, budgets, and regression process
Debugging	Invariant owners, logs, diagnostic commands, and tracing paths
Releasing	Release preparation, publication, and verification

Status and community

Red is an early, pre-1.0 release and is evolving quickly. Bring curiosity and keep backups for critical work.

• Follow development on the CoderSauce YouTube channel.
• Join the Discord community.
• Report bugs and request features in GitHub Issues.

Development

Red requires a recent stable Rust toolchain and Git:

git clone https://github.com/codersauce/red.git
cd red
cargo build
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings

Use narrower commands while iterating on a specific crate or test:

cargo test -p red --lib editor::tests::
cargo test --workspace --exclude red --all-features --tests
python3 scripts/doctest_packages.py --no-default-features

cargo test is the default runner because Red's many short tests complete faster in shared test-binary processes. Install cargo-nextest when per-test isolation, timing, retries, or JUnit reports are useful, then compare both runners with python3 scripts/test_performance.py --runner both --timings. Add --package husk-lexer for a short, focused comparison. The manual Rust Test Performance GitHub Actions workflow provides the same comparison on Linux, macOS, or Windows and can optionally enable sccache or the Linux mold linker.

Use RED_RUNTIME=. while iterating on bundled plugins or themes without rebuilding the executable:

RED_RUNTIME=. cargo run -- path/to/file

Contributions are welcome. For major changes, open an issue before investing in an implementation. Release maintainers should follow docs/RELEASING.md.

License

Red is available under the MIT License.

Built with love for the Rust community and inspired by Vim, Neovim, and Helix.