AI Terminal Sessions
MultiDocker can spawn project-scoped terminal sessions running an AI coding tool, a
plain shell, or a shell inside one of the project’s containers. Each session is a
detached tmux session, so it keeps running after you close the app and you can
re-attach later.
Available tools
Section titled “Available tools”| Tool | What it runs |
|---|---|
claude |
Claude Code (claude, or claude --sandbox in sandbox mode). |
copilot |
GitHub Copilot CLI (gh copilot if the extension is installed, else copilot). |
shell |
Your login shell in the project directory. |
exec |
A shell inside a project container via docker compose exec. |
Check which tools are installed on your machine:
mdocker terminal tools # JSON list with availability per toolCreate and manage sessions
Section titled “Create and manage sessions”mdocker terminal new aurora --tool claude # start a Claude Code sessionmdocker terminal new aurora --tool claude --sandbox # sandbox modemdocker terminal new aurora --tool shellmdocker terminal list aurora # list sessionsmdocker terminal list --all # every project at oncemdocker terminal kill aurora <session-id> # end one sessionmdocker terminal prune aurora # drop dead registry entriesSessions are named mdocker__<project>__<id> in tmux, and their state lives under
.projects[<name>].sessions[] in the registry.
Live session state
Section titled “Live session state”terminal list computes alive live, and for every living session it reads three
extra fields straight out of tmux:
| Field | Source | Meaning |
|---|---|---|
activity |
#{window_activity} |
Epoch of the last pane activity. Fresh output keeps it fresh, so it is what “the tool is working right now” is derived from. |
exited |
#{pane_dead} |
true once the pane’s process has ended (the session is kept with remain-on-exit). |
title |
#{pane_title} |
The title the running program set via OSC 0/2 — null when empty or just the hostname default. |
terminal list --all returns every project that has sessions in one call, as
[{ project, sessions: [...] }]. Projects without sessions are skipped to keep the
payload small. The app polls exactly this one command.
Container shell (exec)
Section titled “Container shell (exec)”To open a shell inside a running container, use terminal exec. It builds the correct
docker compose exec invocation for the project’s COMPOSE_FILE stack:
mdocker terminal exec aurora shop # bash (default) in the shop containermdocker terminal exec aurora db sh # a specific shellWhere sessions start
Section titled “Where sessions start”By default a session opens in the project directory. You can set a per-project start
path (absolute, ~/-relative, or relative to the project), and a separate
“open in editor” path:
mdocker terminal path aurora # show the current start pathmdocker terminal path aurora ./backend # set itmdocker terminal editor-path aurora ~/Projects/auroraIn the macOS app
Section titled “In the macOS app”The app lists a project’s sessions and attaches to them via SwiftTerm. Because the sessions are real tmux sessions, they survive an app quit and can be re-attached later.
From activity and exited the app derives three states, each with its own colour
and glow: „arbeitet“ (red, activity younger than 3 seconds), „wartet auf
Eingabe“ (orange, blinking) and „beendet“ (grey). It polls terminal list --all
every 2 seconds while the app is in front, every 5 seconds otherwise, and only for as
long as a session is alive. When a session goes from working to waiting or finished,
macOS shows a notification — unless that session is open on screen.
The session header shows the auto-title from title (or live from SwiftTerm) plus a
status pill. „Alle AI-Sessions“ in the sidebar collects every session across all
projects in the sections „Arbeitet“, „Wartet auf Eingabe“ and „Beendet“.
See Attached Terminals.
Sessions with a ticket as context
Section titled “Sessions with a ticket as context”If a project is bound to a Spedy board, mdocker spedy session <name> <id> starts a
claude session whose initial prompt points at a generated context file for that
ticket; in the app the same action is the button „AI-Session mit Ticket-Kontext“
in the ticket detail. Such a session additionally carries spedy_ticket in the
registry. See Spedy Tickets.
Related
Section titled “Related”- CLI:
terminal - CLI:
spedy - Attached Terminals (SwiftTerm)