Skip to content

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.

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
mdocker terminal tools # JSON list with availability per tool
mdocker terminal
mdocker terminal new aurora --tool claude # start a Claude Code session
mdocker terminal new aurora --tool claude --sandbox # sandbox mode
mdocker terminal new aurora --tool shell
mdocker terminal list aurora # list sessions
mdocker terminal list --all # every project at once
mdocker terminal kill aurora <session-id> # end one session
mdocker terminal prune aurora # drop dead registry entries

Sessions are named mdocker__<project>__<id> in tmux, and their state lives under .projects[<name>].sessions[] in the registry.

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.

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
mdocker terminal exec aurora shop # bash (default) in the shop container
mdocker terminal exec aurora db sh # a specific shell

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:

session paths
mdocker terminal path aurora # show the current start path
mdocker terminal path aurora ./backend # set it
mdocker terminal editor-path aurora ~/Projects/aurora

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.

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.