// docs
How blip works today
blip currently runs as a single free product: email-backed profile, bring-your-own Anthropic, OpenAI, or Gemini key, plain-English spec generation, optional GitHub admin connect, Blip Playbooks, and an optional dedicated memory repo in your own GitHub account.
Getting started
Create your profile and finish setup
Sign up with email, land in the dashboard, and use Profile as the hub for your account, provider selection, GitHub connection, and account actions.
- Email sign-in is handled by Clerk
- Your blip profile is created automatically on first dashboard load
- Profile shows setup status for your provider key and GitHub
- Dashboard Overview includes a private feedback inbox for bug reports and change requests
- This launch is free-only, with no paid checkout flow in the normal product experience
BYOK providers
Add the provider key you actually want to use
blip is free for now, but spec generation and runs use the provider key you save in Profile. You can currently choose Anthropic, OpenAI, or Google Gemini.
- Choose a default provider and model in Profile
- Save a key that matches the selected provider before generating specs or starting a run
- No shared server-side Anthropic or OpenAI key is required for the normal app flow
- Token counts stay visible as activity telemetry in the dashboard
Specs
Start with plain English, not YAML
Describe what you want built in plain English. blip generates the internal execution spec, branch name, budget, ordered stories, and acceptance checks for review.
- Example request: "Add search and pagination to the notes API"
- blip turns that request into an internal plan with ordered stories and concrete acceptance checks
- Advanced YAML remains available, but it is no longer the default workflow
- Attach a repo when you want repo-specific Playbooks or GitHub delivery
Blip Playbooks
Reuse what already worked
Blip Playbooks are reusable instruction packs. Suggestions from past runs surface reusable lessons, and saved Playbooks are the polished versions blip can apply automatically later.
- Saved Playbooks are your reusable library
- Suggestions from past runs are reviewable drafts, not raw run notes
- Playbooks can apply to all projects or only one repo
- Playbooks are treated as hints and validated against the current repo before blip relies on them
- Run history shows which Playbooks were actually loaded
GitHub connection
Connect GitHub only when the work needs it
GitHub is optional until you attach a repo to a spec. When you do connect it, blip requests repo, delete_repo, and user:email scopes so it can support the full repo workflow.
- Create, edit, and delete repositories on the connected account
- Create branches, commit files, and open pull requests when repo access allows it
- Capability checks run against the exact owner, repo, and base branch on the spec
- Use a sandbox account or org if you want a safer place to test broad repo permissions
Dedicated memory repo
Keep synced context in your own GitHub account
If you enable the dedicated memory repo in Profile, blip creates one private repository in your connected GitHub account. It stays separate from the project repo your spec edits.
- blip writes structured summaries, specs, result metadata, and exported Playbooks
- The memory repo is not a mirror of the full target repo
- Future runs can read supported text files back from that repo within scan limits
- Disconnecting GitHub stops future sync and readback, but does not delete the repo from your account
Run flow
Execution stays story-by-story
Each run executes your spec in sequence. blip reads repo context when available, loads only relevant Playbooks and memory files on demand, and records what was used during the run.
- Stories run in priority order
- Each story gets a fresh agent context
- Sandbox beta can run approved build and test checks after a story finishes
- Writable repos can receive branches, commits, and pull requests
- Read-only repos fall back to context and downloadable output
- Completed runs can be summarized into the dedicated memory repo
Watch mode
Re-check a spec when the base branch changes
Watch mode is opt-in per spec. blip polls the base branch, reruns read-only sandbox checks, and records a visible event log on the spec page.
- No hidden background code edits
- No silent pull requests
- Every watch check is visible in the dashboard
- Failed checks stay attached to the spec that declared them
Troubleshooting
What to check when something fails
Most setup issues come down to a missing provider key, a provider-model mismatch, an expired GitHub token, or a repo that the connected account cannot write to.
- Add a provider key in Profile if spec generation or run start fails
- Make sure the saved key matches the selected provider before you run
- Reconnect GitHub if capability checks or memory-repo access show expired permissions
- Use the runs page, working notes, and loaded Playbooks list to inspect what happened