Skip to content

Embedded terminal

The embedded terminal runs a real Claude Code process for a session, in the same place as its task board. You can start new sessions, resume old ones and move between them from the browser.

When you run Claude Code Kanban alone, the terminal is off. Start the server with --enable-terminal:

Terminal window
claude-code-kanban --enable-terminal

You can also set it in the CCK_TERMINAL environment variable, as JSON:

Terminal window
CCK_TERMINAL='{"enabled":true}' claude-code-kanban

At start, the server prints a line like this:

Terminal enabled - open http://localhost:3541/#t=<token>

Open that URL. The token in it lets the page connect to the terminal, and it changes each time the server starts.

Inside Claude Code Hub the terminal is on by default, and the hub gives the page its token.

The terminal has these limits:

  • It needs the optional package @lydell/node-pty. If that package does not load, the terminal is not available and the server logs the reason.
  • The server refuses the terminal when it listens on an address other than loopback, for example with --host 0.0.0.0.

Open a session, then click the terminal button in the board header or press Ctrl+`. The terminal takes the place of the board and hides the Session Log. Press Ctrl+` again to go back to the board.

The terminal process runs on the server. When you switch sessions or reload the page, it keeps running. Come back to the session and the page attaches to the same screen again.

Key Action
Ctrl+` Show or hide the terminal
Alt+` Move focus between the terminal and the page
Alt+Shift+` End the terminal and close it
Ctrl+Shift+` Open the Terminals manager. Shift+click on the terminal button does the same.
Tab Move focus from the sidebar to the terminal. In the terminal, Tab goes to Claude Code. Use Alt+` to go back to the page.

In the terminal, Ctrl+C copies when you have a selection. With no selection it goes to the process as usual. Ctrl+Shift+C always copies the selection, and Ctrl+V pastes.

To change the terminal text size, press Ctrl++ or Ctrl+- while the terminal has focus. Ctrl+0 resets it to the configured size. The page does not zoom. The browser remembers the size.

When you show the terminal for a session, Claude Code Kanban resumes that session with claude --resume.

If the session already runs in another terminal, a prompt asks what to do, because two processes on one session write to the same transcript:

  • Resume anyway resumes it here too.
  • Shell only opens a shell with no Claude Code process.

To start a new session from a session’s history, right-click its card in the sidebar and choose Fork. The fork gets its own card and terminal.

/clear and /resume in the terminal start or open another session in the same Claude Code process. The terminal moves to that session’s card, and the card of the session you left leaves the Active list.

When Claude Code exits, the terminal stays open as a shell. When the shell exits or you end the terminal, a prompt offers Resume and Shell. For a new session that has no first message yet, the prompt offers Start again and Shell.

If the connection drops, the page tries to connect again five times, from 0.5 to 8 seconds apart. After that it shows a Reconnect button.

Press Ctrl+Alt+N, click the + New pill at the top of the sidebar, or click + on a project header. The New session dialog opens. The + on a project header fills in that project’s folder.

  • Folder. Type to filter the projects you have used before, or click Browse… to pick a folder in the system dialog. Only a known project folder or a folder you picked in the dialog is accepted.
  • Name. Optional. Letters, digits, spaces, ., _ and -, up to 80 characters. It must start with a letter or digit.
  • Prompt. Optional. Claude Code gets it as the first message. If your browser supports speech input, a microphone button lets you dictate it.
  • Images. Paste or drop PNG, JPEG, GIF or WebP images (up to 10 MB each) into the prompt. Each one shows as a thumbnail: click it to see it full size, click × to remove it, or press Backspace in an empty prompt to remove the last one. On start, the board saves the images to <config dir>/.cck/attachments/<session id>/ and adds their paths to the prompt, and Claude Code reads them from there.
  • New worktree. Starts Claude Code in a new git worktree at .claude/worktrees/<name>. The name is optional: letters, digits, ., _ and -, up to 64 characters. With no name, Claude Code picks one.
  • Model. Default, Fable, Opus, Sonnet or Haiku.

The button reads Start in <folder>. Press Enter to start, or Ctrl+Enter while you type in the prompt. Esc closes the image preview or the folder list, then the dialog.

Until Claude Code writes its first message, the sidebar shows a placeholder card with the text “waiting for your first message”. It turns into a normal session card after the first message.

Press Ctrl+Alt+R. The same dialog opens with only the Folder field, and the button reads Resume in <folder>. The terminal runs claude --resume, which shows Claude Code’s own session picker. Until you pick one, the sidebar shows a “Resume session” placeholder card. When you pick a session, the terminal moves to that session on the board.

Press Ctrl+Alt+S to go back to the session you had open before. Press it again to return. If the terminal has focus, it keeps focus after the swap, so you can go on typing.

To jump to any session without leaving the terminal, press Ctrl+Shift+P. The session picker opens, and when it closes the terminal gets focus back.

Inside Claude Code Hub, Claude Code Kanban keeps Ctrl+Alt+N, Ctrl+Alt+R and Ctrl+Alt+S for itself and does not send them to the hub.

On a layout with AltGr, a press that types a character is text, not a session key. For example, on a Polish layout AltGr+S types ś and AltGr+N types ń in the terminal.

Press Ctrl+Shift+Z or click the target button in the Sessions header. The sidebar shows only the current session card and a panel with its context use, scratchpad folder, linked documents, artifacts and live workflow. The session picker (Ctrl+Shift+P) still lists all sessions.

With the terminal open in zen mode, the sidebar shows one session and the terminal takes the place of the board.

To focus on a group or a project, move the sidebar cursor to its header, then press Ctrl+Shift+Z. The sidebar shows only that group, with its subgroups, or only that project. A project does not have to be in a group. The Active/All filter still applies: under Active you see only its active sessions, under All every session in it. Press Ctrl+Shift+Z again to see the full list.

The browser remembers zen mode for the current session, so it stays on after a reload. Press Ctrl+Shift+Z again to leave it. It works when the terminal has focus. Shift+Z also works outside the terminal.

With no session open, zen mode shows the first five sessions of the current list. Click one to open it. The rows below them open the session picker and leave zen mode.

A session in the terminal can post charts, diagrams, mockups and explanations of code to a card at the top right of the terminal. See Show cards.

Press Ctrl+Shift+`, or press Shift and click the terminal button. The Terminals manager shows “N of M running” and a row for each terminal on the server, with:

  • the mode (resume, fork, pick, new or shell)
  • how long it has run
  • the number of attached pages, or “detached”
  • its working folder
  • Open and End buttons

