# Quickstart

> Start prime-agent in a project directory, complete onboarding, run a first task, and verify interactive session health.

- Repository: PrimeIntellect-ai/prime-agent
- GitHub: https://github.com/PrimeIntellect-ai/prime-agent
- Human docs: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1
- Complete Markdown: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1/llms-full.txt

## Source Files

- `README.md`
- `packages/coding-agent/README.md`
- `packages/coding-agent/src/core/agent-session.ts`
- `packages/coding-agent/test/suite/regressions/4658-onboarding-transitions.test.ts`
- `packages/coding-agent/examples/sdk/01-minimal.ts`

---

---
title: "Quickstart"
description: "Start prime-agent in a project directory, complete onboarding, run a first task, and verify interactive session health."
---

`prime-agent` is the interactive CLI entrypoint for Prime Agent. Launched from a project directory, it opens a new interactive session against that working directory, loads credentials and models from `~/.prime/agent/`, and gives the model a single built-in tool: the persistent `ipython` kernel. First launch runs onboarding when no ready model is configured; sessions auto-save under `~/.prime/agent/sessions/` and run as daemon-backed workers so detaching the TUI does not necessarily stop the agent.

<Warning>
Prime Agent executes model-generated Python and project commands with your user permissions. Worker and kernel processes improve lifecycle isolation and recovery; they are **not** a security sandbox. Use trusted repositories, instructions, skills, and extensions only. Prefer a disposable clone or clean worktree for first runs.
</Warning>

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Platform | macOS or Linux for the stable installer path |
| Binary | `prime-agent` on `PATH` (installer), or a source checkout with `./prime-agent.sh` |
| Auth | At least one subscription OAuth login via `/login`, or an API key via env/`auth.json` |
| Project cwd | The directory you want the agent to read and modify |
| Python kernel (optional override) | Auto-bootstrapped on first `ipython` use; set `PRIME_AGENT_KERNEL_PYTHON` to a Python that already has `ipykernel` |

Install is covered in [Installation](/installation). This page assumes you can run `prime-agent` (or the source launcher) from a shell.

## Start path

```text
project cwd
    │
    ▼
prime-agent  ──► interactive TUI + session worker
    │
    ├─ no ready model / first launch ──► onboarding (auth + model)
    │
    └─ model ready ──► editor prompt
                           │
                           ▼
                    user message → provider → ipython tool calls
                           │
                           ▼
              ~/.prime/agent/sessions/*.jsonl  +  optional daemon worker
```

## First session

<Steps>
<Step title="Install or confirm the binary">
Stable release:

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

Beta built from `main`:

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

From a source checkout (Node.js 22.8.0+):

```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci
./prime-agent.sh
```

`./prime-agent.sh` preserves the directory from which it is invoked, so you can call the absolute path from another project. Use `./prime-agent.sh --dist` after a build to run the bundled CLI.

Verify:

```bash
prime-agent --version
prime-agent --help
```

Success: version prints; help shows usage for `prime-agent [options] [@files...] [message...]` and top-level commands such as `agents`, `attach`, `status`, and `doctor`.
</Step>

<Step title="Enter the project directory and launch">
```bash
cd /path/to/project
prime-agent
```

Defaults that matter on cold start:

| Behavior | Default |
|----------|---------|
| Client mode | Interactive when stdin is a TTY and `--print` is not set |
| Working directory | Process cwd (or `--cwd <dir>`) |
| Session persistence | On (JSONL under `~/.prime/agent/sessions/`); use `--no-session` for ephemeral |
| Startup surface | New chat (not the agents browser); use `prime-agent agents` or left-arrow for session catalog |
| Built-in tool | `ipython` only |

Optional launch shapes:

```bash
prime-agent --provider anthropic --model claude-opus-4-5
prime-agent @README.md "Summarize this repository"
prime-agent -p "List the top-level layout and how to run checks"
```
</Step>

<Step title="Complete onboarding">
On first interactive launch, onboarding runs when global settings do not yet mark onboarding as shown **and** there is no ready model with configured auth. Completing or dismissing onboarding sets `onboardingShown` in `~/.prime/agent/settings.json` so the flow does not reopen on every start.

What you will see:

1. **Splash** (when no models are available, or when continuing from Prime CLI auth) with progress such as `Signing in to Prime Intellect...` and `Preparing models...`
2. **Auth** via Prime Inference login when no candidates exist, or the configuration menu when models are already discoverable
3. **Model selection** (`models` tab of the configuration menu); the splash stays mounted until that menu closes

