The terminal user interface (TUI) starts when you run osprey without a subcommand. The osprey agent PROMPT command runs the same agent loop without the interactive screen.

TUI launch sequence

Osprey performs these steps for a bare TUI launch:

The command loads .env, global configuration, and the nearest project configuration.
Osprey resolves the database, provider, model, persona, approval policy, reasoning effort, and tool-result limits.
Osprey provisions an operating-system sandbox only when --sandbox is present.
The launcher reads cached model capabilities without making a network request.
The launcher initializes the terminal.
It installs a terminal restoration guard.
Osprey loads extensions and memory.
It composes the active system prompt.
Osprey creates a fresh user session and its ordered persistence journal.
Osprey constructs the tool and orchestration layers.
The launcher starts the agent task.
It starts the terminal event loop.

Opening the model picker later can refresh the model catalog from models.dev or the configured Nous endpoint. The initial capability read uses only files below the Osprey cache directory.

A startup error before teardown ownership transfers destroys any provisioned sandbox lane. A dispatcher setup error stops the TUI before the agent task starts. An unavailable memory provider also stops startup.

On normal exit, Osprey restores the terminal before session teardown. Teardown drains the journal. It settles subagents and checkpoints SQLite. It also destroys the sandbox lane. During shutdown, the event loop interrupts active workflows. It also denies unresolved approvals. A terminal drawing error still marks active workflows as interrupted.

Layered tool surface

The default unsandboxed dispatcher runs file operations and subprocesses on the host. The current working directory is the first allowed filesystem root. The lead TUI agent receives the composed tool catalog below. Spawnable persona rules can reduce the tool surface of child agents.

Layer	Tools and behavior
Base file and process tools	`read_file`, `write_file`, `edit_file`, `bash`, `process`, `find_files`, `grep`, `list_directory`, and `tree`
Base control and web tools	`todo_write`, `switch_persona`, `task_status`, and `web_fetch`
Conditional base tools	`web_search` needs a configured search provider. `lsp` needs Language Server Protocol configuration. `retrieve` needs semantic tool-result compression.
Skills and extensions	`load_skill` appears when Osprey discovers skills. `extension_manage` and trusted custom tools appear from active extensions.
Subagents	`spawn_subagent`, `send_input`, `wait_agent`, and `cancel_agent` manage persisted child sessions.
Memory	`memory` appears when a memory provider is active.
Workflows	`run_workflow` and `propose_workflow` appear when workflows are enabled.
Lead-agent tools	`question` requests interactive input. `session_search` searches other saved user-session trees.

The default subagent limit is eight running children across one spawn tree. The parent and every child share one optional request-per-minute limit. Each child receives a persisted session, outcome, result, usage record, and tool trace.

Workflow calls use a separate default limit of 16 concurrent agents and 1,000 total agents per run. Disabling workflows removes both workflow tools. The same setting disables /run, /workflows, /deep-research, and discovered workflow commands.

The --sandbox flag replaces only the base coding dispatcher. The sandbox sidecar exposes eight of the base tools. See Sandbox and networking for the isolation boundary and current limitations.

Slash commands

The built-in registry contains the following commands. Built-in names take precedence over discovered skills and workflows with the same name.

Model and reasoning

/model selects a model or opens the model picker.
/provider changes the provider.
/effort changes the reasoning effort.
/moa PROMPT runs one prompt through the default Mixture of Agents (MoA) preset and then restores the session model.
/moa-config opens the interactive MoA preset manager.

Tasks and agents

/agents switches personas or opens the persona picker.
/new starts a new session.
/verify forces a verification audit after the active turn finishes.
/compact requests manual conversation compaction.
/tools shows or hides completed tool rows.
/timestamps shows or hides message timestamps.
/copy copies the latest assistant response. /copy all copies the full transcript.

Sessions and diagnostics

/session opens or operates on the current session.
/sessions opens the session tree.
/status shows current runtime status.
/debug opens a dialog with version, date, operating system, terminal, session, and model information.
/diff displays the current workspace diff.
/export opens the Markdown transcript export dialog.
/bug-report invokes the built-in interview skill. With confirmation, the skill files an Osprey issue.

Policy and discovered content

/approvals manages saved tool approvals.
/extensions shows loaded custom extension tools.
/reload reloads applicable extension content.
/skills lists discovered skills.
/skill NAME shows a discovered skill's name, scope, description, and path.

Workflows and help

/run starts a workflow from a .js script path.
/workflows opens the progress view for active workflow runs.
/deep-research starts the bundled deep-research workflow.
/help shows command help.
/quit exits the TUI.

Approval policies

The TUI defaults to on-request. The headless agent defaults to deny-untrusted because no interactive approval channel exists.

Policy	Behavior
`on-request`	Osprey checks stored approvals or prompts before each requesting tool call.
`on-failure`	Osprey proceeds until a tool fails. The next requesting batch uses stored approval or prompts. A later success clears the failure latch.
`unless-trusted`	Trusted read-only tools proceed. Other requesting tools use stored approval or prompt.
`deny-untrusted`	Trusted read-only tools proceed. Every other tool returns a deterministic denial without prompting or reading saved approvals.
`never`	Osprey proceeds without prompts. The policy-independent hardline bash floor still applies.

