wikis / Prime Agent / wiki / concepts / quickstart-and-usage.md view as markdown report a mistake

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

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

For the latest beta built from main:

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):

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:

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 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).

Slash Commands (selected)

/login, /logout, /model, /effort, /scoped-models, /settings, /resume, /new, /name <name>, /session, /traces [...], /usage, /context, /tree, /fork, /clone, /compact [prompt], /refine [instructions], /copy, /btw <question>, /side <question>, /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

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 <path|id>    # 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:

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)

prime-agent agents
prime-agent list [--all]
prime-agent attach <agent>
prime-agent stop <agent>
prime-agent rename <agent> <name>
prime-agent send <agent> <message>
prime-agent schedule <list|add|cancel>
prime-agent status
prime-agent doctor [--fix]
prime-agent shutdown [--force]

prime-agent package install <source> [--local]
prime-agent package remove <source> [--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 <off|minimal|low|medium|high|xhigh|max>, --models <patterns>.

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 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

• prime agent overview — what Prime Agent is and its place in the Prime Intellect ecosystem.
• rlm — the rlm(...) subagent call introduced during quickstart.
• long running agents — session continuation, autonomous mode, and scheduling referenced from the CLI reference.
• 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