Sessions

Overview

A session is the durable unit of work for an agent run. It owns the user and assistant message timeline, tool parts, status, permissions, questions, diffs, todo state, background children, workspace metadata, and share/export data.

Create or continue

Sessions can be created from the root TUI command, nikcli run, mobile, the web app, or the API. The TUI entry command is nikcli [project]; it starts a worker, validates any provided session id, then opens either a direct RPC UI or a network-backed UI.

nikcli                         # start TUI in the current directory
nikcli ../repo --model openai/gpt-5
nikcli --continue              # continue last session
nikcli --session ses_example   # open a specific session
nikcli run "fix the failing test"

Session record

The session info object is defined in packages/nikcli/src/session/index.ts. It carries identifiers, title, project/workspace metadata, directory, parent links, GitHub or container metadata, timestamps, and summary fields.

Messages and parts

Messages are split from parts so streaming tool calls, text, reasoning, files, diffs, and metadata can update independently. The API exposes both full message reads and part-level mutation routes.

Prompt execution

Prompt execution combines agent config, system prompts, message history, tool registry, MCP and connector tools, permissions, and provider selection. The hot path reaches packages/nikcli/src/session/llm.ts, which normalizes message shapes before calling the provider runtime.

1. User input is persisted as a user message and queued for the session.
2. Session services build system context from agent, config, instructions, tools, skills, project, and locale.
3. Tool availability is gated by model capability, config, MCP state, connector state, and experimental flags.
4. Permissions call PermissionNext.ask before risky actions such as edits, shell, or LSP.
5. LLM.stream chooses provider/model, repairs UI-shaped messages when needed, and streams output.
6. Assistant text, reasoning, tool calls, results, and completion metadata update the message timeline.

Status and events

SessionStatus exposes busy, idle, and retry state. The typed API returns a status map at GET /session/status. The TUI reads status through the sync context and mobile displays status chips in lists and cards.

curl "http://127.0.0.1:4096/session/status?directory=$PWD"

Permissions and questions

Pending permissions and questions are session-scoped live prompts. The TUI aggregates pending requests across a root session and its children; mobile exposes approval and question bars in the composer. Permission replies can approve once, approve always, or reject with optional correction feedback.

Fork, children, background

A fork creates a new child session from an existing session and optional message boundary. Background task tools also create worker sessions and attach them to a parent. The session UI treats root sessions and children differently so parent-level permission/question prompts are not duplicated inside child routes.

Diff, revert, unrevert

Diffs are produced from snapshots, VCS state, and message/tool output. The summary diff route can scope to a message id. Revert and unrevert operate through SessionRevert and return the updated session info.

curl "http://127.0.0.1:4096/session/ses_example/diff?messageID=msg_example"

curl -X POST http://127.0.0.1:4096/session/ses_example/revert \
  -H "Content-Type: application/json" \
  -d '{"messageID":"msg_example"}'

curl -X POST http://127.0.0.1:4096/session/ses_example/unrevert

Sharing and export

Sharing is controlled by config and environment flags. New root sessions may auto-share when NIKCLI_AUTO_SHARE is set or config share is auto. Public share reads are intentionally mounted before auth at /s/:shareID, /share/:shareID, and /api/share/:shareID.

Mobile and workspace sessions

Mobile sessions use the same core session services but route through /mobile/* endpoints that bundle status, git stats, project metadata, and execution target information. Workspace-backed sessions carry workspaceID, letting the server route later session requests to a local or remote workspace target.

• Mobile lists pair Session.Info with optional SessionStatus.Info.
• Container-backed workspaces report runtime availability from workspace/adaptors.
• Remote workspace requests are proxied before the route group handlers execute locally.
• Route-session lookup lets /session/:id requests recover the original workspace context even when the caller omits workspace headers.

Failure modes

Source anchors