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 terminal is a full-height column beside the layer rail, with the canvas to its right; drag the divider to resize it. It renders with xterm.js, supports search and scrollback, and displays any output the underlying process emits. When Denote opens a project, it spawns your login shell, launches Claude Code in the project directory, and wires the process to the 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.

One deliberate detail: Denote launches Claude Code with any ANTHROPIC_API_KEY from your shell stripped, so the terminal signs in with your Claude subscription instead of pay-per-use API billing.

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 /ontology running in the terminal on the left and the Ontology canvas on the right updating mid-conversation, with a new entity row appearing.]

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 canvas accumulates its output. Structural layers benefit from a visual canvas because their content is graph-shaped. Vision is prose-shaped, so prose is the natural surface.

Typing, keyboard, and images

  • Native macOS keys work. Option-arrow word movement, word delete, line kill — the shortcuts you use in every Mac text field.
  • Multiline input. Shift+Enter inserts a newline instead of submitting, and pasted multiline text never auto-submits.
  • Images. Paste an image from the clipboard and Claude receives it inline; drag an image file onto the terminal and Denote saves it into the project and inserts its path at the cursor.
  • Capture to Vision. Select any terminal text and an Add to Vision popover appears; pick a category and the text lands in design/vision.json.
  • Focus follows click. Click the canvas → keystrokes go to Denote's UI. Click the terminal → keystrokes go to the process.

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

  • 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 — the Spec layer's right panel: which layer files are present, which are missing, and the project skill generator. The Spec page header also carries a chip showing whether design/skill.md is up to date.

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 read the last prompt, then respond.

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