Session Management

A session represents a single AI coding task running inside an OpenCode instance. Fleet manages the full lifecycle — from creation through completion or termination.

Creating a Session

To create a session, select a workspace directory and an isolation strategy. Fleet creates the workspace, spawns (or reuses) an OpenCode instance, and starts a new session.

Isolation Strategies

Strategy	What It Does	Best For
existing	Uses the directory as-is. Multiple sessions can share one directory.	Quick tasks on your current branch
worktree	Creates a git worktree from the source repo. Each session gets its own working tree with shared git history.	Parallel feature branches on the same repo
clone	Creates a full git clone of the source repo. Completely independent copy.	Total isolation — different branches, no conflicts

TIP

worktree is the recommended strategy for parallel development. It is faster than clone (shared git objects) and avoids the context collision of existing.

From the Dashboard

1. Click New Session in the top bar
2. Browse and select a workspace directory using the directory browser
3. Choose an isolation strategy (worktree recommended for parallel work)
4. Optionally set a title and branch name
5. Click Create

The session opens automatically in the detail view.

Via API

curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "/home/dev/my-project",
    "title": "Implement auth module",
    "isolationStrategy": "worktree"
  }'

Response:

{
  "instanceId": "uuid-...",
  "workspaceId": "uuid-...",
  "session": {
    "id": "session-uuid",
    "title": "Implement auth module"
  }
}

Session Lifecycle

Created --> Active --> Idle --> (Completed | Resumed --> Active)
                |
            Aborted --> Idle
                |
          Terminated --> Stopped
                |
           Instance dies --> Disconnected --> (Resumed --> Active)

Statuses Explained

Status	Description
active	Processing a prompt — the agent is working
idle	Finished processing — waiting for a follow-up prompt
stopped	Manually terminated by the user
completed	Finished and instance shut down
disconnected	Instance became unreachable (crashed or health check failed)
error	An error occurred during execution
waiting_input	Needs user permission (tool approval)

Sending Prompts

Send a prompt to an active or idle session.

From the Dashboard

1. Click on any session in the sidebar to open it
2. Type your prompt in the input area at the bottom
3. Press Enter to send

The agent's responses appear in real-time in the message stream above.

Via API

The response comes via the SSE event stream — the HTTP call is fire-and-forget.

curl -X POST http://localhost:3000/api/sessions/{sessionId}/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "uuid-...",
    "text": "Add error handling to the login endpoint"
  }'

Returns 204 No Content on success. Watch the SSE stream for results.

Targeting a Specific Agent

Include the optional agent field to route the prompt to a specific agent:

{
  "instanceId": "uuid-...",
  "text": "Write a plan for the refactor",
  "agent": "pattern"
}

Aborting a Session

Abort cancels the current operation without terminating the session. The session transitions to idle and can receive new prompts.

From the Dashboard

Click the Abort button in the session's toolbar to cancel the current operation. The session transitions to idle and can receive new prompts.

Via API

curl -X POST "http://localhost:3000/api/sessions/{sessionId}/abort?instanceId=uuid-..."

Resuming a Session

Resume reconnects a disconnected, stopped, or completed session. Fleet spawns a new OpenCode instance (or reuses one for the same directory), verifies the session still exists, and marks it active.

curl -X POST http://localhost:3000/api/sessions/{sessionId}/resume

WARNING

Resume fails if the workspace directory no longer exists (e.g., a worktree that was cleaned up) or the session was deleted from OpenCode's internal store.

Terminating a Session

DELETE terminates the session — aborts any running work, marks the session as stopped in the database, and destroys the OpenCode instance if no other sessions use it.

curl -X DELETE "http://localhost:3000/api/sessions/{sessionId}?instanceId=uuid-..."

Permanent Deletion

Add permanent=true to permanently remove the session from the database, including its notifications and callbacks. For worktree/clone workspaces, the workspace directory is cleaned up if no other sessions reference it.

curl -X DELETE "http://localhost:3000/api/sessions/{sessionId}?instanceId=uuid-...&permanent=true"

Workspace Cleanup

Add cleanupWorkspace=true to delete the worktree or clone directory when terminating.

Viewing Session History

The history endpoint returns past sessions with search and filter:

curl "http://localhost:3000/api/sessions/history?search=auth&status=completed&limit=10"

Query parameters: search, status, from, to, limit (default 20, max 100), offset.

Viewing Diffs

Get the file diffs generated by a session's agent.

From the Dashboard

Open a session and click the Diffs tab to see all file changes. Additions are highlighted in green, deletions in red. Each file shows the number of lines added and removed.

Via API

curl "http://localhost:3000/api/sessions/{sessionId}/diffs?instanceId=uuid-..."

Returns an array of file diffs with file, before, after, additions, deletions, and status (added, deleted, modified).

Parent-Child Sessions (Callbacks)

When creating a session, you can specify an onComplete callback that notifies a parent session when the child finishes. This enables orchestration patterns where one agent spawns and monitors sub-agents.

{
  "directory": "/home/dev/my-project",
  "title": "Sub-task: implement tests",
  "onComplete": {
    "notifySessionId": "parent-opencode-session-id",
    "notifyInstanceId": "parent-instance-id"
  }
}

When the child session completes, Fleet sends a callback prompt to the parent session with a summary of files changed and final status.