# neckbeard

> Coding-agent plugin that reads an app, scaffolds OpenTofu infrastructure from a tested module catalog, and estimates monthly cloud cost before deployment.

neckbeard is an open-source plugin for coding agents from the bealesh project. It reads an application repository, writes OpenTofu from a versioned, tested module catalog, and shows a monthly cost estimate before anything is deployed. The project is labeled pre-alpha, currently at v0.3.0 under Apache-2.0.

## What It Is

neckbeard splits infrastructure work between a human-maintained catalog and an agent. The catalog holds OpenTofu modules scoped to one workload shape: a container image, up to ten HTTP, worker, and cron processes, Postgres, object storage, and secrets. The agent analyzes the repo, asks questions the code cannot answer, and maps the answers onto catalog inputs; the rest is deterministic Go. If the app needs something the catalog does not cover, such as Redis, the tool returns a named finding rather than an invented module.

It targets AWS, GCP, and Azure, with GitHub Actions or GitLab CI, and either serverless containers (Cloud Run, ECS Fargate, Container Apps) or Kubernetes (EKS, GKE, AKS).

## The Five Commands

- analyze reads the repo into an evidence-backed app-profile.yaml where every fact carries a file and line number, then asks open questions. Planning refuses to run while any remain open.
- estimate plans against the catalog and uses Infracost to show low, expected, and high monthly cost per environment, separating idle baseline from usage and listing unpriced resources next to the total.
- sync plans, estimates, scaffolds, and validates, never silently overwriting edited files. It ends with PASSED, FAILED, or NOT EXERCISED per check.
- doctor installs the CLI if missing and reports which supporting tools are present.
- help gives a short summary.

The CLI can also run without an agent via go install.

## What It Generates and Claims

Output includes three environments with independent state, and CI pipelines that test, build, scan with Trivy, and push using OIDC federation with no static cloud keys. Networks are private by default and secret values never pass through the tool. Two cost controls exist: monthly_budget_alert renders a real cloud budget that notifies people, and monthly_ceiling refuses before resources exist.

Validation is reported in levels: V0 static syntax and policy checks (tofu validate, Checkov, kubeconform), V1 authenticated plan, and V2 deployment verification. V1 and V2 need cloud credentials and stay NOT EXERCISED until a human runs them.

## Current Status

The project describes itself as pre-alpha. Per its README, the static matrix covers all 12 cloud, VCS, and runtime paths, and live deploy, update, and rollback have passed on serverless containers for AWS/GitHub and Azure/GitHub. Live deploy on GCP, the GitLab lanes, Kubernetes, promotion, and recovery drills are implemented but not yet exercised, and landing zones are designed but not built.

## Features
- Evidence-backed app analysis with file and line references
- OpenTofu scaffolding from a versioned, tested module catalog
- Monthly cost estimates (low, expected, high) per environment via Infracost
- Named findings for unsupported infrastructure instead of invented modules
- Unpriced resources listed next to cost totals
- Three isolated environments with independent state
- CI/CD pipeline generation for GitHub Actions and GitLab CI using OIDC
- Trivy scanning, Checkov policy checks, and kubeconform validation
- Layered V0/V1/V2 validation reporting with PASSED, FAILED, NOT EXERCISED
- monthly_budget_alert and monthly_ceiling cost controls
- Never silently overwrites user-edited files
- Standalone Go CLI usable without an agent

## Integrations
Claude Code, Codex, Cursor, AWS, GCP, Azure, GitHub Actions, GitLab CI, OpenTofu, Infracost, Checkov, Trivy, Kubernetes, Cloud Run, ECS Fargate, Container Apps, EKS, GKE, AKS

## Platforms
API, CLI

## Pricing
Open Source

## Version
v0.3.0

## Links
- Website: https://neckbeard.sh
- Documentation: https://github.com/bealesh/neckbeard#readme
- Repository: https://github.com/bealesh/neckbeard
- EveryDev.ai: https://www.everydev.ai/tools/neckbeard