managing instances

an instance is a running (or paused) ai agent session. it has a title, an isolated git branch, an execution mode (tmux or headless), and a lifecycle status. the sidebar lists all instances grouped by their associated plan.

starting an instance

kasmos starts instances automatically when you trigger a lifecycle stage (plan, implement, review). you can also start a standalone instance:

• press n for a new plan, then s to spawn an agent for it
• or open the command launcher and choose new instance or spawn agent

each instance gets a fresh git worktree on a new branch named after the instance title. the worktree is isolated from main and from other instances, so concurrent agents cannot conflict at the git level.

attaching to a tmux session

tmux instances are attachable. press ↵ or o with the instance selected to attach fullscreen:

tui  ──► enter  ──►  tmux session (fullscreen)
          │
          ▼
    ctrl+space or ctrl-q  ──►  detach  ──►  back to tui

a one-time help overlay reminds you of the detach keys when you first attach. press any key to dismiss it and proceed to the session.

headless instances are not attachable — they run as background processes. their output streams to the preview tab in the center pane. use tab to switch to the agent tab and watch it live.

interactive mode

press i to enter interactive mode without going fullscreen. in this mode your keystrokes are forwarded to the agent's pane, letting you type commands or reply to prompts without leaving the tui layout. exit with ctrl+space (or send the current input with ctrl+enter).

press ! as a shortcut that enters interactive mode and immediately sends ! to the agent, activating the harness's shell mode in one keystroke.

stopping and killing

key	effect
k	kill — terminates the tmux session; the instance entry stays in the list with status ready
K	stop — pauses the instance and preserves the branch; use r to resume

kill is reversible: the branch survives. stop is also reversible: r resumes from where the agent left off.

both actions are also available in the instance context menu (↵ on an instance row).

pausing, resuming, and checkout

pause (K) stops the tmux session and records the instance status as paused. the worktree and branch are untouched.

checkout (c) pauses the session and copies the branch name to your clipboard so you can check it out locally:

c
 └─► session paused
 └─► branch name copied to clipboard
 └─► help overlay shows the git commands

git checkout <branch-name>   # inspect the worktree locally

important: checkout requires a clean worktree on main. commit or stash any local changes on main before pausing, then r to resume when you're done. resume continues the agent exactly where it stopped.

resume (r) restarts a paused tmux session. the agent reconnects to the existing worktree and continues from its last state.

headless instance output

headless instances run as background processes managed by the daemon. they appear in the sidebar with the same controls as tmux instances except:

• attach (↵) is disabled — a toast informs you that the instance is in headless mode
• interactive mode (i) is disabled for the same reason
• all output is visible in the preview tab and the audit log

use the info tab (#) to see the instance's current status, wave number, and task number.

orphaned tmux session browser

if a tmux session exists but has no corresponding kasmos instance (e.g. it was started manually or kasmos crashed while a session was running), the session is orphaned.

press T to open the tmux browser overlay. it lists all tmux sessions. from there you can:

action	effect
↵	adopt the session — creates a kasmos instance for it and adds it to the list
a	attach to the session directly without adopting
k	kill the orphaned session

adopted sessions appear in the sidebar like any other instance. you can then attach, pause, or manage them normally.

instance context menu

press ↵ on an instance row (not a plan header) to open the instance context menu:

item	effect
open	attach fullscreen
kill	kill tmux session
restart	kill and restart the agent
pause / resume	pause or resume the session
focus agent	enter interactive mode
rename	rename the instance
push branch	push the instance's branch to origin
create pr	open the pr title input for this instance
open in browser	open the associated plan in the plan browser
mark complete	manually mark this task complete in the wave orchestrator

managing instances from the web admin ui

open /admin/instances in your browser while kas serve is running to see the same grouped agent list as the tui. each row has a three-dot (⋯) overflow button that opens a small action menu.

action	effect
pause	suspends the agent session; the row stays visible with status paused
resume	restarts a paused session from where it left off
restart	kills and immediately restarts the agent
kill	terminates the agent session; the row disappears from the list on the next refresh

actions are enabled or disabled based on the agent's current state — the menu reflects what the backend permits, so you never need to guess whether an action is valid.

kill requires confirmation. a dialog appears before the session is terminated. dismiss it with escape or click cancel to abort.

the browser preview panel includes a composer for writable instances. you can send input from the web ui when the selected instance supports it; paused or unsupported instances keep the composer disabled with an explanatory message.

filtering and sorting

key	effect
1	show all instances (default)
2	show active instances only (running, loading)
3	cycle sort mode (by status, by name, by creation time)
/	activate search — type to filter by instance title or plan name

related concepts

• agents and roles — execution modes, headless vs tmux
• worktrees — how isolated branches are managed
• tui overview — full keymap reference