Quick start

If Nagi is not installed yet, see Install. Then start Nagi from any project directory:

nagi

Nagi launches or attaches to your default background session. You do not manage sockets. If you detach, agents keep running.

Create a workspace

When a session has no workspaces, Nagi opens one automatically. A workspace is a project-level container for tabs, panes, and agents. Give each active project its own workspace; this keeps agent state readable in the sidebar.

Use the mouse

Nagi is mouse-native, so start by clicking. Click panes, tabs, workspaces, and agents to focus them. Drag split borders to resize. Right-click for context menus, including splitting panes and creating tabs. Drag-select text to copy it to your clipboard; double-click a token to copy it directly. Copying does not require Ctrl+C.

Ctrl-click opens pane links when your terminal sends the modified click to Nagi. This works for OSC 8 hyperlinks and visible http:// or https:// URLs. On macOS, use Ctrl-click for Nagi-handled pane links while mouse capture is enabled; Cmd-click is only available through the terminal-native bypass path, such as Shift-Cmd-click or ui.mouse_capture = false.

If you configure ui.right_click_passthrough_modifier, that modifier plus right-click sends right-click, hold, and drag gestures to mouse-reporting pane apps.

Run an agent

Start your coding agent in a pane:

claude

Or codex, pi, opencode, or any other supported agent. Nagi detects it automatically. The sidebar shows whether each agent is working, blocked, done, or idle — across every workspace, so you always know which project needs you.

For managed missions, run nagi doctor before starting. The current tested runtime set is Codex 0.144.5, Claude Code 2.1.212, and OpenCode 1.18.3. Other versions can still run in normal terminal panes, but Nagi does not claim managed-provider compatibility until that exact runtime passes the conformance suite.

Keyboard control

Keyboard control is optional; the mouse covers everything. Press ctrl+b to enter prefix mode, then press an action key.

Common actions:

Action	Key
Split right	`prefix+v`
Split down	`prefix+minus`
New tab	`prefix+c`
Next / previous tab	`prefix+n` / `prefix+p`
Workspace navigation	`prefix+w`
New workspace	`prefix+shift+n`
Detach client	`prefix+q`

New to the prefix idea? Keyboard explains what it is, why multiplexers use one, and how to go prefix-free. Press prefix+? inside Nagi to see every active binding, and prefix+[ to copy from the keyboard in copy mode.

Detach and come back

Press prefix+q or simply close your terminal window. The Nagi server and every agent keep running. Run nagi again to reattach to the same session.

To actually end the session and stop its panes:

nagi server stop

Where next

Concepts — the workspace, tab, pane, and agent model in two minutes.
How to work with Nagi — local, SSH, phone, and nagi --remote workflows.
Agents — supported agents, detection, and integrations that improve state accuracy.
Configuration — keybindings, themes, notifications, and everything else.