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 approvals get cards; Grok sessions are listed and take messages, but you answer their approvals in Grok. 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-mac.zip file, then drag the extracted Vistara app to Applications.
2. Open Vistara from Applications. macOS asks once whether to open an app downloaded from the internet: click Open. The app is signed and notarized by Apple.
3. On the welcome screen, Earn points in the background turns on opening at login, so a restart doesn't stop your node (change it later in ⚙ → Your privacy → Open Vistara when you log in).
4. 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….

The ZIP contains the same signed, notarized app as the DMG installer. If a previously downloaded disk image says it is corrupted or cannot be opened, use the ZIP download above; it does not need to mount a disk image. Both downloads are for Apple Silicon Macs.

Updating

Vistara updates itself. It checks shortly after launch and every few hours, downloads the new version in the background, and tells you when it's ready. Choose Restart to update from the menu-bar icon, or keep working and it installs the next time you quit. Your settings, hooks, node and points are kept.

Coming from 0.2.21 or earlier? Those builds were unsigned and can't update themselves. Download the current version once from vistara.dev and drag it into Applications to replace the old one. On first launch macOS asks once whether Vistara may use its saved key (@pouncer/shell Safe Storage). Click Always Allow and it won't ask again.

The welcome

On first launch the ⌘⇧Space panel opens on the welcome. A new install's node is already on, so it reads Your Vistara node is live, shows which coding agents it found on your Mac, and has two steps. Each 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>). For Codex it also records in ~/.codex/config.toml that you trust these hooks (the [hooks.state] entries /hooks writes), backed up first and removed on Disconnect.
Keep your node running after a restart	Opens Vistara when you log in, so the node keeps earning. Change it any time in ⚙ → Your privacy → Open Vistara when you log in. (If the node didn't turn on by itself, this step reads Turn on your node and does both.) See Points and Vistara Node.

Below the steps, See how a question looks pops a sample question card by your cursor (nothing is sent), and Try a 2-minute task with Claude copies a small sample repo to ~/vistara-demo and runs Claude Code on it in the background: Claude fixes a bug and asks you one question on a card, then the tests pass and it counts as verified work. It 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 helpers and sessions to reconnect adds sub-agents and the Connect list of sessions that need a restart. Show less hides them again. Browser tabs and terminals are never listed; type in the search box to find them.

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.
• Replies go through each agent's own channel and are kept until they land. Claude sessions receive replies through their hook or their own inbox socket; Codex sessions through Codex's app-server; Cursor and Grok through their hooks; sessions Vistara hosts through their own terminal. Every message is saved in Vistara's outbox first, and the row under the conversation says whether it is queued, handed over or delivered. Nothing is copied to your clipboard unless you click Copy.

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, Codex trusts the hooks: Settings → Agents doesn't ask you to approve them.
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 helpers and sessions to reconnect 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 runs a hook only once it trusts it. Connect records that trust; if your config.toml is in a form Vistara won't edit, or the hook command changed, Settings → Agents says so: press Approve there, or run /hooks inside Codex.

The Keychain keeps asking. Click Always Allow, not Allow. After moving from an unsigned build (0.2.21 or earlier) to a signed one, macOS asks once. Signed updates don't ask again.

"Vistara can't be opened" or "Apple could not verify Vistara". You have an old unsigned build (0.2.21 or earlier). Download the current one from vistara.dev; it opens without that warning.

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.