Install Cursio.

1Download#

Take Cursio-<version>-arm64.dmg and the file Cursio-<version>-arm64.dmg.sha256 from the release page. To check that the dmg arrived whole, put the two files in one folder and run this in Terminal, in that folder:

shasum -a 256 -c Cursio-<version>-arm64.dmg.sha256

It must print OK.

2Install#

Double-click the dmg. Drag Cursio onto Applications. Then eject the disk image (the eject button beside "Cursio" in Finder).

3Open it the first time#

This version is not signed with an Apple developer account yet. Apple has not looked at it, so macOS stops it the first time. You allow it once. (The release page says when a version is signed and this step is gone.)

1. Open Cursio from Applications. macOS says that it could not verify that Cursio is free of malware. Click Done. Do not click Move to Trash.

2. Open System Settings, then Privacy & Security. Scroll down to Security. Cursio is named there: click Open Anyway. macOS asks for your password or Touch ID.

3. Open Cursio again. If macOS asks once more, click Open.

Open Anyway says that you trust this download, so do the check in section 1 first. Apple describes the same steps on its page "Safely open apps on your Mac".

If you work in Terminal and you trust the file, this does the same as the three steps:

xattr -dr com.apple.quarantine /Applications/Cursio.app

4The first screen#

The first time, Cursio shows Welcome to Cursio. It shows a mark for each of the nine coding agents it knows (Claude Code, Codex, Gemini CLI, Cursor Agent, OpenCode, omp, pi, Grok and dsh). A dot on each mark says whether that agent is ready (green), has to sign in first (amber) or is not installed on your Mac (grey). An agent that is installed and has not said it is signed out counts as ready. There is one switch: Let Cursio watch and teach my agents. The switch is on.

When you click Continue, Cursio changes only the settings folders of the agents that are ready (for Claude Code that is ~/.claude, for Codex ~/.codex). An agent that is not installed, or that has to sign in first, gets nothing: Cursio never writes to it. Each ready agent gets what its own program can take:

• Hooks, which tell Cursio when the agent works, waits or asks you. Every agent has them except omp, which tells Cursio by itself.
• A short skill, which tells the agent how to use Cursio. Every agent has it except Gemini CLI, Grok and dsh, which Cursio watches and does not teach.
• A short note at the start of each session, which tells an agent that runs in a Cursio pane where it is and what it can do. Claude Code, Codex and Cursor Agent get it. Continue turns the note on; in Settings, on the Agents page, More has a switch for each of its lines.

What exactly? lists each file. Turn the switch off to leave your agents alone. Esc and the cross close the screen and set nothing up. Continue also starts putting the adapters of Claude Code, Codex and pi on your Mac, in the background (section 6).

If the history of your agents on this Mac names folders that are still there, a second page, Pick a folder to start in, lists up to six of them, the newest first. Choose one and click Start to open it as a tab, or click Skip.

If Cursio finds no agent, the first screen has Show how to install. It shows the line that installs each agent, and Install in a terminal beside a line types it into a new tab and leaves the Return to you. Cursio never installs an agent itself.

You can set up an agent later, or take Cursio out of it again, in Settings, on the Agents page: open the agent's row and use Take Cursio out of it. The palette (⇧⌘P) has Set up agents to show the first screen again.

The cursio command

The app is also a command line (cursio ps, cursio git, cursio . to open a folder). A shell that Cursio starts in a pane finds it: Cursio keeps a link named cursio in ~/.cursio/bin, which stands first on the PATH of its panes.

5What it asks for, and when#

macOS asks you, the first time Cursio needs each of these, and Cursio cannot give itself any of them. You can change each answer later in System Settings, Privacy & Security.

6What leaves your Mac#

Cursio has no server and no account. It sends no analytics and no crash reports.

By itself, Cursio asks the network for three things.

