Install

Quick start

If you already have Claude Code and Node 20 installed, this takes about 5 minutes.

What you need: Claude Code, Node 20+, git, Python 3, and a repo. Bassclef will flag any other tool when a skill first needs one — you install it then, not now.

On macOS 13+ you're on the tested path. On Linux or WSL 2 it likely works but is untested — see Supported systems for the honest read.

1. Install the CLI:

pnpm add -g @thebassclef/lite

2. Navigate to your repo: cd /path/to/your-repo (or mkdir new-repo && cd new-repo && git init for greenfield).
3. Run bassclef init.
4. Open Claude Code: claude .
5. Inside the session, type /onboard-repo.
6. Verify: bassclef check.

Then pick your first path:

• Rough product idea? Go to Greenfield to shipped.
• Have a mock or spec? Go to the quickstart.

That's it. Details below explain what each step does.

Details

The rest of this page walks each step. Skip anything that's already clear.

Prerequisites

Install these first. Needed before you run bassclef init.

1. Claude Code CLI — where bassclef runs. Install from claude.com/claude-code.
2. Node.js 20 or newer — the bassclef CLI is a Node package. Check with node --version. Install from nodejs.org. npm ships with Node — pnpm and yarn also work.
3. git — bassclef writes files, hooks, and markers into a git repo. Check with git --version.
4. Python 3 — session-start and pre-commit hooks call python3 for JSON/YAML parsing and prose scans. Check with python3 --version. macOS 12.3+ and most Linux distros ship it. On minimal containers or fresh WSL, install via apt install python3 or your distro equivalent.
5. A repo — new or existing, empty or full of code. Both work. Greenfield? git init before Step 2.

Step 1 — Install the bassclef CLI

pnpm add -g @thebassclef/lite

The command installs the CLI as a global binary. After it runs, the bassclef command is available anywhere in your shell.

Step 2 — Navigate to your repo

cd /path/to/your-repo

If the repo does not exist yet:

mkdir my-new-product && cd my-new-product && git init

Every command from here on runs from the repo root.

Step 3 — Run bassclef init

bassclef init

bassclef init scaffolds the shape bassclef needs to run. It creates:

• .bassclef-source.json — points at the bassclef upstream release you sync from
• .claude/settings.json — wires bassclef's session-start hook
• The session-start hook itself — downloads the substrate on first session
• docs/whereami.md stub — the file bassclef reads at every session start to know project state

bassclef init does not commit anything to your repo. You review the scaffold and commit when you are ready.

Step 4 — Open Claude Code + type /onboard-repo

claude .

That opens a Claude Code session in the current directory. The first session runs the bassclef session-start hook, which downloads the substrate — around 90 skills, 60 rules, 25 hooks — into ~/.claude/skills/ and the repo's .claude/ directory.

Inside the same Claude Code session, type:

/onboard-repo

Claude Code sees the slash command and dispatches the skill. /onboard-repo walks you through the rest of the setup:

• Wires GitHub (bassclef knows the shape — repo settings, PR templates, workflow files)
• Fills in the substrate config with project-specific values
• Confirms which bassclef skills you want on session-start

Modes you can pick inside the session — type the mode after the slash command, or pick from the menu Claude offers when you type /onboard-repo bare:

• default — wires GitHub, fills whereami. What you get when you type /onboard-repo alone.
• --with-deploy-host — plus a Cloudflare Pages or Amplify deploy target.
• --with-secrets — plus a local secrets manifest. Names the env vars you use and where each one lives. Bassclef reads the names at every session start to check nothing is missing. Secret VALUES stay on your machine (or in your CI vault) — bassclef never reads or transmits them.
• --full — all of the above.
• --greenfield-from-intent — cold-start magic demo. Reads one paragraph of intent, then scaffolds personas, a lean canvas, and a starter spec in one shot. If you want the full guided chain instead (six stages, one skill per stage), head to Greenfield to shipped after this install completes.

These are session-time picks, not shell commands. You never type them at your terminal prompt.

If your git host is Azure DevOps or GitLab instead of GitHub, /onboard-repo still runs — it wires the parts that are host-agnostic and flags the GitHub-specific parts for you to translate.

Step 5 — Verify

bassclef check

That prints:

• The substrate version installed
• Which skills are wired
• Which hooks are active
• Whether the required prerequisites are present

If anything looks wrong, the failure-mode playbook has recovery steps for each class of failure.

Step 6 — Pick your first path

Two paths from here:

• Rough product idea, no spec yet? Go to Greenfield to shipped. Walks the full chain from idea through design to a PR.
• You already have a mock or spec? Go to the quickstart. 15 minutes to run your first three commands.

Auto-update posture

Auto-update is off by default. Bassclef will not fetch its own updates without you asking. See auto-update behavior for details.

What if something breaks

Every install step has a recovery path:

• bassclef init fails → check that git is initialized (git init first if not)
• Session-start hook errors → the failure-mode playbook covers the common shapes
• /onboard-repo cannot reach GitHub → check gh CLI is authenticated (gh auth status). If you haven't installed it yet, see the Prerequisites section above.
• bassclef check reports missing skills → run bassclef sync to re-pull the substrate