Tools

A built-in ORG-2 agent does not touch your machine directly. It calls named tools from a registry the app assembles per session, and every call is written to the session's event record. This page lists that surface, says when an agent reaches for each tool, and flags the permission and platform limits. External CLI agents ship their own tools instead — see Agents.

How the tool set is assembled

The registry is narrowed by four independent gates, and a tool has to survive all of them before the model can see it:

• Capability. Each tool declares one — coding, desktop, browser, data, management, orchestration. An agent whose capability set omits it never gets the tool.
• Agent definition. Every agent carries a negative list, expressed as individual names or as groups such as group:web, group:fs, group:runtime, group:browser, group:lsp.
• Runtime dependency. Tools whose backing service is absent are skipped — the LSP tools need the language-server manager, inspect_terminals needs live terminal sessions.
• Mode. Modes subtract tools and never add them. Plan, Ask, and Debug drop the write-and-execute set (run_shell, await_output, edit_file, delete_file, apply_patch, worktree, manage_code_map, manage_lsp, setup_repo). Review keeps run_shell and await_output, because reviewing means running git diff.

Denied tools are filtered out of the schema the model receives, so an agent in Ask mode is never told that edit_file exists and then refused. A tool_search meta-tool lets an agent look tools up by keyword; it reports policy-denied ones as unavailable with the reason rather than hiding them, and it is how MCP tools get pulled in on demand.

Files

read_file returns contents with line numbers. It reads up to 2000 lines by default; files over 256 KB require an explicit offset and limit. offset is 1-indexed and accepts negatives, so -20 is the last twenty lines. It also extracts PDF text, renders .ipynb cells, and returns JPEG, PNG, GIF, and WebP images inline for vision models.

edit_file is both the write tool and the patch tool. Pass file_path plus content to create or overwrite; pass old_string and new_string to patch. The edit fails if the search string is missing or matches more than once, which is what forces an agent to quote enough surrounding context. list_dir and delete_file round out the set, and write_env_file exists so secrets captured out-of-band can reach a dotenv file without the plaintext entering the transcript. Every write is snapshotted; manage_file_history lets the agent list, rewind, and redo those snapshots, and you get the same power from the review UI below.

Terminal and shell

run_shell is the busiest tool in most coding sessions. Two axes matter. terminal_target is integrated by default — a subprocess with clean output capture — or external, which opens your OS terminal and cannot capture output. mode is blocking or background; a blocking command that exceeds its timeout is backgrounded rather than killed, and background mode returns a PID and a log path immediately. Killing a handle sends SIGTERM, waits two seconds, then SIGKILL. The default timeout is 60 seconds unless the agent definition raises it.

Note: run_shell is gated twice. The session's tool policy decides whether the agent may call it at all, and a per-command security check can still raise an approval prompt for a specific command. terminal_target: "external" always prompts, even for a tool you marked always-allowed.

await_output monitors background work — shell PIDs and subagent session ids alike — with wait_for, monitor, and list, an optional regex to wait on, and a tail of recent output. inspect_terminals reaches into ORG-2's own managed terminals to list them, read output, write input, or close one. Subprocess runs are also written to per-workspace log files carrying the PID, working directory, command, status, and exit code.

Git

There is no dedicated git tool. Agents run git through run_shell — the Review mode prompt instructs the agent to run git diff <base_branch>..HEAD. The one exception is worktree, which creates an isolated checkout (add), returns to the main tree (leave), or lists existing ones, and switches the session's working directory when it creates one. manage_workspace registers and unregisters repos but does not clone.

Everything richer is app-owned rather than agent-owned. ORG-2 watches each registered repo, keeps its branch and status state, and exposes branches, commits, staging, stashes, remotes, merges, diffs, and blame to the UI — the Source Control sidebar tab, the branch picker, Generate commit message with AI. The practical consequence: an agent's commits appear in the trajectory as shell calls with the full command line, while your own do not appear there at all.

Code intelligence

ORG-2 ships definitions for 28 language servers, from rust-analyzer, gopls, and Pyright through to Marksman and the Bash language server. manage_lsp deliberately does not run install commands — it returns the command and leaves execution to run_shell, so an install stays visible as a shell call you can approve. The code map is a persistent symbol-and-relationship index, which is why callers and impact answer questions grep cannot.

