An Agent Workspace for people who live in Vim: drive any coding agent in its own terminal interface, by hand and the way you edit.
Note
Adroit is early: it runs, but expect rough edges and changes.
Claude Code, Codex, Pi and OpenCode sessions stand side by side in one window, each in the interface its agent ships, unchanged. You write prompts in a real Neovim, configured for Adroit with the mappings and plugins you choose, and move between tabs, splits, the tree and the details panel with Vim's motions. Sessions are grouped by workspace and worktree, across repositories, with those waiting on you listed first.
api ← a repository
├── main ← a worktree
│ ├── auth-revamp ← a Claude Code session
│ ├── review-api ← a Codex session
│ └── $ dev-server ← a named shell
└── feat/oauth
└── implement
notes ← a directory outside git
└── outline-the-talk
Sessions and shells keep running when the window closes. Open Adroit again to return to them, or open several windows onto the same work. The details panel shows the session's overview, changes, history, agents, resources and the timeline its agent records of its work.
┌──────────────┬──────────────────────────────────┬─────────────┐
│ tree │ 1 auth-revamp │ 2 review-api │ details │
│ ├────────────────┬─────────────────┤ │
│ api │ the agent's │ another window │ Overview │
│ ├── main │ own interface │ of the same tab │ Changes │
│ │ ├── … │ │ │ Log │
│ └── … ├────────────────┤ │ Agents │
│ │ prompt: Neovim │ │ Resources │
│ waiting on │ │ │ Timeline │
│ you │ │ │ usage │
└──────────────┴────────────────┴─────────────────┴─────────────┘
See the concept for who Adroit is for and the ideas behind it.
Adroit needs git and at least one supported agent on PATH. The macOS app
carries the Neovim its prompt and console reader run; built and run from the
source, they run nvim on PATH, or the program ADROIT_NVIM names. Opening a
file in Neovim runs the nvim on PATH either way.
| Agent | Program |
|---|---|
| Claude Code | claude |
| Codex CLI | codex |
| Pi | pi |
| OpenCode | opencode from @opencode/cli, version 2.1 or later |
Install jj to read jj repositories and create jj workspaces. ghq is optional; when installed, its repositories are offered in the directory picker.
On an Apple silicon Mac, install the latest release with Homebrew:
brew install --cask adroit-app/tap/adroitEach release carries the disk
image the cask installs. Adroit.app is signed by a self-signed certificate,
not by an Apple Developer ID, so a downloaded copy needs its quarantine removed
(xattr -dr com.apple.quarantine /Applications/Adroit.app) or opening allowed
in System Settings → Privacy & Security; the cask does this itself.
With Nix (prebuilt in the adroit Cachix cache):
nix profile install github:adroit-app/AdroitBuild and run from the Nix development shell:
nix develop -c cargo run --release -p adroitOn macOS, build and install the application into /Applications:
nix develop -c just install-macosThe installed command is /Applications/Adroit.app/Contents/MacOS/adroit. Add
that directory to PATH to use the adroit commands below from your terminal.
The app is signed by the self-signed identity "Adroit Release" when the login
keychain has it, so a local build keeps the permissions macOS gave the release
or the build before it. Otherwise it is signed ad hoc. Releases are signed by
the same identity; to import it, give it as MACOS_SIGNING_P12 (identity.p12
in base64) and MACOS_SIGNING_PASSWORD:
MACOS_SIGNING_P12=… MACOS_SIGNING_PASSWORD=… just macos-import-identityA release is published as a GitHub Release with a tag such as v0.1.0; the
disk image, the Nix build and the Homebrew cask follow
(ADR). Build the
disk image the way the release does, outside the Nix shell, with
just bundle.
On Windows, build with Rust, the MSVC build tools and LLVM installed, and
Neovim on PATH:
cargo run --release -p adroitShells there run PowerShell. One adroit opens one window, and Claude Code's
external editor is not handed to it. Started from Explorer or a shortcut
rather than a terminal, it opens no console window beside its own, though
Windows shows one for a moment before it does. Start adroitw.exe, built
beside adroit.exe, from a shortcut instead, and none shows at all.
On Linux, the Nix development shell has what the window builds with. Outside
it, install the development packages of WebKitGTK 4.1, GTK 3, libxdo and
OpenSSL (on Debian and Ubuntu, libwebkit2gtk-4.1-dev, libgtk-3-dev,
libxdo-dev and libssl-dev), then build as above. The window copies with
wl-copy on Wayland, else xclip or xsel, opens paths and addresses with
xdg-open and tells of a session waiting with notify-send; each is left
undone where its program is not installed.
CI lints and tests it on Windows with just ci-windows, run from Git Bash. To
check that the source still builds on Windows from another machine,
vitro lints it in a throwaway Windows
VM as vitro.toml says:
vitro test windows- Press
Mod+p(win the tree) to choose a directory. The picker offers workspaces already in use, Claude Code projects, ghq repositories and a file tree. Choose its scratch-session row, or Session → New Scratch Session, to start without choosing a directory. - On the draft, choose a profile, model and permissions.
Ctrl+g pandCtrl+g Pmove through profiles. - Write the first prompt and press
Ctrl+Enter. It starts the session; later prompts go to that same session.
A first line such as name: review-api names the session and is removed from
the prompt sent to the agent. Without one, Adroit makes a name from the prompt.
To start a Codex session from a terminal:
adroit session start --agent codex --dir ~/src/api -- "Review the API"To return to a conversation an agent kept, press Mod+o (O in the tree).
The list includes conversations from the logins your profiles use; choosing one
resumes it in that same login. See sessions and
the directory picker.
Settings → Agents holds named profiles. Each chooses an agent, its login, launch command, environment and defaults for new sessions. You can keep several profiles for one agent, and choose which profile new sessions start from.
A profile can use your terminal's login or keep a login of its own. The latter has its own credentials, history and settings. Log in from the profile's page in Settings. Existing sessions keep the profile and login they started with, even when settings change.
Drafts can override their profile's model and permissions. Read-only and custom permissions use the selected agent's own controls; their scope differs by agent. See profiles and agent behavior.
Mod means Cmd on macOS and Ctrl+Shift elsewhere. Ctrl+q starts window
motions, including while the prompt is in insert mode; Ctrl+w stays with the
program in the console or prompt.
| Keys | Action |
|---|---|
Ctrl+q h/j/k/l |
Move between the tree, content windows, prompt and details panel |
Ctrl+q s, Ctrl+q v |
Split below or beside the focused window |
Ctrl+Tab, Ctrl+Shift+Tab |
Next or previous tab; in details, next or previous tab |
Mod+1 … Mod+9 |
Go to a content tab |
Mod+p |
Choose where a session works |
Mod+t |
Start a session in the selected or focused directory |
Mod+o |
Resume a past conversation |
Mod+n |
Open another Adroit window |
Mod+s, Mod+e |
Open a shell or Neovim in the current directory |
Mod+j |
Go to the next session waiting on you |
Mod+f, Mod+r |
Filter the tree or refresh |
Mod+b, Mod+d |
Show or hide the tree or details panel |
Mod+, |
Open Settings |
F1 |
Show the keys for the current area |
Use j/k and gg/G to move. Enter, o or l opens a row, returning to a
window already showing it or opening a new tab. s, v and t open it in a split below, a split beside or
a new tab. Directories and headings fold and unfold; h goes back out.
Files open in Neovim or a viewer for their kind. x closes what a row shows
without ending its session or shell. n, $ and e start a session, shell
or Neovim in the selected directory.
A Neovim run in Adroit, opened from the tree or started in a shell, keeps the colorscheme its own configuration chooses. To have it draw in the console's theme, and follow the theme as it changes, add this to the Neovim configuration on the work machine:
if exists('$ADROIT_THEME_FILE') | colorscheme adroit | endifThe adroit colorscheme comes with Adroit; nothing needs to be installed. See
Neovim in the theme's colours.
In a session's console, i starts writing in the prompt. Vim motions, search
and selection read the console through Neovim; y copies and q returns to the
live console. Ctrl+g i passes keys directly to the agent until Esc.
When an agent waits on a choice or permission, its console takes the answer
directly. A shell takes input directly too.
The prompt uses Neovim. Ctrl+Enter sends it; unsent text and attachments stay
with the session or draft as you switch tabs. Paste or drop images to attach
them. @ completes sessions and paths, and / offers the selected agent's
commands and skills where supported. On an empty prompt, Tab can accept the
agent's suggestion; with text in the prompt, it is Neovim's.
See the prompt, key configuration and the complete key reference for the controls and agent-specific behavior. Bindings can also be changed in Settings.
Every session Adroit starts has the adroit MCP tools: sessions, models,
start_session and send. It can find the sessions already working in a
repository, ask what they know, and open a separate line of work in another
session, optionally in a new worktree.
Each session answers to you. Work that belongs to it stays with it and its agent's own subagents; another Adroit session is a peer you can read and steer directly. See sessions that open sessions.
Sessions can inspect named terminal resources with
adroit terminal list --json and
adroit terminal screen --terminal <resource-id>. A session's programs can
show images through the kitty graphics protocol. See
terminals and console content.
To keep separate groups of sessions, use adroit --instance <name>. Each
instance has its own hosts and sessions; settings and keys are shared.
adroit --new-window opens another window of the current instance.
Enter the development shell with nix develop (or copy .envrc.sample to
.envrc and run direnv allow), then:
just fmt # format every source
just ci # format check, lint and tests, as in CIFor a machine that only runs the hosts and session commands, build without the desktop window:
nix develop -c cargo build --release -p adroit --no-default-featuresThat executable serves adroit host and adroit daemon and runs the session,
terminal and MCP commands. It refuses requests to open a window or take editor
input. On the work machine it reaches that machine's native sockets.
just test-headless checks this build, including a terminal kept through replacing
its work host.
To use a window on another Mac, run the terminal host, the work host and the
gateway as services on the work machine. adroit remote enable registers all
three as the user's services, with the PATH the login shell has. The service
environment must find the agents, git, jj and any programs its sessions use.
On macOS, run it with the adroit inside Adroit.app. Replacing the work host
leaves terminals running; replacing the terminal host ends its programs.
Pair the client with the work machine: run adroit connect pair <address> on
the client, then adroit remote pair on the work machine and type the code the
client shows. The client adds an environment for the work machine, which every
window lists; check its connection with adroit connect first if you like.
Adding an environment from below the main window's tree pairs too, listing the
work machines announcing themselves on the local network.
See remote hosts for the configuration, recovery
workflow and the remote window's restrictions.
The tests isolate their state and remove inherited Adroit assignment variables, so they can run from an Adroit session. Native integration tests need permission to create temporary Unix sockets.
The concept explains the product,
ADRs record decisions, and
specifications describe the behavior. The generated
key and
settings references come from the code;
regenerate them with just references when changing their definitions.
MIT. See LICENSE.