/agent-brain-install

name: agent-brain-install
description: Install Agent Brain packages using pipx, uv, pip, or conda
parameters: []
context: fork
agent: setup-assistant
skills:
  - configuring-agent-brain
last_validated: 2026-03-16

Install Agent Brain Packages

STOP - READ THIS FIRST

**DO NOT RUN ANY INSTALLATION COMMANDS YET.**

You MUST ask the user which installation method they prefer using the AskUserQuestion tool BEFORE doing anything else.

Step 1: Ask User for Installation Method

**THIS IS MANDATORY. DO NOT SKIP THIS STEP.**

Use the AskUserQuestion tool with this exact structure:

{
  "questions": [{
    "question": "Which installation method do you prefer for Agent Brain?",
    "header": "Install via",
    "options": [
      {
        "label": "pipx (Recommended)",
        "description": "Install globally in an isolated environment. No activation needed."
      },
      {
        "label": "uv",
        "description": "Fast, modern Python tool installer. Good for power users."
      },
      {
        "label": "pip (venv)",
        "description": "Install into a local virtual environment. Requires activation."
      },
      {
        "label": "conda",
        "description": "For conda users. Creates a conda environment with pip inside."
      }
    ],
    "multiSelect": false
  }]
}

**STOP HERE AND WAIT FOR THE USER'S RESPONSE.**

Do not proceed until you have called AskUserQuestion and received the user's selection.

---

Step 1.5: Resolve Version

After receiving the user's installation method choice, resolve the latest version from PyPI:

# Resolve helper script path (installed plugin or local repo)
PYPI_VERSION_SCRIPT=$(find ~/.claude/plugins/agent-brain/scripts ~/.claude/skills/agent-brain/scripts agent-brain-plugin/scripts -name "ab-pypi-version.sh" 2>/dev/null | head -1)

if [ -n "$PYPI_VERSION_SCRIPT" ]; then
  VERSION=$("$PYPI_VERSION_SCRIPT")
  echo "Latest available: $VERSION"
else
  echo "ab-pypi-version.sh not found — falling back to inline version lookup"
  VERSION=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
  echo "Latest available: $VERSION"
fi

Then ask user for version preference using AskUserQuestion:

{
  "questions": [{
    "question": "Which version of Agent Brain do you want to install?",
    "header": "Version",
    "options": [
      {
        "label": "Latest ($VERSION) (Recommended)",
        "description": "Install the latest stable release from PyPI."
      },
      {
        "label": "Specific version",
        "description": "I'll show available versions and ask which one."
      }
    ],
    "multiSelect": false
  }]
}

If user selects "Specific version", show available versions:

curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "
import sys,json
releases = list(json.load(sys.stdin)['releases'].keys())
releases.sort(key=lambda v: [int(x) for x in v.split('.')], reverse=True)
print('Available versions:', ', '.join(releases[:8]))
"

Then ask the user to enter the specific version they want and store it in `$VERSION`.

---

Step 2: Check Python Version

Only after receiving the user's installation method choice:

python --version

Requires Python 3.10+. If lower, tell user to upgrade first.

---

Step 3: Execute Based on User's Selection

If user selected "pipx (Recommended)"

1. Check/install pipx:

   pipx --version 2>/dev/null || python -m pip install --user pipx && python -m pipx ensurepath

2. Install Agent Brain with pinned version:

   pipx install agent-brain-cli==$VERSION

3. Verify (user may need to restart terminal):

   agent-brain --version

If user selected "uv"

1. Check/install uv:

   UV_CHECK_SCRIPT=$(find ~/.claude/plugins/agent-brain/scripts ~/.claude/skills/agent-brain/scripts agent-brain-plugin/scripts -name "ab-uv-check.sh" 2>/dev/null | head -1)

   if [ -n "$UV_CHECK_SCRIPT" ]; then
     UV_CHECK_OUTPUT=$("$UV_CHECK_SCRIPT")
     echo "$UV_CHECK_OUTPUT"
     if ! echo "$UV_CHECK_OUTPUT" | grep -q "available"; then
       curl -LsSf https://astral.sh/uv/install.sh | sh
     fi
   else
     uv --version 2>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
   fi

2. Install Agent Brain with pinned version:

   uv tool install agent-brain-cli==$VERSION

3. Verify:

   agent-brain --version

If user selected "pip (venv)"

1. Create virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # macOS/Linux

2. Install packages with pinned version:

   pip install agent-brain-rag==$VERSION agent-brain-cli==$VERSION

3. Verify:

   agent-brain --version

4. **Tell user:** Must run `source .venv/bin/activate` before using agent-brain.

If user selected "conda"

1. Create conda environment:

   conda create -n agent-brain python=3.12 -y
   conda activate agent-brain

2. Install packages with pinned version:

   pip install agent-brain-rag==$VERSION agent-brain-cli==$VERSION

3. Verify:

   agent-brain --version

4. **Tell user:** Must run `conda activate agent-brain` before using agent-brain.

---

Success Output

After successful installation, show:

Agent Brain Installation Complete
=================================

Install Method: [method user selected]
Installed Version: $VERSION
Resolved from: PyPI (latest) or (user-specified)

Next steps:
  1. Configure: /agent-brain:agent-brain-config
  2. Initialize: /agent-brain:agent-brain-init
  3. Start server: /agent-brain:agent-brain-start

---

Why Ask First?

Different methods have different trade-offs:

| Method | Global? | Isolated? | Needs Activation? | |--------|---------|-----------|-------------------| | pipx | Yes | Yes | No | | uv | Yes | Yes | No |