The complete Bystep tutorial, every mode, step by step

1. 1

   Create an account

   Open bystep.dev, press Get started free, then Continue with Google. The same button creates the account — there is no separate password form.

   A new account goes through three short screens: your name, where you heard about Bystep, and "What describes you best?". The last answer decides your interface.

2. 2

   Choose your interface: developer or simple mode

   	Developer mode (default)	Simple mode
   How to get it	default	pick "I am not a programmer" during onboarding, or Settings → Turn on simple mode
   Clarifying questions	up to 3 rounds (3–6 per round), written for your idea	1 round of 3
   PRD body	10 sections	5 sections, plain language
   Tech choices	yes	skipped (standard stack)
   Tabs in a project	Wiki · Tasks · Cost · Team · Studio	Plan · Build · Publish · Help
   Wording	PRD, task, phase	Plan, Step, Stage

   You can switch modes any time in Settings; existing plans stay.

3. 3

   Know the free allowance

   • Free: 1 PRD per month and 5 Bystep Agent messages per month.
   • Steps that Bystep runs for you have their own monthly allowance, depending on the plan.
   • A failed step never costs an allowance.
   • Using a template does not spend PRD quota.

   One place for the numbers

   Current prices and limits always live on the Pricing page. If a number there differs from what you remember, the Pricing page is right.

4. 4

   Learn the vocabulary

   Simple mode	Developer mode	What it means
   Plan	PRD	the source of truth for the project
   Step	Task	one piece of work with acceptance criteria, checked by machines or human review as specified
   Stage	Phase	a group of steps ending in an approval gate
   Evidence	Evidence	the result of running the acceptance criteria — not an AI opinion
   AI key	API key	your own API key, never an account login
   My computer	bystep serve	your computer runs the agent
   Reviewer	Reviewer agent	a read-only agent that reports Critical/Major/Minor findings

1. 1

   Start a new plan

   From the home screen press Plan, then choose From an idea. (Already have code? Choose From a codebase — Bystep will first ask your agent to scan the repository. Want to start from an existing site? Choose Dissect a website — see Part 1b.)

2. 2

   Write your idea

   Two or three sentences: who it is for, what the problem is, what the result should be. At least 20 characters. Enter submits, Shift+Enter adds a line.

   Under the idea box you can pick the document language (Indonesian/English) and — in developer mode — the AI model.

   Do not want to start from nothing?

   The Templates page holds real plans with at least 5 verified tasks, and using one does not spend PRD quota. The Playbooks page holds ready recipes for small shops, tutoring centres, notaries, cooperatives, clinics and foundations.

3. 3

   Decide the tech (developer mode)

   Either Let AI choose, or Pick my own for frontend, backend, database and deployment. Simple mode skips this step and uses the standard stack.

4. 4

   Answer the clarifying questions

   Bystep interviews you in rounds. It first reads your idea and reference documents and lists what it already found (those facts are never asked), then asks only the decisions it cannot make for you: 3 to 6 questions per round, each with a short title, why it matters, and a recommended answer you can accept with one click. Your answers unlock the next round, up to three rounds in developer mode; simple mode asks a single round of 3 plain questions.

   Every card has a Skip button and an Other chip for adding your own option. Use all recommendations fills the open questions of the round; Copy as questionnaire gives you a Markdown file to hand to whoever holds the answers; Start the questions over discards the interview. Ask the next round needs the current round answered or skipped; Enough, write the plan is always available once everything is answered or skipped. When Bystep has nothing left to ask it shows the shared understanding it will write the PRD from.

5. 5

   Read the PRD draft

   Bystep writes the PRD and then stops on the review page: the document on the left, the Bystep Agent on the right. A developer-mode PRD has 10 sections — Overview, Requirements, Core Features, User Flow, Architecture, Database Schema, Tech Stack, Goals & Success Metrics, Risks, and Milestones. Simple mode has 5.

   Rewriting the PRD costs quota

   Rewrite PRD discards the revisions made in chat and spends one plan credit. For small edits use Edit, or ask in the chat.

6. 6

   Revise through the Bystep Agent

   Ask in plain words, for example "add teacher attendance" or "drop payments for now". The agent rewrites the PRD and then offers a proposal to align the features.

   Proposals are grouped Added / Updated / Removed, and you press Apply or Reject. Nothing is overwritten silently.

7. 7

   Build features & tasks

   Press Build features & tasks. Bystep maps features to sub-features, then writes specs and tasks. In developer mode every feature is broken into 8–20 tasks.

   Tasks are layered on purpose: frontend tasks are 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.

8. 8

   Get to know your workspace

   View	What it is for
   Roadmap	feature map per phase; Map or Timeline, exportable as PNG/SVG/Mermaid
   Tasks	a four-column board: Queued · In progress · Done · Failed
   Wiki	codebase documentation from sync, plus the drift scan
   Cost	tokens, duration and cost per task; exportable as CSV
   Readiness	the project readiness score and the evidence report

   Open a task to see its acceptance criteria, evidence, comments, the files it owns, and a ready-to-paste prompt.

