Skip to content

Install and update

Install, update, and remove the Prism CLI and the plugins, and use them together.

There are three ways to install Prism. The CLI is recommended. The Claude Code plugin and the Codex plugin give you the same recording inside Claude Code or Codex without installing the CLI. Each plugin records only its own tool.

Operating system How to install
macOS The CLI (recommended), the Claude Code plugin, or the Codex plugin
Windows The Claude Code plugin or the Codex plugin. The CLI can be installed on macOS only.
Linux The Claude Code plugin or the Codex plugin. The CLI can be installed on macOS only.

You need Claude Code or Codex on the same computer. If you record every session with prism setup, the command looks for the two tools separately. It finds Claude Code by its configuration directory (~/.claude, or the directory named by CLAUDE_CONFIG_DIR) or a claude program on your PATH, and Codex by its configuration directory (~/.codex, or the directory named by CODEX_HOME) or a codex program on your PATH. For a tool it cannot find, it prints a line of its own, such as Claude Code was not found (no configuration directory and no `claude` on PATH); skipped. or Codex was not found (no configuration directory and no `codex` on PATH); skipped., and registers hooks only for the tool it found.

Create your Prism account first and review what the CLI collects.

Follow Quickstart. The steps have the same names as on the Install guide screen, which you reach with Connect in the header: Install the CLI, Sign in from the terminal, and Start recording. The install command is on the Install script tab and the Homebrew tab of the first step. Prism’s pages do not quote it because it can differ between deployments.

After installing and signing in, run this in a terminal to confirm the result:

Terminal
prism status

prism status should show Login: logged in. If you chose Record every session (prism setup), it should also show Claude Code hooks: registered or Codex hooks: registered for each tool you use. If you only start sessions with prism claude or prism codex, the hooks stay unregistered, and that is expected. Commands describes the full output.

Follow Quickstart: Install the plugin, Sign in, and Check. The plugin installs nothing else, and no prism command is added to your terminal.

/prism:setup, typed into Claude Code, signs you in. After the sign-in it also looks for what the earlier Prism plugin left on this computer. If it finds something, it lists it and removes it only after you agree. If you updated from the earlier plugin, you may already be signed in with the earlier plugin’s key, and then you do not need to enter a code. Use /prism:status to see the state, and /prism:uninstall to remove what the plugin keeps (Remove Prism explains what it does).

The Claude Code plugin records only Claude Code sessions. It does not check or change the CLI or Codex.

Follow Quickstart: Install the plugin, Trust the hooks, Sign in, and Check. Nothing is recorded until you trust Prism’s 4 hooks in /hooks.

If Codex asks permission to run a command while you sign in with $prism:setup, allow it. The sign-in command does not run inside the sandbox. The plugin installs nothing else and adds no prism command to your terminal. Use $prism:status to see the state, and $prism:uninstall to remove what the plugin keeps. The Codex plugin records only Codex sessions. It does not check or change the CLI or Claude Code.

A Codex session started with codex exec is collected once, when it ends, instead of while it runs.

When the CLI and a plugin are both installed

Section titled “When the CLI and a plugin are both installed”

The CLI and both plugins share one sign-in and one set of local files, so one computer is one device. You sign in once, with whichever of the three you set up first, and the others use that sign-in. In the web app the computer appears once under Settings → Devices.

The local files are in one Prism folder: ~/.config/optra-prism on macOS and Linux (or optra-prism inside the folder that XDG_CONFIG_HOME names, when it is set to an absolute path), and %APPDATA%\optra-prism on Windows. CLI settings and files lists what is in it. The sign-in token is stored in the macOS Keychain on macOS, in the Windows Credential Manager on Windows, and in the system secret store on Linux. If that store cannot be used, the token is stored in a file in the Prism folder that only your user can read.

Setting up one does not change the other:

  • prism setup registers hooks for Claude Code and Codex. It does not turn a plugin off.
  • prism setup remove and prism uninstall do not turn a plugin on again, because they never turned one off.
  • When the CLI’s hook and a plugin’s hook both receive the same event, Prism records that event once. You do not need to remove a plugin after you set up the CLI.

