Creating Sessions

Press a in the dashboard to create a new agent session. The wizard walks through directory, harness, skill, model, thinking effort, and an optional first message.

Directory selection

The session creator uses the z zsh plugin to suggest directories ranked by frecency (frequency + recency). Start typing a path and suggestions appear automatically.

The z plugin is optional. Without it, you can type full paths manually.

Harness and model selection

After choosing a directory, pick the harness that backs the session — Claude Code or Codex CLI (the default comes from [harness] in settings). The wizard then offers the harness’s models (fable, opus, sonnet, haiku for Claude; gpt-5.5 and friends for Codex) and a thinking-effort level, both of which override the settings defaults for this spawn only.

The model and effort pickers show what (default) currently resolves to. The model hint reads the effective spawn default: dashboard Codex settings first, then the underlying agent config (~/.claude/settings.json or ~/.codex/config.toml), then the harness’s first advertised model. The effort hint reads dashboard settings first ([effort].default for Claude, [harness.codex].default_reasoning_effort for Codex), then native config (effortLevel in ~/.claude/settings.json or model_reasoning_effort in ~/.codex/config.toml), then harness built-in when no value is configured. Hints are cached for 1 hour; refresh with Ctrl+R in the TUI picker, or the refresh button in web, when you have just edited agent config.

Skill selection

Next, select a skill that determines the agent’s workflow:

Skill Purpose
feature New feature development with TDD in an isolated git worktree
fix Bug fix with root cause analysis
chore Non-code changes (docs, config, CI)
refactor Code restructuring with test preservation
investigate Research and analysis without code changes
implement Execute an approved plan phase-by-phase with context isolation
pr PR review and iteration workflow
rca Root cause analysis for incidents

Each skill loads a specialized prompt that guides the agent through the appropriate workflow — including branching strategy, testing requirements, and delivery steps.

Effort levels

The dashboard pins a Claude Code thinking-effort level on every spawned session and switches it dynamically as the agent works:

  • Every dashboard-spawned session starts with --effort {effort.default} (default: high) — Claude Code pins this at the session level.
  • When the agent enters plan mode (EnterPlanMode), the agent-state-fast adapter hook dispatches /effort {effort.plan} (default: high) into the pane and restores default on plan exit. With both keys set to high (the shipped default) the swap is a no-op; raise effort.plan to max if you want planning to think deeper than implementation.
  • The feature, fix, and refactor skills additionally declare effort: max in their frontmatter. This applies only when the skill is invoked as a slash command (/feature, /fix, /refactor) inside an existing session — not when the dashboard launches a new agent with one of those skills selected.

Override the defaults in settings.toml under the [effort] section, or per spawn in the wizard’s effort step. Valid levels: minimal, low, medium, high, max (Codex clamps max to high).

What happens next

The dashboard:

  1. Creates a new tmux pane
  2. Starts the chosen harness in the selected directory with the chosen skill, model, and effort
  3. The adapter hooks begin writing agent state files
  4. The agent appears in the dashboard list within seconds

Resuming orphaned sessions

When tmux dies — a reboot or tmux kill-server — agent panes are gone but their session state survives. Orphaned sessions linger in the dashboard as resumable instead of being garbage-collected:

  • TUI — press / to open the search palette, Ctrl+O to filter to orphans only, and Enter to resume the selected orphan in a fresh pane (Enter on a live agent jumps to its pane instead).
  • Web — the Cmd+K palette marks resumable sessions with a pill and has an “orphaned only” toggle; selecting an orphan resumes it.

Resuming runs the harness’s native resume (claude --resume <session-id> or codex resume <session-id>), so the conversation continues where it left off.