Installation

Quick Install

The fastest way to get Primer running is the one-line installer:

curl -fsSL https://useprimer.dev/install.sh | sh

This script detects your OS, installs the primer CLI (via pipx or pip), initializes the database, starts the server, registers your engineer profile, and installs the Claude Code hook — all in one step.

Prerequisites

If you prefer a manual installation, you need:

• Python 3.12+ — Primer uses modern Python syntax.
• An AI coding agent — Claude Code, Gemini CLI, or Codex CLI. Primer captures session data via each agent’s hook system (or primer sync for agents without hooks).

Verify your Python version:

python --version   # Python 3.12.0+

Manual Install

Install from PyPI:

pip install primer

Then initialize and start:

primer init
primer server start

primer init creates the ~/.primer/ directory, generates an admin API key, and runs database migrations. primer server start launches the API server in the background.

Install from Source

For development or contributing:

git clone https://github.com/ccf/primer
cd primer
pip install -e ".[dev]"

The [dev] extra includes testing tools (pytest, coverage), linting (ruff, bandit), and other development dependencies.

Set Up Your Engineer Profile

primer setup

This reads your name and email from git config automatically. If they aren’t set, it prompts you. You can also pass them directly:

primer setup --name "Jane Doe" --email jane@example.com

On completion, it creates your engineer account on the server and saves your API key to ~/.primer/config.toml.

Install the Hook

Primer captures session data via hooks that fire when an AI coding session ends. Install the hook for your agent:

Claude Code (default)

primer hook install

This adds a SessionEnd entry to ~/.claude/settings.json that triggers the Primer ingest process when a Claude Code session ends.

Gemini CLI

primer hook install --agent gemini

This adds an exit hook to ~/.gemini/settings.json using Gemini’s matcher-wrapped hook format.

Codex CLI

Codex CLI doesn’t have a SessionEnd hook. Use primer sync to upload sessions:

primer sync                        # One-time sync
primer sync --watch --interval 60  # Continuous watch mode

Verify Installation

Check hook status for a specific agent or all agents at once:

primer hook status                # Claude (default)
primer hook status --agent gemini # Gemini
primer hook list                  # All agents

After your next session ends, the transcript, tool usage, model usage, and other session metadata will be uploaded automatically.

Docker

For team or production deployments, Primer ships with Docker Compose and Helm charts. See the Deployment guide for Docker Compose quick start, Kubernetes setup, and production hardening advice.

Seed Sample Data (Optional)

To explore the dashboard with realistic data before your team starts using Primer:

python scripts/seed_data.py

This creates:

• 3 teams with different configurations.
• 8 engineers with varied usage personas (heavy users, occasional users, new adopters).
• ~90 days of session history including transcripts, tool usage breakdowns, model usage, friction events, and git commit metadata.

Enable MCP Sidecar (Optional)

The MCP sidecar gives Claude direct access to your team’s usage data during coding sessions. Engineers can ask Claude questions like “how’s my team doing this week?” without leaving their editor.

See the MCP Sidecar guide for setup instructions.

Connect GitHub (Optional)

Link Claude Code sessions to pull requests for AI contribution tracking and readiness scoring.

See the GitHub Integration guide for setup steps.

Next Steps

• Configuration — Customize the server, database, authentication, and integrations.
• CLI Reference — Full reference for all primer commands.
• Team Setup — Register engineers, create teams, and assign roles.
• Deployment — Docker Compose, Kubernetes, and production hardening.