1. 1

   The first is which versions are the newest, of Cursio and of each coding agent that is installed on your Mac, and the file of the newest Cursio when it is newer than yours. Once a day, when Cursio starts, it asks github.com for the address of the latest release of Cursio: one request, made by curl, that says Cursio as the program's name and carries no version number of yours and no account (GitHub sees your network address, as it does for any request).

   MoreLess

   Cursio reads the version number out of the answer and nothing else. It then does the same for each agent that is installed, one agent at a time: it runs the agent's own --version to read which version you have (it starts the agent for nothing else, except that after you press Update on an agent's row and the line that Cursio typed has ended, it runs --version once more to say what the agent is on now, and asks the network nothing then), and makes one request of the same kind to the one place where that agent says its newest version, which is npm (registry.npmjs.org) for Gemini CLI, OpenCode, omp and pi, GitHub for Codex, and Anthropic's download page (downloads.claude.ai) for Claude Code. An agent that is not installed is not asked about, and neither are the ones whose place Cursio does not know (Cursor Agent, Grok, dsh). If a newer version of Cursio or of an agent is out, Cursio shows a mark in the top bar (a window whose tab list is put away has no top bar and so no mark: section 7 says where the news is then). This look installs nothing. It does not ask while an agent is at work in the window, and it asks at two times only: when Cursio starts (once in 24 hours), and when you press Check for Updates (in the Cursio menu and the palette, or Check now in Settings, on the About page), which asks at once, at most once a minute, and says what it found. To turn this look off, switch off Look for updates in Settings, on the About page, or put check_updates = false in ~/.config/cursio/config.toml: Cursio then makes none of these asks, runs no --version for them and shows nothing. A build that is not a release (one made from the source) does not ask at all.

   When the look finds a newer Cursio, Cursio also downloads it, unless you turned that off. It takes two files from the release's page on github.com, the checksum of the release's disk image (Cursio-<version>-arm64.dmg.sha256) and the image itself (Cursio-<version>-arm64.dmg), and for each it runs curl twice, in the same way as the look (the same program name Cursio, no version number of yours, no account and no cookie): first for the head of the page only, because GitHub sends the file on to its own file host (release-assets.githubusercontent.com or objects.githubusercontent.com) and Cursio reads where, then for the file itself from that host, when it is a host of GitHub's, and from no other: an address that points anywhere else is not asked at all.

   MoreLess

   The file comes in as a half-file in the folder updates of ~/Library/Application Support/Cursio, is renamed only when its SHA-256 is the one the release names, and is removed when it is not; a file of more than 400 MB is refused. Only the newest download is kept. It starts only for a version that is newer than yours, only on a Mac with Apple silicon, only while the look is on and download_updates is not false, and never while an agent is at work in the window; one that fails says why in one line on the About page, is removed, and is tried again the next day. Cursio never opens, mounts, installs or replaces anything: Show in Finder (Settings, About) shows the file and the rest is yours (section 7). Switch off Download updates in Settings, on the About page, or put download_updates = false in ~/.config/cursio/config.toml, and nothing is downloaded and the folder is emptied; the switch of the look reaches it too.

   The setting Update channel (update_channel) says which answer the look takes for Cursio. stable, the default, is the page of the latest release, which never names a pre-release. preview asks the list of the releases of the same repository instead (releases.atom on github.com, one request in the same way, of which only the first 192 KB are read and only the links to the repository's release tags in it) and takes the newest version in it, a pre-release too. There is no other channel: no build is made for each change. check_updates = false asks nothing on either channel.

2. 2

   The second is for Claude Code, Codex and pi. A Thread with one of them talks to the agent through a small program from npm, its adapter (@agentclientprotocol/claude-agent-acp@0.102.0, @agentclientprotocol/codex-acp@2.6.0 and pi-acp@0.0.34: the version of each is fixed in Cursio, the one that was tried with the real agent).

   MoreLess

   Cursio puts it on your Mac once, in the folder adapters of ~/Library/Application Support/Cursio, by running npm install, so npm asks the npm registry (registry.npmjs.org) and downloads the package: when you press Continue on the first screen, or at the first Thread of that agent (the Thread says Getting Codex ready (first time only)). Cursio never asks npm which adapter is the newest (there is no npm view, no setting and no check for it): a newer adapter reaches you with a release of Cursio. After a Thread of that agent has started, at most once a day, Cursio only sees that the fixed version is on your Mac, and where an older or newer one is there from before, it installs the fixed one beside it in the background and uses it from the next start. Where Node.js is not found, or an install fails, the Thread starts with npx, which asks the registry itself. The switch Look for updates and check_updates = false do not reach this. To turn it off, give Cursio the environment variable CURSIO_ADAPTERS=npx: nothing is installed or looked for then, and the Thread starts with npx every time.

3. 3

   The third is a small file. While the page of Agents in Settings or the start of a Thread is shown, and at most once an hour, Cursio asks raw.githubusercontent.com for one file of the versions of agents that are known not to work with it (known_bad.json, at the head of the same repository that the first look asks about), by curl, in the same kind of request: no account, no cookie, nothing of yours.

   MoreLess

   It is a list of words: nothing in it is run, installed or opened, and Cursio shows the words of a row as one dim line where it shows the agent. The switch Look for updates turns it off with the rest of the first look. Where the repository is not open the answer is 404, and Cursio goes on with the list that it has in itself.

It does start programs that you already have. They use the network the way they always do:

• your coding agents: what an agent sends is between you and that agent;
• gh, the GitHub command line program, if you have it and are signed in to it: for a Folder with a GitHub remote, while a Thread of that Folder is shown, Cursio asks gh about the pull request of the branch and its checks. It asks every 2 minutes, every 15 seconds while the checks run, and not while the window cannot be seen. It also asks when you make, report on or merge a pull request. That is gh talking to GitHub with your own sign-in;
• git, when you push or pull from Cursio, and when you ask for a plugin by a Git address;
• ssh, for a Computer;
• npm and node, for the adapters of Claude Code, Codex and pi (the second thing above);
• curl, when you attach a web address to a message, for the questions about the newest versions above (the same daily look asks each installed agent's own place (npm, GitHub or the agent's download page) and runs its --version, one at a time, and the same switch turns all of it off, and the small file of known bad versions with it), and for the download of a newer Cursio that is described there;
• a Chromium-based browser, when an agent uses the browser tools or you use the browser panel. What you type in the panel's address field that is not an address (a phrase, or one word that is no host) is searched for on DuckDuckGo (duckduckgo.com); cursio browser open and an agent's browser tool never search.

