Core concepts

ORG-2 uses a small set of nouns consistently across the UI, the docs, and the on-disk format. Learning them once makes everything else easier to read. This page defines each one in the app's own vocabulary and shows how they fit together.

How the pieces nest

org
 └── project
      └── work item          (what should happen)

workspace (one or more repos)
 └── session                 (what actually happened)
      └── turn / round
           └── event

The two halves meet through links, not strict containment. A session is anchored to a workspace path and a branch, not to a project; you link a session to a work item when you want the plan and the execution record to point at each other. Sharing is scoped by org: a teammate sees your sessions only for workspaces you have explicitly allowed.

Workspace, repo, and project

A repo is a single Git working tree on disk. The sidebar and Launchpad group these under My Repos. It is the unit that Git status, branches, and diffs attach to.

A workspace is one or more folder roots opened together — the multi-root model familiar from VS Code and Cursor. Each root is either a Git repo or a plain folder, and one is marked primary; the primary root is the default working directory handed to agents and language servers. A saved multi-root workspace is a .orgii-workspace file, listed separately as My Multi-Repo Workspaces. When a session card shows a "workspace", this is what it means.

A project is a planning object, not a folder. It lives in the Project Manager, belongs to an org, and holds work items. Each project has a sync method: Storage (a local database) or Git (via .orgii), which mirrors the org's projects and work items into .orgii/projects/... inside a Git working tree so they travel with the code.

Session, turn, and event

A session is one continuous conversation with one agent, against one workspace. It carries a title, an agent, a model, an execution mode, a repo, a branch, a status, and its full event history. Sessions are long-lived: they survive closing the tab, they can be resumed, and background sessions keep running after their tab is gone. Status is explicit rather than a single busy flag — pending, idle, running, waiting_for_user, waiting_for_funds, paused, completed, failed, cancelled, abandoned, timeout, archived — where the last six are terminal. Each session has an execution mode that changes the system prompt and the available tools; the picker offers Build, Ask, and Plan.

A turn is one user-to-agent round-trip: your message goes in, the agent streams a response, calls tools, and loops until it stops. The chat UI calls these rounds — you will see Round 3 / 12, Your Turn, and Turn Finished, and the session detail view reports a Rounds count. The turn is the unit of cancellation, retry, and rollback: cancelling stops the current turn rather than the session, and each turn tracks its own token usage, tool calls, and touched files. A turn is in one of four states: running, completed, cancelled, or failed.

An event is the atomic record inside a session — a message, a thinking block, a tool call, a tool result, a file change, a terminal write. Each has an id, a session id, an event type, an optional tool name, arguments, a result, searchable text, a timestamp, and a monotonic history sequence number that fixes its order.

Trajectory and replay

The ordered event stream for a session is its trajectory. The Trajectory panel renders it two ways: a UI view with human-readable captions, and a JSON view with raw payloads. Because the trajectory is a durable ordered record rather than a rendering artifact, it is what makes replay, search, analytics, and sharing possible at all.

Replay is reading that trajectory back. Two surfaces use the word: Replay turn on a turn card replays a single round with its tool-call and file-change counts, while the session Simulator plays the whole trajectory with play/pause, a playback speed control, previous/next event stepping, and event filters (All events, Key interactions, File changes, Terminal events, Explore, Other). While a session is live, the same surface is a livestream — you follow the agent instead of scrubbing.

Agent, harness, and runner

An agent is a named, configured actor. The session creator groups them as:

• Built-in Agents — including the SDE Agent (coding), the OS Agent (computer-use automation), and the ADE Manager, a meta-agent that can spawn and coordinate other sessions and drive the app's UI through a structured action system.
• CLI Agents — third-party command-line agents you already have installed, such as Claude Code, Codex, or Cursor CLI. ORG-2 runs them and captures their trajectory.
• External Agent — activity from another IDE, currently Cursor IDE, imported and rendered as a trajectory.
• Custom Agents and Agent Teams — your own definitions, and groups of agents with a hierarchy.

Your harness is everything that stays constant when the agent underneath changes: your skills, MCP servers, rules, and the memories agents have built about your codebase. It is deliberately decoupled from any one vendor so you can swap agents without starting over.

The runner is where the work physically happens. The context bar shows This Mac or Worktree; a session launched against a worktree is locked to it and cannot switch runner after launch.

Work item

A work item is a single unit of tracked work inside a project — the app's equivalent of an issue. It has a status (Backlog, Todo, In Progress, In Review, Done, Cancelled), a priority (No priority, Urgent, High, Medium, Low), an assignee that may be a human or an agent, dates, labels, and an optional linked project. Views are Overview, List, Kanban, Gantt, and Calendar. Deleted items go to a Delete Bin and stay recoverable for 7 days.

Org, member, and role

"Org" means three different things. Keep them apart.

An Agent Team's hierarchy mode is flat (no structure shown), soft (the default — a hint, routing unrestricted), or strict (a member may only message its manager, its direct reports, or the coordinator).

In a collaboration ORG, a member is one participant with a role (admin or member — only admins create invite links) and an identity kind (human or agent — only humans can post in group chat). You join by pasting an orgii:// invite link or code. What you expose is set per-ORG by a session access mode: Off, Session cards only (titles, owners, branches, workspaces), or Full replay (teammates may request the full event snapshot).

Warning: Full replay can include prompts, outputs, tool calls, and file paths. It is opt-in per ORG and limited to an allow-list of workspace paths. See Collaboration.

Memory, skills, and MCP servers

Memory is what survives the end of a session, in two layers. Learnings are per-agent long-term memory: sessions produce Tier-1 items, which are periodically consolidated into Tier-2 themes while the app is idle, and new items arrive pending until you promote them to active so they enter the prompt. Workspace memory is workspace-scoped notes stored as files, by default under .orgii/workspace-memory/.

A skill is a Markdown capability an agent can opt into: a SKILL.md file with frontmatter, in .orgii/skills/ for one workspace or ~/.orgii/skills/ for all of them. Skills can be marked always-loaded, and settings flag any that are unavailable because a required binary or environment variable is missing.

An MCP server is an external tool server speaking the Model Context Protocol. Its tools register into the agent's tool set alongside built-ins, with name collisions gated at registration. Configuration is ~/.orgii/mcp-servers.json globally, or {workspace}/.orgii/mcp-servers.json per workspace.

Terms at a glance

Next steps

• Run your first session and watch the trajectory fill in.
• Read a trajectory back once the session finishes.
• Set up agents and connect your keys.
• Create an org when you are ready to bring in teammates.