Skip to content
Nocturnal
Go to the app

Agents

A session is one agent conversation tied to a project directory. The dashboard is the place you start, watch, stop, and continue it. The model you pick decides which provider CLI runs it — Claude Code or OpenAI Codex. See Model providers and API keys.

Launch

Plus in the agents list creates a client-only draft. Sending the first message runs agent.new and promotes the draft. Follow-ups use agent.continue. Older or archived sessions jump back to the top when you send again.

New and follow-up runs queue per project so you can keep adding prompts without two Claude processes editing the same tree. The next one starts when the current run exits. Right-click a queued session (or use Run now on the composer) to start it immediately beside whatever is already working. agent.stop on a queued session just takes it out of line.

You can keep typing on a session that is already working. Send becomes Queue and the prompt sits in an inbox above the composer. Edit or remove a waiting message there (agent.pending). When the run finishes, Nocturnal continues the same chat before it starts the next waiting agent. Stop leaves those messages in place so you can start them when you want. Archive or Remove from queue drops the inbox.

Loop sits next to Send. After each finish, or on a schedule (every hour, every weekday, …), with a count or until you stop. The first send is now. See Loop for the calendar-style options, what happens if Nocturnal was down, and CLI / MCP. Progress shows on the chat and the agents list. Stop loop cancels remaining repeats without interrupting the live run.

Plain click opens a session in the project's one agent tab. ⌘/Ctrl-click, Shift-click, or middle-click opens another. The top-right of the chat (and the list context menu) always offer Open in Terminal and Open in IDE. Open in Terminal (and Copy resume command) continues the chat in whichever CLI answered last — claude --resume … for Claude, codex resume … for Codex — because each CLI only holds the turns it ran.

The list makes status obvious: a pulsing orange orb while a session is working, a clock plus "Waiting" when it is queued behind another agent, an orange ? when it needs you, and a blue unread dot after a finish you have not opened. That read state lives on the session (seenAt), not in the browser, so a restart or another window does not mark the whole archive unread. Right-click a finished chat (long-press on a phone) and choose Mark as unread to put the dot back, on the chat and its project, until you open it again. The project rail uses the same priority on the right (running → queued → unread). Live ports show as a green line on the left of the rail row.

Mode and model sit on the composer:

  • Agent — existing permission setting (Claude --dangerously-skip-permissions, or the Codex workspace sandbox, when auto-accept is on)
  • Ask — read-only: write tools disallowed on Claude, --sandbox read-only on Codex
  • Plan — Claude --permission-mode plan; on Codex, read-only with a plan-mode prompt. Either way the plan is saved to the project
  • Model — opens a picker with two parts: the model, and its strength. Claude Auto (opus / sonnet / fable) follows the latest in that family; pin a version such as Opus 4.8 or Fable 5.1 to stay on it. GPT models run through Codex instead. Groups whose provider is missing or signed out are marked with the reason and cannot be picked

Strength is how hard the model thinks on a run. Deeper costs more and takes longer; Default leaves it to the model, which is usually right.

The two providers differ here, and the picker follows each one rather than assuming they match. Claude takes the same five levels for every model — Low, Medium, High, Extra high, Max. Codex publishes a list per model, so the picker shows that model's own: GPT-6 Astra goes up to Ultra, GPT-5.5 stops at Extra high. Ultra is Codex-only. Switching to a model that does not offer your current level drops back to that model's default rather than failing the run.

Defaults come from Settings (agentDefaultMode, agentDefaultModel, agentDefaultEffort). The session stores the per-send override. Each row and the chat header show that session's spend. The context meter is occupancy of that model's window (612k of 1M), not a billing total.

Claude in Chrome. Claude runs start with the browser connected by default (claude --chrome), so an agent can use your Chrome through the Claude extension. Turn it off under Strength in the model menu, or in Settings. It stays off until you turn it back on, on every device.

Transcript

Claude stream-json nests text in message.content[]. Nocturnal skips thinking/system/heartbeat lines and shows tool rows from tool_use. Codex streams its own JSON events instead — agent messages, shell commands, and file changes map onto the same rows, and its reasoning items are dropped the same way thinking blocks are. Consecutive tools collapse into "N steps". While a group is running you see the latest 1–2 steps live.

User prompts are written as kind: user on send — Claude's stream does not include them.

Files

The History sidebar on the right has a Files tab: writes and edits for the open session (not reads). Click a row to open the git diff in Nocturnal IDE (ide.open with diff: true). Overview / Versions / Commits sit next to it — see Working changes.

Stop and archive

Stop SIGTERMs the live process (then SIGKILL if it hangs) and leaves the session idle. Pending follow-ups stay; the next other queued session can start. Archive hides it from the default list; search still finds it. Archiving a queued session drops it from the line and clears its inbox.

Other devices

Sign in with your Nocturnal account, pick the computer running the project, and continue the conversation. The session runs on that laptop or desktop — not in a cloud sandbox. Phone → laptop and laptop → desktop are the same path: commands go to the engine on the target device. New chats go to the cloud by default so you can continue them. Settings → Cloud, or Keep on this Mac on one session, keeps that text on the computer. What we track is the public list.

The same session id is what you continue later. Unarchive stays on the composer. Open in Terminal and Open in IDE sit at the top-right of the chat. All launches (new, continue, adopt, version.cut) share one registry so Stop can find them.

If the provider is missing

Install that provider's CLI and log in. Nocturnal does not bundle credentials. A session fails with that hint instead of opening an empty chat, and names the CLI the model you chose needs. Model providers and API keys covers installing, signing in, and keys.