Dictation is recognized on your Mac when the language is installed for it (System Settings, Keyboard, Dictation) and on_device in [voice] is on, which it is unless you turned it off. If the language is not installed, or you turned it off, macOS may send the audio to Apple's servers for that use.

Report a problem... (open the palette with ⇧⌘P and type it) writes a file for you to read. It takes out what looks like a key, a token or a password, but read it before you send it. Cursio sends nothing: you send the file yourself.

7Update#

There is no updater that installs: Cursio never installs or replaces a new version of itself, and never restarts itself. When a newer one is out it shows a mark in the top bar (section 6 says how it knows, and how to turn that off), downloads the new dmg in the background and checks it (section 6 says how, and how to turn that off), and Update in the mark's list opens the download page.

The same list tells you when a coding agent that is installed has a newer version out. Update on an agent's row types that agent's own update line (for example claude update) into a new Terminal tab and stops there: nothing runs until you press Return, and Cursio runs no updater of its own.

While versions are not signed, each one is a new app to macOS. Open it with Open Anyway again (section 3), and macOS asks again for the things in section 5.

By hand

The mark, the card and the download above all come from one look at the page of the newest release. When Cursio cannot read that page it shows nothing and downloads nothing: a repository that is not open answers 404 (section 6), and a network that is not there answers nothing. That is not a fault. A newer file that you have from another place (the release page, or whoever made it) goes onto the old one by hand, in the steps below. Which version runs is on Settings, on the About page; the version of a file is in its name, Cursio-<version>-arm64.dmg or cursio-<version>-windows-x64.zip.

On a Mac

1. Check the new dmg as in section 1.
2. Quit Cursio with Quit and End All Panes (⌥⌘Q). It ends the session server and the programs in your panes (when an agent is working it asks first: press the key again to confirm) and forgets which tabs were open, so the new version starts a server of its own. Quit Cursio (⌘Q) alone leaves the server and those programs running, and a window that starts joins a server that is already there: it does not start a new one because the app was replaced. The new version then works with the old server, and what only a newer server does is not there; and when the two speak different versions of the server's language, the window refuses the old server, and the new version's --kill-server is refused by it in the same way. So if you quit with ⌘Q, end the old server now, before step 3, with the old app: /Applications/Cursio.app/Contents/MacOS/cursio --kill-server. The programs in your panes end with it.
3. Open the new dmg, drag Cursio onto Applications and choose Replace. Then eject the disk image.
4. Open Cursio from Applications. A version that is not signed is a new app to macOS: allow it with Open Anyway again (section 3), and macOS asks again for the things in section 5.

Your settings (~/.config/cursio), what Cursio keeps (~/Library/Application Support/Cursio) and the sessions that your agents keep in their own folders are not in the app. Replacing it leaves all of them as they are.

On Windows

1. Check the zip against its .sha256 file, as for the first one: (Get-FileHash .\cursio-<version>-windows-x64.zip).Hash.
2. Close Cursio with Quit and end all panes (Alt+Shift+Q): it ends the session server and the programs in your panes too. Closing the window, or Quit (Ctrl+Shift+Q), leaves the server running, as on a Mac (step 2 above); then end it with cursio.cmd --kill-server, run in the folder of the old cursio.cmd, before step 3.
3. Unpack the new zip into the same folder as the old one, the folder that holds cursio.cmd (in Explorer, Extract All asks where: give it that folder). The zip holds cursio.cmd, cursio-launch.exe, Read me first.txt, current (one line: the name of the version to run) and one folder named like the version, which holds cursio.exe and the licences. It adds the folder of the new version beside the old one and does not touch the old one, so nothing that runs is written over. It replaces cursio.cmd, cursio-launch.exe, Read me first.txt and current, so say yes when it asks; current then names the new version.
4. Start cursio-launch.exe (double-click it; in a terminal cursio.cmd does the same): it runs the version that current names. SmartScreen asks once again for the new build: More info, then Run anyway.
5. When the new version works, delete the folder of the old one.

