by·step

Project documents

Bystep turns an idea or an existing codebase into a PRD, features and a layered backlog, then hands tasks to your AI coding agent one at a time through the CLI.

Looking for the complete step-by-step tutorial for every mode? Read the full tutorial.

1. Plan

Describe the idea. Bystep interviews you in rounds (questions written for your idea, each with a recommended answer; what your documents already state is never asked), then writes a PRD with ten fixed sections (five in simple mode), maps it into features → sub-features, and breaks every feature into 8–20 tasks.

Tasks are layered on purpose: every frontend task is built on mock data first, and backend tasks (schema → API → realtime) follow. You can click through the UI before a single line of backend exists.

2. Hand it to your agent

Press Start building → Prompt for your AI agent and paste the prompt into Claude Code, Cursor, Codex, OpenCode or any agent with a terminal.

The prompt logs the agent in with a personal token, binds the repo to your workspace, installs the bystep skill, and starts the loop:

npx @bystep/cli task next --plan <id> --json   # the server picks ONE task
npx @bystep/cli task start <ref>
# … work …
npx @bystep/cli task complete <ref>

The agent never sees the whole backlog — it asks for one task, finishes it, and asks again.

3. Checkpoints

Whenever the next task changes layer (frontend → backend) or phase, the agent stops and reports. You verify in the browser, then say continue. That's the whole idea: powerful agent, human decides when to move on.

4. Codebase sync (privacy-first)

npx @bystep/cli sync --plan scans the repo, respects .gitignore, refuses .env and secrets, and uploads only file paths, sizes, hashes and languages. Your agent writes a short summary per file locally; only summaries are uploaded. From those, Bystep builds a wiki and unlocks the next plan in the workspace.

5. Revising the plan

Ask the Bystep Agent to change the PRD. Every change creates a proposal (added / updated / removed) that you approve or reject — nothing is overwritten silently.

Start from a website (Dissect a website)

Have a site you admire, a competitor, or your own old site? Choose Dissect a website on the home screen or the plan chooser and paste its address. Bystep reads the site as BystepBot — robots.txt and Content-Signal: ai-input=no are honoured, nothing behind a login is read, at most 12 public pages and 4 screenshots in an isolated browser — and writes a dissection: product, features (each marked observed, with a quote checked against the page, or inferred), user flows, pricing, an inferred data model, detected technology, design, opportunities and cautions. Usually 1–4 minutes.

Continue to the interview and the interview builds on those facts: it asks which features your first version keeps, who it is for, how it differs and how it earns — never what the site does. The PRD gets a Reference product subsection (a functional reference, not a copy); dropped features become Non-goals; the reference's brand, text and images are never reused. Features, tasks and the build then work exactly as for an idea.

Limits: 3 dissections per 24 hours on the free plan, 12 on paid plans; bank, payment, sign-in and checkout pages cannot be dissected; screenshots and page text are deleted after 7 days. Step by step: tutorial, Part 1b.

6. Bystep inside your chat app (hosted MCP)

Bystep runs an MCP server at https://bystep.dev/api/mcp. Add it as a custom connector and you can steer the Runner straight from Claude.ai, ChatGPT or Cursor — no terminal, no repo, no code in the chat.

Sign in with your access key

Create a personal access key in Bystep (Settings → Access keys); it starts with bs_. Send it as the header Authorization: Bearer bs_…. When the chat app only asks for a URL, append it instead: https://bystep.dev/api/mcp?token=bs_….

A key inside a URL can end up in browser history and proxy logs, so prefer the header, never paste that URL in public, and revoke the key if you do. Bystep does not speak OAuth 2.1 yet — that is why it is a custom connector and not (yet) a directory listing in Claude or ChatGPT.

Add it

  • Claude.ai — Settings → Connectors → Add custom connector → paste the URL (with ?token=) → Connect. Custom connectors are available on paid plans.
  • ChatGPT — Settings → Connectors → Advanced → Developer mode → Create → paste the URL → save, then pick the connector in the composer.
  • Cursor — Settings → MCP → Add new MCP server → type http, URL https://bystep.dev/api/mcp, header Authorization: Bearer bs_….

The seven tools

list_plans · plan_status · run_next · run_status · preview_url · approve_stage · escalate.

They call the very same server the Bystep website calls, so your monthly steps, the stage gates and Proof-of-Done behave exactly as they do on the site. The chat itself never writes code: every tool starts Bystep's own Runner and hands you back a link.

What it sounds like

  • You: continue my salon project
  • Claude: Salon Cantik is 4 of 12 steps done. Shall I build the next one — "Customers can pick a time"?
  • You: yes please
  • Claude: Started it. … Finished. Try it on your phone: https://salon-cantik.apps.bystep.dev
  • You: works for me
  • Claude: Stage 1 approved. Starting step 5…

7. Use any AI assistant (a guide for agents)

Bystep publishes a document written for AI assistants, not for people: agent-guide.en.md (English) and agent-guide.md (Indonesian). It explains how to tell whether the user is a programmer, which door to suggest, the exact button names, and the honest limits. An assistant that reads it will not try to run npx @bystep/cli inside a chat.

If you are not a programmer, just paste this sentence into ChatGPT, Claude or Gemini:

Read https://bystep.dev/agent-guide.en.md first, then guide me step by step. I'm not a programmer.

For agents with a terminal (Claude Code, Codex, Cursor) and integrators:

  • llms.txt — the documentation index in the standard LLM format; llms-full.txt is the single-file version.
  • /api/schema — JSON: every CLI command, MCP tool (stdio & hosted), and the JSON Schema of the Task Packet and evidence payload.
  • npx @bystep/cli --llms or npx @bystep/cli task --llms — a JSON manifest built from the installed CLI itself, so agents read the exact arguments instead of guessing.

Playbooks

/playbooks lists ready-made app recipes (shop, tutoring, notary, cooperative, clinic, foundation) plus community playbooks. To share yours: put a bystep-playbook.json at the root of a public GitHub project and add the topic bystep-playbook. Fields: id, name (id/en), desc (id/en), kitId (a Bystep kit id), examples (id/en lists) (max 3), rules[] (kind always|never|ask, templateId, text (id/en)), tags[]. Public list: GET /api/public/playbooks.

8. Build on your own computer (bystep serve)

Use the Claude Code or Codex subscription you already pay for. npx @bystep/cli serve registers your computer, then picks up the steps you start on Bystep, runs the coding agent locally with your own login, verifies the acceptance criteria and reports the proof back — no Bystep step credits are used. "Try it on your phone" is served through a Bystep link to the app running on your computer. Plain-language setup: bystep.dev/serve. Check readiness with npx @bystep/cli serve --doctor.