Sessions

A session is one continuous conversation with one agent, scoped to one place on your filesystem. It holds the agent's messages, every tool call it made, the files it changed, and the turns you exchanged — all persisted, so you can leave and pick up where you stopped. Everything else in ORG-2 (the board, replay, Agent Blame) is a view over sessions.

Creating a session

Start one from the composer — New session in the spotlight, New Session in the sidebar, or the start page's New session card. Before you press Start, set:

• Session category — Built-in Agents (the native SDE Agent, or OS Agent for computer-use automation), CLI Agents, Custom Agents, Agent Teams, or External Agent for something like Cursor IDE.
• Model and Account — the model to run and which connected key or subscription pays for it. See api-keys.
• Mode — the agent's execution mode (below).
• Repo and branch — the two-segment pill under the input.
• Running location — This Mac or New Worktree.
• Add Context — type @ for files, / for skills and commands.

If you have no repo yet, Clone from GitHub takes a URL and clones it into a temporary workspace. A prompt is required and must be under 10,000 characters; anything shorter than 15 gets a Short Input confirmation. You can attach up to five images.

Execution modes

The mode sets what tools the agent may use. Three appear in the picker:

Two more exist as wire values but are not in the picker: review, which drives background work-item review, and wingman, the passive observer mode.

Scoping to a repo, branch, or worktree

Every session is pinned to a workspace. Clicking the repo segment of the pill switches the repo; clicking the branch segment opens the branch picker and performs a guarded checkout, warning you if the working tree would conflict.

Choosing New Worktree instead of This Mac runs the session in its own git worktree, so an agent can work on a branch without touching the files you have open. The runner is then locked for the session's lifetime — "Locked to Worktree — runner can't change after launch." When the work is done you resolve the worktree explicitly, with a merge strategy of Auto merge (no-ff), Fast-forward or Leave as branch; merging is refused while the repo has uncommitted changes, and Discard deletes the branch and its changes permanently.

Worktrees live under ~/.orgii/agent-worktrees/, and a repo allows eight at once by default. A Cloud running location exists in the UI but is currently disabled.

The Workstation

The Workstation has three station modes: My Station (your editor, terminal, browser and files — the default), Agent's Station (a mirror of what the agent is doing), and Ops Control (the board across all sessions).

My Station uses a single flat tab pool routed to four content hosts, which is also how the dock filter groups tabs: Code (files, explorer, diffs, source control, git log and commits, search, terminal, output, settings, lint scans, subagent detail, AI Impact), Browser (browser sessions and DevTools), Database (tables, queries, schemas, connections) and Projects (dashboards, work items, project and org settings).

Agent's Station has its own dock — Diff, Communication, Code Editor, Browser, Project Manager, Canvas and Background Tasks. Its Trajectory panel shows the raw event stream in UI or JSON form, and its Diff surface shows what changed, scoped to This session or All uncommitted. When the agent drives a browser, the overlay makes control explicit: Agent controlling / User in control, with Take Over and Return to Agent.

Turns and turn intent

A turn is one user submission and everything the agent did in response — ORG-2 also calls these rounds. Each is indexed with its start and end position, duration, event count, status, whether it was interrupted, and the files it modified, so "N files changed this round" is a stored fact rather than something recomputed on screen.

Every submission also gets a turn intent: one canonical id minted when you press send and carried through the optimistic message, the wire call, the scheduler, the persisted event and the turn index. It walks a small state machine — optimistic → queued → running → completed, failed or cancelled — plus stale for an intent invalidated before it ever ran, as when you rewind or edit and resend. That is why a message you queue and then rewind past does not silently reappear as a second turn.

Underneath a turn are events: one per tool call, message, thought, plan, approval or error, each stored with its arguments, its result and a typed payload. That record is what replay plays back and what Agent Blame indexes.

Following, interrupting, and redirecting

While a session runs you can Follow it — the view tracks the agent's current app and auto-scrolls; switch to Free browse to click around without losing the stream. When the agent asks a question, requests permission or proposes a plan, the turn sits in awaiting_user until you reply.

To redirect it, just type: your message is queued rather than dropped, can still be edited, and can be sent now to cut the current work short. To halt it, press Stop — the composer's send button becomes a stop button while a turn runs. The sidebar also has Stop agent process, and shell commands have their own Stop.

The three ways a turn can end early are not equivalent. Stop kills everything the session spawned. Send now kills foreground shells but lets background workers and dev servers survive. Rewind kills nothing — it rewrites the timeline rather than stopping it.

Resume differs by session type. CLI sessions can be resumed as a process; native agent sessions cannot — "Agent sessions cannot be resumed. Send a new message instead."

Rewinding and continuing work

To go back, hover an earlier message of yours and choose Restore checkpoint. Everything after that point is truncated and, by default, the session's file history is rewound to the pre-turn bytes; if the agent changed files since, ORG-2 asks what to do with them — Revert changes or Keep changes — rather than deciding for you. You can also Regenerate a response, Copy turn or Export as Markdown.

There is no user-facing fork or duplicate action. Continuing work means sending another message to the same session, or starting a new one against the same repo and branch. The context meter tells you when the second is the better option: "Context is filling up. Start a new session soon for best results."

Where sessions are stored

Everything lives under ~/.orgii/. The database is ~/.orgii/sessions.db, holding events (one row each, indexed by session and sequence and mirrored into an FTS5 index so session contents are searchable), session_turns, session_turn_intents, code_sessions and code_session_chunks for CLI-agent sessions, plus sessions, session_token_usage, repos and workspaces. Attachments go to ~/.orgii/session-images/, and the archive that rewind restores from is ~/.orgii/file-history/<session_id>/.

Nothing is uploaded unless you turn on sharing for an ORG; see collaboration and security.

Archiving and the board

Ops Control shows sessions as cards in columns — Todo, In Progress, Blocking, Turn Finished, Archived — with List, Diary and Ops Control views, filters by agent type, and a time Range of 12h / 24h / 3d / 7d.

Archive a card by hand, or leave it to Auto archive, which moves idle sessions aside after 12h, 24h (the default), 3d or 7d, or Never. Active sessions are never auto-archived, and archiving is a board state rather than deletion — an archived session keeps its full record and stays replayable.

Deleting is the destructive one. Right-click a session in the sidebar for Rename, Export as Markdown, Pin and Delete. Delete removes the row and its events, kills any running process, and removes the session's worktree and per-session config — with no confirmation dialog on that menu.

Limits

ORG-2 does not cap how many sessions you create or run concurrently, and local sessions do not expire. The limits you will meet are a prompt length of 10,000 characters (with a confirmation under 15), five images per message, eight concurrent worktrees per repo (git.worktree.maxCount), the model's context window — shown as the context meter, with per-agent compaction settings — and, if you sync, the per-plan quotas described in cloud.

Next steps

• Replay — scrub a recorded session, and trace a file back to the session that changed it
• Agents — the agents you can run, and how CLI sessions are ingested
• Projects — repos, worktrees, and work items
• Collaboration — sharing sessions with teammates