Your settings (%APPDATA%\cursio\config.toml) and what Cursio keeps (%LOCALAPPDATA%\cursio, its logs in the folder logs) are not in the folder of the program and stay where they are.

8Remove#

First, if you let Cursio set up your agents, take it out of them: Settings, Agents, open each agent's row and use Take Cursio out of it. Or run this in Terminal:

/Applications/Cursio.app/Contents/MacOS/cursio hooks uninstall

What is left in an agent without Cursio does nothing.

Second, if Cursio put the cursio command where your terminal finds it (section 4 says when), take that link away: Settings, on the Terminal page, the row Command line, Remove. It removes only a link that Cursio made.

Then quit Cursio with Quit and End All Panes (⌥⌘Q) and drag it from Applications to the Trash. Quit Cursio (⌘Q) alone leaves the session server and the programs in your panes running; if that happened, run /Applications/Cursio.app/Contents/MacOS/cursio --kill-server before you drag the app to the Trash, and it ends them.

Cursio keeps your settings and plugins in ~/.config/cursio, and its state and logs in ~/Library/Application Support/Cursio (the adapters of section 6 are in its folder adapters). The link that its own panes use for the cursio command is in ~/.cursio/bin. Delete them too if you want it gone entirely.

On Windows#

There is a first build for 64-bit Windows 10 (version 1809 or newer) and Windows 11. It is unsigned and it is a rough first look: what does not work yet is listed below. A release has a Windows build only when cursio-<version>-windows-x64.zip is on its page (the Windows files are put there by hand, after the Mac ones).

1. Take the zip from the Releases page and check it against its .sha256 file: in PowerShell, (Get-FileHash .\cursio-<version>-windows-x64.zip).Hash is the number that the file holds. Unpack it.
2. Double-click cursio-launch.exe (in a terminal, cursio.cmd starts it too). The first time, Windows stops it with "Windows protected your PC" (SmartScreen), because the build is not signed: click More info, then Run anyway. It asks once for each build.
3. Install Git for Windows if you have not: Worktrees and Changes need it, and Cursio says so, with this address, when it starts without it. Nothing else has to be installed (no Visual C++ redistributable, no WebView2). The coding agents are not in the app, as on a Mac.

Cursio keeps its logs in %LOCALAPPDATA%\cursio\logs: window.log (when the window started, ended or panicked) and server.log, and for a crash one file, crash-<date>-<time>-<number>.txt, with the version and the first words of the panic and never a path of yours. Nothing is sent anywhere. cursio doctor says where they are and what is missing.

A Stop that you press ends the commands that the turn started, a closed pane ends the programs under it, and a command that an agent runs for itself is ended with Cursio however Cursio ends: tested here with stand-in programs, not seen with a real window or a real agent.

What does not work on Windows yet:

• The window has not been looked at by a person on a PC: the caption buttons, dragging, the Windows keys (Ctrl-C and Ctrl-V in a pane), the font of a pane, the taskbar and the picture at 125, 150 and 200 percent are written and tested without a screen, not seen.
• cursio screen, cursio rail, cursio --voice, the shared Codex server (app-server) and the Browser pane (cursio browser) are not there. A shell other than PowerShell, cmd, Git Bash and bash in WSL gets no command blocks, and a picture sent through shared memory is refused.
• Of the agents only Claude Code runs natively. Codex and OpenCode need WSL and have no install line; Gemini, Grok and dsh are not set up. How an agent's hooks, its plugin files and its launch line are written for Windows, a session's name, and the agents that speak ACP through npx.cmd are not done.
• No cursio is put on your PATH: run cursio.cmd, or add its folder to your PATH.
• Updates: Cursio tells you that a newer build is out and opens its release page; it downloads nothing on Windows.
• Open in Editor, Reveal and Open do nothing yet.
• Some words still say "this Mac" where a PC is meant (the Changes view, the Computers page, Tailscale's).
• Where Cursio makes a symbolic link, Windows allows it only with Developer Mode on; the tests of those places were not run there.
• PowerShell, cmd, Git Bash and bash in WSL mark their prompts, but cmd cannot say where a command starts or ends, and the marks of Git Bash and of WSL are written and tested without those shells, not seen; a line can be lost at the top of a pane that is resized while it prints.
• Taking a custom look away puts its file in the Recycle Bin: written and tested without the Recycle Bin, not seen.

Licences#

Cursio is under the MIT or the Apache-2.0 licence, at your option. The licences of the software inside it are in THIRD-PARTY-LICENSES.txt, which is on the release page and inside the app, in Cursio.app/Contents/Resources.