repo-control

A local-first command center for multi-repository workspaces.

When work spans several repositories, the important state is scattered across terminal tabs, Git clients, Docker commands and local AI-agent sessions. repo-control turns one workspace folder into a live operational view: what is clean, what is drifting, what needs attention and which action is safe to run next.

npx repo-control ~/projects

On Windows (PowerShell), install Node.js and Git for Windows, then run:

npx.cmd repo-control "C:\Users\YourName\Projects"

Replace the folder with your own workspace. Setup helps you confirm it, check optional tools and open your first repository. Docker, VS Code and agent CLIs are optional. Native Windows does not require WSL.

Using npx.cmd avoids PowerShell script-policy errors; changing your execution policy is unnecessary. After installing Node.js or Git, open a new terminal so it picks up the updated PATH.

Try the interactive demo — a fictional workspace that stays entirely in your browser.

_{Dashboard triage → customize the widgets → open the repository that is behind → branches → scoped terminal → Ctrl+P search → back to the dashboard. Captured from the live v0.14.0 application on a small demonstration workspace of seven repositories with realistic states (dirty trees, a branch behind, a commit to push); click the GIF for the full-quality video.}

The problem

A normal multi-repository workflow creates three recurring costs:

• State is fragmented. Dirty trees, ahead/behind branches, recent activity, running containers and agent conversations live in different tools.
• Context switching is expensive. Routine work means repeatedly finding a folder, opening a terminal and reconstructing the repository context.
• Automation can become unsafe. Broad scripts are fast, but a command executed in the wrong directory can be destructive.

repo-control keeps the convenience of a dashboard without moving control to a remote service.

The core workflow

1. Point repo-control at a workspace folder. It discovers Git repositories recursively while skipping common dependency and build directories.
2. Triage clean, modified, behind and ahead repositories from the Dashboard.
3. Jump to a project with Ctrl+P; its Overview surfaces working-tree health, sync drift, Docker state and recent commits before any action is needed.
4. Inspect a file diff, prepare a commit, work with branches, run a terminal command or operate Docker without leaving the selected repository boundary.
5. Find a local agent conversation associated with a discovered repository and resume it in a native terminal.
6. Turn repeated operations into visual workflows that can be previewed, monitored and cancelled.

Why this is more than a dashboard

• Local-first safety boundary. The Fastify API binds to 127.0.0.1 by default, resolves project identifiers server-side and scopes project commands to discovered repositories.
• Real developer operations. The UI reads actual Git and Docker state and exposes explicit actions instead of simulating a project-management view.
• Private session discovery. Agent history is read from the CLI files already on the machine, filtered to the active workspace and searched locally.
• Failure-aware automation. Background runs expose live step results, can be cancelled, and drop a repository that fails out of the steps that follow while the rest of the workspace carries on.
• Verifiable engineering quality. Server tests, React Testing Library, 80% coverage thresholds and Playwright browser flows run in CI across Node.js 20, 22 and 24.

Main capabilities

The Docker runtime page opens a console on any running container: a Shell tab holding a live docker exec session, where the working directory and environment persist between commands, and a Logs tab following docker logs. The shell is a pipe rather than a terminal, so full-screen programs such as vim or top do not work; everything else does. Sessions live in the server's memory, are capped in number, and are closed when the dialog closes, when the server stops, or after 15 minutes without a reader.

The repository Docker tab is capability-driven and appears only for repositories with a Compose file. Workspace-level Docker navigation is shown only when the Docker CLI is available. Docker and VS Code are optional; their controls require the corresponding local tool. There is no speculative Deploy tab: a future CI/CD tab should appear only after repo-control detects a supported pipeline for that repository.

Agent session discovery

The Agent sessions page reads the standard local histories created by Codex, Claude Code and Gemini CLI. Only conversations whose working directory belongs to a repository discovered in the active workspace are shown. Search runs on the local API and results are not copied into repo-control's configuration directory.

Resuming a session requires the matching CLI and a supported graphical terminal. repo-control auto-detects common terminals on Linux, macOS and Windows; under WSL it opens Windows Terminal in the current distribution when available. Command and terminal paths can be overridden through environment variables.

Runtime inputs for automations

Add a Text input node when a workflow needs a value at launch, then reference its key from a terminal node with {{inputs.key}}. Preview and execution both prompt for required values. repo-control passes each value through an execution-scoped environment variable instead of concatenating raw text into the shell command.

Workflow runs execute in the background and report pending, running and terminal states. Only one run per workflow can be active at a time. A server restart marks unfinished runs as interrupted rather than silently leaving them active.

A step that fails removes that repository from the steps that follow, and the remaining repositories continue: a sweep across a workspace is worth running only if one broken clone cannot cancel the rest of it. The Summary node always runs and reports what happened, including which repositories failed. Nodes explain themselves when they cannot act on a repository rather than failing: no Compose file, no upstream for the current branch, or a Pull a branch node whose branch is not the one checked out.

Architecture at a glance

flowchart LR
    UI[React + TanStack Query] -->|localhost /api| API[Fastify API]
    API --> Boundary[Workspace and project boundary]
    Boundary --> Scan[Git repository scanner]
    Boundary --> Git[Git services]
    Boundary --> Commands[Terminal, Docker and VS Code]
    API --> Agents[Local agent session index]
    API --> Workflow[Workflow runner]
    Workflow --> Git
    Workflow --> Commands
    API --> Local[(Local preferences, command and run history)]
    Agents --> CLIs[(Existing CLI histories)]

The browser never chooses an arbitrary working directory for a project command. It sends a project identifier; the server resolves and validates the corresponding path under the active workspace. See Architecture for module boundaries, persistence and placement conventions.

Try it in one command

