Install Prime Agent by Prime Intellect on macOS or Linux

Prime Agent is what happens when a coding assistant refuses to treat every terminal session like a first date. It keeps a persistent Python control environment, can hand work to recursive subagents, and can continue running after you close the terminal interface. That makes it interesting for repository audits and long jobs, but it also makes the safety setup more important than the flashy bits.

This guide shows you how to install Prime Agent on macOS or Linux, connect a supported model provider, run a first low-risk task, inspect its work, and recover when the setup misbehaves.

My take: persistent sessions are the reason to try Prime Agent. I would leave /refine alone until installation, login, project instructions, and diff review are all working predictably.

Version and privacy note: This guide was checked against Prime Agent v0.7.2, released 11 August 2026. That release enables pseudonymous usage analytics by default. Prime Intellect says these events can include the app version, operating-system category, run outcomes, latency, token and tool counts, retries and compactions, but not prompts, responses, command text, files, paths, repository details, credentials or raw errors. To opt out for a run, start it with PRIME_AGENT_TELEMETRY=0 prime-agent or DO_NOT_TRACK=1 prime-agent. A global opt-out can set telemetry.enabled to false in ~/.prime/agent/settings.json.

Quick answer: the safest first Prime Agent setup

1. Use a macOS or Linux machine and a disposable clone or clean Git worktree.
2. Download and inspect the official stable installer before running it.
3. Start prime-agent from that project directory.
4. Run /login and choose a supported subscription or API-key provider.
5. Begin with a read-only request, then review git status and git diff before accepting edits.

If you only want the official one-line install command, it is:

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

The official installer downloads a versioned release, checks its SHA-256 checksum, installs the prime-agent command, and can prepare the IPython runtime. I still prefer downloading the script first so there is a moment to inspect what will run.

What is Prime Agent?

Prime Agent is an MIT-licensed coding and research agent from Prime Intellect. The official announcement was published on 5 August 2026. It is a harness rather than a new foundation model: you connect it to a supported model provider, and the harness manages the working environment around that model.

Three ideas make it different from a simple chat-in-the-terminal tool:

• A persistent IPython control environment: the model uses a long-lived Python kernel to inspect files, run commands, retain variables, and call installed skills.
• Recursive subagents: the parent can launch independent child agents for parallel or background work, then receive their findings through agent messages.
• Durable sessions and harness state: sessions, goals, schedules, selected memories, and retained subagents can survive beyond one terminal attachment.

Prime Agent earns its keep when work outlives one terminal session or divides cleanly into independent investigations. For a one-file fix, its background services, persistent state, and subagent machinery may be more tool than the job needs.

Those are useful features for long repository audits. They also mean Prime Agent can do real work with your user account’s permissions.

Read this safety warning before installing

For a first session:

• Use a disposable repository clone, a clean worktree, or another checkpoint you can restore.
• Keep production credentials, browser sessions, private keys, and customer data out of the working directory.
• Do not ask the agent to run an unknown project’s install script until you have reviewed it.
• Use an external VM or container sandbox for genuinely untrusted code or instructions.
• Review every diff before committing or pushing it.

Prime Agent prerequisites

• Operating system: the official stable installer is documented for macOS and Linux.
• Shell and network access: you need a normal terminal and access to the official installer and your chosen provider.
• A model provider: the built-in subscription login supports ChatGPT Plus/Pro through Codex, Claude Pro/Max, and GitHub Copilot. API-key providers include OpenAI, Anthropic, Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, Prime Inference, and others listed in the current provider documentation.
• Git: not strictly required for the program to launch, but strongly recommended so you can inspect and restore code changes.

There is also a source-build route, which currently requires Node.js 22.8.0 or newer. Use that only if you specifically need to inspect or develop the source; the stable binary installer is the shorter beginner route.

Step 1: prepare a safe test project

Do not point a new autonomous coding tool at your production checkout first. Create a small Git repository or use a disposable clone:

mkdir prime-agent-test
cd prime-agent-test
git init
printf '# Prime Agent test project\n' > README.md
git status

If Git asks for your name or email when you later commit, configure those separately. The important thing at this stage is that git status works and the directory contains nothing sensitive.

Step 2: download and inspect the stable installer

