Skip to content

Latest commit

 

History

History
654 lines (573 loc) · 42.7 KB

AI_AGENTS.md

File metadata and controls

654 lines (573 loc) · 42.7 KB

AI agents

The AI panel sits to the right of the workspace and stays available when no terminal tabs are open. Open it from the footer, Window → AI Agents, or Ctrl+Alt+B (Cmd+Alt+B on macOS). Window → Layouts → Swapped sides moves it to the left of the tabs and the sidebar to the right, and Default moves them back; on the left, the history column opens on the panel's left too. Settings remains available from Session → Preferences → Settings and Ctrl+, (Cmd+, on macOS). The footer no longer has a Settings button.

Create a chat with Claude, Codex, Hermes, or a custom ACP executable; the built-in agents show their brand marks in the menu, the panel header, chat history and AI Settings; a custom agent that runs a built-in agent's adapter (for example a different claude-agent-acp version) shows that agent's mark, other custom agents show a generic icon. A working chat shows a spinner in history; its pin remains a separate indicator. Ctrl+N (Cmd+N on macOS) in the panel starts a new chat with the agent the last chat was started with (remembered in agents.toml; before any chat, the default agent); the new-chat menu shows the shortcut beside that agent. A chat the panel shows connects at once, so its model and options can be chosen before the first message ([ai.sessions] warm_start = false connects on the first message instead); the tool listener starts only when needed. Expanding the panel replaces the central workspace area while keeping navigation and the footer accessible. Navigation can be switched, hidden or shown while chat stays expanded. Restoring chat keeps its previous docked width and the navigation width. The control does not change the operating system's fullscreen state. Chats are saved and come back after a restart (see Chats and history). Model favorites are stored separately in agents.toml under the state directory.

Agent setup

The built-in commands use explicit adapter versions:

Id Command Authentication environment inherited by default
claude npx -y @agentclientprotocol/claude-agent-acp@0.85.1 ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, CLAUDE_CONFIG_DIR
codex npx -y @agentclientprotocol/codex-acp@2.1.1 OPENAI_API_KEY, OPENAI_BASE_URL, CODEX_HOME
hermes hermes acp HERMES_HOME

Install the appropriate CLI/adapter prerequisites yourself. The Claude adapter requires Node.js 22 or later; Codex also requires a working Node.js/npm setup. Hermes must be installed and available in PATH. First startup through npx may need network access to download the pinned package. These pins describe the configured defaults, not proof that all agents have been authenticated or successfully tested on your machine.

Desktop applications may receive a different PATH from an interactive shell, particularly with nvm. When a bare command such as npx is not on PATH, Nocterm also looks in the usual Node.js locations: nvm-windows, Volta, Program Files\nodejs, the per-user Node.js install, npm's global directory, Scoop and Chocolatey on Windows, and Homebrew and Volta on macOS. Set an absolute executable path in AI Settings when the program still cannot be found. On Windows agents start without a console window. Arguments are a JSON array of individual strings; Nocterm does not run them through a shell. A blank override keeps the built-in value; an empty arguments array removes the built-in arguments. Custom agent ids use letters, numbers, underscore or dash and need an executable.

AI Settings (Settings → AI agents) controls the master switch, default agent, working directory, agent permissions, terminal access approvals, secret filtering, isolation and the agents themselves. Every change saves itself; text fields save when typing pauses, on Enter and when they lose focus, and invalid text is kept with its error rather than saved. Each agent folds open to show its name, executable, arguments and environment; a custom agent is added with an id and an executable. Disabling or removing an agent retires its current connections. Changes to an agent's command, arguments or environment apply to new connections; existing chats keep their current process. A custom working directory must be absolute; the default is a private agent-workspace directory in application state.

Environment overrides are plain text in settings: do not store secrets there. Recognized credential variable names (such as API key, token and password names) are rejected as overrides; arbitrary secret values cannot be classified. Use inherited environment names for existing API key variables you deliberately want an agent to receive for authentication. The process environment is cleared and rebuilt from allowed desktop/runtime variables plus explicitly inherited names and validated overrides. SSH agent, GPG agent, Nocterm internal variables, and process injection variables are blocked even when explicitly requested.

Chats and history