Requirements: Git and Node.js 20.19+, 22.13+ or 24+ (Node 24 recommended).

npx repo-control ~/projects

That starts the API, serves the dashboard from the same port and opens http://127.0.0.1:3747. With no folder argument repo-control scans the current directory, and the workspace can be changed from the UI without restarting the server.

repo-control [workspace] [options]

  -p, --port <port>    Port to listen on (default 3747)
      --host <host>    Address to bind (default 127.0.0.1)
      --no-open        Do not open the dashboard in a browser
  -v, --version        Print the version
  -h, --help           Show usage

To keep it around, install it globally with npm install -g repo-control and run repo-control.

Run from source

Contributors and anyone who wants the Vite dev server:

git clone https://github.com/LorenzoVicino/repo-control.git
cd repo-control
npm ci
REPO_CONTROL_ROOT=~/projects npm run dev

Open http://127.0.0.1:5173. In this mode Vite serves the UI and proxies /api to the Fastify process on port 3747. The npm version is pinned via packageManager and installed by CI; match it locally before regenerating the lockfile. npm start runs the packaged layout instead, serving the built dashboard from the API port exactly as the published binary does.

For optional integrations, install the tools you intend to use:

• Docker CLI with Compose for container discovery and Compose actions;
• VS Code with a working code launcher for Open in VS Code;
• Codex, Claude Code or Gemini CLI for session resume.

Configuration

Copy .env.example to .env when local settings should live outside the command line. npm run dev:server loads this file when present.

Server and workspace

Sign-in

repo-control opens straight into the workspace by default. Setting both credentials below turns on a sign-in screen and closes every /api route to callers without a session, which is what you want when the machine is shared, screen-shared or left unlocked.

# .env
REPO_CONTROL_AUTH_USERNAME=owner
REPO_CONTROL_AUTH_PASSWORD=choose-a-long-unique-passphrase

• Both variables must be set together. With only one, the server refuses to start rather than leaving an API you believe is protected wide open.
• The session is an opaque token in an HttpOnly, SameSite=Strict cookie. It lasts 12 hours, or 30 days when Remember me is used, and lives in the server's memory only: restarting repo-control signs everyone out.
• Five wrong answers pause sign-in for 30 seconds.
• Sign out from the Profile tab at the bottom of the sidebar, which also holds the settings section and the palette switch. With no credentials configured the same tab reports the local mode and simply has nothing to sign out of.
• GET /api/health stays reachable without a session so a supervisor can probe the API, and answers { "ok": true, "authRequired": true } without naming the workspace folder.
• There is no recovery flow. Change the values in .env and restart.

Local tools and agent CLIs

repo-control also respects CODEX_HOME and CLAUDE_CONFIG_DIR when locating those tools' existing session histories.

If the development API runs somewhere other than http://127.0.0.1:3747, export REPO_CONTROL_API_URL in the shell before starting Vite. This development-only proxy setting is not loaded from the root .env by the server process.

Local data

repo-control stores its own data outside Git by default:

• Windows: %APPDATA%\repo-control
• macOS: ~/Library/Application Support/repo-control
• Linux/WSL: ${XDG_CONFIG_HOME:-~/.config}/repo-control

The directory contains preferences.json, terminal-history.json, workflows.json and workflow-runs.json as those features are used. Terminal command suggestions persist in terminal-history.json; the visible terminal transcript stays mounted while its repository remains open, but is not written to disk. Workflow history includes command output and retains at most 100 runs. Older task-engineering data, if present, remains in the brain/ subdirectory. Interface choices - palette, text size and language - are kept in browser local storage rather than on the server, so they follow the browser and not the workspace.

Windows with WSL

For launches from a Windows .bat through WSL, use the bundled startup script:

./scripts/start-repo-control.sh

It loads nvm when available, validates the Node.js version, installs dependencies and starts the app. This avoids the outdated system Node.js that non-interactive WSL sessions can otherwise select.

Safety and privacy model

repo-control can execute Git, Docker and terminal commands on your machine. Its safety model is intentionally narrow:

• the API and Vite development server bind to localhost by default; a sign-in is available for shared machines but is not a substitute for staying on loopback;
• project commands are resolved against repositories discovered under the active workspace;
• branch changes are rejected for dirty repositories, pull uses --ff-only, and force push or implicit discard flows are not exposed;
• only one terminal command per repository can run at a time, and its active process tree can be cancelled from the repository terminal;
• workflow execution is blocked when the visible graph is invalid, downstream steps stop after a command failure and active runs can be cancelled;
• agent search reads local transcript content, but only returns matching summaries or snippets for sessions associated with the active workspace;
• credentials and workspace content stay local unless a command or resumed external tool sends them elsewhere.

Do not expose the web server or API to a public or untrusted network. Review terminal commands and automation definitions before running them, and remember that saved terminal history and workflow output may contain sensitive values. See Security for the supported trust boundary.

Engineering checks

npm run verify
npm run test:e2e

verify runs ESLint (including React Hooks rules), strict TypeScript checks, server and React tests with 80% coverage thresholds, and the production build. test:e2e starts the real local API and dashboard, then exercises critical browser-to-API flows in Chromium.

CI repeats the verification gate on Node.js 20.19, 22.13 and 24, then runs the browser suite on Node.js 24.

Releases

Release notes are published in CHANGELOG.md and on the repository's GitHub Releases page. While the UI is open, repo-control checks the tags on origin for a newer semantic version and can update a clean local checkout from the app. In-app updating applies only to a Git checkout: an npm install has no repository to pull, reports so in the UI, and is upgraded with npx repo-control@latest or npm install -g repo-control@latest.

Contributing and license

See CONTRIBUTING.md before sharing changes. repo-control is released under the MIT License.