Use the CLI Chat Interface#

The CLI chat interface launches the Osprey agent in your native terminal while running OSPREY’s companion services in the background. This runs the agent in the full terminal TUI — keyboard shortcuts, slash commands, native scrollback — with access to companion services (artifact gallery, session analytics, etc.) via their URLs in a browser.

Launching#

From any OSPREY project directory:

osprey claude chat

This command:

  1. Regenerates Osprey agent integration files (.mcp.json, CLAUDE.md, .claude/settings.json) from config.yml.

  2. Resolves the configured LLM provider and injects authentication.

  3. Starts the translation proxy if the provider needs it (see Configure LLM Providers).

  4. Launches companion web servers in the background.

  5. Opens the Osprey agent TUI in your terminal.

Options#

osprey claude chat -p /path/to/project           # explicit project dir (--project)
osprey claude chat --resume SESSION_ID           # resume a previous session
osprey claude chat --print                       # non-interactive (pipe-friendly)
osprey claude chat --effort high                 # set effort level
osprey claude chat --no-pin                      # ignore the pinned CLI version

When --project is omitted, the current directory is used.

If claude_code.cli_version is set in config.yml, chat launches that exact agent CLI version instead of whatever is installed globally, so every launch of the project behaves the same. --no-pin opts out and uses the global installation.

Companion Services#

On startup, osprey claude chat launches the same companion servers as osprey web. Each server’s URL is printed before the Osprey agent starts:

Companion servers:
  * Artifact gallery  http://127.0.0.1:8086
  * ARIEL server      http://127.0.0.1:8085

Open any of these URLs in a browser to access the service while the Osprey agent runs in your terminal. Which servers start depends on your config.yml — each server respects its own auto_launch setting.

The servers run as background threads and stop automatically when you exit the Osprey agent.

When to Use CLI vs. Web Terminal#

CLI chat (osprey claude chat)

Web terminal (osprey web)

Native terminal experience

Browser-based split-pane UI

Full Osprey agent TUI with keyboard shortcuts

Embedded terminal emulator

Companion services in separate browser tabs

Companion services as side panels

No additional port for the terminal itself

Terminal served on port 8087

Ideal for SSH or remote sessions

Ideal for local development with visual tools

Both modes launch the same MCP servers, companion services, and translation proxy. The agent capabilities are identical.