Prime Agent

1. What is Prime Agent?

Prime Agent is a coding assistant that lives in the terminal. You start it inside a project folder, describe what you want in plain language, and it reads files, runs commands and edits code for you. What sets it apart from similar assistants is its focus on long jobs: sessions keep running in the background after you close the terminal, it can spawn "sub-agents" that work in parallel, and a /refine command lets it store lessons for later sessions.

To be direct: this is a tool for developers and AI researchers. There is no point-and-click interface and no .exe installer. The code is open source under the MIT license and free to download, but to do anything it needs a subscription or an API key from an AI model provider, and that part may cost money depending on the provider you pick.

A good fit if:

• You are comfortable in a terminal on macOS or Linux.
• You have a code project and want to hand an AI long tasks that run for hours.
• You already have a subscription or API key with a model provider.

Not a good fit if:

• You have never programmed and just want a chat app.
• You only have a Windows PC and do not want to set up a Linux environment.
• You need a tool that runs in a safe sandbox. Prime Agent runs commands with your own user permissions.

Note: The official documentation is explicit: Prime Agent executes model-generated Python and project commands with your permissions, and it is not a security sandbox. Use it only on projects you trust and can restore.

2. What you need first

Computer and operating system

The official installer recognises two systems only:

• macOS 13 or newer, on Apple Silicon or Intel.
• 64-bit Linux (x64 or ARM64), including musl-based distributions such as Alpine.

The project's Releases page has no Windows build. On Windows you need a Linux environment on the machine, for example WSL, Microsoft's way of running Linux inside Windows: https://learn.microsoft.com/windows/wsl/install. The project does not document WSL, so treat that route as unconfirmed.

Software

• curl: a command-line download tool. It ships with macOS and nearly every Linux distribution.
• Python and uv: you do not install these yourself. During setup the installer asks whether to prepare the Python runtime; if you agree, it installs uv (a Python manager), Python 3.11 and Prime Agent's runtime.
• Node.js (a JavaScript runtime): only needed if no prebuilt binary matches your machine. In that case the installer falls back to a Node.js install and requires version 20.6.0 or newer. Get it from https://nodejs.org if needed.
• Git (version control): not required to install, but strongly recommended so you can undo whatever the AI changes. Get it from https://git-scm.com.

Accounts

On first launch you run /login and choose a provider: either a subscription or an API key (a secret string used to call an AI model). The provider sets the price. The README lists no pricing, so check your provider's own page.

3. Step-by-step installation

There is one official way to install Prime Agent: a single terminal command. There is no web version and no double-click installer.

Step 1: Run the installer

Open a terminal (on Windows, a WSL window) and paste:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

This downloads the installer from Prime Intellect's site and runs it. The installer detects your operating system and processor and fetches the matching package.

What success looks like: the screen shows "Installing Prime Agent" with download progress.

Step 2: Answer the Python runtime question

Partway through, the installer asks:

Prepare Python runtime now?

It explains that this installs uv, Python 3.11 and the Prime Agent runtime. Press Enter to accept the default (yes). If you decline, the runtime is prepared the first time Prime Agent needs Python, which makes the first session slower.

Step 3: Check the result

When it finishes you will see:

Prime Agent installed
Run it with: prime-agent

The program goes into ~/.local/share/prime-agent and a prime-agent command is created in ~/.local/bin. Close the terminal, open a new one and type:

prime-agent --version

What success looks like: a version number is printed. The latest release when this guide was written is 0.9.8, published on 29 September 2026. If the command is not found, see section 5.

4. First use

Step 1: Create a test folder

Do not start on an important project. The official docs recommend a disposable copy. For example, make an empty folder:

mkdir ~/prime-agent-test
cd ~/prime-agent-test

Prime Agent works in whichever folder you are in and can run commands and change files there.

Step 2: Start it and sign in

prime-agent

A text interface opens in the terminal. Type:

/login

