Agent Configuration

This guide covers how to configure AI coding agents in RAPID.

Overview

RAPID supports multiple AI coding agents. Each agent is configured in rapid.json under the agents section:

{
  "agents": {
    "default": "claude",
    "available": {
      "claude": { ... },
      "opencode": { ... },
      "aider": { ... }
    }
  }
}

Agent Properties

Each agent configuration supports:

Property	Type	Required	Description
cli	string	Yes	Command to execute
instructionFile	string	No	Path to instruction file
envVars	array	No	Required environment variables
installCmd	string	No	Installation command
args	array	No	Additional CLI arguments
yolo	boolean	No	Enable YOLO mode (skip prompts)

YOLO Mode

YOLO mode allows agents to execute commands without permission prompts. This is enabled by default for Claude in RAPID’s default configuration.

What It Does

When yolo: true is set:

• Claude Code runs with --dangerously-skip-permissions
• The agent can execute commands, write files, and make changes without asking for confirmation
• Dramatically faster development cycles

When to Use

YOLO mode is safe when running in:

• Containers: Dev containers provide isolation
• VMs: Lima VMs limit blast radius
• Sandboxed environments: RAPID’s sandbox mode

Configuration

{
  "agents": {
    "available": {
      "claude": {
        "cli": "claude",
        "instructionFile": "CLAUDE.md",
        "yolo": true
      }
    }
  }
}

Enabling/Disabling via CLI

# Enable YOLO mode
rapid agent yolo claude --enable

# Disable YOLO mode
rapid agent yolo claude --disable

Security Considerations

Caution

YOLO mode should only be used in isolated environments. Never enable on production machines or with access to sensitive data.

Mitigations RAPID provides:

1. Container isolation: Run agents in dev containers
2. VM isolation: Use Lima VMs on macOS
3. Sandbox mode: OS-level sandboxing (seatbelt/bubblewrap)
4. Network filtering: Restrict outbound connections

Authentication

Auth Passthrough (Default)

RAPID automatically detects your existing AI tool credentials. If you’re logged into Claude Code, RAPID uses that authentication—no API key configuration needed.

# Already logged into Claude?
claude --version  # Works without prompts

# RAPID uses your existing auth
rapid dev  # No additional setup!

See Auth Passthrough for details.

Explicit API Keys

If you prefer explicit configuration or auth passthrough doesn’t work:

{
  "agents": {
    "available": {
      "claude": {
        "cli": "claude",
        "envVars": ["ANTHROPIC_API_KEY"]
      }
    }
  },
  "secrets": {
    "provider": "1password",
    "vault": "Development",
    "items": {
      "ANTHROPIC_API_KEY": "op://Development/Anthropic/api-key"
    }
  }
}

Checking Auth Status

rapid auth

Output shows detected credentials for all supported providers.

---

Claude Code

Anthropic’s AI coding assistant.

Installation

npm install -g @anthropic-ai/claude-code

Configuration

{
  "agents": {
    "available": {
      "claude": {
        "cli": "claude",
        "instructionFile": "CLAUDE.md",
        "envVars": ["ANTHROPIC_API_KEY"],
        "installCmd": "npm install -g @anthropic-ai/claude-code"
      }
    }
  }
}

Required Secrets

{
  "secrets": {
    "items": {
      "ANTHROPIC_API_KEY": "op://Development/Anthropic/api-key"
    }
  }
}

Instruction File (CLAUDE.md)

# Project: my-project

## Overview

Brief description of the project.

## Code Style

- Language: TypeScript
- Style guide: Airbnb
- Formatting: Prettier

## Important Commands

- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run build` - Build for production

## Architecture

Description of project structure.

## Restrictions

- Do not modify config files without asking
- Always run tests after changes

---

OpenCode

Multi-provider AI coding assistant.

Installation

npm install -g opencode

Configuration

{
  "agents": {
    "available": {
      "opencode": {
        "cli": "opencode",
        "instructionFile": "AGENTS.md",
        "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
        "installCmd": "npm install -g opencode"
      }
    }
  }
}

Required Secrets

{
  "secrets": {
    "items": {
      "ANTHROPIC_API_KEY": "op://Development/Anthropic/api-key",
      "OPENAI_API_KEY": "op://Development/OpenAI/api-key"
    }
  }
}

Instruction File (AGENTS.md)

# Agent Instructions

## Project Type

Node.js/TypeScript REST API

## Key Files

- `src/index.ts` - Entry point
- `src/routes/` - API routes
- `src/services/` - Business logic

## Commands

- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Guidelines

- Use async/await for async operations
- Add JSDoc comments to exported functions
- Write tests for new features

---

Aider

AI pair programming tool.

Installation

pip install aider-chat

Configuration

{
  "agents": {
    "available": {
      "aider": {
        "cli": "aider",
        "instructionFile": ".aider.conf.yml",
        "envVars": ["OPENAI_API_KEY"],
        "installCmd": "pip install aider-chat",
        "args": ["--model", "gpt-4o"]
      }
    }
  }
}

Required Secrets

{
  "secrets": {
    "items": {
      "OPENAI_API_KEY": "op://Development/OpenAI/api-key"
    }
  }
}

Configuration File (.aider.conf.yml)

model: gpt-4o
auto-commits: true
gitignore: true
map-tokens: 1024
dark-mode: true

Using Anthropic Models

{
  "agents": {
    "available": {
      "aider": {
        "cli": "aider",
        "envVars": ["ANTHROPIC_API_KEY"],
        "args": ["--model", "claude-3-5-sonnet-20241022"]
      }
    }
  }
}

---

GitHub Copilot CLI

GitHub’s AI assistant.

Installation

gh extension install github/gh-copilot

Configuration

{
  "agents": {
    "available": {
      "copilot": {
        "cli": "gh",
        "args": ["copilot"],
        "envVars": ["GITHUB_TOKEN"],
        "installCmd": "gh extension install github/gh-copilot"
      }
    }
  }
}

Required Secrets

{
  "secrets": {
    "items": {
      "GITHUB_TOKEN": "op://Development/GitHub/pat"
    }
  }
}

---

Custom Agents

Add any CLI-based AI tool:

{
  "agents": {
    "available": {
      "my-custom-agent": {
        "cli": "my-ai-tool",
        "instructionFile": "MY_AGENT.md",
        "envVars": ["MY_API_KEY"],
        "installCmd": "npm install -g my-ai-tool",
        "args": ["--config", ".my-ai-config.json"]
      }
    }
  }
}

---

Multi-Agent Setup

Configure multiple agents for different tasks:

{
  "agents": {
    "default": "claude",
    "available": {
      "claude": {
        "cli": "claude",
        "instructionFile": "CLAUDE.md",
        "envVars": ["ANTHROPIC_API_KEY"]
      },
      "aider": {
        "cli": "aider",
        "args": ["--model", "gpt-4o"],
        "envVars": ["OPENAI_API_KEY"]
      },
      "opencode": {
        "cli": "opencode",
        "instructionFile": "AGENTS.md",
        "envVars": ["ANTHROPIC_API_KEY"]
      }
    }
  }
}

Running Multiple Agents

# Launch all in tmux panes
rapid dev --multi

# Specific agents
rapid dev --multi --agents claude,aider

---

Environment Variables

Agents receive environment variables in this order:

1. System environment
2. Container environment (containerEnv in devcontainer.json)
3. RAPID secrets (from 1Password/Vault)
4. Agent-specific overrides

---

Switching Agents

Temporarily

# Use different agent for this session
rapid dev --agent aider

Permanently

# Change default
rapid agent default opencode

# Or edit rapid.json
{
  "agents": {
    "default": "opencode"
  }
}

---

Troubleshooting

Agent not found

# Check if installed
which claude
which aider

# Reinstall
rapid start --reinstall-tools

API key errors

# Verify secrets
rapid secrets verify

# Check specific secret
rapid secrets get ANTHROPIC_API_KEY

Wrong model

Check the agent’s args in rapid.json:

{
  "aider": {
    "args": ["--model", "gpt-4o"] // Verify model name
  }
}

---

Best Practices

1. Use specific agents for specific tasks

   • Claude: Complex reasoning, architecture
   • Aider: Quick refactoring, auto-commits
   • OpenCode: Multi-model flexibility

2. Keep instruction files concise

   • Focus on project-specific info
   • Don’t duplicate README content
   • Update when architecture changes

3. Secure your API keys

   • Never commit keys to git
   • Use 1Password or Vault
   • Rotate keys periodically

4. Test agent availability

   rapid status