# Claude Code Plugin

## Overview

The Bluebricks plugin connects Claude Code to the Bricks MCP server, giving it access to your blueprints, collections, and environments. Every infrastructure plan is analyzed for cost, security, and risk before you approve.

## Setup

Install the Bricks CLI and authenticate:

```bash
brew install bluebricks-co/bricks/bricks
bricks login
```

Add the plugin marketplace and install:

```bash
claude plugin marketplace add bluebricks-co/skills
claude plugin install bluebricks
```

The MCP server starts automatically. No additional configuration is needed.

## Deploy infrastructure

Ask Claude to install a blueprint. It resolves the blueprint and target collection, prompts for required properties, generates a plan, and presents a structured analysis before asking you to approve.

```
Deploy the postgres blueprint to staging
Install nginx to production with 3 replicas
Update my s3 environment with versioning enabled
```

Claude follows the standard plan-and-approve model. You review every plan before it executes.

When a plan is generated, Claude analyzes and presents:

* **Resources**: what is being created, modified, or destroyed
* **Cost**: estimated monthly cost impact
* **Security**: public access, IAM changes, network rules
* **Risk**: production impact, stateful changes, potential data loss

If an existing environment matches the blueprint in the target collection, Claude updates it in place rather than creating a duplicate.

## Create blueprints

Wrap community Terraform modules into Bluebricks blueprints without writing YAML manually. Claude fetches the module from the Terraform Registry, categorizes its variables, and generates a validated `bricks.yaml`.

```
Create a blueprint for AWS RDS Aurora without public access
Wrap the terraform-aws-modules/vpc module
```

Claude presents the variable selection for review before generating:

* **Required inputs**: variables you must provide at deploy time (e.g., `vpc_id`, `subnet_ids`)
* **Configurable inputs**: variables with sensible defaults you can override (e.g., `engine_version`, `instance_class`)
* **Hardcoded values**: security best practices and user constraints baked into the blueprint (e.g., `storage_encrypted: true`)
* **Skipped variables**: advanced or internal variables where module defaults apply

After you confirm the selection, Claude generates the `bricks.yaml`, validates it against the [blueprint schema](https://api.bluebricks.co/docs/schemas/latest/bricks.schema.json), and publishes it to your organization.

## Monitor and manage

Query environments, check pending approvals, and investigate failures.

```
Show me all environments in production
What's pending approval?
What went wrong with the staging deploy?
```

For environments in a `planned` state, Claude offers to approve or reject directly. For environments in an `error` state, it surfaces the failure details and links to the plan.

## Promote across environments

Deploy a blueprint through a sequence of collections with approval gates at each stage.

```
Promote nginx from dev to staging to prod
Deploy the api blueprint through all environments
```

Each stage generates its own plan, requires explicit approval, and supports optional validation commands before advancing. If a stage fails or is rejected, the pipeline halts and reports which stage stopped.

{% hint style="info" %}
Per-stage property overrides are supported. For example, you can set `replicas=2` for dev and staging but `replicas=5` for production.
{% endhint %}

## Agents

The plugin includes two specialized agents that handle multi-step workflows autonomously.

### bricks-env

Manages single-environment lifecycle operations: search blueprints, install, analyze the plan, and approve. Use it for any deploy, update, or approval flow that targets one collection.

### bricks-promote

Orchestrates multi-stage promotion pipelines. It validates the full promotion path before deploying, runs each stage in sequence with approval gates, and optionally executes validation commands between stages.

## Slash commands

The plugin provides shortcut commands for common operations:

| Command           | Description                                     |
| ----------------- | ----------------------------------------------- |
| `/bricks:install` | Deploy a blueprint to a collection              |
| `/bricks:create`  | Create a blueprint from a Terraform module      |
| `/bricks:status`  | Check environment status and view plan details  |
| `/bricks:list`    | Browse blueprints, collections, or environments |
| `/bricks:approve` | Approve or reject a pending environment         |

## Authentication

The plugin uses your existing Bricks CLI credentials. If your session expires during use, Claude runs `bricks login` to re-authenticate.

{% hint style="success" %}
The plugin is open source: [github.com/bluebricks-co/skills](https://github.com/bluebricks-co/skills)
{% endhint %}