Each chat is saved as one JSON file in agent-chats/ under the state directory (private 0700 directory, 0600 files). A chat is written when you send a message, when the agent finishes a reply, when its title, name or pin changes, when it fails, and once more when the application quits. Unsent composer text belongs to its chat and is saved in coalesced batches after 300 ms, as well as when leaving the chat or closing the application. Draft-only chats appear as New Agent and restore their text when reopened, without sending it. Only truly empty chats are dropped when you start or open another one. Sending an ordinary message clears its draft after acceptance; temporary queue edits preserve the original unsent text.

A saved chat holds the agent id, the agent's title, your name for it, the pin, the agent session id and its working directory, the last model, the chat's own configuration (mode, model, effort and the agent's other options), unsent text, and the transcript: your messages, the agent's replies and reasoning, and tool calls with the input and output the agent reported for them. The terminal descriptors sent with each prompt are not saved, but a tool call's output can contain terminal text. Images over 512 KiB are replaced by a note, only the last 20,000 entries of a chat are kept, and at most 200 chats are restored, pinned ones first.

The title's ellipsis menu copies the history ID or the complete loaded conversation as readable text, including reasoning and tool inputs/results. Binary attachments appear as references. Copying uses a bounded snapshot and formats it in the background; unsubmitted drafts and queued messages are not part of the conversation.

The attachment picker always starts with Local terminal. In the General chat context, choosing it opens a shell when none is running. Other contexts use an existing shell from their original workspace. Each saved server appears once, regardless of how many tabs use it; attaching it covers all its sessions. A background session can still be shown in a tab from that server's row. Folder attachments remain available.

After a restart, saved chats appear in the history without starting their agent. Browsing the history does not start an agent or MCP. A chat connects as soon as it is shown, whether new, saved or loaded from the history, unless warm_start is off; then it connects on its next message. A restored queue still waits for send-now. Leaving a chat before the runtime admitted it withdraws its request unless it has messages to send. Opening a saved chat, or sending a message, reopens its session with session/resume (no replay) or session/load, whichever the agent advertises; a message's queue entry is saved before the agent starts. Chats containing only a draft or queued messages start a new session even if an older saved record includes an empty provider session id. An agent without restoration, or whose saved session no longer exists, starts a new session. A bounded copy of the saved user/assistant conversation accompanies the next prompt, and the status explains the fallback. Temporary restoration errors are retried once and retain the session descriptor; authentication keeps it for retry after sign-in. A fork whose copy the agent cannot make starts a new session with the copied conversation instead of failing. A chat whose session failed reconnects with the next message; after a second failure without a completed turn it stops reopening that session and starts a new one with the saved conversation. Attached connections and groups survive restarts; a remote terminal attachment restores through its saved connection. Local shells cannot be reconnected from an earlier process. Saved chats load into the first window that opens the panel, so two windows never write the same file. Turning AI off and on again shows them only after a restart.

The clock button opens the history as a column beside the chat rather than in its place: the panel widens by the column's width, and closing it gives the width back. Dragging the divider resizes the column; the panel's and the column's widths are remembered across restarts in layout.json in the state directory, with the sidebar's. On the left of the window the column is on the chat's left. Opening a chat from the history keeps the column open. With no chat open, the history fills the panel.

The history lists pinned chats first, then the most recently changed. Its search field matches titles, names and the text of messages, ignoring case. Each row opens its chat anywhere it is clicked; its … menu offers:

Action Effect
Rename Edit the name in place; Enter or leaving the field saves, Escape cancels. An empty name returns to the agent's title.
Fork A new chat with the same messages and attachments, opened at once. The agent continues in a copy of the session (session/fork) when it advertises forking; otherwise the copy starts a new session with bounded saved conversation context.
Pin / Unpin Pinned chats show a pin before the title and stay at the top.

The trash button deletes the chat and its file.

Your messages and the agent's replies can be selected and copied with the mouse. Hovering a message shows, under it, when it was sent (the clock time today, the date on earlier days; chats saved before times were kept show none), a Copy button that copies the message's text, and a Fork button. Forking from the last message is the same as Fork in the history menu. Forking from an earlier message copies the chat up to and including that message, and the copy starts a new agent session: the agent cannot be made to forget what came after, with bounded saved conversation context accompanying its next prompt.

Attached images are shown as a row of thumbnails above the message field, each with its own remove button, and in a row inside the sent message. Tool output is shown as the text the tool returned, wrapping long lines, and as JSON only for other content.

Typing / offers the commands this ACP agent advertises, including descriptions and input hints. Up/Down select; Tab inserts the selected command, and further Tab/Shift+Tab presses cycle the original matches without leaving the composer. Enter or a click confirms the selection with the caret at the end. Escape closes the suggestions. Rows show a short single-line summary and follow the keyboard selection as you move through the list. Hovering a row shows its full description and arguments. A recognized command followed by a space becomes a highlighted token inside the message field; hovering that token opens the same compact card. There is no automatic description overlay. Clicking the token selects it for replacement; Backspace/Delete remove it as a unit, and undo restores edits. Arguments remain ordinary text, and the sent prompt retains the original /command args text. For model selection, the composer dropdown browses and searches the models the agent advertises; its tooltip reports their count. /model list is not invented or intercepted: each agent decides what its command arguments mean. An advertised /command and any arguments are sent as the first prompt block, without terminal instructions or history prepended. Unknown slash names and paths such as /var/log/nginx/error.log remain ordinary messages with their terminal context and saved history. Unadorned administrative commands remain a single text block; any saved-conversation fallback waits for the next ordinary question. This pending context is saved across further restarts and successful native resumes, then cleared on disk after a completed ordinary turn.

You can send another message while the agent works. It joins this chat's FIFO queue with its text, images and attachment snapshot. The strip peeking above the composer shows the count; clicking it unfolds the complete queue. Its height fits the laid-out text, images and attachments; large queues scroll within a maximum height. The arrow sends a selected message next: it cancels the current response and waits for cancellation to finish before sending. Other messages keep their order. The pencil edits a queued message in place and restores your unsent composer draft after saving or cancelling. The bin removes a queued message without sending it; the one being edited cannot be removed. Send-now controls are disabled while editing. Queued images are saved in full; a message exceeding the saved chat's 32 MiB limit is rejected with its draft intact. Restored queues wait for an explicit send-now action. Stopping, authentication failures and session failures retain and pause the remaining queue. A disk-write failure also pauses the queue and reports the problem. Finishing or cancelling an edit preserves any stop or error that paused the queue during editing.

Streamed replies reveal gradually and fade in, with reduced-motion preferences showing new text immediately. The transcript follows the latest response until you scroll up; Jump to latest resumes following. Reasoning and tool details use the secondary text color.

Stop cancels the current turn (session/cancel). Updates the agent sends after answering the cancellation are dropped, and the next prompt continues in the same session. When the session itself is gone (the agent exited, failed, or did not answer the cancellation within 10 seconds) the queue pauses; the next message or Restart chat starts a new agent process and keeps the chat, its name and its history file.

Context and controls

A new chat attaches the active terminal, if one exists. The + menu of the composer has two parts:

  • Active sessions: every open terminal — your tabs, the bottom shell, and sessions agents opened in the background (with a Show button that moves one into a tab). Attaching one lets the agent use exactly that terminal.
  • Saved servers, laid out as in the sidebar: connections outside folders first, then each folder with its connections indented under it, all by name. Clicking a server attaches it; clicking a folder attaches every server in it. A green dot marks servers with an open session. The arrow (↗) beside a server opens it in a new tab through the normal connection and sign-in flow.

An attached server (directly or through its folder) gives the agent every open session of that server, whether you opened it or an agent did. A server without a session is listed to the agent as an offline server; the agent connects to it with the open_terminal tool, in the background, without opening a tab or taking focus. If the connection needs you, the agent waits up to three minutes; only a new host key moves the session into a tab so you can answer. When the connection of an attached server's terminal drops, the agent's next call on it reconnects it in place and then goes ahead, and open_terminal reconnects a background session the chat opened instead of adding another; the agent tells you only when connecting fails. Your tab stays open either way, and local shells and one-off commands are never restarted. Background sessions a chat opened end when the chat closes or no longer attaches the server. Credentials remembered in the vault and key or agent authentication let background sessions connect without a prompt. A password, passphrase or one-time code is asked in the chat: the session stays in the background, you type the answer into the card and the agent continues. When the saved credential is in a locked vault, the card also offers Unlock vault: it opens the unlock dialog (master password or fingerprint) and the saved secret then answers the sign-in.

The agent receives explicit terminal descriptors: opaque terminal id, title, local/remote status, working directory when known, and selected connection metadata (name, group, description, host, port, user). Descriptor text is filtered and encoded as JSON context. It never serializes a complete profile, SessionSpec, Auth, credential id, private-key path, proxy configuration or shell launch. Context bytes sent by Nocterm are distinct from the agent's reported context window tokens/cost.

Modes, models, effort and image input depend on the agent's real ACP capabilities/configuration. A missing capability does not mean that a default model or token count can be invented. Model favorites are keyed by agent, configuration option and value. agents.toml also keeps the options each agent last reported and the model and reasoning effort last chosen for it: a new chat shows them before its session opens and starts with that model and effort. Each chat then keeps its own configuration, mode included, in its saved file: every session the chat opens (after idle release, a failure or a restart) is given the chat's values, one option at a time, before the first prompt; a value the agent no longer offers is skipped. Changes the agent reports itself become the chat's. Modes are kept per chat and never carried over to other chats. Image input accepts validated PNG, JPEG, GIF and WebP, at most 5 MiB per image, eight images and 20 MiB per prompt. Decoding is bounded to 4096 pixels per axis, 16 million pixels and 64 MiB allocation. Transcript previews preserve aspect ratio and alpha, fit 640 pixels per axis and encode at most 4 MiB of PNG; prompt/history encoding retains the original image.

Usage and plan limits

The ring left of the send button shows how full the agent's context window is. Clicking it opens the Context Usage card over the chat, above the composer; the ring or the card's close button hides it. The card shows what the agent reports and nothing it does not:

Section Source Agents
Percent full, used / window tokens, session cost ACP usage_update All that send it
Split of the used tokens Estimated by Nocterm Shown with the total
Session tokens: input, cache read/write, output, reasoning, total usage of the prompt response (unstable ACP) Claude, Codex, Hermes
Plan limits: 5-hour, weekly, per-model weekly, extra usage Agent metadata attached to ACP usage_update Claude, when reported

ACP reports only the total in the context window. The split into "System prompt, tools & rules", "Messages", "Reasoning" and "Tool calls" is estimated from the transcript at about four characters per token. The remainder of the reported total is attributed to the agent's own instructions and tools. When the agent has compacted its context, the transcript's parts are scaled down to fit the total. The card says the split is an estimate.

Plan limits are not standardized by ACP. Nocterm displays only limits supplied by the agent through ACP metadata:

  • Claude. The Claude adapter attaches Claude Code's rate-limit event to usage_update as _meta["_claude/rateLimit"] (window, utilization, reset time, status). Each report updates its window. Claude sends them only after replies, and not every window in every reply.
  • Codex. The pinned Codex adapter does not forward plan limits in a metadata shape Nocterm supports. The card says that the agent has not reported them.
  • Hermes and unrecognized custom agents have no supported plan-limit metadata; the card shows none. Custom launches recognized as a built-in agent use that agent's metadata shape.

Nocterm does not read Claude sign-in tokens, request private provider account endpoints or scan Codex session logs. Opening the card and finishing a prompt do not poll the provider. Authentication and subscription credentials stay with the agent; inherited configuration-directory and API-key environment variables still reach the agent as described in Agent setup. Agents and their adapters remain subject to their providers' own terms.

Limits are kept per agent for the running application, so a new chat with the same agent shows the last known values. Each limit shows the share used, a bar (warning from 70%, danger from 90% or when reached) and the time until it resets.

Terminal tools and approvals

The nocterm MCP server offers only tools for terminals and servers attached to the chat:

Tool Approval setting Bound
list_terminals None Attached terminal descriptors and offline servers only
read_terminal Ask before reading a terminal (off by default) 2000 logical lines / 64 KiB
send_input Ask before typing or running commands (on by default) 16 KiB input
run_command Live-input approval One command line, at most 16 KiB; known empty shell prompt required
exec_command Separate structured-execution approval 16 KiB program/args, 64 KiB stdin, 5 minute absolute timeout
read_command Reading approval Full 64 KiB stdout snapshot plus 4 KiB stderr tail
cancel_command Structured-execution approval One command owned by this chat
transfer_files Ask before typing or running commands, with a transfer grant for the terminal pair 1 to 64 absolute source paths, 4 active transfers per chat
read_transfer None One transfer started by this chat
cancel_transfer None One transfer started by this chat
open_terminal Ask before typing or running commands One attached offline server
list_files, read_file Ask before reading a terminal (off by default) Terminals with file_tools only; 1000 entries, text files up to 1 MiB read 64 KiB at a time
write_file, edit_file, make_directory, move_path, delete_path Ask before typing or running commands, with a file-change grant for the terminal Terminals with file_tools only; 512 KiB written, 64 KiB per edit text

The settings apply at once, including to running chats. An approval card shows the exact target and input with Deny, Allow once and Allow for this terminal (or server). A grant lasts for the chat's session: it survives later turns, and is dropped when the chat restarts or fails or when an attachment is removed. A new member of a group does not inherit an existing grant. Detaching or closing a terminal prevents further tool calls. The application checks the attachment and terminal state again after approval immediately before input. Connecting and authentication states refuse input; a closed remote terminal is reconnected first, as described above. Live run_command also rejects alternate-screen programs and unknown, busy or dirty prompts, including SSH shells without OSC 133 integration. Grants are separate for reading, live input, structured execution, file transfers and opening connections. Explicit send_input into an unknown, busy or dirty shell always needs a one-time approval, even when normal write approvals are disabled; it never consumes a remembered safe-input grant.

exec_command starts a fresh process through the exact authenticated connection of the attached terminal; local terminals explicitly use the local executor. There is no remote-to-local fallback and no inherited live-shell cwd, environment, aliases or functions. Pass program and arguments separately; local execution passes arguments directly, while SSH renders a POSIX command line. Arbitrary arguments require a POSIX-compatible remote command shell; exact argument handling is not guaranteed on Windows SSH. Use an explicit shell when shell syntax is needed. Short commands return their actual exit status. Long commands return a chat-owned command_id for read_command and cancel_command. Cancelling a read waiter does not cancel the command. Each chat allows four active commands and retains sixteen records; oldest completed records are evicted. stdout is continuously drained beyond the retained 64 KiB and marked truncated, so a noisy command can still finish and report its real status. Startup and execution share an absolute deadline.

Stop, chat closure/restart, AI disable, detachment and session replacement cancel owned structured executions. SSH cancellation sends TERM and closes that command's channel; servers may ignore signals and remote descendants may survive.

Live run_command serializes ownership across chats only while observing its result. Stop requests Ctrl-C only during an active observation that still owns the same session. Accepted human input or reconnect relinquishes ownership, so a later Stop cannot interrupt a new user command. Every observation exit releases the lease. Observation reports completion only on a confirmed shell prompt; output idle or observation timeout leave completion unknown, never invent an exit status, and do not stop the shell. A later Stop no longer controls that program. Use exec_command when execution needs a durable handle, cancellation and a deadline.

File transfers

transfer_files copies files and folders between the hosts of two terminals attached to the chat: this computer (a local terminal) to a server, a server to this computer, or a server to another server. Nocterm relays the data over the SSH/SFTP connections it already holds, so a server needs no credentials for another and the agent has no reason to run scp or rsync. Two local terminals are refused; use exec_command there.

The agent names a source terminal and absolute source paths, a destination terminal and an existing destination folder. Paths are absolute with no . or .. components and ~ is not expanded. Each source is copied into the destination under its own name; folders copy recursively. The destination folder is never created. Existing files are skipped and counted as skipped unless the agent passes overwrite. Symbolic links and special files are skipped and reported, never followed. A file is published atomically: a cancelled or failed file leaves no partial file, and files already published stay.

The copy runs in the background. transfer_files waits yield_ms (default 1000, at most 10 000) and returns a transfer_id with the current report; read_transfer returns a new report, optionally waiting while the transfer is active; cancel_transfer stops it. A report gives the state (queued, discovering, running, completed, failed or cancelled), the direction, the destination, file counts (discovered, completed, skipped, failed), byte totals, whether discovery finished and at most 16 failures with their path, operation and error. Paths and errors in a report honour the chat's secret filtering.

Limits: 1 to 64 sources per call, each path at most 4096 bytes and all sources at most 64 KiB; each chat has four active and sixteen retained transfers (the oldest finished records are evicted), and an agent can only read or cancel transfers its own chat started. Discovery stops at one million entries or 256 levels deep. Transfers share the queue and workers of the Files transfer activity, so they appear there and a long copy of yours can delay an agent's and the reverse; a full queue is an error to retry. The agent sees queued while it waits, and you can cancel an agent's transfer from the activity, after which it reports cancelled.

Approval: transfer_files follows the write policy. The card names the source and destination terminals, lists the source paths, the destination folder and whether existing files are skipped or replaced. Allow transfers between these terminals is a separate grant from execution: it covers transfers between exactly that pair of terminals, in either direction, for the chat's session. Approving a/b and c/d does not approve a/d. It is dropped, like other grants, when either terminal's session is replaced or the chat restarts. A local endpoint reads and writes anywhere you can, as exec_command on a local terminal does, so the same approval applies. read_transfer needs no approval; cancel_transfer only stops a transfer the chat started.

Lifetime: Stop, chat closure or restart and AI disable cancel the chat's transfers, and so does detaching either terminal or replacing its session. Transfers do not reconnect: if an endpoint is offline the call fails and the agent should open the terminal again and retry. Quitting Nocterm freezes and drains the shared transfer queue like Files transfers.

Files of terminals that run no programs

Some terminals serve files but run no programs: a plugin's console tab opened with files, for example a game server panel. exec_command and run_command cannot reach such files, so while one is attached the chat also offers file tools for it, and list_terminals marks it with file_tools: true. The tools appear only then: the chat tells its bridge, the bridge lists them and sends notifications/tools/list_changed to a connected agent, and withdraws them when the last such terminal is detached (ADR 0156). An agent that does not handle that notification sees them after it lists its tools again, for example in a new chat.

list_files and read_file follow the read policy; read_file reads UTF-8 text a range of lines at a time. edit_file replaces exact text that occurs once (or every occurrence with replace_all), so the agent sends only what changes; write_file writes a whole file and refuses an existing one unless overwrite is set. Changes follow the write policy: the card shows the path and the text, and Allow file changes on this terminal grants them for the chat's session. The tools act only on terminals with file_tools; on any other terminal they are refused. With Hide secrets in terminal output on, read_file hides recognised secrets as [REDACTED]; write_file then refuses content with that marker, and edit_file matches the file's real text, so a hidden secret is never overwritten by its marker.

Hub agents (ADR 0148) run on the hub, not on this computer: they reach the servers given Agent access with the account's agent key and use the hub's own server tools, never these terminal and transfer tools. A hub agent signs in only to the servers attached to its chat: the attach menu (+) of such a chat lists the account's servers instead of terminals, and the choice is stored with the chat on the hub, so the web panel and every other device show it. See Hubs.

Agents also have their own permission prompts (for example before running a tool of their own or accessing files). Agent permissions → Ask before an agent uses its own tools controls those requests independently of terminal read and write approvals. Its setting is ai.approval.agent_permissions, with ask as the default. Turning it off (allow) selects the provider's ACP allow_once choice for each request, including requests already waiting. It never automatically selects allow_always: switching back to Ask makes subsequent requests wait again. If the provider supplies no valid one-time choice, the request remains as a card with an explanation and the provider's options for manual review. Stop, disabled AI and requests from an obsolete or different session cancel instead of approving.

The terminal read cursor is inclusive: a resumed read may replace the previous last logical line after more text is appended. It is not an exact byte-stream cursor. Alternate screens expose the visible page only. A local OSC 133 prompt can confirm command completion; an SSH output pause only reports a pause and cannot prove that a command completed. Cancellation/timeout must not be confused with successful execution.

Architecture and protocol

nocterm-ai is runtime-neutral domain logic: registry, environment policy, contracts, ACP update reducer, descriptors, MCP parser, approvals, filtering, favorites and pure image admission. nocterm-image-codec implements bounded physical image validation and PNG previews through injected image ports. nocterm-acp adapts subprocess stdio and local bridge transport. nocterm-agent-chat owns chat state, sessions and tools; nocterm-agent owns the chat UI and routing. Saved chats (nocterm_ai::history), Claude limit metadata and transcript usage estimates (nocterm_ai::usage) remain domain code. nocterm-agent-runtime retains plan-limit projections from accepted ACP events. The panel is split into modules by part: transcript, menus, attach menu, approvals, composer, history and usage card (panel/*.rs). Tests supply scripted agent events; neither tests nor production discover provider credentials or session logs for usage reporting. The composition root injects adapters through domain contracts. Features never import ACP adapters or the terminal/connections features; Workspace supplies neutral narrow terminal ports and ConnectionDirectory contracts.

ACP carries chat messages and configuration. Nocterm enables the schema's unstable session/fork and end-of-turn token usage. It sends session/resume, session/load and session/fork only when the agent's capabilities advertise them. ACP client filesystem and new terminal capabilities are not advertised in this version. Existing terminal tools use stdio MCP: session creation supplies the current Nocterm executable with the agent-bridge subcommand. The subcommand runs before GUI initialization, reads endpoint/token from its environment, and relays stdin/stdout to the application's authenticated listener. Only protocol data goes to stdout.

The listener starts lazily. Unix uses a unique socket in the path returned by Paths::ensure_runtime_dir() (private 0700 directory, socket 0600); Windows uses loopback TCP. A random 256-bit token binds each registration to its chat and is revoked on release, chat close or AI off. Authentication has a bounded hello and timeout. Limits include 16 MiB ACP lines, 1 MiB MCP lines, a 256-event foreground queue, four connections per token and 64 total bridge connections. MCP supports initialization, ping, tools listing and tool calls; unsupported methods fail explicitly.

The conversation document, live ACP session and process container have separate owners. A chat can stay open after its agent stops. Each live session has its own connection, so a hung or unsupported session/close cannot terminate another chat's work. Closing awaits the ACP response (up to five seconds), acknowledges a FIFO fence after earlier foreground events, then waits for process cleanup. A closing session still occupies its admission slot. Failed physical cleanup keeps that slot reserved and reports the error. Late startup results whose UI owner has disappeared are closed instead of being abandoned.

[ai.sessions] controls the policy shared by every window: max_live = 4 counts starting, live and closing sessions; max_idle = 3 retains warm sessions; idle_timeout_secs = 1800 releases idle sessions. The chat a panel shows keeps its session warm regardless of both and yields only when a waiting chat needs its slot and no other idle session is left. Requests wait in their saved FIFO queues when the limit is reached, and the oldest idle session yields first. A session already yielding or closing counts as a freed slot, so one waiting chat never evicts more than one other. Generating, authentication, permissions, bridge calls, configuration requests and active command jobs retain a session. A paused queue, composer edit, pin or draft does not. Idle release leaves background terminals and shell command ownership intact. Release agent resources in chat actions pauses the queue and preserves the document; sending another message activates it again.

On Linux, agents require systemd 254 or later, systemd-run and a reachable systemd user manager. Each connection uses a transient user service with KillMode=control-group, a bounded stop timeout and limits for the complete process tree. [ai.resources] defaults to memory_high_mb = 2048, memory_max_mb = 4096, memory_swap_max_mb = 1024 and tasks_max = 512. Exceeding a hard limit can terminate the agent. A missing user manager prevents launch and reports an error. The internal agent-host helper watches a pidfd for the owning Nocterm process, verifies its /proc start time and exits when that owner dies; systemd then cleans up the cgroup, including children that created new process groups. Child environment variables are rebuilt from the allowlist rather than inherited from the systemd manager.

Switching AI off cancels prompts and pending permissions/tools, closes chats, revokes registrations, stops the listener and hides the panel in every workspace. Turning it on starts nothing. On application exit a synchronous serialized flush waits for any active atomic write, blocks later stale writes, and saves final document snapshots before the windows are destroyed, including dormant chats. A failed save retains its snapshot and queued messages in memory and shows an error independently of ACP ownership. Other Unix systems retain process group teardown; Windows process tree termination is best effort.

Privacy boundary

Saved chats are plain JSON readable by your user account. They contain what the chat showed, including tool output that may quote terminal text. Delete a chat from the history to remove its file. Usage reports arrive from the connected agent through ACP. Nocterm does not extract subscription tokens from provider files, read provider session logs, or send separate requests for plan limits.

Without isolation, local agents run as your user and may read and change any of your files with their own tools, including ~/.ssh. Nocterm's allowlisted context and environment policy do not prevent that access.

Isolate agents (Linux, needs bubblewrap) runs each agent process in a bubblewrap sandbox, following the "workspace write" model of Codex and Claude Code's sandbox:

  • the file system is readable but not writable, except the working directory and the agent's own state and caches (~/.claude, ~/.claude.json, ~/.codex, ~/.hermes, ~/.gemini, ~/.npm, ~/.cache, ~/.local/state);
  • SSH and GPG keys, cloud and container credentials (~/.aws, ~/.azure, ~/.kube, ~/.docker, gcloud, gh), password stores and keyrings, browser profiles, ~/.netrc, ~/.git-credentials and similar files, and nocterm's own configuration and state (including the vault and saved chats) are replaced by empty ones;
  • Selecting home as the workspace keeps credential descendants masked. A workspace inside a credential store, including through a symlink, is refused. The dedicated agent workspace inside nocterm private state remains reachable.
  • /tmp is private; the terminal tools' socket directory stays reachable;
  • the process tree gets its own PID namespace and session, so it ends with nocterm and cannot type into the terminal nocterm was started from.

The network stays available, because agents talk to their model provider. Turning isolation on or off restarts running agents. When bubblewrap is missing, an isolated agent does not start, rather than running unisolated. The terminal tools are not affected: they act through nocterm, with the approvals above.

Nocterm excludes its SSH/vault authentication fields from terminal context. Authentication answers are handled outside terminal scrollback. However, connection descriptions, host/user metadata and terminal output can contain secrets supplied by the user or remote program. Output filtering recognizes private-key blocks, tokens of known shapes (OpenAI/Anthropic, GitHub, GitLab, Slack, Stripe, AWS, Google, npm, Hugging Face, JWT), passwords in URLs, Authorization headers and assignments whose name says they hold a secret; it cannot recognize every secret. Do not attach terminals that show sensitive output. Error/stderr display also applies filtering; it remains best effort.

A process with the same user's privileges and a stolen bridge token can use the registered tools while the token is valid. Approval/attachment checks still apply. Unix directory modes do not isolate against other processes running as the same user. Windows loopback authentication does not promise Unix ACL behavior. AI provider retention and external agent tool behavior are governed by the selected provider/agent, not by Nocterm.

Verification

Domain tests cover stable ACP updates, environment blocks, input limits, metadata filtering, image decoding limits, favorites persistence, saved chat files (round trip, permissions, path safety, bounds, pins and names), profile-selected rate-limit metadata parsing and the context estimate. Runtime tests cover retained limit windows from agent events, missing or malformed reports, unsupported metadata profiles and late reports after shutdown. Panel tests cover saving, restoring and resuming chats, stopping and continuing a session, dropped empty chats, in-place restart, history search, pin, rename and fork, the usage card, the sections and folder tree of the attach menu, opening a server from it, and agents connecting to offline servers in the background. Domain tests cover the bubblewrap policy and secret filtering; an adapter test runs an agent under bubblewrap when it is installed. Adapter tests use scripted ACP traffic and real local sockets/processes; feature tests exercise model state and element ids without screenshots; the layout of the history, the usage card and the attach menu was not checked by eye. Real-agent smoke checks are opt-in and require local installations/authentication. A successful build or fake-agent test alone is not an end-to-end result for Claude, Codex or Hermes.

The new [ai] table uses strict schema validation. Older Nocterm versions that do not know this table may reject those settings; keep a backup before opening the same settings with an older version.

agents.toml rejects unknown fields too: a version older than the stored agent options and choices starts without favorites and replaces the file on its next save, so the favorites are lost.

Unavailable local terminal references stay visible after reopening, including beside working remote attachments. They grant no terminal access and can be removed explicitly. Editing queued attachments changes only that future message; the active turn and saved chat defaults keep their original attachment scope.

Workspace preparation is provided by the injected WorkdirResolver. Native path resolution, home lookup and bubblewrap arguments are implemented by the ACP adapter; AI policy checks supplied path facts. A missing saved workspace or a credential descendant fails before starting an agent. The launch checks current environment and path identities independently of the availability shown in settings.