---
title: Integrated Terminal
description: Multi-tab terminal with xterm.js, running inside each workspace's worktree.
---

Claudette includes a full-featured terminal emulator built with **xterm.js** and **portable-pty**, running natively alongside your agent sessions.

## Opening the Terminal

Toggle the terminal panel with `` ⌘/Ctrl + ` ``. The terminal opens in the current workspace's worktree directory, so you're always in the right context.

## Multi-Tab Support

You can open multiple terminal tabs within each workspace. Each tab runs its own shell session in the workspace's worktree.

{/* TODO: Screenshot of terminal panel */}
:::note[Screenshot coming soon]
A screenshot showing the terminal panel with tabs will be added here.
:::

## Split Panes

Every terminal tab can be split into multiple panes side-by-side or stacked, so you can run a dev server, tail logs, and execute tests without leaving the workspace.

- **Split side-by-side** (vertical divider): `⌘D` on macOS, `Ctrl+Shift+D` on Linux/Windows.
- **Split stacked** (horizontal divider): `⌘⇧D` on macOS, `Ctrl+Shift+Alt+D` on Linux/Windows.
- **Close the focused pane**: `⌘W` on macOS, `Ctrl+Shift+W` on Linux/Windows. When only one pane is left, this closes the enclosing tab.
- **Move focus between panes**: `⌘⌥←/→/↑/↓` on macOS, `Ctrl+Alt+←/→/↑/↓` on Linux. You can also click any pane to focus it.
- **Resize**: drag the divider between two panes.
- **Zoom terminal text only**: `⌘/Ctrl + Shift + =` to increase terminal font size, `⌘/Ctrl + Shift + -` to decrease it.

Each pane runs its own independent PTY in the workspace's worktree. Up to six panes are supported per tab to keep the layout usable.

Split layouts are **ephemeral** — the app reopens each tab as a single pane on restart. Tab identity and titles are persisted; the split arrangement within a tab is not.

## Default Shell

Each PTY launches your platform's interactive shell, with that shell's normal profile loading mechanism intact — so prompts, aliases, modules, and `direnv`/`mise`/etc. integrations from your dotfiles all work.

### macOS / Linux

`$SHELL` is honoured if set; otherwise `/bin/zsh` (macOS) or `/bin/bash` (Linux). The shell's regular profile (`~/.zshrc`, `~/.bashrc`, etc.) loads as it would in any other terminal.

### Windows

`pwsh.exe` (PowerShell 7+) and `powershell.exe` (Windows PowerShell 5.1) read profiles from totally different paths — `Documents\PowerShell\…` vs `Documents\WindowsPowerShell\…` — so blindly preferring PS7 leaves PS5.1 users staring at an unconfigured banner. Claudette's resolution is **profile-aware**: it picks the PowerShell flavour whose profile you've actually written.

1. `pwsh.exe` on `PATH` **and** a PS7 profile exists
2. `powershell.exe` on `PATH` **and** a PS5.1 profile exists (and there's no PS7 profile)
3. `pwsh.exe` on `PATH` (modern default when no profile signal either way)
4. `powershell.exe` on `PATH` (in-box fallback)
5. `%ComSpec%` (deliberate `cmd.exe` override, if set)
6. `%WINDIR%\System32\cmd.exe` (always-present last resort)

Profile detection probes both `%USERPROFILE%\Documents\…` and `%USERPROFILE%\OneDrive\Documents\…` (Office 365 and Windows 11 Backup commonly redirect Documents into OneDrive). Both per-host (`Microsoft.PowerShell_profile.ps1`) and all-hosts (`Profile.ps1`) profiles count.

No extra arguments are passed, so the shell behaves the same as it would in a stock Windows Terminal tab — PowerShell auto-loads `$PROFILE`, and `cmd.exe` honours its `HKCU\Software\Microsoft\Command Processor\AutoRun` entry.

### Nix devshell

If the workspace has a `flake.nix` (or a legacy `shell.nix`) and the bundled **env-nix-devshell** environment provider is enabled, the terminal launches *inside* that workspace's devshell — Claudette spawns it as plain `nix develop`. The toolchain pinned by the flake is on `PATH` from the first prompt, so the integrated terminal matches what `nix develop` gives you outside Claudette, regardless of which devshell Claudette itself was started in.

Because the terminal runs `nix develop` with no `--command`, a devshell workspace's terminal is the devshell's *own* shell — the flake's `shellHook` runs on entry. It deliberately does **not** launch your personal interactive shell (`zsh`/`bash` with your dotfiles) inside the devshell: re-running a full shell profile inside `nix develop` re-applies login-level environment setup (oh-my-zsh, `nix-daemon.sh`, and on nix-darwin the `/etc/zshenv` reset) that overwrites `PATH` and strips the devshell back out. Non-devshell workspaces still open your normal shell as before.

It falls back to a plain shell only when there is genuinely nothing to enter — the provider is disabled, `nix` is not installed, or the workspace has no flake. A flake that *fails to evaluate* is not hidden: `nix develop` reports the error directly in the terminal, so a broken devshell is visible rather than silently swapped for a plain shell with the wrong toolchain. This is independent of **env-direnv** — the terminal enters the devshell through `nix develop` directly, never through direnv. Toggle it per repo or globally from the **env-nix-devshell** entry in `Settings > Plugins`.

Agent subprocesses use the same separation. In a Nix devshell workspace, Claudette starts the harness as `nix develop --command <agent> ...`, so agents see the clean devshell environment rather than direnv's user-shell/profile environment.

## Terminal Font Size

Adjust the terminal font size in `Settings > Appearance > Terminal font size` (range: 8–32px, default: 11px). Press `⌘/Ctrl + Shift + =` or `⌘/Ctrl + Shift + -` to scale only the terminal without changing the rest of the UI.

## Environment Variables

Every terminal session has [workspace environment variables](/claudette/features/settings/#environment-variables) set automatically — `$CLAUDETTE_WORKSPACE_NAME`, `$CLAUDETTE_WORKSPACE_PATH`, `$CLAUDETTE_ROOT_PATH`, and others. These are useful for scripts and tools that need to know which workspace they're running in.

## Command Indicator

The sidebar shows the foreground command running in each workspace's terminal. Detection is automatic — Claudette polls the PTY's foreground process group, so any shell works (zsh, bash, fish, anything else) with no configuration required and no changes to your shell rc files.

The indicator is **macOS and Linux only** — Windows has no equivalent of process-group ownership on PTYs, so the sidebar simply omits the indicator there. The polling path also only observes start/stop transitions, not exit codes, so there's no separate "succeeded vs. failed" colorization.
