Getting started

What you need

• A Mac with Apple Silicon (M1 or later). The beta build is arm64 only; it does not run on Intel Macs.
• A coding agent: Claude Code (in a terminal or in Claude Desktop's Code tab), Codex, or both. Cursor and Grok sessions are listed but get no cards. If you only use Claude Desktop chats, see Claude Desktop for what you get.
• Any terminal: Terminal, iTerm, Warp, or the terminal inside VS Code or Cursor.

You do not need an account, an API key or a local model.

Install

1. Download Vistara for Mac. Open the Vistara-…-arm64.dmg file and drag Vistara to Applications.

2. This beta build is not signed or notarized yet, so macOS blocks the first launch. To allow it once:

   • macOS 15 (Sequoia) and later: open Vistara, click Done on the warning, then go to System Settings → Privacy & Security, scroll down to the message about Vistara and click Open Anyway. Confirm with your password.
   • macOS 14 and earlier: right-click Vistara in Applications → Open → Open.

   After that it opens normally.

3. Vistara lives in the menu bar. It has no Dock icon. Click the menu-bar icon for Open Vistara and pause options; Quit Vistara is under More….

Unsigned beta build

Because the build is not signed with a Developer ID, macOS can forget permission grants when you install an update. A signed build is on the roadmap.

Updating

There is no auto-update in the beta. To update, quit Vistara from the menu bar, drag the new version into Applications to replace the old one, and open it again (you may need Open Anyway again). Your settings, hooks and history are kept.

The welcome

On first launch the ⌘⇧Space panel opens on a Welcome to Vistara page. It shows which coding agents it found on your Mac and walks you through setup. Each step ticks off when it actually happens.

Step	What it does
Connect your agents	Adds Vistara's hooks to ~/.claude/settings.json and ~/.codex/hooks.json (Codex only if ~/.codex exists). Each file is backed up first, next to the original (for example settings.json.vistara-backup-<timestamp>). Codex asks you to trust the new hooks once; run /hooks in Codex to do that.
Turn on your Vistara Node	Creates a node key on your Mac (macOS asks once to keep it in your Keychain; choose Always Allow) and a rewards wallet on Base. Then the Points page opens. See Points and Vistara Node.
See how it works	A sample question card pops up by your cursor. Answer it there; nothing is sent anywhere.
Try a real task (optional, 2 min)	Copies a small sample repo to ~/vistara-demo and runs Claude Code on it in the background (no terminal opens). Claude fixes a bug and asks you one question on a card; after your answer the tests pass and it counts as verified work. Uses your own Claude Code account.

The welcome opens at every launch until you finish it. Closing the panel hides it until the next launch; Skip setup at the bottom turns it off. Reopen it any time from the menu bar: Welcome & setup…

Your first 10 minutes

1. Start or resume an agent. New Claude Code and Codex sessions connect automatically. Sessions that were already running need one restart (see Troubleshooting).
2. Work as usual. Give the agent a task that will make it ask you something, or that needs an approval outside the repo.
3. Answer the card. When the agent asks or needs approval, a small card appears near your cursor. It shows the agent's own question, what you asked it, and the options it offered. Click an option or type a reply. The answer goes to that session. Press Esc (or ×) to hand the question back to the agent's own prompt in the terminal.
4. Press ⌘⇧Space. The overlay opens on Today: asks handled, what is waiting on you, the last thing that finished, and your projects with their checks.
5. Click a session. You see its status, its test and build checks, its last change, and the live conversation from its transcript.
6. Try Send work. From a session, choose Send work… to hand its state to another Claude session, start a new Claude Code or Codex session on it, or copy it. See Send work and handoffs.
7. Look at Points. The Points page shows your node's uptime today, agent work time today, asks handled, and verified work.

At the bottom of the overlay's list, Show everything adds recent tabs and terminals, sub-agents, and the Connect list of sessions that need a restart. Show less hides them again.

Optional settings

Open the overlay and click ⚙.

• Add to Claude Code / Add to Claude Desktop. Lets your Claude sessions and Claude Desktop chats ask Vistara about your other agents, for example "use vistara: what is the Codex agent on my api repo doing?" See Agents and integrations.
• Keep the Mac awake while agents work. On external power only, stops idle sleep while an agent is mid-task. The screen can still turn off. Closing the lid still sleeps the Mac.
• Permissions. Browser tabs in search, Warp terminals and Warp AI, and terminal typing. All are off by default. See Privacy and security.
• Export diagnostics. Saves a redacted file to Downloads that you can send us.
• Disconnect my agents. Removes Vistara's hooks from Claude Code and Codex. Restart their sessions to apply.

What to expect

• Cards are rare. A card appears only when an agent asks a question or needs an approval that your policy does not cover. Finished turns go to a quiet list in the overlay, not a popup.
• A held request waits up to 60 seconds. While a card is up, the agent waits. If you do not answer within 60 seconds, the agent shows its own prompt in the terminal and nothing is lost.
• Vistara never types or switches tabs on its own. Anything that touches another app happens only after your click or keypress.
• Answers to Claude are reliable; free-text replies to Codex are not always. Claude sessions receive replies through their hook or their own inbox socket. Codex approvals go through its hook; a free-text reply to Codex is typed into a visible Warp tab only if you turn on terminal typing, and is otherwise copied to your clipboard. The card tells you which will happen before you click.

Troubleshooting

No card appears at all. Check these in order:

1. Vistara is running: its icon is in the menu bar. If Vistara is closed, agents ask in the terminal as usual.
2. The session started after you connected your agents (see the next item).
3. The request was covered by your local policy. Routine reads, edits, tests and builds inside the repo are approved without a card. See The local policy.
4. For Codex, you trusted the hooks with /hooks.
5. Claude asked in plain text mid-reply. A card for a typed reply appears only when Claude ends its turn with a question.

The menu-bar menu shows a Hooks: line when hooks are missing or a session needs a restart.

No card appeared for a session that was already running. Agents load hooks when a session starts. Sessions started before you connected need one restart. Resume the same conversation in the same tab:

claude --resume <session-id>
codex resume <session-id>

With Show everything on, the overlay lists these under Connect with the exact command; select one and press ⌘C to copy it.

A card appeared, then the agent asked in the terminal anyway. The 60-second hold ended before you answered, or you pressed Esc. Answer in the terminal.

Codex hooks do nothing. Codex asks you to trust new hooks once. Run /hooks inside Codex and approve Vistara's entries.

The Keychain keeps asking. Click Always Allow, not Allow. Unsigned builds can trigger the prompt again after an update.

"Vistara can't be opened" or "Apple could not verify Vistara". On macOS 15 and later, go to System Settings → Privacy & Security and click Open Anyway. On earlier versions, right-click the app in Applications and choose Open, then Open again.

Report a problem

Open the overlay, click ⚙ → Export diagnostics, and send the file to mayur@vistara.dev with a line on what you expected and what happened. The file contains health checks and the last log lines, with tokens and key-shaped strings redacted. Read it first if project folder names matter to you. See Privacy and security.

Uninstall

Click ⚙ → Disconnect my agents, quit Vistara from the menu bar, and move it from Applications to the Trash. To remove its data as well, follow Deleting your data.