Today · First run
Set up RepoOps from one screen
RepoOps fills in what it can detect about this machine, asks you to correct it and set the guardrails, shows you the exact files setup will write, and then runs each step against a check that step declared before it started. A step that returned is not a step that landed.
For: the engineer setting up RepoOps on a machine for the first time, and the owner who wants to know what that setup wrote and where
What it does, and why it helps
The local welcome checklist starts with a GitHub repository, checks captured evidence or a labeled demo, and opens Today. Builder Profile is no longer a setup requirement. Combined Today keeps the case queue available; select a repository for its fixes, build spend, lessons and agent workflow.
The First run tab opens on one screen of questions in four groups: Your code, Your models, Your product, Your guardrails. The repositories are already listed (the ones this instance tracks, or on a fresh machine a walk of your home directory two levels deep, at most fifty). The coding tools are already detected and each carries the depth RepoOps can read it at: Claude Code reads deep, Cursor reads blame, and a tool with no verified reader sits unchecked and reads not claimed, with the reason. A repository whose sessions nothing counted within the eight-second budget reads not counted yet, never 0. A repository the walk did not find goes in by its full path under the list: Add checks that the folder exists, holds a .git folder and sits inside the managed workspace, says which check failed, and for a folder outside the workspace offers to make its parent folder the workspace root. When Git is not installed, a notice above the questions says so, with Get Git and the demo data as the two ways on. The key is the only empty field, and it is optional. First run no longer asks what ships or by when: launch planning is not part of RepoOps.
Pressing Build my RepoOps stores the answers without the key, then opens Review repository setup: the before and after of every file setup will write into each repository. Apply reviewed setup starts the run. Each step names its verb and a declarative check over its own result; the loop calls the handler, the check decides, and the state is written to disk after every step. A verb this build cannot perform refuses the whole run before step one. A failed step stops the run, names the reason, and the page offers Fix it and resume from that step. When every step reads done, the handoff shows what it found, what runs from now on, and Open my Today page.
The pain. A setup wizard asks for things the machine already knows, then reports success because none of its calls threw. The user finds out weeks later that the key was dead, the history was never read, or the hook never installed, and cannot connect the failure to the day it started.
The point of view. Ask only what cannot be detected. Show the exact writes before making them. Let each step declare its own check and refuse to call it done on anything less. Stop at the first failure and resume there, so the user reads a reason rather than a green screen.
What gets easier. Knowing what happened. The setup log shows each step with what it verified, the facts it recorded (sessions read, files written, findings by family), and for a step that ran and declined, the note saying why. The handoff shows the numbers the run recorded and nothing it estimated.
When it helps. A machine that has RepoOps installed and at least one git repository under the managed workspace root or your home directory. A Claude Code install gives the deepest read; the run still completes with no key and with no history.
Its limits. It does not verify that a coding assistant is capturing sessions or that anything reaches a hosted team; the review dialog says so. Stack detection on a large repository overruns its budget and reads not detected. Once a run completes, the tab opens on the handoff and this tab offers no way back to the questions. Sentry is not connected here; the handoff links the Settings flow.
Understand it in 30 seconds
Read the narration
- 0:00 Setup finished. Every step reads green.
- 0:04 Did anything land on this machine?
- 0:06 Every step declares what its result must satisfy.
- 0:09 A call that returned is not proof.
- 0:13 A key Anthropic rejects stops the run and writes nothing.
- 0:16 A repo nobody counted reads not counted yet, never zero.
- 0:23 Fix it and resume from that step. Earlier work stays.
- 0:27 Then Today shows what it found.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000, then Connections in the sidebar, under Workspace tools. - Keyboard: ⌘ K, then type “First run”.
When to use it
A fresh machine with Claude Code history
Situation. You installed RepoOps on the laptop where you have used Claude Code for months. Two repositories sit under your home directory. You have an Anthropic key.
What you do. Leave both repositories checked and Claude Code checked. Paste the key. Pick None yet for errors, keep Write the fix, I approve every one and the 30 days recording window. Press Build my RepoOps, read the two repositories' file previews, press Apply reviewed setup.
What you see. The setup log fills in order: Watch followed by each repository's folder name, Read your AI coding history with the session count per repository, Seed the brain with the files it wrote, Store your model key on this machine with verified: stored equals true and validated equals true, Check attribution setup per repository, Turn on prompt and response recording with the 30-day window, the stack, and the scan with findings by family.
What it establishes. The handoff reads RepoOps is watching. with tiles for repositories watched, sessions read, open issues found and brain files seeded, each a recorded step fact. Recording is on, and the key is in the data directory's .env and live in the running server.
A key the provider rejects
Situation. The same run, but the key you pasted was revoked last month. It is well formed, so a shape check would pass it.
What you do. Nothing until the log stops. Read the failed step's reason, get a working key, paste it into the field beside Fix it and resume from, and press the button. The page reopens the review dialog, then resumes.
What you see. The step Store your model key on this machine reads failed with Anthropic rejected this key (401/403). Check it's active and has access. Every step before it keeps its done row and its facts. The data directory's .env has no ANTHROPIC_API_KEY line, because the check runs before the write.
What it establishes. The resumed run starts at the key step, not at step one, because the stored state matches the plan by step key and input fingerprint. A bad credential never reached disk, so nothing on the next boot picks it up.
Before you start
- Supported versions
- RepoOps desktop v0.3.1, the release this guide was read against. git must be on the machine: each repository is resolved with git rev-parse before anything is planned.
- Where it runs
- Local: the First run tab. The tab opens on whichever state the machine is in: a completed run lands on the handoff, a started run on the log, and only a machine with no run shows the questions. Hosted: no page. The spine marks the leaf shared, but the hosted nav carries no row for it; the hosted checklist at /team/onboarding is a different flow (connect a desktop, publish, confirm telemetry).
- Permissions
- None beyond running the desktop app. The five routes take no operator confirmation. Each selected repository, and the git root it resolves to, must be inside the managed workspace (REPOOPS_WORKSPACE_ROOT, the stored managed root, this instance's own checkout, or your home directory) or the preview and the run refuse with the reason.
- Connections
- Optional: an Anthropic key, checked once against api.anthropic.com/v1/models before it is stored. Nothing else is contacted. Sentry is not connected from this screen; answering Sentry only shapes the handoff link into Settings.
- Plan
- No plan gate. Every question and every step is available on the free desktop tier.
Configure it
- Correct the repository list.
Which repos should RepoOps watch? shows what was found with a session count or not counted yet beside each. Uncheck anything you would rather keep out, and type the full path of any repository it missed into Add a repo by its full path. The run refuses with pick at least one repo to watch if none is left.
- Correct the tool list.
Which coding tools do you use? lists each detected tool with its tier: deep, blame, or not claimed. A verified reader is checked by default; a not claimed tool is offered unchecked and you may check it. Unchecking every tool means the history step reads nothing.
- Paste the key, or leave it blank.
Your Anthropic key is optional. Everything except the LLM-backed surfaces works without it. With a key, the plan gains one step that checks it live before writing it; without one, that step is not built at all.
- Answer the product questions.
Stack is read-only and says what was detected or not detected. Error source is Sentry or None yet; no token is stored either way.
- Set the guardrails.
How much should RepoOps do without asking? is Watch only, tell me or Write the fix, I approve every one. There is no third choice: the schema has no auto-apply member and rejects anything else. Record full prompts and responses is on by default with 30 days, 90 days, Forever, or Off.
- Press Build my RepoOps and review the writes.
Review repository setup lists every file per repository with its before and after, and the note that file installation does not verify live capture or hosted delivery. Back returns to the questions. Apply reviewed setup pins the plan by fingerprint and starts the run; a repository that changed between review and run refuses with Repository files changed or the setup plan was not reviewed.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
repos | First run, Which repos should RepoOps watch? | everything found, minus what you keep out | Each kept repository gets its own Watch and Check attribution setup steps, and its history feeds the count, the scan and the seed. |
tools | First run, Which coding tools do you use? | the tiers the machine detected (deep and blame checked, not claimed unchecked) | The history step reads only the tools you leave checked, mapped to their readers; an unknown id fails validation. |
anthropicKey | First run, Your Anthropic key | blank until you have one you trust | Never written to intake.json or setup-state.json. Checked live, then written as ANTHROPIC_API_KEY to the data directory's .env with owner-only mode. |
errorSource | First run, Error source | None yet until Sentry is connected in Settings | sentry or none. It stores no token; it decides whether the handoff link carries connect=sentry into Settings. |
autonomy | First run, How much should RepoOps do without asking? | approve-each (the default) | watch or approve-each. The remediation routes read this answer from intake.json; watch stops the build stage and reports the case instead. |
transcript and retentionDays | First run, Record full prompts and responses | on, 30 days (the default) | Writes REPOOPS_DEEP_CAPTURE=1 and REPOOPS_TRANSCRIPT_RETENTION_DAYS. Choices are 30, 90 or 0; 0 means the nightly sweep never expires a transcript. Off builds no recording step. |
What you should see
The normal case
Configuration. One or more repositories, Claude Code checked, a working key, recording on at 30 days.
Expect. Every step reads done. Steps that record facts show them under the title: sessions per repository, files written, findings by family, the stack label, the retention window. The handoff tiles repeat the recorded numbers.
Verify. GET /api/onboarding/setup returns complete true with every step status done. The data directory's .env holds ANTHROPIC_API_KEY, REPOOPS_DEEP_CAPTURE=1 and REPOOPS_TRANSCRIPT_RETENTION_DAYS=30. Each repository has the managed block in CLAUDE.md and the seeded .claude/brain files.
A step that ran and declined
Configuration. A repository that already sets core.hooksPath (husky, lefthook, pre-commit) or has an active hook of its own.
Expect. The review dialog notes that brain integration can proceed and commit attribution remains partial until that hook manager is integrated. Check attribution setup reads done with an amber note giving the reason. The run continues to the transcript, stack and scan steps.
Verify. The step row carries a note and no error; its verified line reads attempted equals true. No hook file was written into that repository and core.hooksPath is unchanged.
A refusal before anything runs
Configuration. A selected repository outside the managed workspace, a plan whose fingerprint no longer matches the files, or a build missing a handler for a planned verb.
Expect. The run does not start and no state file is written. The error names the cause: outside the managed workspace, Repository files changed or the setup plan was not reviewed, or this build cannot perform followed by the verb.
Verify. GET /api/onboarding/setup still reports started false. The questions are still on screen with your answers kept.
Data and cost
- What is captured
- Two JSON files under the data directory's onboarding folder: intake.json (the answers minus the key, savedAt, version 1) and setup-state.json (per step: key, title, status, times, error, note, the verify verdict and the compact facts, plus the plan's input fingerprint). Per repository, the writes you reviewed: the managed block in CLAUDE.md and AGENTS.md, .claude/brain/INDEX.md, decisions.md, lessons/lessons.jsonl and repoops-integration.json where absent, and with the hook scope .githooks/prepare-commit-msg, lib/causal/session-trailer.mjs and core.hooksPath; with the adopt scope also .claude/hooks/repoops-briefing.mjs and a SessionStart entry in .claude/settings.json. A journal with before-images per run under the data directory's repository-integrations folder.
- Who can see it
- Local. This feature publishes nothing and reads nothing from a team. What the run turns on (recording, tracking) is governed by its own settings afterwards.
- How long it is kept
- The two answer files have no retention window and no purge route. Recorded transcripts follow REPOOPS_TRANSCRIPT_RETENTION_DAYS: the nightly sweep strips prompts and responses past the window and keeps the cost record; 0 disables the sweep.
- What leaves the machine
- One GET to api.anthropic.com/v1/models with the key in the header, only when you supplied a key, and only to decide whether to store it. The error text never carries the key. Nothing else leaves the machine during a first run.
- What it costs
- No model call. The key check bills no tokens. The scan and the stack detection are local reads.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| A repository reads not counted yet. | Its session count overran the eight-second budget or its reader threw. Neither is evidence of an empty repository. | Leave it checked; the history step counts it during the run and shows the number per repository. |
| Stack reads not detected. | Detection on the first repository overran its eight-second budget, which it does on a large repository (LDG-0356). | Nothing on this screen. The run's own stack step has no budget and records the label if it finds one. |
| The run refuses with Repository files changed or the setup plan was not reviewed. | A reviewed file or the repository's git config changed between Apply reviewed setup and the run, or the resume was sent without the reviewed fingerprints. | Press the button again to open a fresh review, read the new before and after, and apply that one. |
| Selected repository is outside the managed workspace. | The path, or the git root it resolves to, is outside REPOOPS_WORKSPACE_ROOT, the stored managed root, this instance's checkout and your home directory. | Move the repository under one of those roots, or set REPOOPS_WORKSPACE_ROOT to a root that contains it, then reload the tab. |
| The run stops at Store your model key on this machine. | The key is malformed, Anthropic answered 401 or 403, or Anthropic could not be reached. The reason names which. | Enter a working key beside Fix it and resume from and press it. Nothing was written for the rejected key. |
| After a reload the resume asks for the key again. | The key is held only in the page while it is open. Without it the resumed plan has one step fewer and cannot match the stored state. | Re-enter the same key so the plan keeps its shape and resumes at the failed step instead of starting over. |
| Check attribution setup shows an amber note. | The repository has its own hook manager or hooks directory; the step ran and preserved it. | Nothing required. Integrate the Session-Id hook into that manager if you want commit attribution beyond the commit. |
| The tab opens on the handoff, not the questions. | setup-state.json records a completed run, and the tab resumes into the machine's real state. | Change the key, the recording and the tracked repositories in Settings. See Delete below for the answer files. |
- Disable
- Nothing to disable. The run is a request you start, and it ends when its last step is done or its first step fails. What it turned on has its own switch afterwards: Prompt and response recording in Settings, the key under Anthropic API key in Settings.
- Roll back
- Not provided from this tab. The files written into a repository stay; their before-images sit in the run's journal under the data directory's repository-integrations folder, and the repository is under git. lib/install/repository-integration.mjs has an uninstall inspection that lib/routes/repos.mjs exposes, but the First run tab has no control for it.
- Revoke access
- The key: Settings, Anthropic API key, the remove action, which asks Remove the saved Anthropic API key from this machine's data dir? and deletes the line. Rotating the key at Anthropic is your own step.
- Delete
- Not provided. No route deletes intake.json or setup-state.json; they sit in the data directory's onboarding folder. Removing setup-state.json by hand is what would show the questions again, and this guide names the file rather than pretending a control exists.
Related tasks
Maintenance evidence
- Feature id
first-run(spine leaffirst-run)- Owner
- Founder launch loop program (WS1 intake, docs/plans/founder-launch-loop.md; the handoff rows from ARL-WS1 and ARL-WS6). Guide: LDG-0717. Launch questions and plan retired by the product focus program, LDG-0947.
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-24, launch questions and plan step removed and the handoff re-read in public/first-run.html; the desktop first-run flow (harness/flows/desktop/first-run.flow.mjs) passed against an isolated start:verify instance. Earlier sections 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source (public/first-run.html) and the Settings tab source (public/settings.html); the routes, the schema, the store, the step list, the executor, the handlers and the key check read in lib/; no live instance was run for this guide.
- Example fixtures
- No fixture file; the shapes are inline in lib/onboarding/setup-job.test.mjs (the step list, the verify, the resume), lib/onboarding/setup-executor.test.mjs (the refusal, persist after every step, no input in the state, the trailer note), lib/onboarding/setup-handlers-key.test.mjs (the live key check writes nothing on a reject), lib/onboarding/intake-schema.test.mjs, lib/onboarding/intake-store.test.mjs, lib/onboarding/prefill.test.mjs, lib/onboarding/repository-setup.test.mjs, lib/routes/onboarding-intake.test.mjs (the budgets and null over zero) and lib/routes/onboarding-setup-reliability.test.mjs (the fingerprint, the stale preview, the zero-repo request).
- Source references
lib/onboarding/intake-schema.mjs,lib/onboarding/intake-store.mjs,lib/onboarding/prefill.mjs,lib/onboarding/setup-job.mjs,lib/onboarding/setup-executor.mjs,lib/onboarding/setup-handlers.mjs,lib/onboarding/repository-setup.mjs,lib/routes/onboarding-intake.mjs,lib/install/repository-integration.mjs,lib/capture-tiers.mjs,lib/byok-verify.mjs,lib/byok.mjs,lib/routes/transcript-settings.mjs,lib/routes/ai-incidents.mjs,public/first-run.html,public/settings.html- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Story script written 2026-09-15; render and review pending in the same slice.
Last updated