Browser use

Agent browser control goes through the agent-browser sidecar, downloaded from vercel-labs/agent-browser releases for your OS and CPU. The tool is control_browser_with_agent_browser: the agent passes a bare subcommand such as open https://example.com, snapshot, screenshot /tmp/page.png, or close, and ORG-2 supplies the executable path, a fixed orgii session, --json, and headed-Chrome environment. Exactly one browser provider is registered per session; selecting the Playwright provider instead hides this tool and registers control_browser_with_playwright.

web_search and web_fetch are separate and much cheaper — a search returning titles, URLs, and descriptions, and a fetch that strips HTML to readable text. web_search registers only when a Brave Search API key is configured.

Warning: if you built from source and skipped pnpm run download:sidecars, the sidecar is a placeholder and browser control will not work. The embedded Browser panel in the Workstation is a human surface and is not driveable by an agent.

Computer use

control_desktop_with_peekaboo drives the macOS desktop through the bundled peekaboo CLI, downloaded from steipete/peekaboo releases. The agent passes a subcommand — see --app Safari --json, click --on "Reload this page", type --text "hello", hotkey cmd,shift,t, image --mode screen --path /tmp/screen.png — and ORG-2 supplies the binary path and forces JSON output for observation commands.

It is the most heavily gated tool in the app:

• macOS only. On Windows and Linux it is not registered at all.
• Desktop capability required. An agent without it never gets the tool.
• Two system permissions. macOS Screen Recording and Accessibility must both be granted; ORG-2 checks them without triggering a prompt before it starts.
• Abort key. A real Escape keypress anywhere on the system aborts the running desktop operation; ORG-2's own synthesised Escapes do not trip it.

Input commands synthesise real HID events with human-like cadence, and the ORG-2 window hides itself during automation so it does not appear in screenshots or intercept clicks.

Databases and SQL

There is no agent-facing SQL tool. Database work is a human surface: the Database panel, with Connections and Query History tabs, a data grid, and a SQL editor. Local SQLite files open natively; PostgreSQL and MySQL connect over the network; Supabase, Neon, and Turso are offered as hosted variants. Add one through Add Database Connection, or from Spotlight with Scan folder, Open file, or Enter path. An agent that needs SQL shells out with run_shell.

What the trajectory records

Every tool call is persisted with its name, its full arguments, its full result, and its text content, and the argument text is indexed for full-text search — so you can find the session where an agent ran a particular command months later. Each round also materialises the list of files it touched, with per-file status and line counts; only real write, patch, and delete tools contribute, so reads never inflate it. That record is what the Trajectory panel and the replay controls read from; Replay covers playback and filtering.

Timeline, code viewer, and diff viewer

Timeline is a section in the Explorer sidebar for the selected file. It merges that file's git commit history with .orgtrack session lineage, so a row is either a commit — message, relative time, author, short SHA — or an agent session that touched the file, showing the agent, the affected line range, and whether the work was committed. Clicking a row opens the diff.

The code viewer is the CodeMirror 6 editor: syntax highlighting, autocomplete, a minimap, find and replace, go-to-line, git blame, a dirty-diff gutter, and inline diagnostics fed by the language servers into the Problems panel. Nothing locks it while an agent runs — collisions surface through the dirty-diff gutter and a reload-from-disk prompt.

The diff viewer has a Unified / Split toggle, and diffs are computed in Rust so large files open without staged rendering. You reach an agent's changes from the "N files changed this round" card at the foot of each chat turn, which opens the Diff app scoped to that turn. Review is snapshot-based rather than hunk-based: Keep, Keep All, Undo All, and Redo All act on the snapshots taken around each edit, and reverting a round reverts every snapshot at or after that point. Restoring a chat checkpoint asks separately whether to revert or keep the files changed since then.

Next steps

• MCP — add third-party tools to this surface.
• Skills — teach an agent procedures rather than new tools.
• Replay — read the trajectory a tool call produces.
• Security — approval prompts, workspace bounds, and what an agent can reach.