End all appears when two or more terminals run. If a terminal is working or waits for you, a dialog lists every terminal with its state, run time and memory, and warns that work in progress is cut off. If all terminals are idle, End all ends them at once. By default the server allows 30 terminals at the same time.

Terminals run in the server, so a page reload keeps them. A server restart ends them, and the server resumes them on its next start. To turn this off, set "restore": false in CCK_TERMINAL. Inside Claude Code Hub, set it in the terminal block of ~/.claude-hub/config.json:

"terminal": { "restore": false }

The server keeps the list of open terminals in <config-dir>/.cck/terminals.json. As soon as it listens, it runs claude --resume for each one, two seconds apart, without waiting for a page to open. A session shows as running, and a click attaches to it. The server skips a session that runs in another terminal or has no transcript. A terminal you end leaves the list. A terminal whose Claude Code exited, so only the shell runs, also leaves it; when you resume that session again in the same terminal, it comes back. Shell terminals are not restored, nor is a resume picker until you pick a session in it. A resumed session waits at its prompt and does not continue a turn that the restart cut off.

Each server writes the whole list, so two servers on one config dir overwrite each other’s terminals. Give a second server its own file with CCK_TERMINALS_FILE=<path>.

The terminal starts a shell and runs Claude Code in it. To pick the shell, use --terminal-shell <value> or the CCK_TERMINAL_SHELL environment variable. The value is one of:

  • gitbash
  • a program name on PATH, such as pwsh, cmd or zsh
  • a full path to a shell

With no value, Claude Code Kanban uses pwsh, then powershell on Windows. On other systems it uses $SHELL, or /bin/sh. If the named shell is not found, the terminal does not start.

The terminal runs in its own browser process. Typing and output do not wait for work on the board, such as a large session list or a long Session Log.

To get its own process, the terminal loads from the other loopback name of the same server:

You open the board on The terminal loads from
localhost [::1]
127.0.0.1 localhost
any other host name the same host, in the board’s process

If the terminal does not load from the other name in 5 seconds, for example because IPv6 is off, the board loads it from its own host. The terminal then works as before, but it shares the board’s process, and the first terminal you open on the page takes 5 seconds longer to show.

For other terminal settings, such as font size and scrollback, see Configuration. For all keys, see Keyboard shortcuts.