<div align="center">
# mnml
**NvChad meets VSCode — a terminal IDE in Rust.**
Vim *or* standard editing, first-class on both sides — without `if vim {}`
scattered through the codebase. NvChad-style tree / tabline / statusline
chrome; VSCode-style palette, mouse fluency, and modeless keymap. LSP, rich
git, fuzzy everything, embedded terminal & AI panes, a baked-in HTTP client,
and a headless test harness — one binary.
[](https://mnml.sh)
[](https://crates.io/crates/mnml-rs)
[](https://docs.rs/mnml-rs)
[](https://github.com/chris-mclennan/mnml/actions/workflows/ci.yml)
[](#license)
</div>
---
**mnml** is a terminal IDE that aims to be a *real* editor and a baked-in HTTP
request client and a scriptable, testable surface — built so the pieces compose
instead of fighting each other.
It takes NvChad's look — file-tree rail, tabline of open buffers, powerline
statusline, Nerd-Font devicons, tree-sitter highlighting — and marries it to
VSCode's discoverability — command palette, activity bar, right-click menus,
mouse-first chrome, a modeless keymap that doesn't hide anything behind a
modifier. Under both surfaces sits one design decision: **a pluggable input
layer.** Vim modal editing and the modeless standard keymap are both
first-class, both fully remappable, and swappable at runtime. The editor,
buffer, and render layers never branch on which one is active.
## Highlights
- **Two editing modes, one codebase.** A modal vim keymap (Normal / Insert /
Visual / Visual-Block / Replace + a `:` ex-command line) and a modeless
standard keymap. Swap live with `:set input=vim` or the command palette. Input
handlers translate keys into a closed set of edit operations — the rest of the
app is mode-agnostic.
- **Splits, panes, tab pages.** A recursive split tree; editors, terminals,
diffs, and tool panes are all `Pane`s. Vim `Ctrl-W` window chords and mouse
drag-to-resize both work. An optional **right side panel** (`Ctrl+Shift+B` or
`:set rightpanel`) gives a collapsible, drag-resizable column on the right edge.
- **LSP, batteries included.** Completion with docs, hover, go-to-definition,
references, rename with preview, code actions, inlay hints, semantic tokens,
document/type/call hierarchy, signature help, and a Problems pane — driven by a
config-driven server table.
- **Rich git + a coloured-lane commit graph.** Gutter line-signs, a diff pane
with per-hunk staging, blame, a staging view, a coloured-lane commit DAG, a
branch/worktree/PR rail, and AI-written commit messages.
- **Fuzzy everything.** File finder, command palette, buffer switcher, symbol
picker, and a which-key leader popup — all over one fuzzy-match core.
- **Embedded terminal & AI panes.** Run a shell, the `claude` CLI, or Codex as
panes; on-selection AI actions (explain / fix / refactor / write tests) and
Copilot-style inline suggestions, with a CLI or direct-API backend.
- **A baked-in HTTP client.** Send `.http` / `.curl` / `.rest` files, run request
chains, generate stubs from an OpenAPI spec — an editable, form-style request
pane lives right in the IDE.
- **Headless & scriptable.** `mnml --headless` renders to a virtual screen driven
over a file-IPC channel; a line-based `.test` format runs end-to-end UI tests
against the same `App` the terminal uses.
- **94 themes** (the NvChad base46 set) and tree-sitter highlighting for **39+
languages**, with language injection (highlighted fenced code blocks, embedded
`<script>` / `<style>`, and more).
See **[FEATURES.md](FEATURES.md)** for the complete, organised inventory.
## Install
```bash
cargo install mnml-rs # the crate is mnml-rs; the binary it installs is `mnml`
```
`cargo install` compiles from source and needs [Zig](https://ziglang.org/) 0.16.0
+ `git` on PATH so `mnml-libghostty-vt-sys` can build Ghostty's VT lib
(`brew install zig` / `scoop install zig` / `snap install zig --classic --edge`).
The build script emits a helpful message if either tool is missing.
Prefer prebuilt binaries — no toolchain needed:
- **Homebrew** (macOS / Linux): `brew install chris-mclennan/tap/mnml`
- **Scoop** (Windows): `scoop install mnml`
- **Direct download**: [releases page](https://github.com/chris-mclennan/mnml/releases)
A [Nerd Font](https://www.nerdfonts.com/) is recommended for devicons and
powerline glyphs. Without one, pass `--ascii` (or set `[ui] ascii_icons = true`)
for a plain-text fallback.
## Quick start
```bash
mnml # open the current directory
mnml ~/code/project # open a specific workspace
mnml --input vim # start in vim mode (default is standard)
mnml --ascii # no Nerd Font? plain-text icons
mnml --startup-picker # show a workspace chooser on launch
```
Once it's open:
| `Ctrl-P` | fuzzy file finder |
| `Ctrl-Shift-P` / `F1` | command palette |
| `Ctrl-B` | toggle the file tree |
| `Ctrl-K` / `<space>` | which-key leader popup |
| `Ctrl-\`` | scratch terminal |
| `:` (vim) | ex-command line |
Every key is remappable — see [Configuration](#configuration).
## Editing: vim or standard
mnml ships two input handlers and lets you pick per-session or per-workspace:
```toml
# ~/.config/mnml/config.toml
[editor]
input_style = "vim" # or "standard"
```
Switch at runtime with `:set input=vim` / `:set input=standard`, or the
`editor.toggle_keymap` command. The **vim** handler covers modal editing in
depth — operators and text objects, registers and macros, marks, `:`-commands
(`:%s///`, ranges, `:g/`, `:norm`, …), surround, and more. The **standard**
handler is a modeless VS Code-style keymap. Both resolve through the same
config-driven keymap, so `[keys.global]`, `[keys.vim]`, and `[keys.standard]`
rebind either of them.
## Configuration
mnml reads TOML, merged lowest-to-highest precedence:
```
built-in defaults
→ ~/.config/mnml/config.toml
→ <workspace>/.mnml/config.toml
→ --config PATH
```
```toml
[editor]
input_style = "standard" # "vim" | "standard"
tab_width = 4
[ui]
theme = "onedark" # any of 94 themes — gruvbox, catppuccin, kanagawa, nord, …
ascii_icons = false
wrap = false
[keys.global]
"ctrl+s" = "buffer.save"
"ctrl+p" = "picker.files"
"f5" = "dap.run"
# "key" = "none" unbinds
[lsp.rust]
cmd = "rust-analyzer"
extensions = ["rs"]
# Bufferline right-cluster icons. Setting this key replaces the built-in
# Claude Code + Codex defaults. `command` is a registered command id or
# a colon-prefixed ex-cmdline string (e.g. ":term my-binary").
[[ui.launcher_icon]]
id = "claude_code"
glyph = "\u{F0E2D}"
fallback = "CC"
command = "ai.claude_code"
color = "orange"
tooltip = "Claude Code (right dock)"
```
`[lsp.*]`, `[ai]`, `[dap.*]`, `[linters.*]`, `[formatters.*]`, `[tasks.*]`, and
the SCM dashboard tables are all configurable too — see
[FEATURES.md](FEATURES.md) for the full surface.
### Themed shell prompt (optional)
mnml ships a small powerline-style prompt (`themes/mnml-prompt.sh`)
that auto-themes against the active mnml palette. When mnml spawns
a shell it installs the script to `~/.config/mnml/prompt.sh`
and exports `$MNML_PROMPT_SCRIPT` plus the palette colors. To enable
it, add one line to your `~/.zshrc` (or `.bashrc`):
```sh
[ -n "$MNML_PROMPT_SCRIPT" ] && source "$MNML_PROMPT_SCRIPT"
```
Outside mnml shells the env var is unset and the line is a
no-op, so normal terminals are unaffected. The prompt shows `cwd ·
git branch (± when dirty) · exit code (only non-zero) · clock ·
context-chip`. Switching mnml themes auto-rethemes the next shell
spawned. No external binary required — pure bash/zsh + ANSI.
## Building from source
```bash
git clone https://github.com/chris-mclennan/mnml
cd mnml
cargo build --release # binary at target/release/mnml
cargo test # unit + e2e + ipc suites
cargo clippy --all-targets # kept warning-free
cargo fmt
```
Development convenience wrappers:
```bash
./run.sh [WORKSPACE] # build + run, with a rebuild-on-exit-75 loop
./run.sh restart # tell a running instance to rebuild + relaunch (IPC)
./run.sh stop # send quit to the running instance
./run.sh status # show marker (workspace, IPC dir)
./run.sh headless [WS] # same loop but --headless
./run.sh menu # interactive numbered picker
```
Optional Cargo features:
| `aws-codebuild` | `Pane::CodeBuilds` + `Pane::LogTail` — AWS CodeBuild builds browser and CloudWatch log tail, both shelling out to the `aws` CLI. Off by default. |
```bash
cargo build --features aws-codebuild
```
mnml builds on stable Rust (MSRV **1.87**, edition 2024).
## Family
mnml is one of a small family of terminal-native Rust tools:
| **mnml** | A terminal IDE | ← you are here |
| [**mixr**](https://github.com/chris-mclennan/mixr) | A terminal DJ app | electronic-music mixing |
| [**fim-engine**](https://github.com/chris-mclennan/fim-engine) | Embedded code completion | powers mnml's inline suggestions |
mnml runs in any terminal — Apple Terminal, iTerm2, Ghostty, kitty,
WezTerm, Alacritty, and others.
## Contributing
Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the
workflow, conventions, and architecture notes, and [`CLAUDE.md`](CLAUDE.md) for
the load-bearing design spine; the release history lives in
[CHANGELOG.md](CHANGELOG.md).
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.