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.
Turn the terminal on
Section titled “Turn the terminal on”When you run Claude Code Kanban alone, the terminal is off. Start the server with --enable-terminal:
npx claude-code-kanban --enable-terminalYou can also set it in the CCK_TERMINAL environment variable, as JSON:
CCK_TERMINAL='{"enabled":true}' npx claude-code-kanbanAt 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.
Show and hide the terminal
Section titled “Show and hide the terminal”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.
Open a session in the terminal
Section titled “Open a session in the terminal”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.
- Fork starts a new session from its history.
- Shell only opens a shell with no Claude Code process.
When Claude Code exits, the terminal stays open as a shell. When the shell exits or you end the terminal, a prompt offers Resume, Fork 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.
Start a new session
Section titled “Start a new session”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.
- 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 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.
Resume a past session
Section titled “Resume a past session”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.
Swap to the previous session
Section titled “Swap to the previous session”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.
Zen mode
Section titled “Zen mode”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.
The browser remembers zen mode, 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.
Terminals manager
Section titled “Terminals manager”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. By default the server allows 30 terminals at the same time.
Restore terminals on start
Section titled “Restore terminals on start”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. Fork and 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.
Choose the shell
Section titled “Choose the shell”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 aspwsh,cmdorzsh - 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.
For other terminal settings, such as font size and scrollback, see Configuration. For all keys, see Keyboard shortcuts.