Configuration Guide

This guide covers configuring Claude Code and CLAUDE.md for optimal use with Pixery AI tools.

CLAUDE.md

The CLAUDE.md file provides instructions to Claude Code. Project-level ./CLAUDE.md takes precedence over user-level ~/.claude/CLAUDE.md when both exist.

User-Level Template

The installer creates a default user-level CLAUDE.md at ~/.claude/CLAUDE.md. This template is fetched live from the server:

Loading template...

Project-Level Template

For project-specific instructions, create a CLAUDE.md in your project root. Here's an example:

# Project: MyApp
 
## Tech Stack
- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS
- PostgreSQL with Drizzle ORM
 
## Project Structure
- /src/app - Next.js app router pages
- /src/components - React components
- /src/lib - Utilities and helpers
- /src/db - Database schema and queries
 
## Conventions
- Use server components by default, "use client" only when needed
- API routes go in /src/app/api
- Use Zod for all input validation
- Error responses follow { error: string, code: string } format
 
## Commands
- `npm run dev` - Start development server
- `npm run db:push` - Push schema changes
- `npm run db:studio` - Open Drizzle Studio
 
## Do Not
- Modify /src/db/schema.ts without asking
- Add new dependencies without approval
- Change tsconfig or eslint rules

MCP Server Configuration

MCP servers can be configured at two levels:

Global MCP Servers (User-Level)

Add MCP servers that should be available in all projects to ~/.claude.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/playwright-mcp"]
    }
  }
}

Local MCP Servers (Project-Level)

Add project-specific MCP servers to .mcp.json in your project root:

{
  "mcpServers": {
    "my-project-db": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Project-level servers are merged with global servers. If the same server name exists in both, project-level takes precedence.

Updating Configuration

Via Installer

Re-run the installer to update all configurations:

curl -fsSL https://ai-server.pixerylabs.net/install.sh | bash

Manually

Edit the files directly:

# Edit global CLAUDE.md
nano ~/.claude/CLAUDE.md
 
# Edit Claude config
nano ~/.claude.json

Via MCP Tool

Use the Pixery AI MCP server to fetch the latest template:

Get the latest CLAUDE.md template from Pixery

Best Practices

User-level for general rules - Keep AI workflow instructions (Context7, Codex reviews, code style) in ~/.claude/CLAUDE.md
Project-level for specifics - Tech stack, project structure, conventions go in project root CLAUDE.md
Don't duplicate - Project CLAUDE.md should only contain project-specific info, not repeat global rules
Keep it concise - Claude reads the entire file, avoid unnecessary content
Be specific - Vague instructions lead to inconsistent behavior

Troubleshooting

Changes Not Taking Effect

Restart Claude Code after editing
Check file location (project vs global)
Verify markdown syntax is correct

MCP Server Not Loading

Check the command exists (which npx)
Verify the package is available
Check environment variables are set
Look at Claude Code logs for errors

Configuration Conflicts

Project-level CLAUDE.md overrides global settings. If you see unexpected behavior:

Check for project-level CLAUDE.md
Verify which settings take precedence
Consider consolidating configurations