A list of providers appears, with subscription sign-ins and API-key options. Pick the one you have and follow the prompts.

Step 3: Give it a small job

Type a simple request, for example asking it to create a Python file that prints a multiplication table and then run it. You will see it write the code, run it and report the output. Afterwards, open the folder and look at the file it created.

Step 4: Learn the session commands

Because sessions run in the background, these commands are worth knowing. Type them in the terminal, outside the Prime Agent interface:

prime-agent agents
prime-agent attach session-name
prime-agent --resume
prime-agent status
prime-agent shutdown

• agents: browse running, idle and saved sessions.
• attach: reconnect to a running session (replace session-name with the real name).
• --resume: browse and reopen earlier sessions.
• status: inspect the background service.
• shutdown: stop every agent and background service.

Inside the interface there are also commands such as /goal (keep an objective alive across turns), /autonomous (let it continue on its own within turn, token and time limits you set) and /refine (turn the session so far into lessons for next time).

5. Common errors and fixes

Symptom	Cause	Fix
prime-agent gives "command not found"	~/.local/bin is not on your PATH (the list of places the system looks for commands)	Close and reopen the terminal. If it persists, add ~/.local/bin to PATH as the installer suggests
Installer says "Node.js 20.6.0 or newer is required"	No prebuilt binary matched, so it fell back to the Node.js install and Node.js is missing or too old	Let the installer set up Node.js, or install a current version from https://nodejs.org and run it again
"refusing to replace existing command"	A prime-agent command already exists in ~/.local/bin that this installer did not create	Remove or rename the old one, or set PRIME_AGENT_BIN_DIR to another folder and reinstall
"installation is locked"	Another install is running or was interrupted	Make sure no installer is running, then delete the .install-lock file in the install folder as the message says
"Python preparation failed"	Downloading uv or Python failed, usually a network issue	No reinstall needed: Prime Agent retries the first time it uses Python
Sessions hang or the background service stops responding	The background service is in a bad state	Run the check and repair commands below

To inspect and repair the background services:

prime-agent doctor
prime-agent doctor --fix

On Alpine Linux, if the prebuilt binary complains about a missing C++ library, the installer suggests switching to the Node.js build by setting PRIME_AGENT_INSTALL_METHOD=node before running the install command again.

For anything else, the project takes bug reports through Discussions: https://github.com/PrimeIntellect-ai/prime-agent/discussions

6. Uninstalling and updating

Updating

prime-agent update

Add --force to force it. Running the install command from section 3 again also works. If a new version misbehaves, the installer can switch back to the previous one:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- --rollback

Uninstalling

The README does not give an official uninstall command. Based on what the installer creates, you can remove it by hand. First stop everything:

prime-agent shutdown

Then delete the command and the program folder:

rm ~/.local/bin/prime-agent
rm -rf ~/.local/share/prime-agent

Note: Those are the default locations. If you changed them with PRIME_AGENT_INSTALL_DIR or PRIME_AGENT_BIN_DIR during install, delete the folders you chose instead. The README does not say where session data is kept; ask in Discussions if you need a complete wipe.

7. Frequently asked questions

Does it cost money?

Prime Agent itself is free and open source (MIT license). The cost is the AI model: you need a subscription or API key with a provider, and they bill you their own way.

Does it need an internet connection?

Yes, both to install and to reach the model provider you signed in with.

Is my code sent anywhere?

To do its job, Prime Agent sends the content it needs to the model provider you chose in /login. The source code also contains a usage-analytics component; according to that component's documentation it can be switched off with the DO_NOT_TRACK or PRIME_AGENT_TELEMETRY environment variables. See the official repository for details.

Does it run on Windows?

There is no Windows build. The installer accepts macOS and Linux only. The only route is a Linux environment such as WSL, which the project does not document.

If I close the terminal, do I lose the running task?

No. Sessions are kept alive by a background service and continue when the terminal disconnects. Use prime-agent agents to see them and prime-agent attach to reconnect.