If a model is already selected and authenticated (for example after exporting an API key), onboarding is skipped.

You can always re-auth later with `/login` and pick models with `/model` (or Ctrl+L).
</Step>

<Step title="Authenticate if needed">
Use one path. Credentials are provider-neutral: subscription OAuth or your own API keys (BYOK).

<Tabs>
<Tab title="Subscription / OAuth">
In the interactive editor:

```text
/login
```

Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot. Tokens land in `~/.prime/agent/auth.json` with auto-refresh.
</Tab>

<Tab title="API key (environment)">
```bash
export ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY, PRIME_API_KEY, GEMINI_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, ...
prime-agent
```

Env var names are provider-specific; full tables live under authentication and providers docs.
</Tab>

<Tab title="API key (auth file)">
Store keys in `~/.prime/agent/auth.json` (created mode `0600`). Auth-file credentials take priority over environment variables.

```json
{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "prime-inference": { "type": "api_key", "key": "..." }
}
```

You can also run `/login`, choose an API-key provider, and paste a key so it is written for you.
</Tab>
</Tabs>

If no models resolve, the CLI surfaces:

```text
No models available. Use /login to log into a provider via OAuth or API key.
```

For a selected model without credentials:

```text
No API key found for <provider>.
```

Recover with `/login`, then `/model` if needed.
</Step>

<Step title="Run a first task">
In the editor, type a request and press Enter:

```text
Summarize this repository and tell me how to run its checks.
```

Expected runtime behavior:

- The assistant streams a response in the messages pane.
- Tool use appears as `ipython` cells (Python control plane: files, shell magics, skills, subagents).
- The long-lived kernel bootstraps on first tool use; override Python with `PRIME_AGENT_KERNEL_PYTHON` or a managed venv via `PRIME_AGENT_KERNEL_VENV` when you need a fixed environment.
- Session transcript appends under `~/.prime/agent/sessions/`.

Useful first prompts:

```text
Review authentication and test coverage as independent subtasks. Run them in parallel, then synthesize the findings.
```

```text
!npm run check
```

Notes:

- `@` fuzzy-searches project files; `@path` can also be passed on the CLI.
- `!command` runs a shell command and sends output to the model; `!!command` runs without adding output to context.
- During agent work, project commands usually run inside the IPython control environment (for example a `%%bash` cell), not as separate built-in tools.
- Multi-line input: Shift+Enter (Ctrl+Enter on Windows Terminal).
</Step>

<Step title="Verify interactive session health">
Confirm the session is usable with these signals:

| Check | How | Healthy signal |
|-------|-----|----------------|
| UI ready | After onboarding | Startup header + empty editor; no hard auth error banner |
| Model bound | `/session` or footer via `/usage` | Model/provider present; `/usage` shows context/token fields |
| Auth valid | Send a short prompt | Streaming text or tool cells; not `401` / “Authentication failed” |
| Session file | `/session` | Session ID and path under `~/.prime/agent/sessions/` |
| Background service | `prime-agent status` | Supervisor/worker status reports without fatal socket errors |
| Detach safety | Close TUI, then reattach | Worker still listed; `prime-agent attach <agent>` restores the UI |
| Diagnostics | `prime-agent doctor` | Clean report, or `--fix` clears stale sockets/orphans |

```bash
prime-agent status
prime-agent list
prime-agent doctor
prime-agent agents
prime-agent attach <agent>
```

Continue or resume later:

```bash
prime-agent -c                  # most recent session
prime-agent -r <path|id>        # resume a saved session
prime-agent --resume <path|id>  # same selector form
```

Inside the TUI: `/resume`, `/new`, `/tree`, `/fork`, `/clone`, `/reload`.
</Step>
</Steps>

## Interactive surface

From top to bottom:

| Region | Role |
|--------|------|
| Startup header | Brand + runtime summary; `--verbose` lists loaded `AGENTS.md`, prompts, skills, extensions |
| Messages | User text, assistant output, `ipython` tool calls/results, notifications, errors |
| Editor | Prompts, `/` commands, `@` files, `!` shell |
| Footer | Empty by default; `/usage` for tokens, cost, context |

While the agent is working:

| Input | Effect |
|-------|--------|
| Enter | Queue a *steering* message (after current tool batch) |
| Alt+Enter | Queue a *follow-up* (after the agent finishes all work) |
| Ctrl+C | Interrupt; twice exits while the exit hint is visible |
| Escape | Clear input without interrupting |

