Sessions

Everything on this page drives a cloud session over the same /v1 API the dashboard uses. What a session is, its statuses, and how it executes: Cloud Agents sessions. Install and authenticate first: Agent CLI.

Start

agent session start starts a session in the Ellipsis cloud. The prompt is the per-session instruction and can be positional (or -p/--prompt; pass one or the other, not both):

agent session start "triage the failing CI on splitshift-api"

A config source is optional. With none, the session runs your team's default agent: the repository default for the repo you are standing in if one is set, else the account default, else a bare ad-hoc config (an empty system prompt on claude-opus-5, no triggers), so the prompt is the sole instruction. When a default resolves, the CLI says which agent picked up the work. The CLI also detects the repository you are standing in (the origin remote) and sends it along; the server clones it into the sandbox on top of whatever the config declares.

To start from a saved config, an inline config file, or a built-in template, pass at most one of -c/--config (a saved config id), -f/--config-file (a .yaml/.yml or .json file), or -t/--template (a slug from agent template list):

agent session start --config agent_x9Kd3Fq2
agent session start --config-file agents/ci-triager.yaml
agent session start --template welcome-to-ellipsis --watch

Sugar flags set individual config fields for one session without editing a config: --model, --system (the system prompt), -r/--repo (repeatable, owner/name or a bare name), --cpu, --memory, --timeout, and --budget (per-session USD). They merge into one override on top of the chosen or default config; --config-override (inline YAML) and --config-override-file take a full partial config, and an explicit sugar flag wins over the same field in a raw override. --rebuild skips the sandbox image cache for a fresh full build, -m/--metadata key=value attaches metadata (repeatable), and --json prints the raw API response.

By default start returns as soon as the session is created (-d/--detach). Two flags block instead: -w/--watch streams live output until the session reaches a terminal status, and --connect opens the interactive view (see Connect). --watch --quiet waits without streaming steps, printing only status transitions and the final summary; either watch form exits 0 only when the session completes, so it works as a CI gate.

$ agent session start "triage the failing CI on splitshift-api" --watch
using config "CI failure triager" (repo default)
✓ started session session_7Hq2mX4p
  https://app.ellipsis.dev/splitshift-hq?session=session_7Hq2mX4p
09:14:03  scheduled
Session scheduled · CI failure triager
Session starting…
Starting sandbox…
Preparing image…
Fetching repositories…
Sandbox ready · splitshift-hq/splitshift-api · cached image
09:14:31  running
Bash  (gh run list --repo splitshift-hq/splitshift-api --limit 10)
Read  (splitshift-api/tests/trades/test_expiry.py)
Bash  (cd splitshift-api && pytest tests/trades/test_expiry.py -q)
The failing job is test_trade_expiry_grace_period: the fixture freezes time
before the trade is created, so the 24h grace window is already expired when
the assertion runs. Opened splitshift-hq/splitshift-api#512 with the fix.
09:19:47  completed

✓ session session_7Hq2mX4p completed

List, inspect, and re-run sessions:

agent session list --limit 20              # filter with --config, --source, --author, --days, --since, --until
agent session get session_7Hq2mX4p         # one session's status, cost, and dashboard link
agent session get session_7Hq2mX4p --watch # follow a running session until it finishes (--quiet for the result only)
agent session record session_7Hq2mX4p      # the stored transcript, one line per record
agent session log session_7Hq2mX4p -o session.jsonl   # download the complete archived log
agent session replay session_7Hq2mX4p      # re-run the session's trigger input as a fresh session

$ agent session list --limit 3 --source cli
ID                STATUS     SOURCE  CREATED           COST
session_7Hq2mX4p  completed  cli     2026-07-29 09:14  $0.87
session_3Vd8nQ2j  completed  cli     2026-07-28 16:40  $1.42
session_5Kp9wB3n  error      cli     2026-07-28 11:02  $0.19

--source filters on where a session came from: laptop, react, manual, api, cli, mention, or cron. --author takes a GitHub login and resolves it against agent github members. --since and --until accept ISO 8601 or the natural forms today, yesterday, and N days ago.

agent session log concatenates the archived log segments and prints them gunzipped (-o writes a file, --gzip keeps the compressed bytes, --json prints the segment manifest instead). While a session is still running, the archive can trail the live feed; the command says so and you re-run it shortly for the rest.

agent session replay re-runs a finished session, optionally with changes: -c/--config swaps the saved config, --config-override/--config-override-file merge a partial config, -p/--prompt replaces the prompt (pass '' to clear it, omit to inherit), and -w/--watch/--quiet follow the new session.

Connect

agent session connect opens a running session in your terminal: the conversation so far, live output as it happens, and a composer to send messages the agent picks up at its next turn boundary.

agent session connect session_7Hq2mX4p              # follow live and send messages
agent session connect session_7Hq2mX4p --no-input   # follow read-only (no composer), for scripts

--no-records skips replaying prior records on open. Inside an Ellipsis sandbox the session id is optional: the current session is used automatically. When you quit, the session keeps running and the CLI prints the command that reopens it:

resume with: agent session connect session_7Hq2mX4p

The composer appears only for a session that accepts messages: one you started (CLI, API, or dashboard) whose agent is interactive. Connect to a session a trigger started and it opens watch-only with a note saying why: a mention session is steered by replying on its Slack thread, GitHub comment, or Linear issue, where the agent's answers post; react and cron sessions are single-shot. Following is never restricted, so you can watch any of your sessions.

