Skip to content
Docs

The embedded terminal

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

What the terminal pane is

The right side of the workspace is a full terminal. It renders with xterm.js and the WebGL addon, supports search, handles resize, and 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 is not aware of Denote. It has no special API to the app. The integration is the shared filesystem, nothing more.

What happens when you run a skill

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

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

The terminal is dominant in Vision

Most layers treat the terminal as a secondary surface. You do the thinking in the canvas (dragging nodes in Structure, drawing regions in Layout), and the terminal is there to run skills when you want to regenerate.

Vision is the exception. The Vision layer treats the terminal as the primary surface. The conversation is where the thinking happens; the sidebar is a side effect.

This is a deliberate split. 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, and keyboard handling

The boundary between the canvas and the terminal is a draggable divider. Drag it left or right to resize. Previous versions of Denote had focus and collapse modes; those were removed because dragging covers the 90 percent case and the extra modes added bugs without adding value.

Focus follows click. When you click in the canvas, keystrokes go to Denote's UI. When you click in the terminal, keystrokes go to the process. `Cmd+`` (the keyboard shortcut for terminal focus) will be added in a later polish pass.

Copy and paste work as they do in any terminal. Selection, right-click menu, and the browser-native copy shortcut all behave normally.

Why embed the terminal at all

Denote could have chosen to talk to Claude Code over an RPC or a custom protocol. It does not. The reasons:

  1. No drift with standalone Claude Code. Whatever the latest Claude Code version does, the embedded pane does. No shim, no compatibility layer, no version-locked API. A new Claude Code command becomes a new Denote command the moment it ships.
  2. Every terminal feature comes free. History, search, scrollback, copy and paste, ANSI rendering, Unicode handling. None of it is Denote's code. All of it is xterm.js plus the Claude Code binary.
  3. Claude Code outside Denote still works. You can 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

A few small surfaces wrap the terminal without interfering with it.

Skill status chip. Below the terminal, a small chip shows whether a skill is running, which skill, and how long it has been running. When the skill finishes, the chip briefly confirms success or surfaces an error. The chip reads its state from the process output; it does not intercept input.

Activity hub (top-right icon). The activity hub is a persistent project-scoped log of every skill run, file write, rename, deletion, and dangling-reference warning. It is not a notification tray. It is the durable history of what Denote has done. Entries persist across sessions via design/.denote/activity.jsonl.

Write status. Pipeline write state (which layer files are present, which are missing, which might be stale) appears inside the Plan panel rather than next to the terminal. Plan is the build-facing surface, so pipeline state lives there.

Troubleshooting

If the terminal shows no prompt on project open, Claude Code may not be on PATH. Denote looks for claude in the standard locations. See Troubleshooting for the resolution steps.

If Claude Code is logged out, the terminal prints the login prompt. Click into the terminal, run claude login, and follow the standard auth flow. The authentication applies across all Claude Code sessions, so you only do this once per machine.

If a skill seems stuck, the process is probably waiting on your input. Click into the terminal and respond. The status chip will show whether the skill is still running.

What the terminal is not

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

Where to next