1. 1

   Open Dissect a website

   From the home screen choose the Dissect a website card, or press Plan and choose Dissect a website. Both open /plan?flow=website.

2. 2

   Fill in the form

   Website address: a bare domain is enough (for example plane.so) or a full address. Public sites over http/https on standard ports only; IP addresses, localhost and internal networks are refused.

   What do you want to build? (optional, up to 2,000 characters): the direction of your version, for example "a version for Indonesian small businesses, paid with QRIS, simpler than the original". The note shapes the idea draft and the interview.

   Your relation to this site	Meaning
   Inspiration	a site you admire
   Competitor	you want to do better than it
   Your own site	rebuilt or modernised — the interview asks what must stay the same for existing users
   Client site	a project for your client

   Pick the output language (and the AI model in developer mode), tick the usage statement, then press Dissect now. The statement is required: the dissection is for analysis and inspiration only, without imitating another site's brand, logo, text, images or distinctive look.

3. 3

   Wait for the dissection (usually 1–4 minutes)

   The first step shows the stage in progress and a live log:

   • Reading the site's robots.txt rules. If the site forbids automated tools, Bystep stops.
   • Opening the page you entered, then picking up to 12 important pages (pricing, features, product, how it works, integrations, FAQ…) from the navigation, sitemap and llms.txt.
   • Reading the pages one at a time, with a pause between them, as BystepBot.
   • Taking screenshots of up to 4 pages in an isolated browser; pages that need JavaScript are read there too.
   • The AI reads everything and writes the dissection.

   You can leave

   The work continues and the result is saved in the plan. Open it again any time from your plan history.

4. 4

   Read the dissection

   The result is grouped: Product (who it is for, the problem it solves, value propositions, business model), Features, User flows, Pricing, Data model (inferred), Detected technology, Design, Main navigation, Screenshots, Opportunities for your version, Cautions, Not visible from outside, Draft idea for your version, and What the interview will ask.

   Feature label	Meaning
   observed	quoted from a page that was read; the quote is checked to really be on that page
   inferred	the AI's conclusion that is not directly visible, such as screens behind the login or the data model

   Copy report copies the whole result as Markdown. Once the dissection is done, the draft idea for your version becomes the plan's idea, and the temporary title "Dissect <domain>" is replaced with a new one.