The trusted read-only list contains read_file, find_files, grep, list_directory, and tree. The TUI --read-only preset resolves to unless-trusted. The headless --read-only preset resolves to deny-untrusted. The --yolo preset resolves to never.

Osprey permits --yolo without --sandbox. It writes a warning. Unsandboxed --yolo relies on external isolation plus the hardline bash floor. The hardline floor is not a complete shell analyzer.

Saved approvals use $OSPREY_HOME/approvals.toml. A missing or malformed approval file loads as an empty store. Approval updates use a file lock. The file rewrite is not crash-atomic. Shutdown denies every pending interactive approval so callers can finish.

Task completion and finalization

The TUI and headless command use different completion claims.

The TUI uses declared completion because one session spans many user messages. The active persona must call task_status with done or blocked for substantive task completion. A normal assistant response does not declare the interactive task complete.

The headless command uses implicit completion. A final response without tool calls becomes a completion candidate. A persona terminal tool also creates a completion candidate.

The finalization adjudicator checks each candidate against active completion evidence and verification objections. The adjudicator can request another model turn instead of accepting the candidate. Each public launch supplies a continuation limit to the adjudicator. The TUI uses 4,294,967,295 when configuration does not set max_turns. The headless command defaults --max-turns to 150.

An exhausted limit produces MaxContinuations. Structured output exhaustion produces an error instead of an invalid final object. --output-schema PATH validates final JavaScript Object Notation (JSON) against the supplied JSON Schema. Non-strict schema formatting by the provider does not replace Osprey's final validation.

Verification

The verification checkpoint records completion claims, supporting evidence, and unresolved objections. Self-reported status can request more work, but self-reported status cannot bypass an objection.

Use /verify only after the active turn finishes. The command re-arms the checkpoint. It asks the agent loop to audit the current task. Osprey rejects /verify while the agent is working.

Successful write and verification tools update the completion state. Compaction preserves the completion checkpoint with the summarized context. Resume and session switching restore the persisted checkpoint.

Retries and stalled work

A logical model turn has one deadline across its initial request and all driver retries. The default headless turn timeout is 300 seconds. Retryable driver errors receive three retries by default. The default retry delays are one, five, and 15 seconds. The turn deadline can stop the retry sequence earlier.

Osprey tolerates two consecutive empty completions by default. Each empty completion receives a corrective user message. The next consecutive empty completion fails the loop.

Three consecutive calls with the same tool name and arguments trigger the doom-loop correction. Osprey suppresses the repeated dispatch. It asks the model to change its approach.

The identical-failure detector counts matching failed calls even when other calls occur between them. The default threshold is two failures. At the threshold, Osprey prepends a retry-suppressor notice to the tool result. A successful matching call resets the identical-failure counter.

Semantic no-progress detection also tracks process failure families and artifact stasis. Headless defaults use three matching failures in a ten-observation window. Artifact stasis defaults to ten turns. Equivalent advisories are suppressed for 30 turns by default. The detectors add recovery guidance and completion objections.

Two consecutive turn timeouts without text or tool calls produce ActionlessTimeout by default. A session time budget produces BudgetExpired when exhausted. Cancellation produces Cancelled. Osprey preserves recorded usage.

Headless outcomes and status

Completed, internal cancellation, and a successful terminal tool produce exit status 0. MaxContinuations, BudgetExpired, ActionlessTimeout, and a failed terminal tool produce status 1. An external Control-C interrupt produces status 130.

Headless output uses JSON Lines when standard output is not a terminal. Pass --events-jsonl to select the same format on a terminal. The final session_end object names the loop outcome and reports available usage.

Web fetch and search

web_fetch accepts one to five Hypertext Transfer Protocol (HTTP) or Hypertext Transfer Protocol Secure (HTTPS) Uniform Resource Locators (URLs). Requests run concurrently. Results retain input order. Each response has a five-mebibyte body limit. The character window is clamped between 2,000 and 100,000 characters. The request timeout is capped at 120 seconds.

The fetch client rejects URL credentials and credential-like query parameters. The client rejects private, loopback, link-local, and other non-public destinations. Every resolved address must pass the destination guard. The client revalidates each redirect. It pins the selected address.

web_fetch renders Hypertext Markup Language (HTML), text, JavaScript, JSON, and Extensible Markup Language content. Portable Document Format extraction is unsupported. One failed URL becomes an error section without discarding successful sibling results.

web_search appears only with Exa, Brave, or SearXNG configuration. Automatic provider selection prefers Exa, then Brave, then SearXNG. Search returns five results by default and accepts at most 20. Each search request has a 15-second timeout and a five-mebibyte response limit.

Search providers contact their configured endpoints through a host network client. The public-destination guard for model-supplied fetch URLs does not wrap configured search endpoints.

Terminal recovery and crash reports

The terminal guard leaves the alternate screen during normal teardown. It also restores the cursor. The panic hook also attempts terminal restoration before reporting a crash.

The hook writes $OSPREY_HOME/crash/osprey-crash-TIMESTAMP-NONCE.txt. If Osprey cannot create the crash directory, the hook uses the system temporary directory. The report contains the Osprey version, operating system, panic message, report path, and Rust backtrace. Osprey removes a partial report when the report write fails.

Back to Osprey