--- title: "Quickstart and Usage" type: concept tags: [overview, platform, foundational, well-established, user] created: 2026-08-06 updated: 2026-08-06 sources: ["raw/github_doc-packages-coding-agent-docs-quickstart-md.md", "raw/github_doc-packages-coding-agent-docs-usage-md.md", "raw/github_doc-packages-coding-agent-docs-terminal-setup-md.md"] confidence: high prime_agent_version: "v0.7.0" --- ## Definition Quickstart and Usage cover the path from installing Prime Agent to a working first session, plus the recurring day-to-day interaction loop: the terminal UI, its editor and slash commands, session management, and the `prime-agent` CLI (flags, modes, and environment variables). ## How It Works ### Install ```bash curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh ``` For the latest beta built from `main`: ```bash curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- beta ``` "Both commands fetch versioned Prime Agent release artifacts and install the `prime-agent` command. The inherited npm workspace identifiers in the source tree are not the public install path." To run from a source checkout (requires Node.js 22.8.0 or newer): ```bash git clone https://github.com/PrimeIntellect-ai/prime-agent cd prime-agent npm ci ./prime-agent.sh ``` Then start it in the target project directory: ```bash cd /path/to/project prime-agent ``` ### Authenticate Two paths, both reachable via `/login`: - **Subscription login** — run `/login` inside Prime Agent and pick a provider. "Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot." - **API key** — set an environment variable before launch, e.g. `export ANTHROPIC_API_KEY=sk-ant-...`, or run `/login` and choose an API-key provider to store the key in `~/.prime/agent/auth.json`. ### First Session and the IPython Loop "Prime Agent gives the model one built-in tool, `ipython`. The long-lived kernel is a control environment for reading and editing files, running project commands, inspecting data, retaining Python state, and invoking installed skills." The kernel bootstraps automatically on first use; set `PRIME_AGENT_KERNEL_PYTHON` to reuse an existing Python environment with `ipykernel`. Recursive subagents are reachable directly from a prompt, e.g.: "Review authentication and test coverage as independent subtasks. Run them in parallel, then synthesize the findings." See [[concepts/rlm]] for the mechanics of `rlm(...)`. ### Project Instructions Prime Agent loads context files at startup: `~/.prime/agent/AGENTS.md` for global instructions, and `AGENTS.md` or `CLAUDE.md` walking up from parent directories to the current directory. Restart Prime Agent, or run `/reload`, after changing context files. ### Interactive Mode The interface has four areas: **Startup header** (compact brand/runtime summary; `--verbose` lists loaded context files, prompt templates, skills, extensions), **Messages**, **Editor**, and **Footer** (empty by default; `/usage` shows token/cost/context details). | Feature | How | |---------|-----| | File reference | Type `@` to fuzzy-search project files | | Path completion | Tab | | Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal | | Images | Paste with Ctrl+V (Alt+V on Windows), or drag into the terminal | | Shell command | `!command` runs and sends output to the model | | Hidden shell command | `!!command` runs without sending output to the model | | External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` | ### Slash Commands (selected) `/login`, `/logout`, `/model`, `/effort`, `/scoped-models`, `/settings`, `/resume`, `/new`, `/name `, `/session`, `/traces [...]`, `/usage`, `/context`, `/tree`, `/fork`, `/clone`, `/compact [prompt]`, `/refine [instructions]`, `/copy`, `/btw `, `/side `, `/export [file]`, `/share`, `/reload`, `/hotkeys`, `/changelog`, `/quit`. ### Message Queue - **Enter** queues a steering message, delivered after the current assistant turn finishes its tool calls. - **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work. - **Ctrl+C** interrupts; pressing it again while the exit hint is visible exits. - **Escape** clears the input bar without interrupting the agent. - **Alt+Up** retrieves queued messages back to the editor. ### Sessions and Non-Interactive Modes ```bash prime-agent -c # Continue the most recent session prime-agent -r [path|id] # Browse sessions or open a specific session prime-agent --no-session # Ephemeral mode; do not save prime-agent --fork # Fork a session into a new session file ``` Inside Prime Agent: `/resume`, `/new`, `/tree`, `/fork`, `/clone`. Sessions run in worker processes, so closing the TUI detaches rather than stops the agent; use `prime-agent agents` to inspect or reattach. For one-shot prompts: ```bash prime-agent -p "Summarize this codebase" cat README.md | prime-agent -p "Summarize this text" prime-agent -p @screenshot.png "What's in this image?" ``` `--mode json` gives JSON event output; `--mode rpc` gives stdin/stdout process integration. ### CLI Reference (usage.md) ```bash prime-agent agents prime-agent list [--all] prime-agent attach prime-agent stop prime-agent rename prime-agent send prime-agent schedule prime-agent status prime-agent doctor [--fix] prime-agent shutdown [--force] prime-agent package install [--local] prime-agent package remove [--local] prime-agent package list prime-agent package update [source] prime-agent update [--force] prime-agent config ``` Built-in tools: `ipython` (the only one). Model options include `--provider`, `--model`, `--api-key`, `--thinking `, `--models `. ## Key Parameters - Autonomous defaults (usage.md): `--autonomous-gate-retries` 3, `--autonomous-gate-timeout-ms` 300000 (5 min), `--autonomous-max-continuations` 3, `--autonomous-max-turns` 12, `--autonomous-max-tokens` 80000, `--autonomous-timeout-ms` 1800000 (30 min). See [[concepts/long-running-agents]] for the full autonomous-mode discussion. - Environment variables of note: `PRIME_AGENT_CODING_AGENT_DIR` (default `~/.prime/agent`), `PRIME_AGENT_SESSION_DIR`, `PI_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PRIME_AGENT_DOWNLOAD_BASE_URL`, `PI_CACHE_RETENTION`, `PRIME_API_KEY`, `PRIME_AGENT_KERNEL_PYTHON`, `VISUAL`/`EDITOR`. - Resource discovery flags: `--extension`, `--skill`, `--prompt-template`, `--theme`, and their `--no-*` counterparts, plus `--no-context-files` / `-nc`. - Terminal requirement: Prime Agent "uses the Kitty keyboard protocol for reliable modifier key detection." Kitty and iTerm2 work out of the box; Ghostty, WezTerm, VS Code's integrated terminal, and Windows Terminal need explicit config (see terminal-setup.md) to forward `Shift+Enter`/`Alt+Enter` correctly. ## When To Use - First-time install/auth and running a first prompt in a project directory. - Day-to-day interactive coding sessions using `@file` references, `!shell` commands, and slash commands. - Scripting or CI integration via `-p` (print mode), `--mode json`, or `--mode rpc`. - Fixing terminal-specific key handling (e.g., Windows Terminal's default `Alt+Enter` fullscreen binding, or Ghostty/tmux `Shift+Enter` conflicts) before relying on message-queue shortcuts. ## Risks & Pitfalls - Prime Agent "runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback." - Some terminals cannot distinguish modified Enter keys at all: "xfce4-terminal, terminator... have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`," breaking custom keybindings such as `submit: ["ctrl+enter"]`. IntelliJ IDEA's integrated terminal has the same limitation for `Shift+Enter`. - On Windows Terminal, `Alt+Enter` is bound to fullscreen by default, which silently prevents Prime Agent from receiving the follow-up-queue shortcut until remapped. - An old Ghostty `shift+enter=text:\n` mapping (added for older Claude Code versions) sends a raw linefeed indistinguishable from `Ctrl+J`, so "tmux and Prime Agent no longer see a real `shift+enter` key event" — remove it unless you still need it for Claude Code in tmux. - Source checkouts require Node.js 22.8.0+; older Node is not supported for `npm ci` / `./prime-agent.sh`. ## Related Concepts - [[concepts/prime-agent-overview]] — what Prime Agent is and its place in the Prime Intellect ecosystem. - [[concepts/rlm]] — the `rlm(...)` subagent call introduced during quickstart. - [[concepts/long-running-agents]] — session continuation, autonomous mode, and scheduling referenced from the CLI reference. - [[concepts/architecture]] — how the CLI/TUI client relates to the daemon-backed worker. ## Sources - raw/github_doc-packages-coding-agent-docs-quickstart-md.md - raw/github_doc-packages-coding-agent-docs-usage-md.md - raw/github_doc-packages-coding-agent-docs-terminal-setup-md.md