Agents and integrations

Vistara works with agents where they already run, and you don't have to change how you start them. You can also start a session inside Vistara: + New and Send work run the agent in a terminal Vistara hosts, and Move to Vistara (a session's ⋯ menu) moves an idle session over. How a reply reaches each agent is in How it works.

Support at a glance

Agent or tool	Listed in the overlay	Cards for questions and approvals	Your answer reaches the session	Live conversation	Checks in Workstate
Claude Code	Yes	Yes, through hooks	Yes: its held hook, its own inbox, or its next hook	Yes	Yes
Codex	Yes	Approvals, through hooks	Approvals: through the hook. Messages: a turn on its thread through Codex's app-server, or its next hook	Yes	Yes
Cursor (CLI and IDE chats)	Yes	Approvals, through hooks	Messages: its held Stop hook or its stop follow-up	No	No
Grok	Yes	No: Grok's hooks can't hold an ask, so you answer in Grok	Messages: its held Stop hook or its next hook	Yes	—
Warp AI	Only with the Warp permission on	No	Only with Terminal typing on	No	No
Claude Desktop (chat)	No	No	No	No	Reads all of it through the Vistara MCP server

Claude Code

Claude Code is the most complete integration.

• Hooks. Connecting adds HTTP hooks to ~/.claude/settings.json for approvals, AskUserQuestion questions, turn ends, and session events. See How it works.
• Approvals and questions are held for up to 60 seconds while a card is up. Your click goes back as the hook's response.
• Questions at the end of a turn. When Claude ends a turn with a question ("Want me to open the PR?"), its Stop hook is held for up to 60 seconds. A typed reply continues that same turn.
• Replies at any other time are saved in Vistara's outbox first, then go through the session's own inbox socket. This works whichever tab or window the session is in, and whether it is busy or idle. If the inbox can't take them, Claude's next hook carries them in: a tool call, your next prompt in its terminal, or the end of its turn.
• Sub-agents show by name under their parent session and stay quiet when they finish.

Sessions started before you connected need one restart: claude --resume <session-id>.

Claude Code inside Claude Desktop

Claude Code running inside the Claude Desktop app should use the same ~/.claude/settings.json hooks and work the same way. This has not been verified yet.

Codex

• Hooks. Connecting adds a command hook to ~/.codex/hooks.json for approvals, session start, prompts, tool use and turn ends. Connect also records in ~/.codex/config.toml that you trust these hooks (what /hooks records), only for Vistara's entries; Disconnect removes it.
• Approvals are held for up to 60 seconds. Codex waits during the hold. If you do not answer in time, Codex asks in its own terminal, and the card tells you so.
• Messages. A message to a live Codex session becomes a new turn on its thread, or steers the running turn, through Codex's own shared app-server, while the thread is open there. Otherwise it waits in Vistara's outbox for Codex's next tool call or turn end. Nothing is copied to the clipboard. Vistara types into a Codex window only if you turn on Terminal typing.
• Option keys. When Codex shows a menu in its terminal, no message is sent (it could pick an option). Option buttons press the menu's key in a session Vistara hosts, or, with Terminal typing on, in its window.

Sessions started before you connected need one restart: codex resume <session-id>.

Cursor

Vistara reads Cursor's agent transcripts and its IDE chat database to list Cursor sessions and their state. The live conversation view is not available for Cursor yet. Connecting adds hooks to ~/.cursor/hooks.json when Cursor is installed: approvals are held for a card, and a message goes in through Cursor's held Stop hook or its stop follow-up. Cursor's hooks carry no questions, so you answer those in Cursor.

Warp

Warp is optional. With Warp terminals and Warp AI turned on, Warp tabs appear in search and Warp's own agent appears in the session list. macOS asks once to let Vistara read Warp's data.

With Terminal typing turned on, Vistara can type a reply into the session's own Warp pane or tab, after checking it is the right one. It is off by default. Warp cannot focus a specific tab from outside, so for a terminal search result Enter copies cd <path> instead.

Any terminal

The core loop needs no terminal integration. Hooks, Claude's inbox and Codex's app-server work the same in Terminal, iTerm, Warp, or the terminal inside VS Code or Cursor. Only the optional typing fallback is Warp-specific.

Claude Desktop

Claude Desktop's chat mode has no hooks, so Vistara cannot show cards for its conversations or answer them. Desktop chats can still read everything Vistara knows, through the Vistara MCP server.

From the app: open the overlay, click ⚙ → Add to Claude Desktop, then quit and reopen Claude Desktop. In any chat:

use vistara: what are my agents doing?

Vistara adds one vistara entry to ~/Library/Application Support/Claude/claude_desktop_config.json, keeps every other entry, and saves a backup of the file first (claude_desktop_config.json.vistara-backup-<time>). It will not touch a config file it cannot parse.

The entry runs Vistara's own executable as a small bridge between Desktop (which speaks MCP over stdio) and Vistara's local endpoint, so it needs no Node.js or npx install:

"vistara": {
  "command": "/Applications/Vistara.app/Contents/MacOS/Vistara",
  "args": ["/Applications/Vistara.app/Contents/Resources/mcp/vistara-mcp-bridge.mjs"],
  "env": {
    "ELECTRON_RUN_AS_NODE": "1",
    "VISTARA_MCP_URL": "http://127.0.0.1:47322/mcp",
    "VISTARA_MCP_TOKEN": "<your local token>"
  }
}

If Vistara is not running, the tools answer with "Vistara is not running". To remove it, delete the vistara entry and restart Claude Desktop.

The Vistara MCP server

Vistara runs a small, read-only Model Context Protocol server on your Mac. Any local agent that speaks MCP can ask it what your other agents are doing.

Tool	What it returns
vistara_today	Today across all agents: sessions, asks handled, verified work, and one line per project with status, checks and last change.
vistara_sessions	Running sessions (Claude Code, Codex, Cursor) with title, agent, folder, state and session id. Takes an optional query.
vistara_context	One session's full context: status, checks, files touched, recent commands and conversation. Takes session, a session id or words from its title or project.

The server is read-only. It cannot start, stop or reply to any session.

Add it to Claude Code

From the app: open the overlay, click ⚙ → Add to Claude Code. This adds the server at user scope, so every new Claude session can use it.

By hand:

claude mcp add --transport http --scope user vistara \
  http://127.0.0.1:47322/mcp \
  --header "Authorization: Bearer $(cat ~/.vistara-relay/local-token)"

Then, in any new Claude session:

use vistara: what has the Codex agent on my api repo been doing?

Claude calls vistara_context and answers from Vistara's record, without you copying anything.

To remove it: claude mcp remove vistara --scope user.

Other MCP clients

Any client that supports MCP over Streamable HTTP can use the same URL and header. The server accepts JSON-RPC POST requests on /mcp and returns JSON responses; it does not open a server-initiated stream. See Privacy and security for how the endpoint is protected.