Skip to content
Docs

The embedded terminal

The embedded terminal is the pane inside Denote where Claude Code runs. Real xterm-powered terminal connected to the same Claude Code binary you'd run from your system terminal, operating on the same project directory, reading and writing the same files. The only thing different: it lives inside the Denote window so you never alt-tab between thinking surface and building surface.

What the pane is

The right side of the workspace is a full terminal. Renders with xterm.js + WebGL addon, supports search, handles resize, displays any output the underlying process emits. When Denote starts, it spawns a Claude Code process pointed at the open project's directory and wires the process stdio to the terminal pane.

You type. The process reads. Claude Code responds. Files on disk change. Denote picks up the changes and updates the relevant layer canvas.

From the process's point of view, nothing is unusual. It isn't aware of Denote. No special API. The integration is the shared filesystem, nothing more.

What happens when you run a skill

Typing a slash command like /ontology or /architecture triggers Claude Code's normal slash-command resolution. Claude Code finds the command at .claude/commands/<name>.md, loads it, and begins executing. That execution typically involves reading several files under design/, having a conversation with you, and writing files back.

You see the conversation in the terminal. You see the files change in the corresponding layer canvas as the writes land. Both surfaces are reading the same directory.

[Screenshot TODO: split view showing the Ontology canvas on the left updating as /ontology runs on the right, with a new entity card appearing mid-conversation.]

The terminal is dominant in Vision

Most layers treat the terminal as secondary. You do the thinking in the canvas (dragging screens in Architecture, placing chips in Screens), and the terminal runs skills when you want to regenerate.

Vision is the exception. The conversation is where the thinking happens; the sidebar is a side effect. Structural layers benefit from a visual canvas because their content is graph-shaped. Vision is prose-shaped, so prose is the natural surface.

Resizing, focus, keyboard

  • Boundary between canvas and terminal is a draggable divider. Drag left or right to resize.
  • Focus follows click. Click the canvas → keystrokes go to Denote's UI. Click the terminal → keystrokes go to the process.
  • Copy/paste work as in any terminal. Selection, right-click menu, the browser-native copy shortcut all behave normally.

Why embed the terminal at all

Denote could have talked to Claude Code over an RPC or custom protocol. It doesn't:

  1. No drift with standalone Claude Code. Whatever the latest version does, the embedded pane does. No shim, no compatibility layer, no version-locked API. New Claude Code command → new Denote command the moment it ships.
  2. Every terminal feature comes free. History, search, scrollback, copy/paste, ANSI rendering, Unicode. None of it is Denote's code. All of it is xterm.js + the Claude Code binary.
  3. Claude Code outside Denote still works. Run the same commands from your system terminal when Denote is closed. The project folder is the universal interface. Nothing in Denote is load-bearing for the build pipeline.

Status surfaces around the terminal

  • Skill status chip — below the terminal, shows whether a skill is running, which skill, how long it's been running. Reads its state from the process output; doesn't intercept input.
  • Activity hub (top-right icon) — persistent project-scoped log of every skill run, file write, rename, deletion, dangling-reference warning. Durable history; entries persist via design/.denote/activity.jsonl.
  • Write status — pipeline write state (which layer files are present, which are missing, which might be stale). Available from the activity hub. The Spec panel's empty state prompts you to run /spec once upstream layers have something to work from.

The build-mode banner

While the project is in build mode, a red strip pinned to the bottom of the terminal reads "Claude won't be a design partner in Build Mode" with a Switch button. Only renders in build mode; design mode (the default) shows no banner.

The banner exists because mode affects what Claude says in the terminal but not what Denote's canvas does. Without a persistent reminder, it's easy to type /vision in build mode, get a confused response from Claude, and not realize why.

Clicking Switch opens the same mode-swap dialog the top-bar chip uses. See Design and Build mode.

Restart after a mode swap

Claude Code only reads CLAUDE.md when its session starts. A mid-session toggle doesn't retroactively change the running Claude's behavior. To make the new mode actually apply, Denote restarts the embedded terminal as part of every swap.

What you see:

  1. The mode-swap dialog closes.
  2. The terminal goes briefly blank as the running process is killed.
  3. A fresh Claude Code session spawns in its place, reading the new CLAUDE.md.
  4. A toast confirms the switch.

The dialog warns you before you confirm — the running Claude conversation ends. There's no way to apply a mode change without the restart.

Troubleshooting

  • No prompt on project open — Claude Code may not be on PATH. Denote looks for claude in standard locations. See Troubleshooting.
  • Logged out — the terminal prints the login prompt. Click in, run claude login, follow the auth flow. Authentication applies across all sessions; once per machine.
  • Skill seems stuck — the process is probably waiting on your input. Click in and respond. The status chip shows whether the skill is still running.

What the terminal is not

  • Not a code editor. Executes; doesn't edit files. To edit a design file by hand, open it in your own editor. Denote picks up changes either way.
  • Not a shell. Runs Claude Code, not bash. You can't ls or cd. Standalone Claude Code supports its own shell-like commands; those work here too.
  • Not an integration layer. Denote doesn't pass structured data to Claude Code through the terminal. All data crosses through the filesystem.

Where to next