Download the official script to a temporary path:

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh \
  -o /tmp/prime-agent-install.sh

less /tmp/prime-agent-install.sh

Check that the script is downloading from Prime Intellect’s expected domains, installing a versioned release, and performing the checksum validation described in the official quickstart. Exit less with q, then run it:

sh /tmp/prime-agent-install.sh

Open a new shell if the installer changes your path. Then confirm that the command is visible and ask Prime Agent to inspect its services:

command -v prime-agent
prime-agent --version
prime-agent doctor

A printed command path confirms the shell can find the installation. prime-agent doctor is the official diagnostic command for the local background services.

Step 3: start Prime Agent inside the project

Prime Agent works from the current directory, so verify that directory before starting:

pwd
git status
prime-agent

That directory becomes the agent’s working area. If pwd shows your home directory or a folder full of unrelated files, stop and move to the intended project first.

Step 4: connect a model provider

Inside Prime Agent, run:

/login

Choose the provider you already use. The official documentation lists subscription logins for:

• ChatGPT Plus or Pro through Codex
• Claude Pro or Max
• GitHub Copilot

There is one billing detail worth noticing: Prime Intellect’s provider documentation says Claude subscription authentication in this third-party harness uses Anthropic’s extra usage and is billed per token rather than against normal plan limits. Check your provider’s current terms before starting a long autonomous job.

If you prefer an API key, set the provider’s environment variable before launch. For example:

export OPENAI_API_KEY='your-key-here'
prime-agent

Do not paste a real key into a public issue, a repository file, a screenshot, or the agent prompt. The interactive /login route can store credentials in ~/.prime/agent/auth.json, which the documentation says is created with user-only read/write permissions.

Step 5: choose a model and run a read-only first task

Use /model to select a model and /effort to choose the reasoning level. Your first request should make the boundary obvious:

Read this repository without modifying files. Summarize its purpose,
identify the documented test command, and list the three highest-risk
areas you would inspect before making a change.

This checks four things at once: provider authentication, model access, file reading, and the IPython control environment. It also gives you a chance to see how the tool reports commands before it is allowed to edit anything.

Step 6: let it make one contained change

When the read-only task looks sensible, give it a small reversible job:

Add a short 'Running checks' section to README.md using only the commands
already present in this repository. Do not install packages or modify any
other file. Show me the diff when finished.

After the agent finishes, inspect the result yourself:

git status --short
git diff -- README.md

If the diff is wrong, edit or discard only the affected file through your normal Git workflow. Avoid treating an agent’s confident summary as proof that the file contents are correct.

Step 7: try recursive subagents without creating chaos

Prime Agent can launch independent child sessions through its built-in recursive language model runtime. You do not need to write the Python call yourself for a normal task; ask for bounded parallel work:

Review this repository using three independent read-only subtasks:
1. authentication and secret handling,
2. test coverage and likely regressions,
3. stale or misleading documentation.

Run them in parallel. Do not modify files. Synthesize the findings with
file paths and evidence after the subagents reply.

The useful word here is independent. Parallel agents are most valuable when each owns a clear question. Sending three agents to “improve everything” produces more overlap than insight.

Step 8: detach, inspect, and continue a session

Prime Agent’s sessions run through background workers. Closing the terminal interface can detach you without necessarily stopping the work. From a normal shell, use:

prime-agent agents
prime-agent status
prime-agent attach <agent>

To continue the most recent saved session:

prime-agent -c

To stop every local agent and background service, use:

prime-agent shutdown

Do not add --force casually. Give workers the normal shutdown path unless you are recovering from a stuck service.

Step 9: give Prime Agent project-specific instructions

Create an AGENTS.md file in the project root for stable rules such as:

# Project instructions

- Run the existing test command after code changes.
- Never run production migrations.
- Do not read files outside this repository.
- Do not install or update dependencies without approval.
- Show a concise summary and the exact files changed.

Prime Agent also recognises CLAUDE.md. Its quickstart says it loads global instructions from ~/.prime/agent/AGENTS.md and project instructions from parent and current directories. Run /reload or restart the session after changing context files.

Useful Prime Agent commands

Common Prime Agent installation problems

prime-agent: command not found

Open a new terminal so the shell reloads its path, then run:

command -v prime-agent

