BTSBTS

Claude Code Skill

bts-setup is a Claude Code skill that takes a repository from nothing to a live pull-request preview on BTS. It reads your code, writes the config, creates the project, connects GitHub, opens the first PR, and keeps fixing the deploy until the preview answers.

Install

For you, in every repository:

curl -fsSL https://test.buildingswell.com/install-skill.sh | sh

Or only for one repository. Commit .claude/skills/ and your whole team gets it:

curl -fsSL https://test.buildingswell.com/install-skill.sh | sh -s -- --project

The installer verifies a SHA-256 checksum and re-running it upgrades the skill in place. Prefer to look first? Download bts-setup.zip (checksum: .sha256) and unzip it into ~/.claude/skills/.

Use

Open Claude Code in your repository and ask:

Set this repo up on BTS

or run /bts-setup. The same skill also extends an existing setup (“add the worker to BTS”, “why is my preview failing?”).

What it does

  1. Logs in. It prints a link; you click Approve in the dashboard. The API key lands in ~/.bts/credentials.json (mode 0600) and never appears in the chat.
  2. Maps your codebase. Services, workers, migrations, databases, queues, env vars, and blockers. It works for monorepos, and for apps split across several repositories.
  3. Designs the preview and asks you. Where there's a real choice (an addon your plan doesn't include, seed data, OAuth callbacks, multi-repo without Enterprise), you get the options with their trade-offs, and you decide.
  4. Writes the files. A Dockerfile.bts per service (your existing Dockerfiles are left alone), nexos.yaml, and a gitignored .env.bts.local for secrets that you fill in yourself.
  5. Creates the project, uploads secrets straight from that file, and links extra repositories.
  6. Opens the first preview PR after you've installed the GitHub App. It then watches the build and fixes failures until the preview is live.

What you'll do by hand

The skill tells you exactly when and where. The full list:

  • Sign in at app.test.buildingswell.com with GitHub, once.
  • Click Approve on the login link.
  • Install the BTS GitHub App on your repositories. The skill gives you a link preselected to exactly those repos. If you aren't an org owner, an owner approves the request. For private repos, your BTS account needs a connected GitHub account that can see them.
  • Fill in .env.bts.local with test-mode credentials for third-party services.
  • Approve each outward-facing step: creating the project, pushing the branch, and opening the PR. Nothing is created or pushed without a yes.

Good to know

  • Previews are created by non-draft pull requests. Each push redeploys, and deleting the branch removes the preview. Closing the PR alone doesn't.
  • Some features are plan-gated: multi-repo projects (Enterprise), and the Elasticsearch, ClickHouse, Redpanda and Keycloak addons (Pro). When you need one, the skill writes a ready-to-send request for your BTS admin and meanwhile sets up what your plan allows.
  • Requirements: Claude Code, bash, curl andgit. docker (local build checks) and gh (opening the PR) are optional.
  • Signing out: ask Claude to log out of BTS, or run ~/.claude/skills/bts-setup/scripts/bts logout. That also revokes the key.

After setup

For everyday operations from any MCP client (deploy, logs, env vars, SQL console), connect the hosted BTS MCP. The config it wrote is documented in nexos.yaml.

Claude Code Skill - BTS Docs