Docs

AI agents

NOBLE does not run an agent of its own. It hosts the ones you already use (Claude Code, Codex, GitHub Copilot, OpenCode, Antigravity CLI and Cursor CLI), shows what each one is doing, and brings their conversations back after a restart.

What NOBLE shows

Without help NOBLE can only guess whether an agent is busy. With the optional status hooks on (see below), each agent reports its prompts, answers, permission requests and errors, and the state appears on the tab dots, in each pane's title and on Home. Antigravity CLI and Cursor CLI report less (see Per agent below), so NOBLE never shows needs you for them.

StatePane title and tabHome listMeaning
workinga spinner, or a still …●The agent is busy on a prompt
needs you◆◆The agent asks for permission or a question
your turn●○The agent finished its answer and waits for your next prompt
error✗✗The last turn failed (Claude Code: an API error or a rate limit)
running○●An agent that NOBLE knows by name but that has no hooks: its state is not known

A pane title leads with the state, for example ⠋ claude · working 2m +2 (the spinner, how long it has been working and its running subagents), ◆ claude · needs you or ● claude · your turn. Each tab starts with a dot for the most urgent state among its panes, in this order: needs you, error, your turn, working, running.

Note: A background tab lights up the moment an agent asks for permission, so you can keep working elsewhere. A Claude session stays working while its subagents still run, and Claude's idle reminder does not count as needing you.

Turning the status hooks on

Turn them on in Settings → Terminal → Agent status hooks. The row appears when at least one agent is installed on this machine (its command is on your PATH) or already has hooks, and it reads "N of M on". It opens the AGENT STATUS HOOKS popup with one row per agent, in the order Claude Code, Codex, GitHub Copilot, OpenCode, Antigravity CLI and Cursor CLI. Each row says on, off or not found. Press ⏎ or space on a row, or click it, to install or remove that agent's hooks. ↑ ↓ (or k j, or tab) move between the rows, and esc closes the popup.

The first time you launch an agent that is installed but has no hooks, a notice appears at the bottom right: "Show agent status in NOBLE?" with enable, which installs the hooks of every installed agent that lacks them. The offer is shown only once. While it is showing, the palette also has Enable Agent Status Hooks and Dismiss Agent Status Offer.

Hooks apply to sessions that start after the install, so restart an agent that is already running. Apart from that one offer, NOBLE writes them only when you turn them on or off. At each start it adds the events a newer NOBLE has to the hooks you already installed.

Where the hooks are written

AgentSettings file (the same on Windows, Linux and macOS)
Claude Code~/.claude/settings.json
Codexhooks.json in $CODEX_HOME when that names an existing folder, else ~/.codex
GitHub Copilotnoble.json in $COPILOT_HOME/hooks when set, else ~/.copilot/hooks
OpenCodeplugins/noble.js in $XDG_CONFIG_HOME/opencode when set, else ~/.config/opencode
Antigravity CLI~/.gemini/config/hooks.json, NOBLE's entry under its own noble key (no documented variable moves it)
Cursor CLI~/.cursor/hooks.json, NOBLE's entries in its hooks lists (the same path on every platform)

On Windows these live in your user profile (%USERPROFILE%\.claude, %USERPROFILE%\.codex, and so on). Each agent runs noble hook <event>, with --agent <id> for the agents other than Claude Code. The command is plain noble when that is on your PATH, otherwise the full path of the running NOBLE. The hook writes one small file per pane into NOBLE's data folder and exits; outside NOBLE it writes nothing (Antigravity and Cursor still read a JSON reply from stdout, which NOBLE prints there too), and it never reports an error back to the agent.

Installing keeps your own hooks and writes a backup once, next to the file (settings.json.noble-bak, hooks.json.noble-bak, noble.json.noble-bak). A settings file that does not parse is never written; NOBLE says "cannot parse" with its path. The OpenCode plugin gets no backup.

Turning an agent off removes only NOBLE's entries:

Per agent

Shift+Enter in Claude Code and Codex

Shift+Enter starts a new line in Claude Code and Codex inside NOBLE instead of submitting the prompt. Where it works depends on the platform:

Ctrl+Enter is passed on the same way; what it does is up to the program. If Claude Code misses NOBLE's answer to the protocol query (it can, in its first-run folder-trust dialog), Shift+Enter still starts a new line.

Notices

When an agent in a background tab needs you, errors or stops, and [terminal] notify is on (Settings: Notify from background tabs), NOBLE shows a notice: <tab> · <message>, such as "api · Claude asks to run Bash". Without a message it says the agent needs your attention, stopped with an error, or finished. The tab gets its marker, and the notice reaches the outer terminal too (see Outside NOBLE). A permission request and the notice that follows it count as one. Messages are cut at 120 characters.

Conversations come back

With Resume agent conversations on (resume_agents under [terminal], on by default), a restored pane whose launcher starts an agent picks its last conversation up again, using the launcher's own command:

AgentResumed withLeft alone when the launcher already has
Claude Codeclaude --resume <id>--resume -r --continue -c --session-id
Codexcodex resume <id>resume
GitHub Copilotcopilot --resume=<id>--resume --continue
OpenCodeopencode --session <id>--session -s --continue -c --fork
Antigravity CLIagy --conversation <id>--conversation -c --continue

The Home continue line

When the selected project has a Claude Code conversation in its folder and a claude launcher is installed, its Home card shows a ↻ Continue claude · 2h ago button (or just now). The time is the modification time of the project's folder under ~/.claude/projects/. NOBLE reads no transcript, and the line needs no hooks. A click opens a tab in the project that runs claude --continue; the launcher's own arguments stay, and --continue is not added when the launcher already picks a conversation.

