Run a headless task

osprey agent requires a prompt and a provider key. The command applies command options, environment variables, project configuration, user configuration, and built-in defaults.

TASK_PROMPT="Inspect the tracked changes and report test risks."
osprey agent "$TASK_PROMPT"

Headless runs use deny-untrusted approval by default. The default run allows 150 turns and 300 seconds for each turn. The stream idle watchdog is 60 seconds. The driver retry limit is three retries.

Use --approval to select another noninteractive policy. Use --read-only to reject mutation tools. Use --allowed-root more than once to permit additional filesystem roots.

Event output

--events-jsonl writes JSON Lines (JSONL) events to standard output. Osprey selects JSONL automatically when standard output is not a terminal. The final event reports session disposition and usage.

Logs for subcommands go to standard error. This separation keeps the JSONL stream available to another process.

The next command creates or replaces osprey-events.jsonl in the current directory.

TASK_PROMPT="List the affected modules and return a risk summary."
osprey agent --events-jsonl "$TASK_PROMPT" > osprey-events.jsonl

Validated structured results

--output-schema reads a JavaScript Object Notation (JSON) Schema file before provider execution. Osprey rejects an unreadable or invalid schema before the model call. Osprey also validates the final JSON result locally.

Save this schema as risk-result.schema.json:

{
  "type": "object",
  "required": ["summary", "risk"],
  "properties": {
    "summary": {"type": "string"},
    "risk": {"type": "string", "enum": ["low", "medium", "high"]}
  },
  "additionalProperties": false
}

TASK_PROMPT="Inspect tracked changes and return the required JSON object."
osprey agent --output-schema risk-result.schema.json "$TASK_PROMPT"

A schema mismatch makes the run fail. Real tools remain available while the model produces the structured result.

ATIF trajectories

--atif-output writes an Agent Trajectory Interchange Format (ATIF) document. The output uses ATIF v1.7. The document includes tool definitions, timing, usage, tool calls, and the initial prompt. Osprey records a system-prompt digest by default.

--atif-system-prompt-plaintext=true includes the full system prompt. Plaintext output can contain private instructions and extension content.

TASK_PROMPT="Summarize the repository structure."
osprey agent --atif-output osprey-run.atif.json "$TASK_PROMPT"

Osprey writes the ATIF file atomically. An ATIF flush failure produces a warning but does not change a successful exit status. Verify the requested file before downstream automation consumes it.

Resume and fork

--resume continues a persisted session. --fork-from creates a new branch from a persisted session. The two options are mutually exclusive.

Each value accepts the identifier form supported by the headless resolver. Resume and fork require SQLite or PostgreSQL persistence. They fail with an in-memory store.

SESSION_QUERY="saved-session-label"
TASK_PROMPT="Continue the analysis from the saved context."
osprey agent --resume "$SESSION_QUERY" "$TASK_PROMPT"

Tool-result controls

Tool output is capped at 32,768 bytes by default. Osprey keeps 12,288 bytes from the head and 12,288 bytes from the tail. The default line limit is disabled.

--tool-result-raw-dir enables raw sidecar files for capped results. Without that option or an ATIF sibling directory, capping continues without a spill file. Spill and read failures are nonfatal.

--compress-context=true enables semantic compression after a result spills. Compression is disabled by default and uses a 2,048-byte minimum. If compression fails, Osprey keeps the capped result.

Exit behavior

Condition	Exit status
Completed run	`0`
Cancelled agent outcome	`0`
Successful terminal tool	`0`
Failed terminal tool	`1`
Turn budget or actionless timeout	`1`
Maximum continuation limit	`1`
Ordinary command error	`1`
Process-level Control-C	`130`

Do not use exit status 0 as proof that the requested ATIF trace exists. Check required artifacts and the final JSONL disposition separately.

Back to Osprey