Everything the shipping build does, and how to use it.

• macOS, Apple silicon — a .dmg. Drag Primal Code to Applications.
• Windows x64 — installs for the current user, no administrator rights needed.
• Windows x64, all users — installs for every account on the machine; asks for administrator rights.
• Linux x64, .deb — Ubuntu, Debian, Linux Mint, Pop!_OS and other Debian-based systems.
• Linux x64, .rpm — Fedora, RHEL and openSUSE.
• Linux x64, .tar.gz — any other distribution; unpack it and run it in place.
• What changed in this build: the release notes.

1. Open the .dmg and drag Primal Code to Applications.
2. Right-click (or Control-click) the app and choose Open. Double-clicking shows a warning with no Open button; right-click is the route.
3. Choose Open in the dialog. From then on it opens like any other app.

1. Run the installer. SmartScreen shows “Windows protected your PC”.
2. Click “More info”, then “Run anyway”. The installer continues normally.

• Ubuntu, Debian and their relatives: sudo apt install ./PrimalCode-linux-x64.deb
• Fedora and RHEL: sudo dnf install ./PrimalCode-linux-x64.rpm. On openSUSE: sudo zypper install ./PrimalCode-linux-x64.rpm
• Anything else: unpack the .tar.gz and run PrimalCode-linux-x64/bin/primal-code

Then open Primal Code from your applications menu, or run primal-code in a terminal. It runs on Ubuntu 20.04, Debian 10, Fedora 36, RHEL 8 and anything newer.

Saved API keys go into your desktop keyring, GNOME Keyring or KWallet. On a minimal window manager without one, install gnome-keyring before adding keys.

Nothing to set up. When the app starts it looks for the credentials Claude Code stores in the operating system’s keychain and, if they are there, the Claude models appear in the model picker under that login. No key is copied anywhere.

Run Primal Code: Manage Providers from the command palette, choose a provider and paste the key. Keys are stored by the operating system’s secret storage (the keychain on macOS, Credential Manager on Windows), never in a settings file.

Anthropic

Claude models; also drives the Claude agent when no Claude Code login is present.

OpenAI

GPT models; drives the Codex agent; also powers dictation.

Google

Gemini models; also powers dictation.

DeepSeek, Kimi, GLM, MiniMax

Chat models through each provider’s own API.

Custom endpoint

Any OpenAI-compatible base URL, with its own key.

The microphone in the chat box turns speech into text with your own OpenAI or Google key: the recording goes to that provider and nowhere else, and the key never leaves the app’s main process. Anthropic has no speech service, so with only a Claude key the microphone is not shown. Press the mic, speak, press it again; when something goes wrong — a rejected key, a rate limit, the provider down — the notice says so in a sentence.

• A model that is not in the current session’s pool cannot answer there. Pick a model the session type can run, or start the matching session type.
• Removing a key in Manage Providers takes its models out of the picker immediately.
• Keys are read by the agent runtime on this machine only.

Ink, Basalt, Tide, Dusk, Fern and Ridge. Press ⌘K ⌘V (or run Vibes: Choose Vibe...) for the picker; ⌃⌘. cycles through them. The status bar shows the current vibe by name.

⌘K ⌘G (or Primal Code: Browse Themes) opens every colour theme the window has as a searchable grid. Arrow keys preview a theme live; Esc puts back the one you had. Each card carries a readability verdict computed on the spot, written as a word and a glyph.

• Paste a base16 or base24 palette, or a colour-theme JSON, to import it. Nothing is fetched from the network.
• Themes named “(unreviewed)” were generated by the theme engine and pass every automated gate, but have not yet been signed off by a person.

Text contrast

WCAG contrast on every text surface.

Terminal colours

A minimum distance between every pair of the sixteen ANSI colours.

Semantic colours

Error, warning, added and deleted are placed on a lightness ladder, so they stay apart under protanopia, deuteranopia and tritanopia.

Distinct families

Two themes that differ only in a hue some readers cannot see are refused.

The globe is on by default. To change it, run Motif: Choose Motif... from the command palette (arrow keys preview, Escape puts back what was there); the setting behind it is primalCode.motif.id, with static for no motion at all. It shows large on Primal Start and on the Agents window’s landing, and as a quiet strip behind the editor. The four film shots are drawn on the GPU and need WebGL2; without it they stay off and the ground keeps its static wash.

settle (default)

Moves for a few seconds after a theme change, the window taking focus or a project opening, then eases to rest.

perpetual

Keeps moving while the window is focused. Costs battery and GPU; a pause control appears. This is the default on the two stages — the Start page and the Agents window’s landing — where the motif is the picture rather than the ground.

off

Never moves; the ground keeps its static wash.

The setting is primalCode.motif.motion. On battery, motion stays off unless primalCode.motif.perpetualOnBattery allows it, at a lower frame rate.