If it still returns nothing, re-read the installer’s final output for the installed location. Re-run the stable installer only after confirming that you downloaded the official script.

The provider login works, but the model is unavailable

Run /model and choose a model enabled for that provider. For GitHub Copilot, the official provider notes say a “model not supported” error may require enabling that model in VS Code’s Copilot Chat model selector first.

The IPython kernel will not start

The kernel is normally prepared on first use. Run:

prime-agent doctor

If you already maintain a Python environment with ipykernel, the quickstart documents the PRIME_AGENT_KERNEL_PYTHON environment variable for selecting it. Do not point that variable at a production environment full of secrets or sensitive tooling.

You closed the terminal and cannot find the task

List sessions and workers before starting a duplicate job:

prime-agent agents
prime-agent list --all

Attach to the existing agent with prime-agent attach <agent>, or use prime-agent -c for the most recent saved session.

The agent edited more files than requested

Interrupt or stop the task, inspect git status --short, and review each diff. This is exactly why the first run belongs in a disposable or clean Git checkout. Restore only the files you have verified through your normal version-control workflow; do not blindly accept a bulk rollback command proposed by the same agent that made the mistake.

Prime Agent gets stuck after an update

Run the official diagnostics first:

prime-agent status
prime-agent doctor

The CLI also documents prime-agent doctor --fix, but inspect the diagnosis before allowing an automated repair. If a normal shutdown is possible, restart the services cleanly rather than forcing them down.

Prime Agent FAQ

Is Prime Agent free?

The Prime Agent software is open source under the MIT licence. The model behind it may require a paid subscription, API key, or usage charges, depending on the provider you choose.

Can I use Prime Agent with ChatGPT Plus?

Yes. The official provider documentation lists ChatGPT Plus and Pro through Codex as a built-in subscription login. Start the program and use /login.

Can Prime Agent use Ollama or LM Studio?

Yes, but not through the normal /login screen. Add the endpoint in models.json using the official custom-model guide. Prime Agent supports Ollama, LM Studio, vLLM, and compatible APIs this way. I would treat that as a second-stage setup after confirming the basic installation with a hosted provider.

Does Prime Agent run on Windows?

The stable quickstart currently documents the installer for macOS and Linux. The project also has Windows notes stating that Prime Agent needs a Bash shell and checks Git Bash, a Bash executable on the path, or a custom shell path. Follow the current official Windows page rather than assuming the macOS/Linux installer command behaves identically in PowerShell.

Is Prime Agent sandboxed?

No. Its workers and kernel improve lifecycle isolation, but the official documentation explicitly says they are not a security sandbox. Use an external restricted environment for untrusted repositories or instructions.

Can Prime Agent keep working after I close the terminal?

Yes. Sessions can remain active in background worker processes. Use prime-agent agents to find them and prime-agent attach <agent> to reconnect.

Should I use /refine immediately?

I would wait. First confirm that ordinary sessions, project instructions, and review habits behave as expected. /refine can make focused changes to supplemental harness state and records snapshots for rollback, but durable changes deserve more scrutiny than a one-off prompt.

Where Prime Agent fits in a practical AI coding stack

Prime Agent is the harness: it manages sessions, a Python control environment, provider calls, and subagents. Other tools solve different layers. If you want to give a local model external tools, see the llama.cpp MCP setup guide. For a Node.js multi-agent application built around GitHub’s SDK, use the GitHub Copilot SDK multi-agent tutorial. If you prefer a smaller coding assistant with a more conventional Git workflow, compare it with the Aider installation guide.

The sensible Prime Agent trial is deliberately boring: a disposable repository, a read-only audit, one contained documentation edit, and a careful diff. If that feels reliable, add subagents and longer jobs one boundary at a time. Persistent agents are useful precisely because they can do more than a chat window; they deserve correspondingly better guardrails.

Primary sources

• Prime Intellect: Prime Agent announcement
• Prime Agent official GitHub repository and MIT licence
• Prime Agent official quickstart
• Prime Agent provider documentation
• Prime Agent usage and CLI reference
• Prime Agent long-running agent documentation
• Prime Agent Windows notes
• Prime Agent v0.7.2 release notes
• Prime Agent pseudonymous usage analytics settings
• Prime Agent custom-model documentation