claude-bootstrap 1.0.0

Detect, scaffold, and reverse a complete Claude Code setup — in one command.

claude-bootstrap inspects your project, tells you why it picked a profile, shows the plan, asks once — then emits a full .claude/ tree: a permissions baseline, curated license-audited skills, and path-scoped rules. Idempotent, with --check and a real uninstall.

Why · Install · Quick start · Profiles · What you get · Docs · Contributing

🌐 English · Português · Español · Italiano · עברית

[!NOTE] v1.0.0 — first public release (2026-08-11). Install from a clone or with pip install git+https://github.com/ulissesflores/claude-bootstrap (Install). The PyPI package name follows via the release workflow.

Why it exists

Claude Code ships its own /init — and an interactive setup behind CLAUDE_CODE_NEW_INIT=1 — that writes a CLAUDE.md. claude-bootstrap is not a replacement; it's complementary, and deliberately does more on the axes that matter for a reproducible, auditable setup you re-run across many repos:

Use native /init for a quick conversational CLAUDE.md. Reach for claude-bootstrap when you want a reproducible, auditable, profile-based .claude/ baseline. (More: docs/02-state-of-the-art.md §7.2.)

What you get

• 🔎 Detect, then explain. Scans the project and prints the evidence for the profile it picks (e.g. pyproject.toml found, torch in deps → data-science) — never a black box.
• ✋ Confirm before write. Shows the plan via --check, asks [y/N], writes nothing on decline. Skippable with --yes/--non-interactive for CI.
• 🧱 A real .claude/ tree. CLAUDE.md (≤60-line policy), PROJECT-STATE.md, a settings.json permissions baseline, profile skills + path-scoped rules, and subdirectory CLAUDE.md files where a folder has a distinct role.
• ♻️ Idempotent + reversible. Re-running never clobbers your edits (create-only; <file>.new on update). A manifest records every emitted file so claude-bootstrap uninstall reverses the whole thing — and keeps any file you modified.
• 📦 License-audited skills with verified provenance. 30 bundled skills across profiles: 25 vendored, each pinned to an upstream commit and content-verified (scripts/verify-skill-provenance.py; a weekly CI job flags drift), plus 5 first-party skills authored in this repository under its own MIT licence. Every bundled skill carries a redistribution licence we actually read — MIT or Apache-2.0 — with its full text shipped alongside. Four Anthropic skills were de-bundled 2026-07-26 because they carry no such grant; we point at upstream instead of redistributing them.
• 🧹 Anti-bloat by design. Everything is plain Markdown/JSON you can read, edit, or delete — and the tool tells you how (--check, skill remove, uninstall).

Install

[!IMPORTANT] Not on PyPI yet — install from a clone:

git clone https://github.com/ulissesflores/claude-bootstrap
cd claude-bootstrap
bin/bootstrap.sh init --profile=universal-software      # or: uv run -m claude_bootstrap.cli init

The curl method is live now; uv / pipx / pip activate when the package lands on PyPI:

Verify: claude-bootstrap version → v1.0.0 or later. Requires Python 3.11+.

Quick start

# 1. (optional) see what kind of project this is — read-only
claude-bootstrap detect

# 2. scaffold: detect → rationale → plan → confirm → emit
claude-bootstrap init --profile data-science

# 3. health-check the install (13 checks)
claude-bootstrap doctor

# changed your mind? reverse the whole emit (keeps files you edited)
claude-bootstrap uninstall

[!TIP] claude-bootstrap init --check prints the full action plan and writes nothing — the safest way to preview.

Profiles

Single-stack repos get one profile; monorepos get a union of all detected code stacks. Adding a profile is zero-touch on the others. Each bundles skills with per-skill provenance in its NOTICE.md.

detect scans filesystem signals (*.tex → academic, torch/tensorflow in deps → data-science, package.json+tsconfig → frontend, a web framework → backend, *.tf/Chart.yaml → devops). A monorepo with several stacks in sub-projects (e.g. frontend/ + backend/) emits a single root .claude/ union — union permissions + all skills + path-scoped rules/<stack>.md — plus a thin <subdir>/CLAUDE.md per sub-project. academic stays exclusive (whole-repo). Details: docs/05-profiles.md.

What gets installed

your-project/
├── CLAUDE.md                      # project instructions (≤60-line policy)
├── PROJECT-STATE.md               # curated state (you edit; not Claude's auto-memory)
├── .gitignore                     # soft-merged with yours
└── .claude/
    ├── settings.json              # permissions allow/deny + env (profile-merged)
    ├── skills/<name>/             # curated, license-audited skills
    ├── rules/<name>.md            # path-scoped rules
    └── .bootstrap-manifest.json   # records the emit so `uninstall` reverses it safely

All files are create-only: re-running won't overwrite your edits; update writes <file>.new for review. It's just files — prune freely.

Distribution

Beyond the CLI, each curated profile is also packaged as a Claude Code plugin via a .claude-plugin/marketplace.json — so the bundles can be pulled with /plugin install.

Docs

Organized by intent — start where your need is. Full index: docs/.

Contributing

Issues and PRs welcome. Dev setup is one command (uv sync), commits follow Conventional Commits, and everything is gated by pytest + pre-commit. See CONTRIBUTING.md and the CODE_OF_CONDUCT.md.

License

MIT © Carlos Ulisses Flores. Bundled third-party skills retain their upstream licenses (MIT or Apache-2.0) — see each profile's NOTICE.md and the LICENSE.txt that ships inside every skill directory. The first-party skills in universal-software are MIT under this project's own license. Built one layer above superpowers; declares the dependency, never duplicates it.