• The window is not focused.
• The machine is on battery and battery motion is not allowed.
• The system reports heat or processor throttling.
• You are typing; motion resumes a moment after you stop.
• Reduced motion is on in the operating system; the motif stays on a single frame.

The status bar item Motif Motion says whether the motif is moving or parked, and its hover says why. Motif: Pause or Resume Motion and Motif: Play Motion are in the command palette.

Choose a project and an agent (Claude or Codex), type the task and send. Before sending you can set how the agent asks for permission, whether it works in a fresh git worktree, and which branch it starts from.

Ask Before Edits / Bypass Permissions

Whether the agent stops to ask before changing files and running commands. Bypass is faster and riskier; the window says so.

New Worktree

The session works in its own git worktree, so your working tree is untouched until you bring the changes over.

Base branch

The branch the worktree is created from.

The Claude agent runs on the Claude Agent SDK, downloaded on first use; a notification shows the progress and it can take several minutes on a slow connection. Later launches are immediate.

Each row says its state in words first. Beside it sits a small character that nods while the agent works, asks for attention when the session is waiting on you, cheers once when it is done and turns into an exclamation mark when something fails; a dot means there is something you have not read. It rests when the window is in the background and keeps still when reduced motion is on.

• Agents, skills, instructions, hooks, MCP servers and plugins are listed under CUSTOMIZATIONS in the sidebar, with counts.
• They are read from the same places the command-line agents read them, so a setup you already have carries over.

The first launch, and any launch with nothing to reopen, offers three destinations: the IDE, the Agents window and the CLI panel. Press 1, 2 or 3, or click. Every window then has a switcher in its title bar to go to the others. Jarvis is marked as coming soon.

• Add a project folder, then New Pane (Cmd+T on macOS, Ctrl+Shift+T elsewhere) and choose Claude Code, Codex, Gemini CLI or a shell.
• A grid holds up to 16 panes. Drag the dividers, maximise a pane, or pick a layout from the title bar.
• A missing CLI is installed in its pane with its official command, in full view, and signs in there as it would in any terminal.
• Primal looks for a CLI again before each pane starts it. If it cannot check, it says Could not check rather than offering Install; if the check after an install fails, the pane shows the error and a Restart button.
• After a reload the CLIs keep running. After quitting and reopening, each pane comes back and its CLI picks up its conversation where it can, and says whether it did.

Working · 12s

The CLI is on a turn.

Waiting for you

It asks for a permission or an answer. A filled badge and a highlight along the pane's top edge draw attention to it. The title bar counts waiting panes; notifications respect Do Not Disturb.

Done

The turn ended.

Ready · Resumed · New session

At its prompt; after a restart, whether it picked up its conversation.

Every state is a word beside a shape, never a colour alone. Crew characters give each agent an identity and a pose that follows its state. Reduced motion keeps them calm. The attention queue brings panes needing a response together; Do Not Disturb lets you pause interruptions.

An agent pane can work in its own git worktree, on a branch you name, so agents working side by side never write over each other. The Changes tab shows what the focused pane changed and the diff of each file, then commits, brings the work back to the branch it came from, or removes the worktree after saying what would be lost.

Each project has a board: To do, In progress, Review and Done. Drag a card onto an agent's pane, or use Send to, and Primal pastes it into that CLI and submits it; the card moves to Review when the agent finishes its turn.

Primal Code: Report a Problem in the Help menu builds the report for you — version, system, the active theme, vibe and motif, the names of configured providers, and the log tail with your home directory folded to “~” and anything that looks like a credential replaced by “[redacted]” — and opens the issue form with it filled in. If the report is too long for a link, it is copied to the clipboard and the issue form asks you to paste it. Primal Code: Copy Problem Report puts the same text on the clipboard.

Open a new issue and include:

• The version and commit from Primal Code › About.
• Your operating system and whether it is Apple silicon or Windows x64.
• What you did, what you expected, what happened instead.
• The last lines of the log: run “Developer: Open Logs Folder” from the command palette and copy the end of main.log. Read it before pasting; remove any path or value you would not want public.

When a new release is published, the app shows a notification with the release name and a download link for your platform. The check compares the build you are running against the published one, so a notice only appears when the published build is newer than yours. It checks shortly after launch, every few hours after that, and again whenever a window regains focus if the last check is more than twenty minutes old — so a release published while you were away is offered within minutes.

• The release page carries the installers and the notes: this build, all builds.
• To turn the check off, set primalCode.update.mode in Settings.

• macOS: quit Primal Code, open the new .dmg and drag the app to Applications, replacing the old one. Your settings, keys and sessions are stored outside the app and carry over.
• Windows: run the new installer; it replaces the previous version in place.
• Linux: install the new .deb or .rpm the same way as the first time; it replaces the previous version. The notice’s download link is the .deb; the release page has the .rpm and .tar.gz.