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 sdk), 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.

sdk instances are not attachable — they run as in-process backends without a PTY. 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.

sdk instance output

not all sdk instances are equal. kasmos distinguishes two classes:

daemon-managed sdk agents are wave execution agents started by the orchestrator and registered with the kasmos daemon. the daemon owns their process and exposes dedicated capture, send, and lifecycle routes. the web admin ui can pause, resume, restart, kill, send input to, and capture output from these instances — they show up in /admin/instances with the full three-dot action menu. the ManagedByDaemon field on the livepreview.Record (internal/livepreview/records.go) distinguishes them from standalone records.

standalone sdk agents are sessions started directly from the TUI with N, s, or S when the resolved execution mode is sdk. they run in-process inside the TUI and are written to the on-disk state.json as ordinary instance records — they are not registered with the daemon.

both classes appear in the sidebar with the same controls as tmux instances except:

• attach (↵) is disabled — a toast informs you that the instance is in sdk 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. for instances spawned as sdk-fast, the info pane also shows a speed tier: fast row beneath the execution mode row.

sdk-fast sessions. when you choose sdk-fast in the S spawn picker (codex only), the session runs as an ordinary sdk session with SDKSpeedTier = "fast". it shares all the same standalone sdk limitations listed above — attach and interactive mode are disabled, and the web admin ui has no actions available. the fast tier is forwarded once at session start (serviceTier: "fast" on thread/start); it is not re-negotiated during the session.

typing /fast inside a running codex sdk pane. keystrokes typed in interactive mode are forwarded verbatim to the codex process. if you send /fast manually, codex may switch its internal rate-limit lane, but kasmos does not intercept that command: the stored SDKSpeedTier field on the instance record is not updated, and previously written audit-log events are not revised. the info pane will continue to display whatever tier was set at spawn time (sdk-fast or blank).

web admin ui limitation — standalone sdk agents only. livepreview.ValidateAction (internal/livepreview/records.go) rejects every lifecycle and i/o action for standalone (non-daemon-managed) sdk instances: send, capture, pause, resume, restart, and kill all return an error. as a result, /admin/instances shows these instances in the list but the three-dot overflow menu is empty — no actions are available. the browser preview panel's composer is also disabled. this applies equally to sdk and sdk-fast standalone sessions — the fast tier does not unlock any additional web-ui capabilities. this is a known limitation: the web path has no tmux pane and no daemon to delegate to.

if you need web-ui control over an sdk agent, start it through a plan so the daemon manages its lifecycle.

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, sdk vs tmux
• worktrees — how isolated branches are managed
• tui overview — full keymap reference