Agents

"Agent" means two different things in ORG-2, and the distinction shapes almost everything else. There are built-in agents, which run inside ORG-2's own Rust engine and use its tools, permissions, and event record; and there are CLI agents, third-party binaries such as claude or codex that ORG-2 launches as child processes and whose output it parses back into the same record. This page covers both, the supported list, and what you can configure.

Built-in agents versus CLI agents

The sidebar groups sessions accordingly: OS Agent, SDE Agent, Wingman Agent, Custom Agent, CLI Agent, and Cursor History. In Settings, the equivalent sections are Built-in Agents, Custom Agents, CLI Agents, and Teams.

The built-in agents

Built-in agents are defined in Rust and cannot be deleted. They form a small inheritance tree rooted at builtin:base, a minimal template:

• OS Agent — general-purpose assistant and the only agent that chat channels talk to.
• SDE Agent — the coding assistant, described in Settings as a "Workspace-scoped coding assistant — model, iterations, compaction, and tool policy".
• Wingman Agent — a passive desktop co-pilot mode.
• Explore and General — delegation sub-agents. Explore is read-only codebase search; General has full tool access. Both are always reachable and cannot be added to or removed from an agent's sub-agent list.
• Memory extractor and memory consolidator — background workers, covered in Memory.

A few more ship for internal roles — an AI-research agent, a work-item manager, and an agent architect — and are not normally started by hand.

Supported CLI agents

These are the CLIs ORG-2 can install, authenticate, and drive. One registry backs both the setup wizard and the launcher.

Each row in Settings → Models & Keys → CLI Clients shows whether the binary is Installed, what it was Installed via, and an install and uninstall script for the package managers that tool supports — curl, Homebrew, npm, WinGet, uv, and so on. Authentication for each is covered in API keys.

Note: These eight are the agents ORG-2 launches and supervises directly. Sessions from several other tools can be read into the record without ORG-2 driving them — see Reading sessions from other tools below.

How ORG-2 launches and supervises an agent

A built-in agent needs no process: your message goes to the session runtime, through the turn executor, out to the model provider, and the tool calls it returns are executed by the Rust tool layer. Everything is written to the session's event record as it happens, which is what makes Replay possible.

A CLI agent is a subprocess. ORG-2 builds an explicit non-interactive command, spawns it with piped stdio (not a PTY), streams its stdout through a per-vendor parser, stores the resulting activity chunks, and broadcasts them to the UI. Spawning is retried up to three times with a short backoff, and every live process is tracked so cancelling a session terminates its whole process tree. Three consequences surprise people:

• CLIs are launched pre-approved. Claude Code gets --dangerously-skip-permissions, Gemini CLI --yolo, Copilot --allow-all-tools, Cursor --force --approve-mcps, and Codex --sandbox workspace-write. The approval settings ORG-2 exposes for those tools edit their own config files and mostly do not apply to runs started from ORG-2. Use ORG-2's session modes and a worktree if you want restraint.
• Only Claude Code and Codex accept extra directories. In a multi-root workspace, other CLIs see only the primary root, and the runner logs a warning rather than dropping it silently.
• Copilot, Kiro, and OpenCode speak ACP, the Agent Client Protocol, as bidirectional JSON-RPC over the child's stdin and stdout. Their approval requests surface as ORG-2 permission prompts, with a remembered always allow.

For CLIs that accept a base-URL override — Claude Code, Codex, Gemini CLI — ORG-2 injects credentials through the vendor's own environment variables. Cursor, Copilot, and Kiro do not, so ORG-2 can instead run a short-lived local HTTPS proxy on an ephemeral port for that session and intercept the CLI's API traffic. That path needs a one-time CA certificate install and is used only when credentials have to be swapped.

Choosing a model

Model choice is per session. The pill under the composer opens a two-column palette — Recent Models across the top, then All Models on the left and the Accounts that can serve them on the right, so you pick a model and the key that pays for it in one pass. Where a model has several reasoning variants, a versions pill lets you pick the Effort level between Faster and Smarter.

Each agent also carries a Default Model, a preferred account, and an optional Summarization Model used for compaction — "empty = use the agent's main model. A fast model is recommended." Reliability settings sit alongside: Provider Retry, Max Retries (1–10), Base Backoff in milliseconds, and a comma-separated list of Fallback Models tried after the primary is exhausted.

Modes, permissions, and isolation

A built-in agent runs in an execution mode that decides which tools exist at all. The picker offers Build (the default, full tool access), Ask (read-only research and Q&A), Plan (produce a plan file gated by your approval), and Debug (reproduce, narrow hypotheses, root-cause). Two more modes — review and wingman — exist as wire values but are driven internally. For a CLI agent, ORG-2 cannot change its tool set, so it injects a mode instruction into the prompt instead; treat that as guidance rather than enforcement.

Underneath the mode sits a per-agent policy: Access Mode (Read Only / Read + Write), Workspace Only, Forbidden Paths, a command Block List, and an Always Ask List. High-risk commands are always blocked regardless of the agent. When a tool call needs your consent you get a Your permission is needed prompt with Allow, Deny, and Always Allow; the prompt times out after five minutes, and always-allow rules can be per-tool or per-pattern and are persisted in .orgii/permissions.json.