Claude background sessions

Claude Code's background sessions (started with claude --bg) are listed on Home in the AI usage panel, under the agent sessions and a BACKGROUND header, at most three rows: ● <name or folder>, with the state at the right edge. NOBLE runs claude agents --json --all only while Home is open and only with a claude launcher installed: about once a minute (every three minutes on battery). A failure shows an empty list.

Note: NOBLE lists background sessions and attaches to them. It does not start them.

Command blocks

PowerShell (pwsh and Windows PowerShell), bash 4.4 or newer, zsh and fish mark where each command starts and ends. NOBLE keeps the last 200 commands of each pane as blocks, and each block keeps the typed line above it as its context (for example ~/app $ cargo test). cmd.exe sends no marks, so it has no blocks and no exit code: its title shows only how long a command took. bash 3.2 (the /bin/bash of macOS) sends no start mark, and WSL's bash.exe gets no integration, so on those there are no blocks to jump to or copy. Blocks are dropped when their lines leave the scrollback or the pane is reflowed to a new width. None of this is configurable.

ActionKeyWhat it does
Jump to Previous Command, Jump to Next Commandprefix . (pane menu), or the paletteCenters the previous or next command in the view. At the edges the toast says there is none in this pane.
Copy Last Outputpane menu, or the paletteCopies the output of the newest finished command, without its trailing blank lines.
Send Last Output to Agenty after the prefixPastes the output into an agent pane, led by a context line. Details below.

Jump to Previous or Next Command and Copy Last Output have no default key. Bind them under [keys.prefix_bindings], for example "key" = "copy_last_output". A click on a failed command's ✗ badge in the pane title scrolls to its output.

Send Last Output to Agent

Prefix y sends the focused pane's selection if there is one, or else the newest finished command's output. The target is the first other pane in the same tab with a detected agent; failing that, the agent pane you sent to last. With no such pane NOBLE says "no agent pane to send to: open one in this tab".

Progress reports

A program can report its progress with OSC 9;4, which Claude Code does. The pane title shows the percentage (42%), a spinner while busy work has no percentage, ✗ on an error and ‖ while paused. The tab gets a busy dot. The report ends when the program sends state 0 or when the shell shows its next prompt. An agent without hooks counts as working while its report says busy.

Outside NOBLE

The window NOBLE runs in shows the agents too. While any agent needs you, the window title reads NOBLE · ◆ 1 (the dev build: NOBLE dev · ◆ 1) with the number waiting, and the terminal gets a paused progress report (OSC 9;4;4). Both are cleared as soon as nothing waits. Background alerts also go out as one desktop notification, OSC 9 or OSC 777 chosen from the terminal NOBLE runs in (OSC 777 for foot, rxvt-unicode and Konsole, OSC 9 elsewhere), with a bell, while NOBLE is not in front and notify is on. A terminal that understands both shows it once. The window title is sent on every platform. On Windows the progress report goes only to Windows Terminal (WT_SESSION) or to a terminal that sets TERM_PROGRAM, and the notifications only when TERM_PROGRAM is set. The title the terminal had before NOBLE is restored on exit.

Quota warnings

The agent's launcher on Home shows ⚠ while its quota is full, launching it says when the quota resets, and the pane title shows the fullest window past warn_at (⚠ 5h 92%). These use the numbers NOBLE already has, so they need no request. The providers and the warning settings are on AI quota.

noble doctor

noble doctor prints a report for bug reports. It opens no terminal, writes no file and changes no settings file. Its Agent hooks section lists each agent as installed, not installed, not found (no settings file and not on your PATH) or unknown (the settings file cannot be read or parsed). It never prints a token or a key; AI providers are shown as detected or not.

shell
$ noble doctor
$ noble doctor --config <path>

Windows, Linux and macOS

WindowsLinuxmacOS
Hook commandwhen noble is not on PATH, the path with forward slashes, such as C:/…/noble.exe hook stop, unquoted when it has no spaces or shell syntax (the folder's 8.3 short name is used where the volume has one) and double-quoted otherwise. Copilot's PowerShell entries put & before a quoted path. Antigravity and Cursor have one command field per hook, so there a quoted path may work only in shells that take it as written (cmd.exe, Git Bash); which shell runs these hooks is not documented. A plain noble on PATH stays plain.a single-quoted path when noble is not on PATH; a plain noble on PATH stays plainas on Linux
Command blocksPowerShell (pwsh and Windows PowerShell) yes; cmd.exe no; WSL bash.exe no; Git Bash as bashpwsh, bash 4.4 or newer, zsh and fishzsh, fish and PowerShell; bash 3.2 gives exit codes but no blocks
Progress and notifications to the terminalthe title always; progress only with WT_SESSION or TERM_PROGRAM; notifications only with TERM_PROGRAMalways sent (the terminal decides)always sent (the terminal decides)

Resume, the Home continue line, background sessions, quota warnings, noble doctor and the Settings popup work the same on all three. The claude and other agent commands are found on your PATH. On Windows NOBLE also looks for agy and cursor-agent in the folders their installers use (%LOCALAPPDATA%\agy\bin, %LOCALAPPDATA%\cursor-agent).

Settings: The switches are Agent status hooks (in Settings, Terminal), Resume agent conversations (resume_agents) and Notify from background tabs (notify), which also controls the notices and the outer-terminal alerts above. Command blocks, progress reports, background sessions and noble doctor have no config keys.