rae

Reproducible Agent Environment (RAE)

Standardized AI agent configurations for consistent development across projects. Provides shared skills and coding standards for Claude Code.

Why RAE?

Just as Docker standardizes runtime environments, RAE standardizes the context and tooling for AI agents working on your code. This means:

• Consistent behavior across projects
• Shared improvements flow to all projects via plugin updates
• Version-controlled workflows that evolve with your practices
• Enforced guidelines — not suggestions, requirements

Installation

Install the Plugin

RAE is distributed as a Claude Code plugin. No files are added to your repos.

Interactive (in Claude Code):

/plugin marketplace add peabody124/reproducible_agent_environment
/plugin install rae@reproducible_agent_environment

Scripted (one-liner):

curl -fsSL https://raw.githubusercontent.com/peabody124/reproducible_agent_environment/main/scripts/install-user.sh | bash

This installs Claude Code (native binary), pyright, the RAE plugin, and the recommended plugin suite (pyright-lsp, official Claude plugins, Hugging Face hf-cli, superpowers). Beads is disabled by default — see Bead-Driven Development to enable it.

Recommended Plugins

The install script installs all of these automatically. For manual installation:

# Official Claude plugins
/plugin install pyright-lsp@claude-plugin-directory
/plugin install code-review@claude-plugin-directory
/plugin install feature-dev@claude-plugin-directory
/plugin install code-simplifier@claude-plugin-directory
/plugin install plugin-dev@claude-plugin-directory

# Beads (optional — disabled by default, see Bead-Driven Development section)
# curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# curl -LsSf https://astral.sh/uv/install.sh | sh
# /plugin marketplace add steveyegge/beads
# /plugin install beads
# bd setup claude

# Hugging Face skills (hf-cli for model/dataset operations)
/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skills

# Superpowers (TDD enforcement, planning, review)
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

The hf-cli skill also requires the Hugging Face CLI tool:

# Via uv (preferred)
uv tool install 'huggingface_hub[cli]'

# Or via pip
pip install 'huggingface_hub[cli]'

Scaffolding a New Project

Use the /scaffold-repo skill to create a properly structured Python project:

/scaffold-repo my-project A tool for analyzing motion capture data

This creates the full RAE-compliant project structure: src/ layout, pyproject.toml, tests, .gitignore, and optionally a devcontainer. See skills/scaffold-repo/SKILL.md for the complete reference.

Devcontainers

New project: Use /scaffold-repo with the devcontainer option, or copy .devcontainer/ from this repo into your project. No custom Dockerfile needed — everything is installed via postCreateCommand.

Existing devcontainer: Add these fields to your devcontainer.json:

{
  // Mount host Claude config (create first: mkdir -p ~/.claude)
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached"
  ],

  // Install RAE + full plugin suite after container creation
  "postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/peabody124/reproducible_agent_environment/main/scripts/install-user.sh | bash",

  // Node.js for excalidraw rendering (npx)
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  },

  // Required environment variables
  "containerEnv": {
    "RAE_VERSION": "main",
    "CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
    "ENABLE_LSP_TOOL": "1"
  }
}

The install-user.sh script handles everything: Claude Code, pyright, RAE plugin, and the full recommended plugin suite.

Note: If you enable beads (or other custom git hooks) and use git-lfs, use git lfs install --force || true in your onCreateCommand to avoid hook conflicts that silently abort the container build. See Troubleshooting.

Headless rendering note: if your project uses PyOpenGL with PYOPENGL_PLATFORM=egl, keep libegl1 in the devcontainer apt-get install list. That provides libEGL.so.1, which PyOpenGL needs at runtime. The library alone isn't enough: set PYOPENGL_PLATFORM=egl before any GL import, pin/probe a real GPU, and verify you aren't silently on the llvmpipe CPU rasterizer (10–50× slower). The /efficient-rendering skill covers that runtime setup plus the mesh/point-cloud/overlay and camera-convention patterns.

See .devcontainer/ in this repo as the canonical reference.

What's Included

Skills