agent session start --connect starts a session and drops straight into this view. With no prompt, the session starts idle and your first message is its first instruction, like a local claude. If the config sets interactive: false, the connect degrades to watching with a printed note, because the server refuses the message surface for non-interactive sessions.

Stop an in-flight session at any time:

$ agent session stop session_7Hq2mX4p
✓ stopped session session_7Hq2mX4p (stopped)

IDE

agent session ide opens a live session's sandbox in the browser IDE: the same working tree the agent is editing, with a terminal. The URL is the sandbox page in your dashboard, gated on org membership, so it grants nothing by possession and is safe to paste in Slack.

$ agent session ide session_7Hq2mX4p
https://app.ellipsis.dev/sandboxes/sbox_2Kf8pQ4w

--no-open prints the URL without opening a browser; --json prints the raw response.

agent session port opens a preview of a port the sandbox is listening on: a dev server the agent (or you, from the IDE terminal) started. Any TCP port serves; 3000, 5173, 8000, and 8080 are the usual dev-server picks. The preview renders while something in the sandbox listens on that port.

$ agent session port session_7Hq2mX4p 3000
https://app.ellipsis.dev/sandboxes/sbox_2Kf8pQ4w?port=3000

Both require a running sandbox: a session that has gone idle answers with an error telling you to send it a message first (agent session connect), which wakes the conversation in a fresh sandbox. IDE and port access is on by default and controlled per agent by the config's ellipsis.ide flag; an agent with ide: false refuses both. Details on the sandbox side: IDE and ports.

Search

agent session search searches your team's whole session history from the terminal, across four arms at once: transcript text, recap text, created pull requests, and recap similarity. Results are grouped by session, newest first, with the matching snippet under each.

$ agent session search "shift trade webhook" --since "3 days ago"
session_7Hq2mX4p  completed  priya-shah  2 days ago  matched: records, recap
    Traced the duplicate shift-trade webhook deliveries to a missing idempotency key on the trade-accept path.
    6 matching records
session_3Vd8nQ2j  completed  marcus-lee  3 days ago  matched: records
    the webhook retry queue drains twice when the trade engine restarts mid-delivery
    2 matching records

Inspect one: agent session get <session-id>. Full log: agent session log <session-id>

A PR-shaped query (#512, splitshift-web#512, or a pull request URL) also finds the session that created that exact pull request:

agent session search "splitshift-hq/splitshift-web#512"
agent session search "webhook retries" --author marcus-lee --since "3 days ago"

Narrow further with -r/--repo, -s/--source (repeatable), --status (repeatable: scheduled, creating_sandbox, running, retrying, completed, error, cancelled, stopped), -c/--config (a config id, repeatable), --session (repeatable), --scope records|recaps|both, and -l/--limit (default 20, up to 100). -a/--author and --since/--until work as on list. Follow a hit with agent session get for status and cost, agent session record for the full timeline, or agent session log for the complete archive.

Sync

agent hook manages local session sync: Claude Code hooks that upload each session you run in an enrolled repository, so laptop work appears in the same session history (and the same search) as cloud work. The full workflow: Search every agent session your team has run.

$ agent hook install
Installed Stop + SessionEnd hooks in /Users/priya/.claude/settings.json.
No repositories enrolled yet, so nothing will sync. Run `agent hook enroll` inside a repo to opt it in.
$ cd ~/code/splitshift-api && agent hook enroll
Enrolled splitshift-hq/splitshift-api. Claude Code sessions in this repo will sync.

Sync is opt-in per repository: nothing uploads until you enroll a repo, and agent hook unenroll opts it back out. The hooks are otherwise silent, so the state commands answer "is it working":

$ agent hook status
HOOK        INSTALLED
Stop        yes
SessionEnd  yes

ENROLLED REPOSITORY
splitshift-hq/splitshift-api

Last sync 4m ago (synced), 12 synced / 0 failed in 24h, 0 spooled pending

agent hook log shows what the background syncs did, newest last (-n/--tail for the last N entries, --failures for only failed ones, --json for NDJSON); agent hook stats prints the sync counters; agent hook uninstall removes the hooks and keeps every enrollment. A sync that fails on the network spools to disk and flushes on the next successful sync, and a hook failure never interrupts your Claude Code session.

agent session sync is the upload itself, normally invoked by the hooks with their context on stdin; --transcript, --session-id, --reason, and --cwd exist for manual runs.

Once a laptop session is synced, hand it off: agent session handoff pushes a snapshot of your working tree (without disturbing it) and continues the work in a fresh cloud session.

$ agent session handoff "finish the retry backoff and add tests" --parent session_5Kp9wB3n
✓ pushed working-tree snapshot 4c19e7d2a8b1 to refs/ellipsis/handoff/4c19e7d2a8b1
✓ started handoff session session_9Rw3kT6v (scheduled)
  https://app.ellipsis.dev/splitshift-hq?session=session_9Rw3kT6v
  follow with: agent session get session_9Rw3kT6v --watch

-p/--parent names the synced laptop session to chain from (find it with agent session list --source laptop); --cwd picks a repository other than the current directory. The snapshot is pushed to a hidden ref, never a branch, so it does not appear in branch UIs; pushing requires push permission on the repository.