Omniscio

Inbuilt Terminal

A real shell terminal inside Omniscio, scoped to a project's folder — open it from the sidebar, keep the last 100 KB of scrollback across a close and reopen, fuzzy-search saved command snippets, and find within the output. In development: it appears only when its Labs toggle is on.

On this page

What it is

A real shell terminal inside Omniscio, scoped to a project. In-development feature — visible only when Labs → Inbuilt terminal is on (or the env var AMC_SHOW_INBUILT_TERMINAL=1 is set).

Where to find it

Click the terminal icon in the sessions sidebar header to open a terminal in the current project's folder. While a terminal is focused, Ctrl/Cmd+T opens another. Saved snippets are managed in Settings → search "Terminal snippets" — a deep-link-only page, since the feature is unreleased.

How it behaves

What it does — How it behaves

  • Open a terminal in the current project's folder by clicking the terminal icon in the sessions sidebar header (or Ctrl/Cmd+T when a terminal is focused).
  • Runs whatever shell your OS picks up ($SHELL on macOS/Linux; on Windows, PowerShell 7 pwsh.exe when it's installed, else Windows PowerShell powershell.exe, else cmd.exe). The Windows shell is resolved on PATH before use, so an uninstalled shell is never handed to node-pty (that mismatch was the "File not found:" spawn crash). Renders via xterm.js; the PTY is node-pty in the main process.
  • Persistent scrollback — the last 100 KB of output survives closing and reopening the panel. Restored via @xterm/addon-serialize on mount.
  • Ctrl/Cmd+K opens a snippet palette — fuzzy-search over your saved snippets, arrow keys navigate, Enter pastes the command into the terminal (paste-only; you press Enter yourself to run it).
  • Save a snippet with the bookmark-icon button in the panel header — opens a dialog with Name + Command fields.
  • Ctrl/Cmd+F reveals a Find bar over the terminal (uses xterm's SearchAddon).
  • Live theme rebind — switching light/dark or changing the accent color re-applies the terminal theme without recreating it. The pane's own chrome (background, header, snippet palette) follows the app theme's surface ramp and accent, so the terminal no longer paints a fixed dark shell in a light app; the xterm colour scheme is resolved from the same --color-* tokens with documented two-pole fallbacks (terminal-theme.ts).

In a session's side panel

Each agent session's side panel has a Terminal tab (same Labs switch; only when the session's files are on this computer). It holds the session's own shells, opened in the folder the session works in — its worktree when it has one.

  • Several terminals: the + button opens another, each as its own tab inside the Terminal tab.
  • Split panes: the side-by-side and top-and-bottom buttons (or Alt+Ctrl+Shift+5 for side by side) split the focused terminal, up to four panes per tab.
  • Limits: up to 8 terminals per session and 24 across the app.
  • Links: clicking a web link opens it in the session's Browser tab; hold Ctrl/Cmd to open it in your system browser instead. Other kinds of links do nothing.
  • Send lines to the agent: select lines and press Add to message in the terminal's header (or Alt+Ctrl+Shift+K) — see Attach references to a message.
  • Keys stay in the shell: while a terminal has focus, app shortcuts such as Ctrl+W or Esc go to the shell; only Ctrl+1–0 navigation and the side panel's own shortcuts still work.
  • They keep running while the tab is hidden or you switch sessions, and show what you missed when you come back (the most recent 256 KB).
  • They stop when you close a terminal, close the Terminal tab (it asks first while a shell is open), archive or delete the session, delete its project, sign out, turn the Labs switch off, or quit. Nothing about them is saved — no scrollback, no sidebar row.
  • They work only in the desktop app's main window; phones and the web never reach them.

Clipboard — OSC 52 reads are refused (F041)

The clipboard provider the terminal's OSC 52 handler is wired to is NO_READ_CLIPBOARD_PROVIDER in features/terminal/terminal-clipboard.ts.

OSC 52 READ is a clipboard-exfiltration primitive — anything that can write to the terminal can emit the escape sequence and receive the user's clipboard back in the terminal's own output, whether that is a program the user ran, a script they pasted, or a remote shell. The addon's default provider answers a read with navigator.clipboard.readText() when the selection is c, so the real clipboard leaves the app. Reads are therefore refused outright — the provider answers every read with an empty clipboard.

Writes are NOT restricted. OSC 52 WRITE is the ordinary terminal "copy to clipboard" action, and it is forwarded to the same browser provider the addon would have used, so per-selection handling of c (system) vs p/s (primary) is unchanged.

The provider reaches @xterm/addon-clipboard through a lazy import() and takes only a import type at module scope. That is deliberate: the guard tests/unit/lint/1d/terminal-panel-lazy-loaded.test.ts requires xterm to be value-imported by exactly one module (useTerminalSession.ts), so that the whole xterm stack stays behind the dynamic-import boundary TerminalPanel sits on and is not paid at first paint. Adding a second static from '@xterm/...' anywhere in the renderer fails that guard.

Manage snippets

Settings → search "Terminal snippets" (deep-link only — no nav row while the feature's unreleased). Full CRUD list: Add / Edit / Delete rows. Deletes go through ConfirmDialog and register an undo via useUndoStore (a toast surfaces the restore action).

Snippets are user-wide (one shared list across every project). Storage: terminal_snippets table (id, name, command, position, is_deleted, timestamps).

Command blocks (v3)

Additional gate: command blocks require BOTH AMC_SHOW_INBUILT_TERMINAL=1 AND AMC_SHOW_INBUILT_TERMINAL_BLOCKS=1 (or Labs → Inbuilt terminal blocks). The block overlay is completely invisible unless both flags are on.

What it does — Every command you run in the terminal gets a

Every command you run in the terminal gets a "block" — a visual unit in the gutter to the left of the xterm viewport:

  • A green check or red X gutter dot marks exit-code 0 vs non-zero.
  • Hovering the gutter reveals three icon buttons: Fold (collapse the block's output rows), Copy (copy just that command's output to the clipboard), and Re-run (types the original command text at the prompt — you press Enter yourself; it never auto-executes).
  • Blocks are fully persistent: they survive closing and reopening the terminal panel, restoring with the same fold/copy/re-run affordances. The restore sequence waits for both the scrollback content and the block metadata before mounting (see Invariant 3 below).

Shell integration — how it works

When the inbuilt-terminal-blocks feature is visible, TerminalPtyService.spawn() injects per-shell env vars that load bundled shell-init scripts without touching any user rc file:

Shell Mechanism User rc
zsh ZDOTDIR → scratch tempdir whose .zshrc sources Omniscio's init, then Omniscio's init sources the real ~/.zshrc via $AMC_USER_ZDOTDIR read-only (never written)
bash BASH_ENV → Omniscio's init script, which sources ~/.bashrc via $AMC_USER_HOME read-only
pwsh AMC_USER_PROFILE → Omniscio's init script; $PROFILE.ps1 sourced from inside the init read-only

Omniscio's init scripts emit OSC 133 sequences (\x1b]133;A\x07, B, C, D;<exit>, P;cwd=<path>) around each command lifecycle. Nothing writes to ~/.zshrc, ~/.bashrc, or $PROFILE.ps1.

Data flow

Shell (zsh/bash/pwsh)
  └─ emits OSC 133 sequences on PTY output stream
       │
       ▼
terminal-osc133-parser.ts (Task 4)
  └─ strips OSC 133 markers from stream (xterm never sees \x1b]133)
  └─ emits BlockEvent[] (prompt-start, command-start, command-end, cwd-change)
       │
       ▼
terminal-block-processor.ts (Task 5)
  └─ accumulates BlockEvent[] into PartialBlock drafts → seals TerminalBlockRow on command-end
       │
       ▼
terminal-session-manager.ts (Task 6)
  └─ persists sealed blocks to terminal_blocks (SQLite, additive migration)
  └─ emits TERMINAL_BLOCK_EVENT push to renderer
       │
       ▼
TerminalBlockOverlay.tsx (Task 7)
  └─ subscribed via usePushListener(TERMINAL_BLOCK_EVENT)
  └─ positioned absolutely over xterm viewport
  └─ renders TerminalBlockGutterRow per block (exit-code dot + fold/copy/re-run actions)

IPC channels (v3 additions)

  • TERMINAL_BLOCKS_LOAD — renderer hydrates its per-session block store on mount.
  • TERMINAL_BLOCK_EVENT (push) — main pushes a TerminalBlockEvent to the renderer whenever a block seals or updates.
  • TERMINAL_RUN_COMMAND_IN_SESSION — "Re-run" click: main calls terminalPtyService.write(sessionId, command) with NO trailing newline (user must press Enter).

Known limits + roadmap

  • A sidebar terminal session holds one terminal; several terminals and split panes live in a session's side panel Terminal tab.
  • No SSH profile manager and no session recording (roadmap v4).
  • A session that runs inside a WSL distro (Settings → Lab → Run sessions inside WSL) opens its Terminal tab inside that distro, in the session's folder; one on your own SSH host opens a shell on the host (with SSH host pages on). Cloud sessions still have no Terminal tab. See wsl-run-location.md and ssh-remote.md.

Running apps covers the dev-server preview panel — the other place Omniscio starts and shows a process for you — and Drive Omniscio covers the watch-and-steer cockpit that drives the app's own UI. Where Omniscio runs shell commands on your behalf in general — and what it refuses — is described under the app's shell settings.

Last verified 2026-10-26