📋How-To Guide

Claude Code (Terminal) Integration

Configure prAxIs OS to work with Claude Code CLI as your primary AI agent.

Note: Claude Code also supports VS Code integration. See Claude Code in VS Code if you prefer editor integration.

Prerequisites

✅ Mechanical installation complete (via install-praxis-os.py)
✅ Claude Code installed (npm install -g @anthropic-ai/claude-code or similar)
✅ Anthropic API key configured
✅ .praxis-os/ directory exists in your project

Overview

Claude Code CLI is a standalone terminal-based AI coding assistant. As the primary agent, it will:

Control the MCP server lifecycle
Have full access to all prAxIs OS tools
Manage RAG index and workflows

You need:

.cursorrules file (behavioral triggers)
Claude Code MCP configuration
Start Claude Code in your project directory

Step 1: Install Claude Code CLI

# Via npm (check official docs for latest)
npm install -g @anthropic-ai/claude-code

# Verify installation
claude-code --version

Note: Installation method may vary. Check Anthropic's official docs for current CLI installation.

Step 2: Configure API Key

# Set Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Or add to shell profile (~/.zshrc, ~/.bashrc)
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc

Step 3: Handle .claude/CLAUDE.md File

The .claude/CLAUDE.md file triggers prAxIs OS behavioral patterns in Claude Code. ⚠️ CRITICAL: Never blindly overwrite existing .claude/CLAUDE.md files!

Note: .claude/CLAUDE.md is Claude Code-specific (similar to .cursorrules for Cursor). It provides behavioral triggers for the LLM.

Handling Existing .claude/CLAUDE.md

If .claude/CLAUDE.md already exists, follow the merge protocol from the Cursor guide. The merge logic is the same:

Check if file exists → If no, copy directly
If exists → Use merge protocol (auto-merge, manual merge, or backup-and-replace)
prAxIs OS rules must be at the TOP - Critical for:
- Attention span: LLMs read files sequentially - instructions at the top have the best chance of being followed
- Hook point: Ensures orientation queries are triggered before other rules

Quick reference: See Cursor guide - Step 1: Handle .cursorrules File for the complete merge protocol with code examples (replace .cursorrules with .claude/CLAUDE.md).

What it does:

Triggers orientation (10 bootstrap queries)
Enforces search-first protocol
Prevents direct file reads of indexed content

Step 4: Configure MCP for Claude Code

Note: Claude Code uses .claude/CLAUDE.md for behavioral patterns. If you want to trigger orientation queries, they'll be automatic via this file.

Claude Code uses a configuration file for MCP servers. Location varies by installation:

Typical locations:

~/.config/claude-code/mcp.json (Linux/Mac)
~/.claude-code/mcp.json (alternative)
Project-level: ./.claude-code/mcp.json

Create or edit the MCP configuration:

