# Argo for Raycast

URL: https://www.raycast.com/fernando_jacob/argo

> Continue existing Agent sessions through Argo bridges or control Herdr terminals directly in Raycast.

- Install: raycast://extensions/fernando_jacob/argo
- Author: [Fernando Jacob](https://www.raycast.com/fernando_jacob)
- Installs: 0
- Platforms: macOS
- Categories: Developer Tools, Productivity
- Updated: 2026-11-13
- Source: https://github.com/raycast/extensions/tree/9fe3617a91159f550a60587441745a5a21de435c/extensions/argo/

## Commands

- **Agent Sessions**: Browse Argo and Herdr sessions, view output, send tasks, and respond to prompts inside Raycast.
- **Recent Agent Session**: Continue the last session opened in Argo.
- **Connect a Server**: Start with an uninstalled Agent, discover ordinary forwarded ports and pair once.

## README

### Argo

Continue existing Agents from Raycast through Argo bridges or a direct Herdr connection. Browse sessions, read output, send tasks, and respond to prompts without leaving Raycast. Native Codex bridge support remains experimental.

Argo is a **self-configured companion bridge**, not a hosted AI service. Installing this extension installs the Raycast UI only: it does not install the Argo runtime, open a tunnel, start a model, or install a launchd/systemd service. You run the bridge and connector on machines you control and keep their processes and transport alive. No Argo cloud account or model API key is required by the extension; your existing agent's authentication and permissions still apply.

#### Herdr: no bridge required

With Herdr already running, open **Agent Sessions** and choose a Herdr terminal. The source filter switches between all sessions, Argo bridges and Herdr. Local and HC-configured remote terminals share the list without changing your existing Agents. If connection fails, open **Herdr Connection Details** and set **Herdr Socket Path** for a custom session. Discovery connects only to an existing private Unix socket and never starts a core. GUI applications may not inherit your shell's environment.

**Conversation** lists messages sent from Raycast and conservatively derived terminal output as separate rows, latest first. Each new message captures a fresh screen baseline; streaming snapshots replace that turn's output rather than append repeated history. Exact message echoes and meaningful overlap can isolate new output. Shared trailing lines are retained after those boundaries rather than guessed to be removable terminal footers. Unclear redraws fall back to **View Raw Terminal**, not a fabricated Agent reply. Existing terminal history and messages sent elsewhere are not imported as structured chat. Reopened unfinished turns stay paused; no output is retrospectively attributed and nothing replays. Multiple views merge individual saved turns instead of overwriting whole-history snapshots, and returning from All Sessions refreshes local history.

**Terminal Output** remains the live raw-screen view for terminal controls and ambiguous output. **Read Full Width** with **⌘⇧F** expands the selected message or raw screen; the same shortcut returns to the split view. Derived conversation replies render safe Markdown headings, lists, tables and code blocks. Raw terminal screens remain literal, preserving original line breaks and indentation without reflowing approval prompts. **Terminal Identity** holds capture time, method, dimensions and connection details. Incomplete capture, changed-state and delivery warnings stay visible. Automatic capture reads only the current screen; **Read More History** is explicit because HC may scroll the original interface. Plain-text capture may lose color-only selection highlights, so approvals always use original-screen review.

Use **Send Message** with Enter or **Compose Message** with **⌘N**, just as with an Argo conversation. Both reported `idle` and `done` states accept the next message. Completed answers display **Ready**. Working preserves your next draft locally, without pretending it is queued. HC only accepts `idle` or `working` conditions: idle sends use `if:idle`, while done sends recheck readiness and omit that condition with `force:false`. This is not an atomic ready-state guarantee. Blocked permission, question and authentication dialogs instead open **Terminal Controls** inside Raycast. Inspect the live prompt, send one navigation key, then review the updated screen before explicitly sending Enter, Escape, a digit, letter or custom chord. Argo never guesses Allow/Deny shortcuts or appends Enter to key input. **Respond to Current Prompt** reviews your text and screen before explicit submission with HC `force:true`; ordinary task sends always use `force:false`. Unreported programs have a separately reviewed terminal-input flow and may execute shell commands. **Interrupt Terminal** uses HC's interrupt operation, not kill.

The exact target uses permanent owning-core and terminal identities. Reconnection or observed program replacement invalidates reviewed controls. Fresh screen checks reduce races, but HC has no atomic screen/approval condition or idempotent input API. Submitted keys do not prove an approval was applied. Input attempts are persisted before network writes. A timeout or disconnect blocks further input across reopen and never retries automatically. Inspect current output before explicitly acknowledging uncertainty; acknowledgment itself sends nothing. **Open Herdr** is an optional escape hatch, not the primary interaction path.

HC needs no bridge runtime or pairing. Its socket grants your account's terminal access and is not a sandbox or separate permission broker. Argo validates ownership/private directory boundaries, does not forward the raw API, and leaves remote credentials with HC. Drafts, input-attempt records and a bounded reconstructed conversation are stored locally in Raycast LocalStorage. History is scoped to the exact target and observed program, with up to 40 recent turns and a bounded text budget. Raw screen baselines and ambiguous full-screen fallbacks are not persisted. This derived history is not a native Agent transcript or an approval receipt. Developed against HC 0.1.17 and Herdr App 0.1.12, using negotiated generation-1 methods/features rather than version matching.

#### Argo bridge requirements

- Raycast on **macOS**.
- On the bridge/agent machine: **Node.js 22.13+**, npm, and an already-running supported agent. The public installer also needs tar and HTTPS access to GitHub release assets and the npm registry. Argo does not install system packages.
- Claude Code with its Bash tool and an authoritative current session identity for cooperative pull. No restart or MCP configuration is needed for this default path.
- For a server: ordinary SSH Local Port Forwarding or VS Code Ports, exposing the bridge only on your Mac's loopback interface. The setup tool must support persistent background execution for Argo's processes.

Setup targets the separately installed, pinned **v0.1.4** runtime after inspecting its installer. If the pinned tag or release assets are unavailable, stop rather than falling back to an older version or mutable branch. GitHub distributes code, not conversation traffic.

**Runtime security update:** v0.1.4 fixes the client-revocation race for requests already uploading when access is revoked. Existing v0.1.3 and older bridges require an explicit runtime upgrade and bridge restart; installing or updating this extension does not patch a running server. Stop the old bridge before upgrading, and do not reuse it as a patched server. See the [security assessment](https://github.com/MatrixA/argo/blob/v0.1.4/docs/security-review.md).

#### First connection: an unconfigured server

You do not need a pre-existing Argo installation, bridge address, or pairing code.

1. Open **Argo → Connect a Server**. Choose **Copy Fresh Server Setup Prompt** and give it to your **existing** server agent, not a new session or subagent. The prompt uses these fixed, tag-pinned [server setup instructions](https://github.com/MatrixA/argo/blob/v0.1.4/docs/server-setup.md).
2. The agent checks prerequisites, inspects and installs the pinned runtime, starts or reuses a server-local bridge, and connects its exact current session through the supported adapter. It reports installation, bridge startup, and agent registration separately. Unsupported prerequisites mean **not connected**, not permission to start a replacement agent or weaken security policy.
3. The agent prints the actual endpoint, such as `http://127.0.0.1:49120`, on its own line in terminal output and its handoff, and returns a short-lived **Mac pairing code** separately. VS Code can detect the URL when automatic forwarding is enabled; check its Ports view for the actual Mac mapping. Otherwise forward the returned server port manually.
4. Use ordinary **Local Port Forwarding** into one unused **Mac loopback port 49120–49139**. Keep listeners private. No Remote Forward is required for this flow. Multiple servers may use the same server port but need different Mac-mapped ports. The discovery range is configurable in extension preferences, up to 64 ports.
5. Choose **Find Forwarded Server Bridges** in Connection Setup, or scan again in Connect a Server. Select the matching discovered identity, choose **Pair This Server**, and submit the Mac pairing code with **Verify and Pair Server**. **Pairing is mandatory:** signed discovery checks a fresh bridge signature, not authorization or transport confidentiality. Use only your own trusted loopback listener or SSH/VS Code forward. A malicious local proxy can relay a genuine signature and observe bearer credentials; signed discovery is not TLS and does not prevent relay attacks. The code must match that bridge; pairing grants control of all its agent sessions, not just one agent. No durable credential or admin-file copying is needed in this flow.
6. Open **Agent Sessions**. After pairing, Argo remembers the server. If a code expires or its claim is uncertain, request a fresh code using `client-invite` on the bridge machine rather than retrying an uncertain claim.

The bridge and connector are tool-managed processes, not permanently installed services. If their process handles end or the tunnel closes, delivery stops. Installing the extension alone cannot make a server reachable.

##### Local or existing bridges

A bridge can instead run on your Mac, or use an existing working loopback tunnel. Follow the [topology guide](https://github.com/MatrixA/argo/blob/v0.1.4/docs/topologies.md). **Connection Setup → Use an Existing Bridge** accepts a private client configuration **file path**, not a pasted token, and verifies authentication before switching. The default path is `~/.argo/client.json`; the Client Configuration File preference can override it. Attach each additional agent separately using its scoped pairing prompt. Importing client access does not attach an agent.

#### Everyday use

Global command hotkeys are personal Raycast settings, not defaults an extension can install. Set them in **Raycast Settings → Argo**. Suggested mapping: **⌃⇧⌘J** for **Recent Agent Session**, **⌃⇧⌘K** for **Agent Sessions**, and **⌃⇧⌘L** for **Connect a Server**. Updates do not intentionally change these user-owned settings.

Native conversation messages show routine delivery state as a small list-row icon. Hover for role, exact time and state meaning, or open **Message Details** from Actions for keyboard-accessible status and complete diagnostics. Failed and unknown results retain visible warning text. The reply pane is reserved for message content.

Conversation replies support safe Markdown tables, headings, lists and code blocks. Message links, images and HTML remain inert; copying a message retains its original source. Block parsing distinguishes nested prose from list-contained or quoted code. Display formatting normalizes list indentation and line endings; excessive block nesting falls back to the complete literal source. Herdr raw screens and approval review are always literal terminal text. **Read Full Width** remains available for wider HC tables.

- **Agent Sessions** aggregates Argo bridges and Herdr terminals. **Agent Sessions** opens the full source-aware list. **Recent Agent Session** reopens the last valid conversation; use **All Sessions** to change targets. Reopening checks the configured loopback range and can relocate a paired bridge by its pinned identity when mapped ports change. It is not a system-wide background scanner.
- Use **Send Message** for short input or **Compose Message** (**⌘N**) for longer drafts. Only explicitly submitted text is sent; drafts never send automatically after reconnecting. Replies appear as Markdown details, not Raycast AI chat. Bridge history begins at binding, not at the start of your terminal conversation.
- For a supported pending approval, open **Review Approval**, inspect the parameters, then press **Enter** for **Allow Request** or **⌘⇧D** for **Deny Request**. There is no second confirmation modal; the explicit action submits the decision. Expired requests cannot be answered. Runtime support determines which requests can be relayed—this does not bypass agent permissions.
- Codex approvals show command, working directory, reason, file changes and permission rules in separate sections. **View Original Parameters** opens the complete unchanged details read-only. Unknown fields remain visible and Agent text cannot become active Markdown links or images. This formatting does not alter the reviewed request or the decision.
- Pending approvals and submitted requests stay above the conversation. Completed and expired requests move to **Approval & Question History** below the messages, so they do not bury replies. Open it for read-only browsing in batches of 20, use **Show More Requests** for earlier records, or search all completed records. Nothing is deleted or replayed.
- Approval details stay subscribed to the original request. Expired, already handled, submitted, disconnected and changed-parameter requests have distinct explanations and cannot be approved. The Mac uses the bridge's HTTP Date clock with monotonic elapsed time, not its local wall clock. Missing bridge time blocks approval. Failed or uncertain decisions are never automatically replayed. These UI checks do not prove native approval completion.
- Codex approval identifiers preserve their protocol-safe colons for compatibility with the published bridge. A failed request check sends no decision and can be retried explicitly after reconnecting. An uncertain decision POST is never replayed automatically.
- If a prompt's outcome becomes unknown after disconnection, check the original agent before using **Resume Queue After Checking Agent**. Argo does not automatically replay uncertain work.

#### Agent limitations and verification

**Claude cooperative pull:** waiting occupies the original session's current turn. It cannot independently advance its previous task while waiting, although existing background processes continue. The agent must keep its receive/ack/reply loop running; Raycast cannot wake an ordinary completed prompt. Expired waits may consume additional agent turns. Tool approvals stay in the original terminal; this mode has no remote approval relay, native interruption, or automatic token streaming. Optional native Channels require separate startup authorization and are not enabled by Store installation.

**Codex — experimental:** requires authoritative `CODEX_THREAD_ID`, `codex app-server proxy` support, and an **existing compatible shared App Server with that exact thread already loaded**. An ordinary standalone TUI may not provide these. Argo must not start a new daemon/thread/model, use `codex exec` or CLI resume, guess from history, or weaken sandbox/approval policy to attach. Connector process exit requires a fresh scoped binding before restarting.

Development used Claude Code 2.1.314 and Codex CLI 0.157.1. Native Codex testing passed initialization and metadata reads but failed empty-thread rejoin with `no rollout found`; no model turn was sent to manufacture a rollout. Real populated-session rejoin, model replies, and multi-client approval routing remain unverified. Published-runtime installation, forwarded loopback discovery/pairing, and synthetic Claude messaging were tested; actual Raycast discovery/pairing was also exercised. These are **not** real model round-trips or external SSH acceptance. A dedicated real local Claude session has since passed direct-loopback messages and pre-attachment context recall with unchanged native identity. Cooperative-pull permission views remain in the original terminal. See [local acceptance](https://github.com/MatrixA/argo/blob/v0.1.4/docs/local-acceptance.md). Discovery, registration, and a passing build do not establish end-to-end agent support.

#### Privacy, storage, and removal

- **Transport trust:** HTTP is intentionally loopback-only and relies on your trusted local processes and SSH forwarding. It is not a security boundary against other users or processes that can replace or proxy your forwarded listener. Do not use shared/untrusted machines or public/shared forwarded endpoints. If the listener changes unexpectedly, stop and verify your tunnel before connecting.
- Conversation traffic goes between Raycast, your chosen self-hosted bridge, and its scoped agent connectors, directly or through your existing tunnel. Argo does not upload conversations to an Argo cloud or automatically collect your screen, browser pages, selected text, or source files. Your agent provider's own data policies still apply.
- Pairing saves an independent durable Mac client credential in a mode-`600` file under the extension's support directory (`clients/`). Existing configurations remain private files. Tokens are not stored in Raycast preferences or LocalStorage. Agent credentials authorize one binding; Mac client credentials authorize the bridge's sessions. Never paste durable tokens into agent chat, logs, GitHub issues, or screenshots. Treat temporary pairing codes as private too.
- Saved connection references, draft text, pending message IDs and their original text/session generation, and recent-session identifiers live in Raycast LocalStorage on the Mac. Pending IDs are saved before submission and reused after reopening so an uncertain response does not silently create a second execution. An unknown pending message blocks different text or a changed session generation until its original submission can be acknowledged. A confirmed rejection releases the pending ID only after every history page proves it was not already queued, while keeping the draft. Network errors, unavailable history and storage failures keep the original retry ID. Bridge messages/events persist in `~/.argo/bridge.sqlite` on the bridge machine; connector outbox data lives in `~/.argo/outbox/` on the agent machine (`ARGO_HOME` can change these runtime locations). Private files are not application-level encrypted storage. There is no automatic retention or cloud backup.
- **Unbind Session** revokes that agent binding without stopping the original agent or deleting history. Removing a saved connection only removes its Mac reference; it does not revoke credentials or stop the server. `revoke-clients` on the bridge machine revokes all paired Mac clients. Revocation is not deletion: back up needed data and stop the relevant Argo processes before manually removing their stored data. Removing the Raycast extension does not uninstall the separate runtime.

Argo is an independent companion tool, not an official Raycast, Anthropic, or OpenAI product. [Source and further documentation](https://github.com/MatrixA/argo).