5. 5

   Continue to the interview

   Press Continue to the interview. In developer mode the next step is the tech choice; above it you see the technology the reference site uses, for information only — you do not have to use the same. The questions step shows a Reference website card; View dissection opens the report again.

   The interview treats the dissection as facts: what the site does is never asked again. Round 1 usually covers Version-one features (picked from the reference's features), who your version is for, the main difference, monetisation compared with the reference's pricing, and the platform. Simple mode stays one round of 3 questions; the third offers the reference's features in everyday words.

6. 6

   PRD and build as usual

   The PRD is written from your answers, not from the reference's feature list. Section 1 gets a Reference product subsection: which site served as a functional reference (not an affiliation and not a copy), what this product keeps, what it does differently, and what it deliberately leaves out. Features you dropped go to Non-goals. The PRD never uses the reference's brand name and carries no images or links from that site.

   After you read the PRD, Build features & tasks runs as usual, then you build through any path (A, B, C or Team Build). The Bystep Agent on the PRD review page also reads a summary of the dissection.

7. 7

   If the dissection fails

   What happens	Why	Do this
   Refused before it starts	an IP address, localhost, an internal network, a port other than 80/443; a bank, e-wallet or payment site; a military domain; a sign-in, checkout or payment page	enter the home page of a public site
   robots.txt forbids it	the site owner closed that page to automated tools; a robots.txt that errors counts as forbidding everything	Change URL, or Continue without dissection
   Content-Signal: ai-input=no	the site owner forbids using its content as AI input	Continue without dissection and describe your own idea
   Behind a sign-in or bot protection	the page needs a login, or a bot check/captcha appears — Bystep does not bypass it	enter the site's home or marketing page
   Site unavailable, too slow, server restarted, AI failed	a temporary problem	Try again
   Government site (.go.id)	read in light mode: 3 pages, longer pauses, no screenshots	the result is still usable

   On failure, Change URL and Continue without dissection (write your own idea, at least 20 characters, then go to the normal interview) are always there; Try again appears when the cause is temporary.

1. 1

   Turn on simple mode

   During onboarding pick "I am not a programmer", or switch it on any time in Settings → Turn on simple mode. Every screen then uses everyday language.

2. 2

   Describe the idea and read the plan

   Follow Part 1 above. In simple mode the plan is short (around 15 steps at most) and the first stage is always called "A first version you can use".

3. 3

   On the "Your plan is ready" screen, choose Build it for me

   Three doors appear: Build it for me, Guided, and On your own. Take the first.

   Opening gradually

   The automatic path is opening gradually for early users. If it is not available for your account yet, the button reads Join the waiting list and we email you. Everything else in this tutorial still works.

4. 4

   Press Build it for me on the Build page

   The Build page shows "Step n of m" and a sentence about what is being worked on. You do not need to sit and watch — close the tab, we will tell you.

   The Build with card lets you choose who pays: Bystep step credits, your own AI key, or My computer (Path C).

5. 5

   Try it on your phone

   After each stage, Open the app gives you a trial version you can open on a phone. If it fits, press Continue. If something is wrong, say it plainly: "this part is wrong, it should …".

6. 6

   When it gets stuck

   Bystep tries to fix itself up to twice, then stops and explains in plain language. Your options: retry this step, go back to the previous version, skip the step, or Ask for a review by a human from the Help page.

   Failed steps cost nothing

   The allowance is spent only on steps that actually finish.

7. 7

   Publish

   The Publish page runs a security check and then gives you a link anyone can open. After that you get Update the live app, Version history (restore a version), Download a copy (ZIP), and instructions for adding it to a phone home screen.

Prerequisites: you are inside a Git project folder, you have network access, and Node.js 18 or newer.

1. 1

   Install the CLI

   Install CLI 0.7.0 from this versioned download, then use the bystep command. The package on npm can lag behind the Bystep download:

   TerminalCopy

   npm install -g https://bystep.dev/downloads/bystep-cli-0.7.0.tgz
   bystep --version

   Want the command list without guessing? The CLI publishes a machine manifest:

   TerminalCopy

   bystep --llms
   bystep task --llms

2. 2

   Log in, bind the folder, install the skill

   Replace <workspaceId> and <planId> with the workspace and project IDs you will work on. Both are saved so subsequent task commands use the correct project.

   TerminalCopy

   bystep login
   bystep connect --workspace <workspaceId> --plan <planId>
   bystep init

   login uses a device flow: a code appears in the terminal and you confirm it in the browser (valid 10 minutes). You can also pass a token directly: login --token bs_… from Settings → API keys.

   connect writes .bystep/config.json with ids only — safe to commit. init installs the Bystep skill, the guard hook and the subagents into the agents it detects (Claude Code, Cursor, Codex, OpenCode, AGENTS.md).

3. 3

   Check the setup

   TerminalCopy

   bystep doctor
   bystep doctor --repo

   doctor checks Node, the API address, the token and the repository binding. doctor --repo scores this checkout for agent readiness, offline.

4. 4

   Run the loop

   TerminalCopy

   bystep task next --plan <planId> --json
   bystep task start <ref>
   # … the agent works on this one task …
   bystep task verify <ref>
   bystep task complete <ref>

   The server picks the next task — the agent never sees the whole backlog. task next returns a Task Packet: description, acceptance criteria, the files the task owns, files it must not touch, conventions, verify commands, and the project decisions.

   task complete runs verify first and refuses while the evidence has not passed. Failed twice? Report it honestly:

   TerminalCopy

   bystep task fail <ref> "<reason>"

5. 5

   Choose when it stops

   The default is Autopilot. Change it from the task board (Execution) or from the terminal:

   TerminalCopy

   bystep plan exec --plan <planId> --mode checkpoint --verifier local
   bystep plan exec --plan <planId> --mode strict

   Mode	Stops when
   Autopilot (default)	never waits for approval; stops when finished, failed, or after three red verifications
   Checkpoint	every time a phase + layer group is complete
   Strict	after every single task

6. 6

   Approve a stage gate

   While a gate is waiting, task next exits with code 3 and hands out no task. Approving is a human decision — an agent must never press it on your behalf.

   TerminalCopy

   bystep task approve <phase> --layer frontend
   bystep task approve <phase> --layer backend

   Name the layer

   Checkpoint gates are stored per phase AND layer. Without --layer the CLI sends "all", which matches no gate, so nothing appears to happen. Use --layer frontend or --layer backend; the hint line in the CLI output already names the right layer.

   Want to send part of the work back with a note?

   TerminalCopy

   bystep task approve <phase> --layer frontend --return <ref>:"<reason>"

   Strict mode is approved per task, and that is only possible from the web page or the hosted MCP — not from the CLI.

7. 7

   Send a codebase summary (optional, useful)

   TerminalCopy

   bystep sync --plan <planId>
   bystep status

   sync scans the repository, respects .gitignore, refuses .env and secrets, and uploads only paths, sizes, hashes and languages. Your agent writes a short summary per file locally; only the summaries are uploaded. From those Bystep builds the Wiki — and the Wiki unlocks the next plan in that workspace.

8. 8

   Already have a spec elsewhere?

   TerminalCopy

   bystep import ./spec --from speckit --workspace <workspaceId>

   Import supports Spec Kit, OpenSpec, backlog.md and Task Master.

1. 1

   Install Node.js and your agent

   Install Node.js LTS from nodejs.org. Then install your agent and sign in yourself on that computer — Bystep never copies an agent login.

   ClaudeCopy

   npm install -g @anthropic-ai/claude-code
   claude

   ChatGPT / CodexCopy

   npm install -g @openai/codex
   codex

2. 2

   Check the computer is ready

   TerminalCopy

   bystep serve --doctor
   bystep login
   bystep serve

   serve --doctor answers in plain language: the Node version, git, which agents were found and their versions, where their credentials appear to come from, the protocol version, how many parallel steps this computer accepts, and the free disk space.

   Credential source is a guess

   The "subscription" or "API key" note is inferred from the files and variables present on the computer. It is not proof of account identity.

3. 3

   Or connect with a pairing code (no login)

   On the My computer page (bystep.dev/serve), signed in, press Show pairing code. You get an 8-character code, a QR code and the command. On the target computer:

   TerminalCopy

   bystep serve --pair <8-char-code>

   The code works once and for 10 minutes only. The computer receives a key of its own, valid 90 days and renewed automatically when less than 7 days remain. A wrong, expired or already-used code gives the same message — just show a new one.

4. 4

   Point the project at that computer

   In Bystep open the Build page → the Build with card → My computer, then pick the machine. From now on Build it for me sends steps to that computer, and Bystep step credits stay untouched.

   Leave the serve window open. "Try it on your phone" keeps working as long as the computer is on and connected.

5. 5

   Tune it to taste

   TerminalCopy

   bystep serve --parallel 2
   bystep serve --runs-per-hour 6
   bystep serve --name "MacBook kantor"

   Option	What it does
   --parallel <n>	cap the team sessions this computer runs at once (1–8). Without it the computer follows the team, up to 4.
   --runs-per-hour <n>	an opt-in brake: at most n runs per hour. Off by default.
   --once	build one step, then exit.
   --dir <path>	the project folder to use (default: ~/.bystep/projects/<workspace>).
   --no-listen	turn the local listener off; agents then report only through their output.
   --yolo	let the agent run any command without asking — only on a machine you trust.

6. 6

   Keep it running in the background

   TerminalCopy

   bystep service install
   bystep service status
   bystep service uninstall

   service install runs serve as a service that restarts itself (systemd on Linux, launchd on macOS, Task Scheduler on Windows). Log in or pair first — the token is never copied into the service unit.

7. 7

   Update the CLI

   TerminalCopy

   bystep update
   bystep update --apply
   bystep update --apply --channel preview

   update on its own only checks. --apply downloads, verifies size and sha256, then installs. Restart serve or its service afterwards.

8. 8

   Which agents you can use

   Agent	On your computer	In the cloud
   Claude Code	yes	yes
   Codex CLI	yes	yes (your own API key required)
   Cursor Agent	yes	no
   Gemini CLI	yes	no
   opencode	yes	no
   Your own script (custom)	yes	no
   GitHub Copilot CLI	listed, not enabled yet	no

   An agent only works if the program is installed and signed in on your computer. The always-current list lives at /api/agents (sign-in required).

   Want to use your own script? Put an executable file in .bystep/agents/, then select it when you start an agent team:

   TerminalCopy

   # .bystep/agents/mine.sh  (Windows: mine.ps1)
   #!/usr/bin/env bash
   echo "$BYSTEP_PROMPT" | my-own-agent --run
   
   # select that script when you start an agent team:
   bystep workflow start --plan <planId> --agent custom:mine

   Bystep fills in BYSTEP_PROMPT (or BYSTEP_PROMPT_FILE), BYSTEP_RUN_ID, BYSTEP_TASK_REF, BYSTEP_API_URL and a BYSTEP_TOKEN scoped to that step. The result is read from JSON on stdout or from .bystep/out/<runId>.md.

This chapter covers collaboration between people. The Agent teams chapter covers several agents running under Bystep management. You can choose a suitable tool for each task, but a Team Build claim does not launch an agent automatically.

1. 1

   Invite the team and choose a project

   Open the workspace → Team / Team build. The owner opens Team settings to invite developers. Members must accept the invitation using their own accounts before working. Select a project at the top; draft projects can also be used.

   An invitation gives collaboration access according to the member role. Access to the owner’s computer, secrets, payment account and deployment requires separate configuration.

2. 2

   Turn a PRD, brief or codebase into agreed scope

   Starting point	What to do in Project scope
   You have a PRD	Paste text or import Markdown/plain text, then preview the requirements.
   You do not have a PRD	Choose a brief and describe the goal and initial needs. Review assumptions before approving tasks.
   You have a codebase	Connect the repository with the CLI and run bystep sync --plan <planId>. Choose codebase to inspect the file baseline, commit and scope.
   You are adding a feature to an existing project	Choose an additional plan; decide whether each requirement uses an existing task, needs an additional task or should be excluded.

   The owner reviews source and extraction coverage, edits requirements, chooses relevant verification commands and applies the approved selection. Previewing does not run commands. A file appearing in a manifest does not prove the feature works; check what is observed, verified and unknown.

   For PDFs or other formats, use extracted text and inspect its coverage. Changing scope or criteria after work starts can invalidate older context, evidence or approvals; tell the developer to fetch fresh context.

3. 3

   Assign the task owner and reviewers

   On a task card, press Assign. Choose the person responsible, a technical reviewer and a product reviewer when needed. Select Technical or Technical and product according to the team decision, and explain the assignment. A reviewer must be someone other than the task owner.

   Assignment records who is responsible. A claim records who is working on it now. Start with clearly bounded tasks; coordinate changes to shared files through branches, PRs and handoffs.

4. 4

   Claim a task, then give context to your own AI

   On each developer computer, use Node.js 22 or newer and run commands from the project repository. Replace <workspaceId>, <planId> and <ref> with the actual workspace ID, project ID and task reference. Supply both IDs when connecting a new repository:

   TerminalCopy

   npm install -g https://bystep.dev/downloads/bystep-cli-0.7.0.tgz
   bystep --version

   TerminalCopy

   bystep login
   bystep connect --workspace <workspaceId> --plan <planId>
   bystep team tasks --mine

   TerminalCopy

   bystep team claim <ref> --agent codex
   bystep team context <ref>

   Replace codex with your tool name, or manual for work without AI. After the claim succeeds, fetch context and give it to your chosen tool. Start the AI yourself with your personal login. The agent name on a claim records the tool; Bystep does not copy AI logins or subscriptions. If using a daily budget or shared resources, use the resources.json claim example in the budget step below.

   One active claim per task

   Claims last 15 minutes by default. Extend the lease while working, before it expires. Do not start editing a task still claimed by someone else. Add .bystep/team-claims/ to .gitignore; each developer keeps their own claim state. Use the same repository when switching between CLI and MCP.

5. 5

   Verify the revision, refresh context, then report

   Finish the changes at a known Git revision, run the agreed checks and ensure evidence refers to that same commit. Fetch context again after verification records the latest revision. If sources, rules, decisions or scope changed, review the impact and update the work before reporting:

   TerminalCopy

   bystep team heartbeat <ref>
   bystep task verify <ref>
   bystep team context <ref>

   Create report.json. Replace every <…> value in this example: acceptanceHash from the latest context, the full commit SHA, a truthful summary of the work and checks, and the verification evidence ID. Do not submit placeholders or claim tests passed before running them.

   report.json — example for code workCopy

   {
     "status": "ready_for_review",
     "acceptanceHash": "<current-acceptance-hash>",
     "commitHash": "<full-commit-sha>",
     "summary": "<summary-of-work-and-checks>",
     "evidenceIds": ["<verification-evidence-id>"]
   }

   TerminalCopy

   bystep team report <ref> --file report.json

   Use blocked or failed with an explanation when the result is not ready. Tasks whose criteria are all manual can be submitted to an independent human reviewer; they do not receive an automatically verified test label. Code criteria still require matching passing evidence.

   If a report is rejected

   Check the claim lease, assignment, context and revision. Older session results are rejected after a claim is relinquished, replaced, expired or revoked. To retry an identical request, retain the idempotencyKey returned by the CLI and reuse it with --key; a different payload needs a new key.

6. 6

   Get an independent review of that result

   The reviewer opens My reviews and checks the criteria, code changes, test results and evidence. Accept the result or request changes with a note. When the policy requires technical and product reviews, both must be satisfied.

   A review is bound to the criteria, commit and PR revisions assessed. Later changes require evidence and review matching the latest version. AI can assist a reviewer, but a decision through CLI or MCP still uses the identity of the human giving the instruction.

   State	What it means
   Verified	Machine checks passed for the relevant criteria and revision.
   Accepted	The review policy is satisfied for the current result.
   Override	The owner recorded an exception; it remains distinct from an accepted or verified result.
   Released	The owner recorded a deployment of the accepted result.

7. 7

   Record a release after deployment is complete

   After acceptance, deploy through the process agreed by your team and check the application. The owner then presses Record release on the task and enters the environment and deployment URL. The record binds the release to the accepted criteria and revision and appears in the history.

   Recording a release does not deploy it

   Record release does not send code to hosting or grant access to a deployment account. If merging produces a different SHA, update evidence and review for the merged revision before recording its release.

8. 8

   Hand over context when changing people or tools

   Before leaving the work, write handoff.json with goal, completed, the current acceptanceHash, commitHash if available, and nextSteps (a list). Add toUserId, branch, evidenceIds, checks, risks or decisions when relevant. A handoff ends the claim and assigns the task to toUserId; omitting it leaves the task unassigned. The recipient must be an accepted member and cannot be a reviewer of that task.

   TerminalCopy

   bystep team handoff <ref> --file handoff.json

   Alternatively, to stop without a handoff, create reason.json with an explanation such as {"reason":"Stopping for today"}, then use this command instead of handing off:

   TerminalCopy

   bystep team relinquish <ref> --file reason.json

   Stop the external editor or agent yourself. The recipient claims the task and fetches fresh context with their own account. A handoff does not transfer a native model conversation session or an AI login.

9. 9

   Track progress in Overview

   Use My work for your own tasks, My reviews for your review queue, and the blocked filter for issues needing attention. Overview shows milestones, blockers, expired sessions, updates for your account and release history.

   Set milestone tasks and a target date, then track accepted results and recorded releases. CSV export helps evaluate activity and review time. Unknown costs and missing data still need follow-up; task counts alone do not prove result quality.

10. 10

    Connect PRs and GitHub checks when needed

    In Repositories & PRs, the owner saves a GitHub token with read access to metadata, PRs, checks and commit statuses for the relevant repositories. Register the repository and exact required check names, then Refresh from GitHub and link the PR to a task. One task can require several PRs from different repositories, each with its own SHA.

    CI is trusted from authenticated snapshots for the exact revisions. A self-reported ci label does not establish trusted CI. Refresh and review again when a PR or merge changes. A signed webhook requires separate administrator configuration; registering a repository does not install it automatically. Manual refresh remains available.

11. 11

    Configure computers and budgets when sharing is needed

    The simplest workflow uses each person’s own computer and AI. To use another member’s computer, register it through bystep serve; its owner grants a specific member, agent and expiry in AI & budgets. A claim with --file resources.json can specify the authorized executorId and executorOwnerId. A grant does not automatically start remote AI work.

    The payer provides a separate grant and daily budget. At claim time, payerId and requestedBudgetMicros set the payer and session reservation; 1 USD = 1,000,000 micros. If a daily budget is enabled, declare a reservation before starting. Actual usage is reported separately.

    TerminalCopy

    bystep team claim <ref> --agent codex --file resources.json
    bystep team context <ref>

    MCP 0.5.0 does not expose grant or reservation parameters on team_claim. For this case, create the claim through the CLI with resources.json first, then continue with MCP in the same repository so it uses that local claim.

    Unknown stays unknown

    Unreported subscription or personal costs are not counted as zero. Reservations remain held until the payer reconciles costs with a note. Bystep limits session reservations; AI usage outside the session follows the provider account. A revoked grant, offline computer or changed runtime can reject reports; revocation does not guarantee an external process has stopped.

12. 12

    Import GitLab issues while preserving local decisions

    In Issue integrations, the owner saves a GitLab.com token with read_api permission, enters group/project and chooses whether task titles and descriptions follow GitLab or Bystep. Preview issues, select them, resolve conflicts between local and remote changes, then apply.

    Import and refresh read issues from GitLab.com. Bystep execution and review status remain separate from issue status; task changes are not automatically written back to GitLab. Disabling a connection preserves created tasks. Linear, Jira and self-hosted GitLab are not available in this workflow.

1. 1

   Turn it on from the Build page

   Open the Build with an agent team panel, switch on Work on several at once, then press Start agent team. The switch appears only when your plan allows more than one.

   Advanced settings holds the number of parts at once plus the token, USD and minute limits. The cost estimate appears under the button before you press it.

2. 2

   Or drive it from the terminal

   TerminalCopy

   bystep workflow start --plan <planId> --parallel 2 --usd 5 --minutes 60
   bystep workflow list --plan <planId>
   bystep workflow show <id>
   bystep workflow message <id> "<guidance for the team>"
   bystep workflow stop <id>

3. 3

   Know the rules

   • Each step works in its own folder; steps touching the same files take turns.
   • One wave holds at most 4 steps whose owned files do not overlap. A task with no owned files counts as touching everything, so it runs alone.
   • A step counts as finished when the combined evidence passes; the stage gate still waits for you.
   • A message to the team is read on the next assignment — it never interrupts a running agent.
   • Stopping completes only after every process is proven to have stopped.

   On your own computer, --parallel caps how many parts that machine takes at once.

4. 4

   When parts collide on merge

   The team stops, Bystep creates a "Merge conflict: <ref>" task and an Inbox item "Conflict — needs you". Fix tasks always go first. Conflicts are never resolved automatically.

   A team stopped by a limit shows as "Stopped because of a limit …" in the Inbox and on the Cost page.

5. 5

   When it stops on a limit or the computer went away

   The Inbox may offer Continue in the cloud or Continue on your computer, with a cost estimate. This is never automatic: you have to press and confirm.

   In the workspace settings you choose between Ask first (default) and Never move.

1. 1

   Stop mode and verifier

   Setting	Options	Notes
   Mode	Autopilot · Checkpoint · Strict	default Autopilot; in Autopilot the checkpoint banner never appears
   Verifier	Local · Bystep Reviewer · GitHub Actions	default Local; GitHub Actions is still disabled in the interface
   Reviewer agent	Off · Auto · Always	default Off
   Gate	Critical · Major	a finding at or above the gate holds the result
   Command approvals	Off · Risky · All	default Off; own computer only

   The Bystep Reviewer verifier runs only after the local check passes, and it may downgrade a pass to a fail. When its allowance runs out the check is skipped and the local result stands.

2. 2

   The Reviewer (a read-only agent)

   After the combined result passes, an extra agent reads the changes without editing any file and reports findings labelled Critical, Major or Minor. There is no "run the Reviewer" button — it runs by itself according to the setting.

   A finding at gate level stops the team and appears in the Inbox. From the Reviewer findings panel you can press Fix all (which creates a Fix task per owning file), Re-check, or Review from scratch.

   Three similar names, three different things

   The Reviewer agent reports findings. The Bystep Reviewer verifier decides pass or fail for one step. Ask for a review is a paid human review on the Help page.

3. 3

   Command approvals

   On Risky, clearly safe commands run on their own (git status, pnpm test, ls). Anything else waits for you to press Allow or Decline in the Inbox, and you can tick Remember for this project.

   Claude Code only

   Only Claude Code can ask per command. Codex, Gemini, Cursor, opencode and custom scripts stay inside their own sandbox and are recorded as approval_unsupported. The setting also applies on your own computer only, not in the cloud.

4. 4

   Decision cards

   One question, two or three options with their consequences. Your choice becomes a project decision that every later agent reads, and a card can be answered only once.

   Check the plan looks for contradictions inside the plan and spends 1 chat message from your allowance per click.

   Decisions can also be recorded from the terminal:

   TerminalCopy

   bystep decision list
   bystep decision add "<decision>" --why "<reason>"
   bystep decision replace <id> "<new decision>"

5. 5

   See what is happening

   • Work trail: what the agent did, in plain language — messages, reading/editing/running, changed files, commands and their output.
   • Technical log: a read-only terminal view. You cannot type commands to the agent from there.
   • Why this status?: the effective state, the rule that decided it, and the last signals. Agents with no signal are marked clearly — silence does not mean working.
   • The Turn lens on the task board regroups cards into AI working, Needs you, Ready and Done. Drag and drop is off in that lens.
6. 6

   When you need to step back

   Undo this step returns files to the state before one agent turn. Files that changed again afterwards are not overwritten.

   What is not undone

   Only files on disk are restored. Task status, evidence and saved versions do not change — verify again afterwards. The same computer and project folder must be running; files over 5 MB, symlinks and submodules cannot be restored; team sessions on your own computer are not supported yet.

   When undo is not possible, use Restore version — it puts back an earlier version of the app without rebuilding it.

7. 7

   Inbox and notifications

   The Inbox collects everything waiting for you: stage gates, command approvals, failed steps, merge conflicts, Reviewer findings and decision cards. Every row has Open and Why?.

   Notifications separate "needs attention" from "finished", and can go to email, Telegram or Discord. Messages that could not be delivered are logged with the reason in the notification settings.

1. 1

   stdio MCP in Claude Code or Cursor

   Install MCP 0.5.0 from the versioned download. Install the CLI separately as in Path B, run bystep login and connect the repository first:

   TerminalCopy

   npm install -g https://bystep.dev/downloads/bystep-mcp-0.5.0.tgz

   Add the bystep-mcp executable to your agent configuration. Set BYSTEP_REPO and BYSTEP_REPO_ROOT to the same absolute path to the connected repository; both are needed so context and verification use the same folder:

   .mcp.json / mcp.jsonCopy

   {
     "mcpServers": {
       "bystep": {
         "command": "bystep-mcp",
         "env": {
           "BYSTEP_REPO": "/absolute/path/to/repo",
           "BYSTEP_REPO_ROOT": "/absolute/path/to/repo"
         }
       }
     }
   }

   From the connected repository directory, Claude Code also supports:

   TerminalCopy

   claude mcp add bystep -- bystep-mcp

   The server reuses your local CLI login and reads the plan id from .bystep/config.json. Ensure bystep-mcp is on the application PATH, or use its absolute executable path. CLI and MCP for Team Build must point to the same repository; do not share .bystep/team-claims/ files.

2. 2

   stdio MCP in Codex

   TerminalCopy

   # ~/.codex/config.toml
   [mcp_servers.bystep]
   command = "bystep-mcp"
   [mcp_servers.bystep.env]
   BYSTEP_REPO = "/absolute/path/to/repo"
   BYSTEP_REPO_ROOT = "/absolute/path/to/repo"

3. 3

   Hosted MCP for Claude.ai, ChatGPT or Cursor

   Add a Streamable HTTP connector with a Bystep API key from Settings → API keys:

   TerminalCopy

   https://bystep.dev/api/mcp
   Authorization: Bearer bs_…

   The hosted server speaks plain language: list plans, plan status, run the next step, run status, a link to try it on a phone, approve a stage, and escalate when something is stuck.

4. 4

   Available tools

   Group	Tools
   Plans & steps (stdio)	plan_get · plan_list · task_next · task_packet · task_start · task_verify · task_complete · task_fail · task_evidence_get · phase_approve · wave_next · sync_status
   Team Build (stdio)	team_tasks · team_claim · team_context · team_heartbeat · team_assign · team_report · team_handoff · team_relinquish · team_review · team_release
   Agent teams (both)	workflow_list · workflow_get · workflow_start · workflow_stop · workflow_resume · workflow_message
   Control (both)	review_submit · approval_list · approval_answer · decision_card_list · decision_card_choose · decision_list · decision_add · rules_list · state_get
   Hosted only	list_plans · plan_status · run_next · run_status · preview_url · approve_stage · escalate · task_packet

   Only on the user request

   Approving a stage, answering a command approval, choosing a decision card, and starting or stopping an agent team must never be done by an agent on its own initiative.

1. 1

   Open a Design Room

   From the home screen choose Start from a Design Room, then New room. Set the title, the session template, the room language, whether cards are anonymous, whether votes are hidden, and how many votes each person gets.

2. 2

   Invite the participants

   Press Create link. Anyone with that link joins with just a name — no account. The link is valid for 30 days, and creating a new one invalidates the old.

3. 3

   Work through the six steps

   Problem → Users → Assumptions → Ideas → Vote → Decide. Everyone adds cards (and may build on someone else card), then marks I am done with this step.

   Ideas stay hidden until the session lead presses Reveal all ideas — which needs at least three ideas. They are then clustered automatically and the session moves to voting. Votes stay blind until voting is closed.

   The AI facilitator panel can summarise, challenge, critique via personas, cluster ideas and draft hypotheses. The AI never votes.

4. 4

   Turn the result into a plan

   On the last step the session lead presses Formulate & create plan. Bystep creates a plan complete with the wizard answers and the origin trail, starts the PRD, and closes the room. A session report is available as Markdown for every participant.

5. 5

   Share the plan as a read-only link

   Share in the project header gives you a public link. Visitors see the PRD, the feature list per phase, a Proof of Done card (numbers only), and the phases you approved. Task titles and outputs are never included.

   The link is created when the dialog opens

   A share link has no password, does not expire, and cannot be revoked yet. Do not share a plan whose content is confidential.

6. 6

   Invite a client to the portal

   In the Team card enter an email, pick the Client role, press Invite and send the link. The invitation is bound to that email: the account accepting it must use the same address.

   Clients see progress per phase, evidence statistics, estimate versus actual, and the approval timeline. The only button they can press is Approve phase, with an optional note. The Client role does not consume a team seat.

1. 1

   Publish the app

   The Publish page runs a security check, then gives you a public link. After publishing you get Update the live app, Version history, Put it to sleep, Copy link, and Download a copy (ZIP).

   Publishing needs a project that can actually run (it has a package.json).

2. 2

   Keep the documentation alive

   Run a codebase sync regularly. Bystep builds the Wiki from the file summaries, and that Wiki is what unlocks the next plan in the same workspace.

   The Wiki tab has Scan drift to compare the PRD against the code that actually exists; the result becomes a proposal you Apply or Reject. The drift scan is a Pro feature.

3. 3

   Watch cost and readiness

   • Cost page: tokens, duration and cost per task; exportable as CSV.
   • Project readiness page: the readiness score and a downloadable evidence report.
   • Public agent readiness page: paste any public GitHub repository URL for a 0–100 score and eleven checks, no sign-in needed.
   • Public benchmark page: real pass rates per agent and per criterion type, not an illustration.
4. 4

   Export anywhere

   Start building offers: download the PRD (Markdown), download a ZIP, a Kiro spec, Spec Kit, OpenSpec, Backlog.md, Task Master, Claude Code Tasks, GitHub Issues, Linear, and a ready-to-paste prompt for an AI agent.

Builder is aimed at the automatic path: 20 verified steps and 2 live apps per month. There are also Campus and Facilitator plans.

1. 1

   Buy or extend

   Open Pricing, pick a plan, and complete the payment. Rupiah checkout runs on Pakasir (QRIS and virtual accounts from the major banks); USD checkout runs on Paddle with taxes included. Vouchers apply to rupiah checkout only.

2. 2

   Top up without changing plan

   Top-up	Contents	Price
   PRD	5 credits	Rp 39,000
   Chat messages	100 messages	Rp 89,000
   Runner steps	10 steps	Rp 99,000
   Reviewer	25 reviews	Rp 79,000

   Top-up credits do not expire and are used once the monthly allowance of your plan runs out.

3. 3

   Use your own AI key

   In Settings → My AI connections you can store an Anthropic, OpenAI, OpenRouter or custom API key. Test connection confirms that it works. Up to 10 connections, and usage is billed straight to your provider account, not to Bystep.

   An API key, not an account login

   Values that look like a subscription token are refused. If what you have is a Claude or ChatGPT subscription, use Path C and run it on your own computer.

When you are the agent inside a Bystep step, report your state and submit findings like this:

bystep report --state blocked --message "<what is blocking>"
bystep review submit --body '{"verdict":"…","comments":[]}'

To take one wave of at most four non-overlapping tasks:

bystep wave next --plan <planId> --json