Terminals

Every workspace in CodeSense has real terminals: a full PTY with xterm.js, clickable links and WebGL rendering. It isn’t a simulated console. Anything you run in Terminal.app or iTerm runs here, including make, your scripts and any agent CLI.

Your shell, your config

A CodeSense terminal starts a login zsh (zsh -l) in the workspace’s folder, which for a story is its worktree. It loads your own .zshenv, .zprofile, .zshrc and .zlogin, so your PATH, aliases, functions and prompt are all there.

CodeSense adds only a little on top:

• ~/.codesense/bin goes first on PATH. It holds codesense-bridge, the MCP bridge agents use.
• A few variables such as CODESENSE_TAB_SESSION_ID and CODESENSE_API_PORT identify the tab to CodeSense.
• claude and codex start connected to CodeSense: its MCP tools and, for Claude, its status and new-mail hooks. command claude runs the plain CLI. See MCP tools for agents.
• TERM=xterm-256color.

zsh only for now

The terminal always starts zsh, even if your login shell is bash or fish. $SHELL isn’t read.

Coming

Terminals that start your own $SHELL, such as bash or fish.

Unlocks with your own login shell.

See Run your own tools and scripts in a worktree for a walkthrough.

Tabs and tiles

A workspace can hold several terminal tabs. Split them into tiles to watch several agents or shells at once, drag to split, and arrange tiles as columns, rows or a grid.

Shortcut	Does
⌘\	Toggle the terminal
⌘⇧L	Cycle the tile layout (columns, rows, grid)
⌘⇧M	Expand in and out: the focused tile fills the area, then shows all its tabs at once, then steps back out to one tab and to all your workspaces, turning round at each end. With one tab it’s a plain expand and restore. A brief note names where you are. In all tabs, drag a divider to resize, double-click it to even the pair
⌘⇧] / ⌘⇧[	Next or previous terminal tab
⌘⌥ + arrow	Focus the pane in that direction
⌘T	New terminal tab in the focused tile
⌘W	Close the tab: Hide if something is running, End if it’s idle
⌘⇧T	Reopen the last closed tab (a Hidden tab comes back running; an Ended one opens a fresh shell in the same place)
F2	Rename the tab whose pill has keyboard focus (in the terminal itself, F2 goes to the program)
⌘F	Find in the terminal: ⏎ / ⇧⏎ next or previous, Aa match case, Esc closes
⌘⇧K	Clear the terminal (skipped while a full-screen program is running)
⌘⌥1…⌘⌥8	Jump to tab 1–8 in the focused tile; ⌘⌥9 jumps to the last tab
⌘⇧J	Jump to what needs you: a waiting question, a permission prompt or a crashed tab, across all workspaces

Each team remembers whether its terminal tray is showing. The shortcuts are listed and can be changed in Settings → Shortcuts.

On a Mac the terminal shortcuts use ⌘, never ⌃: Control chords like ⌃T, ⌃F and ⌃K always go to the shell. ⌘1…⌘9 jump between workspaces.

Output is never lost to the UI

The terminal process, not the view, owns the session. Each session keeps a 5 MiB replay buffer, so switching teams or tabs, or closing a tile, doesn’t lose a running agent’s output. If the app’s window reloads or crashes, CodeSense re-attaches to the terminals that are still running.

New tabs open instantly because CodeSense keeps a few zsh shells warm in the background. Set the count with Warm terminal pool size in Settings → General (0 to 5, default 2).

Closing the window vs quitting

By default, closing the window keeps CodeSense running in the background. The MCP host, sync and any running agents keep going, and clicking the dock icon brings the window back. To make closing quit instead, turn on Quit on window close in Settings → General.

Quitting CodeSense (⌘Q) is different: terminal sessions don’t survive a quit. The next launch opens fresh shells.

Background agents

An agent launched headless, or from a page, runs with no visible tab. The Agents list in the bottom workspace lists live agent sessions with their status, and Stop all unattended stops every background agent after a confirmation.

To stop a page or routine from flooding your machine, background agents are capped. The Background agent limit in Settings → General is Auto (6), 2, 4, 6 or 8. Tabs you have open don’t count toward it.

Agents can use terminals too

Agents launched from CodeSense can open a terminal tab in an open workspace, run a command in it, and read the output back, for example to start a dev server and watch its logs. See MCP tools for agents.