neckbeard
A plugin for your coding agent that turns an app into cloud infrastructure you
can actually review, with the monthly bill attached.
Coding agents are great at application code and weirdly confident about
infrastructure. Ask one to "deploy this to AWS" and you'll get three hundred
lines of plausible HCL, a security group open to the world, an IAM policy with
a star in it, and no idea what any of it costs. It reads like the work of
someone who has absorbed every blog post and never once been paged. The model
isn't lying to you. It has simply never seen the invoice.
neckbeard splits the job. Humans maintain a catalog of OpenTofu modules that
are versioned, tested in CI on every change, and scoped to one honest workload
shape: a container image, up to ten HTTP, worker, and cron processes, Postgres,
object storage, secrets. The agent reads your repo, works out what the app
needs, asks you the questions code can't answer, and maps the answers onto
catalog inputs. Everything in between is deterministic Go. The planner writes a
hash-verified blueprint.yaml, the renderer is a pure function of it, and
regeneration refuses to overwrite a file you've touched. The agent never
invents infrastructure. If your app needs Redis, you get a named finding that
says the catalog doesn't do Redis yet, rather than a module that looks like it
might.
It covers AWS, GCP, and Azure, with GitHub Actions or GitLab CI, as serverless
containers (Cloud Run, ECS Fargate, Container Apps) or Kubernetes (EKS, GKE,
AKS). The plugin shape is borrowed from
ponytail, which proved a plugin
can be mostly one good prompt.
Install
Claude Code, as two separate prompts:
/plugin marketplace add bealesh/neckbeard
/plugin install neckbeard@neckbeard
Then open your app's repo and run /neckbeard:analyze. Your first neckbeard
command installs the small CLI the plugin drives (a sha256-verified release
binary, or go install if you have Go around), and that's the whole setup.
Cost estimates and validation lean on tools you may already have, namely
Infracost, OpenTofu, and Checkov. /neckbeard:doctor tells you what's missing
and what each one buys you.
Codex, Cursor, or anything else that reads a SKILL.md: see
INSTALL.md.
What it's like to use
You run /neckbeard:analyze and the agent reads the repo the way a careful
new hire would. Dockerfiles, exposed ports, environment variables, health
endpoints, the Procfile, the corner of settings.py where Django quietly
reads DATABASE_URL. It writes an app profile in which every fact carries a
file and line number, every inference carries a confidence, and every
assumption is loud. Then it asks you the things it genuinely can't know: how
much traffic to expect, how much downtime you'll tolerate, whether that
Postgres is one you already run or one you want built, what the worker is for.
Your answers get recorded next to the assumptions they resolve, and planning
refuses to run while any of them is still open.
/neckbeard:estimate plans against the catalog and shows you the bill before
anything exists. /neckbeard:sync scaffolds the infrastructure, the
pipelines, and on Kubernetes the cluster manifests, then validates them and
tells you precisely what it did and didn't prove. From there you review the
files like any other pull request and follow the generated docs/bootstrap.md
once per environment, with real credentials in your own hands. The agent never
gets those.
| Command |
What it does |
/neckbeard:analyze |
Read the repo into an evidence-backed app-profile.yaml, ask the open questions, propose neckbeard.yaml. |
/neckbeard:estimate [comparison] |
Plan against the catalog and show the monthly cost table, including everything that couldn't be priced. serverless vs kubernetes or solo vs smallteam runs both. |
/neckbeard:sync |
Plan, estimate, scaffold, validate. Your edits are never silently overwritten. Ends with PASSED, FAILED, or NOT EXERCISED for each check. |
/neckbeard:doctor [plan|estimate|validate|all] |
Install the CLI if it's missing and report which tools are present. |
/neckbeard:help |
The short version of this page. |
The bill
Nobody tells you what infrastructure costs until the invoice arrives, which is
a strange way to make an engineering decision. So neckbeard asks Infracost
first. Same reference app (an HTTP service, a worker, a cron job, Postgres),
smallest tier, all three environments, live prices:
|
Cloud Run |
Container Apps |
ECS Fargate |
EKS |
GKE (regional) |
AKS |
| monthly |
$77 |
~$98* |
$250 |
$396 |
$754 |
~$801* |
The asterisk matters. Infracost can't price Container Apps compute yet, and
the honest move is to say so rather than let a low number lie, so the report
lists every resource it couldn't price right next to the total. The rest is
what you'd want from anyone who has read a cloud bill with their name on it:
the idle baseline separated from usage, the usage assumptions written down
where you can edit them, low, expected, and high scenarios, and a footer saying
where the numbers came from. The table is also how the tool argues. When a solo
developer asks for Kubernetes, the numbers say "not yet" so nobody else has to.
What it will and won't claim
Infrastructure tooling has a long tradition of implying more than it has
proven. A passing tofu validate has never once meant a thing deploys.
neckbeard reports in three levels and insists on showing you the third:
V0 PASSED tofu validate [prd]
V0 PASSED checkov policy [prd] every skip carries a written reason
V0 PASSED kubeconform (clusters/)
V1 NOT EXERCISED authenticated plan requires cloud credentials
V2 NOT EXERCISED deployment verification requires cloud credentials
V0 is syntax and policy. Every Checkov skip in the generated config carries a
written reason, because a skip without one is a lie about your security
posture. V1 is an authenticated plan and V2 is a verified deployment; both
need credentials, and both stay NOT EXERCISED until a human runs them. When
live runs break, the failures go into the public
findings ledger and from there into the catalog. The first
real deployment produced ten of them, and five became module fixes the same
afternoon. Degraded paths say why: an Azure plus GitLab merge-request plan
can't federate, so the generated pipeline says that out loud instead of
failing in a way you'd lose an evening to.
What's in the box
Three isolated environments with their own state, sized by tier presets that
spell out traffic, availability, recovery objectives, and how many people are
actually around to operate the thing. Every preset value is visible and
overridable within the catalog's tested envelope, and anything outside that
envelope is marked rather than blessed. Pipelines come from one internal model
for either CI: test, build, scan (Trivy blocks HIGH and CRITICAL), push, plans
on pull requests under a read-only identity, applies on main under a write
identity, production gated behind environment protection. There are no static
cloud keys anywhere. It's OIDC federation end to end, and a test fails the
build if a rendered pipeline so much as mentions AWS_SECRET_ACCESS_KEY.
Networks are private by default, secret managers hold the names the operator
fills in (values never pass through neckbeard, its state, or your git
history), and managed WAF rules switch on where the tier calls for them.
Where it actually stands
Pre-alpha, and specific about which parts.
| Claim |
Evidence |
| analyze, plan, estimate, scaffold, validate on all 12 cloud × VCS × runtime paths |
Static matrix runs in CI on every PR; three unrelated fixture apps onboard end to end |
| Live deploy, update, and rollback on serverless containers |
Passed on AWS/GitHub and Azure/GitHub with real database checks (evidence) |
| Live deploy on GCP, the GitLab lanes, Kubernetes, promotion, recovery drills |
Not yet. Implemented, NOT EXERCISED |
The plugin's product today is the front half: reviewable infrastructure,
pipelines, a cost estimate, and a runbook you can hand to whoever holds the
credentials. The deployment lifecycle underneath it (neckbeard release,
documented in the skill) exists and has worked for real on two lanes, but it
stays experimental until it clears the gates in the
launch plan. Static validation is not deployment proof.
Landing zones, meaning org structure and guardrails, the Path F story in
DESIGN.md, are designed and not built.
How it's put together
you / your agent deterministic core
┌──────────────────────┐ ┌───────────────────────────┐
repo ──▶│ analyze: facts w/ │ profile │ plan: catalog @ pinned │
│ evidence, questions, ├───────────▶│ versions → blueprint.yaml │
│ judgment, answers │ config │ (hash-verified lockfile) │
└──────────────────────┘ └─────────┬─────────────────┘
┌──────────────┼──────────────┐
▼ ▼ ▼
estimate scaffold validate
Infracost, ownership V0 static,
scenarios, contract: V1 plan,
unpriced never silently V2 deploy,
named overwrite each reported
The repository root is the plugin. skills/neckbeard/SKILL.md
is the agent's operating manual, commands/ holds the slash
commands, and the Go CLI under cmd/ plus the module catalog
under catalog/ is the deterministic half. The CLI runs fine
without an agent at all:
go install github.com/bealesh/neckbeard/cmd/neckbeard@latest
neckbeard analyze && $EDITOR app-profile.yaml neckbeard.yaml
neckbeard plan && neckbeard estimate && neckbeard scaffold && neckbeard validate
If you've run anything in production for long enough, you know the expensive
mistakes rarely live in the application code. They live in the account bill
and the 3am page. This is a tool for catching them while they're still a diff.
More, if you want it: DESIGN.md is the full design, kept honest
since day one. docs/findings/ is what reality taught us.
CONTRIBUTING.md is how to help.
License
Apache-2.0, see LICENSE.
一个 Claude Code 插件，能把一个应用代码仓库变成 AWS、GCP 或 Azure 上的云基础设施。它使用一份由人工维护的、经过测试的 OpenTofu 模块目录，并在真正部署任何东西之前先给出费用估算。