Skip to content
create-bsv-app

Guides

Use it with AI agents

Let Claude Code, Cursor or any coding agent scaffold and extend BSV apps. One JSON file in, an AGENTS.md out, and docs every agent can read.

create-bsv-app was built to be driven by agents as well as people. Three things make that work: a deterministic input (--file), a generated guide in every project (AGENTS.md), and docs agents can read (Markdown at stable URLs).

Give your agent the skill#

The fastest setup is a skill: a short instruction file that teaches an agent the commands, flags and gotchas. We publish one.

mkdir -p .claude/skills/create-bsv-app
curl -fsSL https://createbsvapp.vercel.app/.well-known/agent-skills/create-bsv-app/SKILL.md \
  -o .claude/skills/create-bsv-app/SKILL.md

The CLI package also ships a smaller skill (scaffolding-bsv-apps) inside node_modules/create-bsv-app/.claude/skills/. Ours adds the troubleshooting knowledge from these docs.

Connect the docs over MCP#

These docs are also a read-only MCP (opens in a new tab) server, so your agent can search and read them mid-task instead of guessing:

claude mcp add --transport http create-bsv-app-docs https://createbsvapp.vercel.app/mcp
Tool What it does
search_docs full-text search over every section; returns page slugs and anchors
get_page one page as Markdown, by slug (tutorial, cli, troubleshooting…)
list_pages every page with its one-line summary

No auth, no state, and it only reads the published docs.

Prompts that work#

scaffold
Scaffold a full-stack BSV app called "tipjar" with wallet login and signed requests
using create-bsv-app. Run it non-interactively, then read AGENTS.md and summarise
the routes and hooks I can use.
add a feature
Using the signed-requests capability, add POST /api/tips that records
{ identityKey, amount, note } and a React form that calls it with signedFetch.
Follow the patterns in AGENTS.md and add a node:test test like
https://createbsvapp.vercel.app/docs/testing.md
existing app
Add wallet-connect and wallet-login to this repo with create-bsv-app in add mode,
then apply the "Wiring (manual)" section of the generated AGENTS.md.

Rules for agents#

  • New project: npx create-bsv-app@latest <dir> --starter full-stack --capabilities wallet-login,signed-requests --yes
  • Existing project: npx create-bsv-app@latest add --capabilities wallet-connect,<more> --yes. List wallet-connect explicitly the first time, because add mode doesn't expand dependencies.
  • Non-npm package managers: add --package-manager pnpm|yarn|bun. It isn't auto-detected.
  • Errors go to stderr, the exit code is 1, and config problems start with Invalid config:. The message says what to change.
  • After scaffolding, read AGENTS.md before writing code. It has the exact function signatures, file paths and wiring for every installed capability.

The deterministic door: --file#

Everything the prompts ask, as JSON. Same pipeline, same output, no prompts:

config.json
{
  "mode": "new",
  "name": "tipjar",
  "starter": "full-stack",
  "capabilities": ["wallet-login", "signed-requests"],
  "packageManager": "npm",
  "network": "test",
  "install": true
}
Terminal
npx create-bsv-app@latest --dir tipjar --file config.json

Every field is in the ProjectConfig reference. Check the file into your repo and the scaffold is reproducible.

What's in AGENTS.md#

Every generated project gets one at its root, rebuilt on every run:

  • Install: the exact dependency ranges added to each package.
  • Wiring: "wired automatically", or in add mode / --no-glue, the exact snippets to paste into main.tsx, App.tsx and the server entry.
  • Per capability: How it works, How it's used (files and function signatures) and Future integrations (sessions, persistence, Redis nonces and more).

Docs built for context windows#

URL What you get
/llms.txt an index of every page, with one-line summaries
/llms-full.txt the entire docs site as one Markdown file
/docs/<page>.md any page as Markdown, e.g. /docs/cli.md
any page + Accept: text/markdown the same Markdown via content negotiation
/.well-known/agent-skills/index.json discoverable skills, with SHA-256 digests
/mcp the MCP server above (card at /.well-known/mcp/server-card.json)
Terminal
curl -H "Accept: text/markdown" https://createbsvapp.vercel.app/docs/capabilities

Every page also has Copy page and Ask Claude / ChatGPT buttons, top right.