Manage · Dashboard quickstart
Open one dashboard for every repo
Run one supported RepoOps host, add repositories to its live store, then choose a repo and read its brain. The host is the dashboard; each tracked repository supplies the content.
For: a developer opening RepoOps for the first time, or an operator adding another repository to an existing local host
What it does, and why it helps
RepoOps has one local dashboard host and a list of tracked repositories. The packaged desktop app starts its bundled server in a separate workspace by default. A source checkout can start the same dashboard with npm run restart, which uses a dedicated runtime worktree. In either case, Settings writes a tracked repository to the local SQLite store and initializes a mirror. The repository picker then scopes the dashboard to that repo.
A tracked repo does not need a brain before it can appear. If memory is absent, use Set up memory in a repo to review the exact file plan, then apply it. Brain pages render from their markdown source per request. There is no generated HTML copy to rebuild. A self-contained portable dashboard for a repo without this host is Not provided. The source template is a stub, and the full portable host is not tracked.
The pain. A copied dashboard in each repo creates another server, another set of files, and another update path. The source tree does not ship the portable template that this approach would need.
The point of view. Treat RepoOps as the host and repositories as content. Register a repository once, keep its source files in that repository, and switch scope in the shared dashboard.
What gets easier. Starting the supported runtime, adding a repo, seeing mirror state, setting up memory with a reviewed plan, and opening the canonical markdown-backed tabs from one place.
When it helps. Use this path for the packaged desktop app, for a maintained repo-dashboard source checkout, or when adding another local or GitHub repository to a running host.
Its limits. It does not turn an arbitrary repository into its own dashboard host. Tracking does not set up memory, capture hooks, or team publishing. Memory setup is a separate reviewed action, and AI enrichment is optional.
Understand it in 30 seconds
Read the narration
- 0:00 A dashboard copy per repository sounds quick, but that portable host is unshipped.
- 0:06 Run one supported RepoOps host, then track repositories as content instead.
- 0:13 The live store records each repo, and the mirror reads its brain.
- 0:17 Missing markdown renders a placeholder until memory is set up.
- 0:23 Choose the repo, read the source, and leave portable hosting marked unsupported.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000, then Local settings in the sidebar, then Dashboard quickstart under Workspace utilities. - Keyboard: ⌘ K, then type “Dashboard quickstart”.
When to use it
Open the packaged desktop app with its own server
Situation. Another RepoOps server may already be running on the machine, or an older desktop profile may hold history you do not want moved.
What you do. Leave Settings, Desktop server, Run my own separate server on. Restart the app after changing that control. Add the repository through Connect from GitHub or Add a repo manually.
What you see. Desktop server shows the desktop and server versions, build identities, port, mode, and verification state. The control is on by default. First use copies the safe repo and settings subset; historical records remain in the original profile.
What it establishes. The desktop app uses its bundled server and separate data workspace. If identity verification fails, startup does not attach to the other listener.
Run the dashboard from a source checkout
Situation. You maintain RepoOps itself or need a local source runtime rather than the packaged desktop app.
What you do. Install dependencies under Node 20 or later, then run npm run restart from the repo-dashboard checkout. Open the loopback URL printed by the server.
What you see. The launcher creates or reuses a sibling runtime worktree, targets origin/main, reconciles dependencies when the lockfile changes, and starts a supervised server. When fetch is offline, it uses the last synced origin/main.
What it establishes. The source dashboard runs from the dedicated runtime worktree. The working checkout is not the server worktree.
Track an existing local repository
Situation. The repository is already on disk and contains a .git directory, but it is not listed in the dashboard.
What you do. In Settings, open Add a repo manually. Enter Repo path (absolute). Add optional name, branch, color, or organization values, then press Add repo.
What you see. The repo appears under Tracked repos. The route records it in the local database, detects a branch when none is supplied, initializes its mirror, and warms its index.
What it establishes. The repository appears in the picker even when it has no .claude/brain directory yet. Mirror errors remain visible on the tracked row rather than making registration look absent.
Add memory after the repo is tracked
Situation. The repository is visible, but its brain pages have no source markdown yet.
What you do. In Settings, open Set up memory in a repo. Choose the repo, press Review memory setup, inspect every proposed file, then apply the current plan.
What you see. The preview lists before and after content. A changed plan or a concurrent edit is refused. The applied brain-only scope preserves existing knowledge and instructions outside managed sections.
What it establishes. The repo gains the minimal memory files the reviewed plan named. Capture hooks and hosted delivery are still separate and unverified.
Before you start
- Supported versions
- RepoOps desktop v0.3.1. A source checkout needs Node 20 or later and its installed dependencies. The guide was checked against the v0.3.1 source launcher and desktop safeguards.
- Where it runs
- Local desktop and local source host. Hosted: Not provided for this quickstart runtime. Hosted team pages are separate views, not a browser-hosted copy of the local dashboard.
- Permissions
- Read access to the repository is enough to track and mirror it. Memory setup writes only after a current plan is reviewed. The path must be inside the managed workspace root, the app checkout, or the current user's home directory.
- Connections
- Manual local registration needs no GitHub App connection. Connect from GitHub needs GitHub authorization and network access. The preferred source launcher fetches origin when available and may run npm ci when dependencies are absent or stale.
- Plan
- No feature-specific plan gate was found for local tracking or brain-only memory setup. A managed install can still apply its own valid team binding rules before serving repository content.
Configure it
- Start a supported host.
Use the packaged desktop app with Run my own separate server on, or use npm run restart from a Node 20 source checkout. npm start and npm run brain invoke the source supervisor directly, but the README marks that path advanced and expects a worktree.
- Open the local dashboard.
The source default is http://localhost:4000. PORT overrides the config port. The server binds 127.0.0.1 by default and prints the actual URL when it is listening.
- Set the workspace boundary if needed.
Settings, Managed workspace root controls where RepoOps may clone and track repos outside the always-allowed app checkout and user home. A refused add names the configured root to widen.
- Track the repository.
Use Connect with the RepoOps GitHub App to clone selected repos into the managed root, or Add a repo manually for an existing local git repo. Runtime Settings writes the SQLite store, so no restart is needed.
- Choose the repo.
Use the repository picker at the top of the dashboard. The selected repo becomes the source for Brain and Docs routes, while the mirror follows the recorded remote and branch.
- Review memory setup when needed.
Set up memory in a repo first previews a fingerprinted plan. Apply only that current plan. This creates minimal memory and merged instruction blocks, not capture hooks or hosted publishing.
- Read and edit the markdown source.
Open Local settings, then Dashboard quickstart under Workspace utilities. Brain pages render their .md source per request. Edit the .md file in the repository; no generated prose twin exists to refresh.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
Run my own separate server | Settings, App, Desktop server | on (the default) | The desktop app uses its bundled server and separate workspace. Turning it off permits shared attachment only after an exact product, version, and build match, and applies after restart. |
Managed workspace root | Settings, Repos & accounts | the parent folder where RepoOps may clone and track your repos | Paths under this root are allowed. The app checkout and current user's home are also allowed. The source fallback is C:/Projects. |
Repo path (absolute) | Settings, Add a repo manually | an existing local git repository | The route refuses a missing path or a directory without .git, then initializes the mirror after the row is stored. |
Name (optional) | Settings, Add a repo manually | leave empty to use the folder name | This is the display name. The route derives the id from the supplied id or folder basename. |
Branch (optional) | Settings, Add a repo manually | leave empty to detect the default branch | The mirror follows this branch. A later branch change reinitializes the mirror. |
Color (optional) | Settings, Add a repo manually | leave empty for the next built-in palette color | The color distinguishes repositories in shared dashboard controls. |
Organization (optional) | Settings, Add a repo manually | the GitHub owner or organization when useful | The value is stored with the repo and projected to the browser. It is metadata, not a credential. |
PORT | source process environment | unset for repos.config.json port 4000 | A numeric environment value wins over config.port. Use a free port when 4000 is occupied. |
mirrorRoot | repos.config.json, source host global settings | C:/Projects/.repo-dashboard-mirrors (the checked-in value) | Each tracked repo gets a worktree below this root. Removing a tracked repo removes its mirror by default, not its source checkout. |
syncIntervalMs | repos.config.json, source host global settings | 30000 (the checked-in value) | The mirror schedules its next fetch and reset at this interval, including after a transient initialization failure. While the branch does not move the wait doubles, up to 5 minutes, and a change or a click on the repo sync chip resets it. |
REPOOPS_RUN_WORKTREE | source process environment for npm run restart | unset to use the sibling <canonical>-run path | Set it only when the dedicated runtime worktree needs a different path. |
What you should see
Packaged desktop, isolated by default
Configuration. Run my own separate server on, then restart the desktop app.
Expect. The app starts the bundled server on its own port and data profile. A prior server remains untouched. Safe settings and repo rows may be imported on the first isolated start, but old history stays in its original profile.
Verify. Settings, Desktop server shows isolated mode, the port, matching desktop and server identities, and Version and build verified.
Source host on the default port
Configuration. Node 20 or later, dependencies installed, npm run restart, and no PORT override.
Expect. The launcher owns a dedicated runtime worktree, starts the supervised server, and the server listens on loopback port 4000. An offline fetch falls back to the last synced origin/main.
Verify. The terminal prints the runtime worktree revision and the listening URL. Open http://localhost:4000 and confirm Settings loads.
Tracked repo with no memory yet
Configuration. Add an existing git repo through Add a repo manually and do not run memory setup.
Expect. The repository appears in Tracked repos and the picker. Routes backed by absent brain markdown show their missing state; registration itself remains valid.
Verify. Select the repo, then return to Settings. Its row shows mirror readiness or the current mirror error. Set up memory in a repo still offers a review for that repository.
Markdown-backed brain page
Configuration. The tracked repository contains .claude/brain/dashboard.README.md and no generated dashboard.README.html.
Expect. The canonical Dashboard quickstart tab renders the markdown per request. No twin generation step runs.
Verify. Open Local settings, then Dashboard quickstart under Workspace utilities. Change the markdown in the working repo, reload the page, and inspect the rendered source selected by the route.
Data and cost
- What is captured
- Tracking stores repository metadata in the local SQLite data.db and creates a git worktree under mirrorRoot. The memory scaffold writes the reviewed .claude/brain files plus managed instruction blocks into the selected working repository.
- Who can see it
- The quickstart host is local and binds loopback by default. Tracking alone does not publish repository content to a team. A separately enabled hosted or team feature has its own data contract.
- How long it is kept
- No quickstart retention knob is provided. The repo row stays in data.db until Remove. Remove deletes its mirror by default and leaves the source checkout. Scaffolded memory stays in the repository until the reviewed integration lifecycle removes or rolls it back.
- What leaves the machine
- Manual registration makes no provider call itself. Mirror initialization and refresh run git fetch against the configured remote. Connect from GitHub sends its authorization and clone requests to GitHub. The preferred source launcher also fetches origin when available and may contact the npm registry for npm ci.
- What it costs
- No model call is part of tracking, mirroring, markdown rendering, or the brain-only scaffold. The host uses local CPU, memory, and disk. Network and provider charges, if any, come from Git, GitHub, or npm under your own connection terms.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| The source server reports port 4000 is already in use. | Another RepoOps server or another process owns the port. | Stop that process or set PORT to a free port, then start again. Do not assume the listener is a compatible RepoOps build. |
| The desktop app refuses to attach to a running server. | Shared mode is off, or the product, version, or application build does not match exactly. | Turn Run my own separate server on and restart. If shared mode is intentional, update both sides until Settings reports matching identities. |
| Add repo says the path is outside the managed workspace. | The path is outside Managed workspace root, the app checkout, and the current user's home. | In Settings, change Managed workspace root to a parent of the repo, then retry. |
| Add repo says not a git repo. | The selected directory has no .git entry. | Choose the repository root. For a new project, use Birth a repo, which creates the folder when needed, runs git init, stamps the kernel, and tracks it. |
| The repo is listed, but a brain page has no content. | The repository is tracked but the source markdown does not exist yet. | Use Set up memory in a repo, review the exact plan, and apply it. Tracking and memory setup are separate actions. |
| The mirror row shows an error or stale content. | The remote or branch is wrong, the network is unavailable, credentials cannot read the remote, or a git child timed out. | Check the row's error, branch, remote, and repository access. The mirror schedules another attempt after the configured interval. |
| Editing repos.config.json did not add the repo. | The config repos array seeds SQLite only when the database is empty. | Use Settings or node bin/cli.mjs add for an existing source install. Keep repos.config.json edits for the first seed only. |
| A copied portable dashboard does not start in another repo. | The portable brain.template.mjs is a stub and the full dashboard host is not tracked. | Not provided. Run the packaged desktop app or the repo-dashboard aggregator, then track that repository. |
- Disable
- No feature-level disable is provided. Stop the source supervisor or quit the desktop app. Turning Run my own separate server off changes the desktop connection mode on the next start; it does not turn RepoOps off.
- Roll back
- Tracking has no content rollback because it does not edit the source repo. Use Remove to undo tracking. For memory setup, Settings, Maintain your repo integration can preview Undo a setup run; unchanged recorded work can be restored, while concurrent edits are refused.
- Revoke access
- Manual local tracking creates no provider credential. If Connect from GitHub was used, open its repository picker and use disconnect to forget the local token, then revoke the GitHub App authorization at GitHub if access must end at the provider too.
- Delete
- Remove under Tracked repos deletes the local database row and mirror folder by default, and leaves the actual repository untouched. It also prunes that repo's minted GitHub credential and unused per-repo adapter overrides. Memory files are separate; use the reviewed Remove this integration action for unchanged RepoOps-owned files.
Related tasks
Maintenance evidence
- Feature id
dashboard-quickstart(spine leafdashboard.README)- Owner
- Runtime repo CRUD, desktop server safeguards, and navigation Help programs. Guide: LDG-0717.
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source; startup, registration, memory review, markdown rendering, removal, and desktop isolation checked in source and tests.
- Example fixtures
- lib/routes/repos-workspace-root.test.mjs covers path bounds; lib/routes/repos-scaffold-review.test.mjs covers current-plan review and concurrent edits; lib/install/scaffold-into-repo.test.mjs and lib/install/repository-integration.test.mjs cover brain-only setup and recovery; lib/routes/mirror-files.twin-fallback.test.mjs covers markdown without twins; scripts/run-dashboard.test.mjs covers the source supervisor; installer/lib/isolated-server.test.mjs and installer/lib/server-probe.test.mjs cover desktop isolation and exact attachment identity.
- Source references
lib/canonical-spine.json,lib/canonical-tabs.mjs,.claude/brain/dashboard.README.md,package.json,README.md,scripts/run-dashboard.mjs,server.mjs,lib/routes/repos.mjs,lib/mirror.mjs,lib/routes/mirror-files.mjs,lib/install/scaffold-into-repo.mjs,lib/install/repository-integration.mjs,lib/data-dir.mjs,public/dashboard.html,public/settings.html,installer/lib/isolated-server.mjs,installer/lib/server-probe.mjs- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Narrated story rendered and published 2026-09-26 (render 51925fd37136, LDG-1018) with the breadcrumb Local settings, checked against main at 0f24215b5. One frame, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721.
Last updated