{
  "mcpServers": {
    "praxis-os": {
      "command": ".praxis-os/venv/bin/python",
      "args": [
        "-m",
        "ouroboros",
        "--transport",
        "dual"
      ],
      "cwd": "${workspaceFolder}/.praxis-os",
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

Important: Primary agents always use --transport dual to enable HTTP endpoint for secondary agents.

Or use absolute paths:

{
  "mcpServers": {
    "praxis-os": {
      "command": "/absolute/path/to/project/.praxis-os/venv/bin/python",
      "args": [
        "-m",
        "ouroboros",
        "--transport",
        "dual"
      ],
      "cwd": "/absolute/path/to/project/.praxis-os",
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

Windows: Change venv/bin/python to venv\Scripts\python.exe

Step 5: Start Claude Code

# Navigate to your project
cd /path/to/your/project

# Start Claude Code
claude-code

# Or specify project directory
claude-code --project /path/to/project

On startup, Claude Code will:

Load MCP configuration
Start prAxIs OS MCP server
Connect to MCP server
Read .claude/CLAUDE.md → Loads behavioral patterns
Detect .rebuild_index flag → Build RAG index (first run)
Tools become available

Expected startup: 5-10 seconds for first RAG build

Step 6: Validate Installation

Test 1: Check MCP Connection

In Claude Code terminal:

"Use search_standards tool to query: orientation bootstrap"

Expected: RAG results with orientation content

Test 2: List Available Tools

"What MCP tools are available?"

Should list:

search_standards
pos_workflow
pos_browser
current_date
get_server_info

Test 3: Test RAG Search

"Search prAxIs OS standards for concurrency patterns"

Should return relevant chunks from .praxis-os/standards/

CLI Workflow Tips

Running Orientation

# First thing in any session
> "Run the 10 mandatory orientation queries from .claude/CLAUDE.md"

Claude Code will read .claude/CLAUDE.md and execute queries.

Creating Specs

> "Create a spec for user authentication feature"

Uses pos_workflow tool to start spec creation workflow.

Querying Standards

> "How should I handle database connection pooling in Python?"

Uses search_standards to find relevant patterns.

Running Workflows

> "Start the spec execution workflow for auth-feature spec"

Manages phase-gated workflow via pos_workflow.

Troubleshooting

MCP Server Won't Start

Symptom: "Failed to connect to MCP server" on Claude Code startup

Check:

# Test MCP server manually
cd .praxis-os
./venv/bin/python -m ouroboros

Solutions:

Verify Python 3.9+ installed
Check virtual environment exists: ls .praxis-os/venv/

Re-install dependencies:

.praxis-os/venv/bin/pip install -r .praxis-os/ouroboros/requirements.txt

Check MCP config path: claude-code --show-config

Tools Unavailable

Symptom: Claude Code doesn't recognize search_standards or other tools

Check:

# Verify MCP config exists
cat ~/.config/claude-code/mcp.json
# or
cat ~/.claude-code/mcp.json

Solutions:

Create MCP config file (Step 4)
Use absolute paths instead of ${workspaceFolder}
Restart Claude Code after config changes
Check Claude Code logs (if available)

Empty Search Results

Symptom: search_standards returns no results

Check:

# Verify RAG index built
ls -la .praxis-os/.cache/vector_index/

# Check standards exist
find .praxis-os/standards -name "*.md" | wc -l
# Should be 60-80 files

Solutions:

Create rebuild flag: touch .praxis-os/standards/.rebuild_index
Restart Claude Code → Rebuilds index
Verify permissions: chmod -R u+rw .praxis-os/.cache/

Slow Performance

Symptom: Queries take >5 seconds

Check:

# Check system resources
top

# Check index size
du -sh .praxis-os/.cache/vector_index/

Expected:

Less than 1 second per query
20-50MB index size

Solutions:

Rebuild index (delete .praxis-os/.cache/vector_index/)
Ensure SSD (not HDD) for project
Check Python not competing for CPU with other processes

API Rate Limits

Symptom: "Rate limit exceeded" errors

Note: prAxIs OS tools run locally and don't call Anthropic API. But Claude Code LLM calls do.

Solutions:

Wait for rate limit reset
Upgrade Anthropic API tier
Reduce query frequency (though prAxIs OS queries don't count toward API limits)

Terminal vs VS Code Mode

Claude Code has two primary modes:

Terminal (This Guide)

✅ Lightweight, fast startup
✅ Works in any terminal (tmux, screen, etc.)
✅ Good for server/remote development
❌ No GUI/editor integration

VS Code Mode (See vscode.md)

✅ Editor integration
✅ Visual diff, inline suggestions
✅ File tree, debugging
❌ Heavier, requires VS Code

Choose based on your workflow. Both support prAxIs OS equally.

Configuration: Project vs Global

Project-Level (Recommended)

# Create project-specific config
mkdir -p .claude-code
cat > .claude-code/mcp.json << 'EOF'
{
  "mcpServers": {
    "praxis-os": {
      "command": "${workspaceFolder}/.praxis-os/venv/bin/python",
      "args": [
        "-m",
        "ouroboros",
        "--transport",
        "dual"
      ],
      "cwd": "${workspaceFolder}/.praxis-os"
    }
  }
}
EOF

Pros: Team can share config, version controlled

Global (Alternative)

# User-level config
mkdir -p ~/.config/claude-code
cat > ~/.config/claude-code/mcp.json << 'EOF'
{
  "mcpServers": {
    "praxis-os": {
      "command": "${workspaceFolder}/.praxis-os/venv/bin/python",
      "args": [
        "-m",
        "ouroboros",
        "--transport",
        "dual"
      ],
      "cwd": "${workspaceFolder}/.praxis-os"
    }
  }
}
EOF

Pros: Works for all projects automatically

Multi-Project Setup

If you work on multiple projects with prAxIs OS:

{
  "mcpServers": {
    "praxis-os": {
      "command": "${workspaceFolder}/.praxis-os/venv/bin/python",
      "args": [
        "-m",
        "ouroboros",
        "--transport",
        "dual"
      ],
      "cwd": "${workspaceFolder}/.praxis-os"
    }
  }
}

The ${workspaceFolder} variable resolves to current project directory automatically.

Next Steps

✅ Installation complete!

Now:

Run orientation: "Run the 10 mandatory bootstrap queries"
Test search: "Query standards for [topic]"
Create spec: "Create a spec for [feature]"
Build with guidance: prAxIs OS provides context throughout

Prerequisites​

Overview​

Step 1: Install Claude Code CLI​

Step 2: Configure API Key​

Step 3: Handle .claude/CLAUDE.md File​

Handling Existing .claude/CLAUDE.md​

Step 4: Configure MCP for Claude Code​

Step 5: Start Claude Code​

Step 6: Validate Installation​

Test 1: Check MCP Connection​

Test 2: List Available Tools​

Test 3: Test RAG Search​

CLI Workflow Tips​

Running Orientation​

Creating Specs​

Querying Standards​

Running Workflows​

Troubleshooting​

MCP Server Won't Start​

Tools Unavailable​

Empty Search Results​

Slow Performance​

API Rate Limits​

Terminal vs VS Code Mode​

Terminal (This Guide)​

VS Code Mode (See vscode.md)​

Configuration: Project vs Global​

Project-Level (Recommended)​

Global (Alternative)​

Multi-Project Setup​

Next Steps​

Prerequisites

Overview

Step 1: Install Claude Code CLI

Step 2: Configure API Key

Step 3: Handle .claude/CLAUDE.md File

Handling Existing .claude/CLAUDE.md

Step 4: Configure MCP for Claude Code

Step 5: Start Claude Code

Step 6: Validate Installation

Test 1: Check MCP Connection

Test 2: List Available Tools

Test 3: Test RAG Search

CLI Workflow Tips

Running Orientation

Creating Specs

Querying Standards

Running Workflows

Troubleshooting

MCP Server Won't Start

Tools Unavailable

Empty Search Results

Slow Performance

API Rate Limits

Terminal vs VS Code Mode

Terminal (This Guide)

VS Code Mode (See vscode.md)

Configuration: Project vs Global

Project-Level (Recommended)

Global (Alternative)

Multi-Project Setup

Next Steps