Each plugin still records only its own tool.

If you use the Claude Code plugin, new versions come with plugin updates. Update it by typing /plugin marketplace update optra-prism into Claude Code, because marketplaces that are not official do not update automatically by default.

If you use the Codex plugin, update it by running codex plugin marketplace upgrade optra-prism in a terminal. Codex asks you to trust the changed hooks again in /hooks.

If you installed the CLI, install the newer version the same way you installed the first one, then run any prism command in a terminal. The newer program copies itself into the versions folder of the Prism folder and becomes the version that the hooks run when its version number is higher than the current one. Your registration and sign-in stay as they are.

prism status shows the need for an update on the Upgrade needed line:

  • no: nothing to do.
  • yes, the server needs prism <version> or newer; <how to update>: update to that version or later.
  • yes, the server refused the last send; <how to update>: the server did not accept the last send from this version.

<how to update> tells the CLI to re-run the install script or brew upgrade, and a plugin to run the plugin update command above. When a Prism plugin on the same computer is newer than the CLI, prism status shows a Plugin newer than this CLI line; update the CLI then.

A newer version lifts the block that a refused send puts on your sessions, and sending resumes. Run prism status once more to confirm.

Choose how much to remove:

Command Where you run it What it removes
prism setup remove Terminal Only the hooks and Codex trust records that prism setup registered in Claude Code’s settings file (~/.claude/settings.json) and Codex’s settings file (~/.codex/config.toml). It acts on every configuration directory that prism setup remembered. The sign-in and the local files stay, and so do the plugins. Run prism setup to register again.
prism uninstall Terminal The hooks and Codex trust records, this device’s sign-in on the server and the stored token, and the files Prism keeps in the Prism folder. It lists what it will remove and asks for confirmation. A plugin that is still installed shares that sign-in, so it is signed out too; sign in again with /prism:setup or $prism:setup to keep recording.
/prism:uninstall Inside Claude Code The plugin’s way to sign this device out and delete the files in the Prism folder. It lists what it will remove and asks before it goes on.
$prism:uninstall Inside Codex The same as /prism:uninstall, for the Codex plugin.

Before you confirm, prism uninstall and the plugin commands print Unsent envelopes that will be lost, the number of records that were not sent yet. Add --yes to prism uninstall to skip the confirmation.

A plugin’s uninstall command removes the sign-in and the files only when the CLI is not set up on this computer. If prism setup registered hooks here, the command says that the CLI is set up, removes nothing, and leaves the device signed in. Use prism uninstall then. Because the sign-in is shared, removing it through one plugin also signs out the other plugin, and a CLI that you never set up with prism setup. Sign in again with prism login, /prism:setup, or $prism:setup.

The plugin’s uninstall command does not remove the plugin itself, so its hooks stay registered until you do. Remove the plugin with /plugin uninstall prism@optra-prism inside Claude Code, or with codex plugin remove prism@optra-prism in a terminal.

If you installed the program with Homebrew, prism uninstall leaves that program in place and tells you to run brew uninstall prism.

Removing Prism from your computer does not delete the data Prism already received. To delete data, see Data collection and visibility.

From a set date, Prism stops accepting records from the current version of the Prism plugin for Claude Code. The web app can show a banner that names the date and has an action to open the install guide. To keep recording, choose one of two ways:

  1. Update the plugin and run the setup. In Claude Code, type /plugin marketplace update optra-prism, then /prism:setup. The updated plugin removes the telemetry values the earlier version wrote to Claude Code’s settings. The earlier plugin’s key is not revoked, and the updated plugin signs in with it automatically. Only if that sign-in fails does /prism:setup ask you to sign in with a code. After the sign-in, /prism:setup lists the earlier plugin’s local items, including prompt text that could not be sent, and removes them once you agree.
  2. Install the CLI and remove the plugin. Install the CLI, run prism login and prism setup as in Quickstart, then remove the plugin from Claude Code. If you have not updated the plugin, prism setup finds the telemetry values it wrote, asks for your consent, and removes them.

prism uninstall removes only what the CLI created, and neither it nor prism setup remove changes any plugin’s hooks or settings.