⚙️ Configuration

Configure Code Puppy to work exactly how you want. Settings can be configured via config file, environment variables, or runtime commands.

Configuration File

Code Puppy looks for configuration in ~/.code_puppy/puppy.cfg:

[default]
# Default model to use
model = gpt-5.1

# Enable YOLO mode (no confirmations)
yolo_mode = false

# Verbosity level (quiet, normal, verbose)
verbosity = normal

# Enable autosave
autosave = true

# Default agent
agent = code-puppy

API Key Configuration

API keys can be configured using the /set command or environment variables.

Using /set Command (Recommended)

The easiest way to configure API keys is with the /set command. Keys are saved to puppy.cfg and persist across sessions:

# Set API keys using lowercase names
/set openai_api_key sk-your-openai-key
/set anthropic_api_key sk-ant-your-anthropic-key
/set google_api_key your-google-key
/set cerebras_api_key your-cerebras-key
/set mistral_api_key your-mistral-key
/set groq_api_key your-groq-key

Using Environment Variables

Alternatively, you can use environment variables (uppercase with underscores):

# Required: At least one provider key
export OPENAI_API_KEY="sk-your-openai-key"
export ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"
export GOOGLE_API_KEY="your-google-key"
export CEREBRAS_API_KEY="your-cerebras-key"
export MISTRAL_API_KEY="your-mistral-key"
export GROQ_API_KEY="your-groq-key"

Other Environment Variables

Optional Settings

# Custom config directory
export CODE_PUPPY_CONFIG_DIR="~/.my-puppy-config"

# Default model
export CODE_PUPPY_MODEL="claude-4-5-sonnet"

# Enable debug logging
export CODE_PUPPY_DEBUG="true"

Runtime Configuration

Change settings on the fly using slash commands:

View Current Settings

# Show all settings
/show

# Show specific setting
/show yolo_mode

Change Settings

# Enable YOLO mode (no confirmations)
/set yolo_mode true

# Set verbosity
/set verbosity verbose

# Enable autosave
/set autosave true

# Set safety permission level
/set safety_permission_level high

Common Configuration Options

Option	Default	Description
yolo_mode	false	Skip confirmation prompts for shell commands
verbosity	normal	Output verbosity (quiet, normal, verbose)
autosave	true	Automatically save sessions
allow_recursion	false	Allow recursive file listing
safety_permission_level	medium	Safety level for command execution
reasoning_effort	medium	AI reasoning effort (low, medium, high)

Adding Custom Models

Add custom models via ~/.code_puppy/extra_models.json:

{
  "models": [
    {
      "name": "my-custom-model",
      "provider": "openai",
      "model_id": "gpt-5.1-codex-api",
      "api_base": "https://my-custom-endpoint.com/v1"
    }
  ]
}

Model Pinning

Pin specific models to agents:

# Pin a model to the current agent
/pin_model gpt-5.1

# Unpin
/unpin

# Models are persisted in the config

Agent Rules (AGENT.md)

Create an AGENT.md file in your project root to give Code Puppy project-specific instructions:

# AGENT.md

## Project: My Awesome App

### Coding Standards
- Use TypeScript for all new files
- Follow the existing naming conventions
- All functions must have JSDoc comments

### Testing
- Write tests using Jest
- Maintain 80% code coverage

### Architecture
- Use the repository pattern for data access
- Keep components under 200 lines

Custom Commands

Create custom commands in .claude/commands/:

# .claude/commands/deploy.md
Deploy the application to staging:
1. Run the tests
2. Build the production bundle
3. Deploy to staging server

Then use with: /deploy

Configuration Directory Structure

~/.code_puppy/
├── puppy.cfg           # Main config file
├── extra_models.json   # Custom model definitions
├── agents/             # Custom agent definitions
│   ├── my-agent.json
│   └── another-agent.json
├── sessions/           # Saved sessions
└── mcp/                # MCP server configs
    └── servers.json