Guardrails Commands

Guardrails are rules and instructions that constrain the AI agent’s behavior. They help ensure the agent follows your project’s coding standards and avoids certain patterns.

ralph guardrails

List all configured guardrails.

ralph guardrails

Alias: ralph guardrails list

Output:

Guardrails:

[✓] 1. Always use TypeScript strict mode
[✓] 2. Never commit .env files
[ ] 3. Use Prisma for database access (disabled)

Options:

ralph guardrails add

Add a new guardrail.

ralph guardrails add "Always use async/await instead of .then()"

Arguments:

Examples:

ralph guardrails add "Use functional React components, no class components"
ralph guardrails add "All API endpoints must validate input with Zod"
ralph guardrails add "Never use any type, always provide explicit types"

ralph guardrails remove

Remove a guardrail by its ID.

ralph guardrails remove 3

Arguments:

ralph guardrails toggle

Enable or disable a guardrail.

ralph guardrails toggle 3

Arguments:

Disabled guardrails are not included in the agent prompt but remain in your configuration for easy re-enabling.

ralph guardrails generate

Auto-generate guardrails from codebase analysis.

ralph guardrails generate

Analyzes your codebase to suggest guardrails based on:

• Detected frameworks and libraries
• Existing patterns in code
• Configuration files (tsconfig, eslint, etc.)

Options:

Example:

# Review suggestions first
ralph guardrails generate

# Auto-apply suggestions
ralph guardrails generate --apply

How Guardrails Work

Guardrails are injected into the AI agent prompt at the start of each iteration:

## Project Guardrails

You must follow these rules:
1. Always use TypeScript strict mode
2. Never commit .env files
3. Use functional React components

The agent sees these instructions and follows them when implementing tasks.

Guardrail Storage

Guardrails are stored in ~/.ralph/projects/<project>/guardrails.json:

{
  "guardrails": [
    {"id": 1, "text": "Always use TypeScript strict mode", "enabled": true},
    {"id": 2, "text": "Never commit .env files", "enabled": true}
  ]
}

Best Practices

Be Specific

Vague guardrails don’t help:

# Bad
ralph guardrails add "Write good code"

# Good
ralph guardrails add "Use early returns to reduce nesting, max 2 levels deep"

Include Context

Explain why when it helps:

ralph guardrails add "Use Bun instead of npm - this is a Bun project"

Don’t Over-constrain

Too many guardrails slow down the agent and can cause conflicts. Focus on important rules.

Next Steps

• GitHub Commands — GitHub integration
• Configuration — Full configuration reference