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.
| State | Pane title and tab | Home list | Meaning |
|---|---|---|---|
| working | a 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.
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
| Agent | Settings file (the same on Windows, Linux and macOS) |
|---|---|
| Claude Code | ~/.claude/settings.json |
| Codex | hooks.json in $CODEX_HOME when that names an existing folder, else ~/.codex |
| GitHub Copilot | noble.json in $COPILOT_HOME/hooks when set, else ~/.copilot/hooks |
| OpenCode | plugins/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:
- Claude Code and Codex: a hook group that also holds your own hook keeps that hook.
- GitHub Copilot:
noble.jsonis deleted only when nothing but its version key is left; otherwise it is written back without NOBLE's entries. - OpenCode:
plugins/noble.jsis deleted only when it is NOBLE's own file. Another file of that name is left alone. - Antigravity CLI: the
noblekey goes when nothing but itsenabledflag is left; your own handlers and keys stay. - Cursor CLI: only NOBLE's entries go. An event list left empty is removed, and
hooksgoes when nothing is left in it;versionand your own entries stay.
Per agent
- Claude Code reports prompts, stops, notifications, session start and end, subagent start and stop, permission requests and
StopFailure(an API error or a rate limit, shown as an error). Only a permission request, a question and an agent waiting for input show as needs you, at once. Other notifications (auth, quota auto-resume, plugin notices) leave the state alone, and so does the idle reminder. Answering a question or permission prompt in the pane (Enter, a digit, y or n) reads as working at once, not at the end of the turn. A compaction in the middle of a turn keeps the state. The notices name the request: "Claude asks to run Bash" or "Claude asks a question". - Codex reports prompts, stops (an interrupted turn included), permission requests, session start and end, and subagent start and stop. It has no failure event, so it never shows an error. Codex runs user-level hooks only after you trust them once: after an install NOBLE says "Codex: open /hooks once to trust NOBLE's hooks". Open
/hooksin Codex and trust them; NOBLE cannot do this for you. - GitHub Copilot reports session start and end, prompts, stops, notifications, permission requests and errors. Its notices read "Copilot asks to run <tool>", "Copilot asks for permission", "Copilot asks a question" or "Copilot stopped with an error". Its idle and completion notices are not recorded. It has no subagent hooks: NOBLE does not install them, since a subagent start carries no id to pair its stop with, and it removes the ones an older version wrote.
- OpenCode loads a small plugin that forwards session status (busy and idle), session idle and errors, and permission requests and replies. Token-level events are not forwarded, and the plugin runs NOBLE only inside a NOBLE pane. A subagent (a child session the task tool starts) leaves the pane's state alone, so the pane stays working while the main session works, and it never becomes the pane's resume id. Its permission requests still show needs you.
- Antigravity CLI (
agy) reports the start of a session (idle), each model call (working) and each stop (idle). A stop that reports an error shows as an error, with the error text when agy gives one. agy has no permission, notification, subagent or session-end event, so NOBLE never shows needs you for it, and a turn that waits for an approval still reads working. NOBLE registers no PreToolUse hook, since its answer decides whether the tool may run. An entry you turned off in agy's/hooksview counts as off and stays off at each start; installing turns it on again. - Cursor CLI (
cursor-agent) reports the start of a session (idle), each prompt, each tool call (postToolUse, plus shell commands and file edits) and each stop (idle). A stop whosestatusiserrorshows as an error; Cursor does not document its stop status values, so this depends on what the CLI sends. The CLI runs only some of Cursor's hook events, and none of the ones NOBLE registers reports a question or a permission prompt, so NOBLE never shows needs you for it. NOBLE registers no permission hook (beforeShellExecution, preToolUse and the rest), so Cursor's own approval prompts are not touched. A turn with no tool call may not show as working at all, because the CLI may not send the prompt event.
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:
- Windows: always. NOBLE passes Shift+Enter on in the form each program reads.
- Linux and macOS: when the terminal NOBLE runs in supports the kitty keyboard protocol, such as kitty, Ghostty, WezTerm or foot. NOBLE turns the protocol on at startup and off on exit.
- Any other terminal on Linux and macOS: NOBLE only receives a plain Enter, which submits the prompt.
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:
| Agent | Resumed with | Left alone when the launcher already has |
|---|---|---|
| Claude Code | claude --resume <id> | --resume -r --continue -c --session-id |
| Codex | codex resume <id> | resume |
| GitHub Copilot | copilot --resume=<id> | --resume --continue |
| OpenCode | opencode --session <id> | --session -s --continue -c --fork |
| Antigravity CLI | agy --conversation <id> | --conversation -c --continue |
- The id comes from the agent's hook payload, so that agent's status hooks must be on. NOBLE keeps only an id of 1 to 128 letters, digits,
-and_. - The pane must have been opened from a launcher that starts that agent: quick launch on Home, the Home launcher keys or the palette. A launcher with extra arguments still counts as the agent it starts. An agent you typed by hand into a shell pane restores as a plain shell.
- It applies to session restore at launch (
restore_session), to saved workspaces and to Reopen Closed Tab (prefix T). - NOBLE does not check that the saved conversation still exists. With the setting off, panes start fresh and no id is saved.
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.
- The glyphs: ● working (running, busy, working, active, starting), ◆ needs you (waiting, needs_input, blocked, idle, paused), ○ done (done, completed, finished, stopped, exited), ✗ failed (failed, error, crashed, killed), and · for any other state.
- Finished and failed sessions stay listed for 24 hours after they started. Running ones always stay.
- A click runs
claude attach <id>in a new tab, in the session's folder when it exists (else your home folder). The tab is titled "<folder> · claude bg".
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.
| Action | Key | What it does |
|---|---|---|
| Jump to Previous Command, Jump to Next Command | prefix . (pane menu), or the palette | Centers the previous or next command in the view. At the edges the toast says there is none in this pane. |
| Copy Last Output | pane menu, or the palette | Copies the output of the newest finished command, without its trailing blank lines. |
| Send Last Output to Agent | y after the prefix | Pastes 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".
- The text starts with a context line such as
~/app $ cargo test → exit 101. It is capped at the newest 400 lines and 64 KiB; when lines are cut, a line "[… N earlier lines cut]" follows the context. - It is pasted, never run. NOBLE never presses ⏎: read the text and press it yourself. Focus moves to the agent pane.
- A multi-line paste into a shell that has not turned on bracketed paste asks first, with "N lines — each may run as a command. Paste?".
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.
$ noble doctor $ noble doctor --config <path>
Windows, Linux and macOS
| Windows | Linux | macOS | |
|---|---|---|---|
| Hook command | when 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 plain | as on Linux |
| Command blocks | PowerShell (pwsh and Windows PowerShell) yes; cmd.exe no; WSL bash.exe no; Git Bash as bash | pwsh, bash 4.4 or newer, zsh and fish | zsh, fish and PowerShell; bash 3.2 gives exit codes but no blocks |
| Progress and notifications to the terminal | the title always; progress only with WT_SESSION or TERM_PROGRAM; notifications only with TERM_PROGRAM | always 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).
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.