## Project instructions

Prime Agent loads context files at startup:

| Location | Scope |
|----------|-------|
| `~/.prime/agent/AGENTS.md` | Global |
| `AGENTS.md` or `CLAUDE.md` walking from parents into cwd | Project and ancestors |

Example `AGENTS.md`:

```markdown
# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.
```

System prompt overrides (optional):

| File | Effect |
|------|--------|
| `.prime/agent/SYSTEM.md` or `~/.prime/agent/SYSTEM.md` | Replace default system prompt |
| `APPEND_SYSTEM.md` in either location | Append without replacing |

After edits, restart or run `/reload`. Disable discovery with `--no-context-files` / `-nc`.

## Config and state paths

Default agent directory: `~/.prime/agent/` (override with `PRIME_AGENT_CODING_AGENT_DIR` when the package is configured as `prime-agent`).

| Path | Purpose |
|------|---------|
| `auth.json` | OAuth tokens and API keys |
| `settings.json` | Defaults, including `onboardingShown` |
| `sessions/` | JSONL session transcripts |
| `logs/` | Client, daemon, and agent diagnostics |
| `models.json` | Custom models / providers |

## Non-interactive and SDK smoke tests

One-shot print mode (also merges piped stdin into the prompt):

```bash
prime-agent -p "Summarize this codebase"
cat README.md | prime-agent -p "Summarize this text"
```

Headless event modes: `--mode json`, `--mode rpc`. Editor integrations: `--mode acp` (see ACP docs).

Minimal programmatic session (package identifiers in source retain the `@earendil-works/pi-coding-agent` name):

```typescript
import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("What files are in the current directory?");
```

`createAgentSession()` discovers skills, extensions, tools, and context from cwd and the agent dir; model comes from settings or the first available authenticated model.

## Common failure signals

| Symptom | Likely cause | Recovery |
|---------|--------------|----------|
| `No models available` | No OAuth/API key configured | `/login` or export provider env var; see [Authentication and providers](/authentication-providers) |
| `No API key found for <provider>` | Model selected without credentials | `/login` or set the provider env key / `auth.json` entry |
| `Authentication failed for "..."` | Expired token, bad key, or network | `/login`; message guidance includes `Run /login to update credentials.` |
| Onboarding never returns | Auth cancelled mid-flow | Exit and relaunch; use `/login` then `/model` |
| Kernel bootstrap errors | Missing Python/`ipykernel` | Set `PRIME_AGENT_KERNEL_PYTHON` to a working interpreter with `ipykernel` |
| `session_already_active` / lease errors | Another worker owns the session | `prime-agent list`, attach the active agent, or stop the conflicting worker |
| Stale sockets / orphaned services | Unclean shutdown | `prime-agent doctor --fix`; escalate with `prime-agent shutdown` if needed |
| Detach loses the UI but work continues | Expected resident worker behavior | `prime-agent agents` / `attach <agent>` rather than starting a duplicate session |

## Useful commands after first success

```bash
prime-agent agents                   # Browse running, idle, and saved sessions
prime-agent attach <agent>           # Reattach interactive UI
prime-agent --resume <path|id>       # Resume a saved session
prime-agent status                   # Background service state
prime-agent doctor [--fix]           # Inspect or repair services
prime-agent update [--force]         # Update the installed binary
prime-agent shutdown [--force]       # Stop agents, workers, and supervisor
```

In-session commands worth knowing early: `/model`, `/effort`, `/settings`, `/usage`, `/session`, `/compact`, `/refine`, `/goal`, `/hotkeys`, `/quit`.

## Next

<CardGroup>
<Card title="Authentication and providers" href="/authentication-providers">
Login, API keys, multi-provider selection, and auth recovery.
</Card>
<Card title="RLM control plane" href="/rlm-control-plane">
Persistent IPython as the control tool, prompt-as-variable context, and `rlm(...)` subagents.
</Card>
<Card title="Sessions and runtime" href="/sessions-runtime">
Session lifecycle, queueing, tree navigation, and durable vs session-scoped state.
</Card>
<Card title="Run daemon-backed sessions" href="/daemon-sessions">
Detach, reattach, resume selectors, and worker recovery.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Auth failures, resume selectors, provider 401s, and connection probes.
</Card>
<Card title="Minimal SDK agent" href="/sdk-minimal">
Copy-paste SDK bootstrap and first-run output.
</Card>
</CardGroup>