Warning: ORG-2 does not run agents in an OS-level sandbox. The real isolation primitive is a git worktree — a sub-agent can be given Worktree isolation, "Run in a temporary git worktree (isolated file and shell access)". See Security and privacy.

Agent definitions and custom agents

Every agent, built-in or not, is one agent definition. The interesting fields are its identity and Soul ("Agent's identity and voice" — the role-and-voice prompt that opens its system prompt), what it inherits from, its capability set, its tool allow and deny lists, its sub-agents, its model and account preferences, its policy, and its session model, including max iterations per turn, which defaults to 500.

Create one under Settings → Agent Teams → Agents with Add Agent. The wizard has four tabs:

• General — Agent Name ("Unique name to identify this agent"), Description, and the Soul markdown editor.
• Models — Context Window (Auto (follow model) or a custom value), Max Response Tokens (default 16384), Temperature (default 0.0), and Context Compaction, which when enabled exposes a trigger ratio, a keep ratio, a Summarization Model, and several token floors.
• Capabilities — "Toggle which subsystems this agent can use; disabled capabilities turn off their tools and gating logic at runtime": Coding (with a nested Mode Switch toggle), Desktop, External Browser, Internal Browser, Gateway, Data, and Management. All default off except Mode Switch.
• Subagents — Add Sub-Agent…, per-sub-agent Worktree isolation, and Max tool-use concurrency ("Concurrent tool calls per assistant message. Default: 10.").

Tools, MCP servers, skills, and rules are edited afterwards on the agent's own detail tabs. Custom agents are stored as one JSON array in ~/.orgii/agent-definitions.json; built-in agents stay compiled in, but a user overlay at ~/.orgii/builtin-overrides.json lets you re-pin their model, tools, and policy without forking the source.

Importing agents written for other tools. Import from another platform scans your repo and home directory for vendor agent files under .claude, .cursor, .codex, and .gemini and converts each into an ORG-2 agent.

Teams. Add Agent Team groups agents under a Coordinator with a Hierarchy mode — Flat (everyone can message everyone), Soft, the recommended default, where reporting lines are a hint to the model but routing stays unrestricted, or Strict, where a member may only message its manager, its direct reports, or the coordinator. A Strict-mode reachability preview dry-runs who can reach whom before you launch.

Sessions started in other tools

ORG-2 reads history that other tools wrote on your machine, so work you did outside the app still shows up in the sidebar, grouped by source: Codex App, Claude Code, OpenCode, Windsurf, WorkBuddy, and Cursor History. These sessions are read-only — you can browse and replay them, but sending a message to one is refused. There is no toggle: ingestion is always on, lazy, and cache-backed, and Cursor's database is opened strictly read-only.

Claude Code is read from ~/.claude/projects/*/ (its sessions-index.json plus per-session JSONL), Codex from ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl, Cursor from its state.vscdb, and OpenCode, Windsurf, and WorkBuddy from their own local databases, with platform-specific alternatives on each OS. A second scanner feeds Dev Record analytics from ~/.gemini/tmp/*/chats/*, ~/.kiro/sessions/, and ~/.aider/history/ as well; results are cached, re-scanned on file modification time with a one-minute cooldown, and re-parsed in full when the parser version changes. Nothing from either scan is uploaded.

ORG-2 can also attach to a Cursor IDE composer that is running right now and mirror its output into a live session, and it can register the repositories it finds in imported history as ORG-2 repos in one step.

Resource-aware execution

The resource ORG-2 actually schedules around is your attention. Set your presence from the sidebar pill — "Set your availability — agents will adapt to whether you're at the keyboard." — as Online, Invisible, or Away, optionally with a return time.

Presence does two things. First, it swaps a guidance paragraph into the agent's prompt; the Away default is "I am away from the keyboard. Do not block on me — make the best decision you can with the information you have, finish what you can finish, and leave a concise summary of what happened and any open questions for when I return." Second, it changes three backend-enforced timeouts, all editable under My roles:

Zero disables a behaviour. These are enforced in the Rust backend, so a pending question resolves even with the UI closed, and an auto-approved plan is marked as such on its approval card. If you want a machine that is running agents to stay awake, turn on Prevent system sleep during sessions — it is off by default.

The hardware half is narrower. Settings → Device & Network shows a Performance Monitor with per-core CPU, a RAM History chart, a RAM breakdown by subsystem, and the child processes agents have spawned — but nothing throttles an agent turn on CPU. Memory gates exactly one thing: the background session-analysis pass pauses when the backend's resident set climbs past a soft and then a hard threshold, or when free system memory runs low, and resumes once it falls back. The other place hardware drives a decision is local models, where ORG-2 sizes candidate models against your machine and rates the fit before you run them.

Next steps

• API keys — connecting the accounts agents run on.
• Sessions — starting, steering, and scoping a run.
• Tools — what the built-in tool set can reach.
• Scheduling — routines that start agent sessions without you.