monadevai/fixlab

FixLab is a reusable engineering workflow for investigating, validating, and repairing software defects. It combines repository-aware diagnosis, isolated worktrees, focused tests, local application startup, Playwright browser journeys, and review evidence in one visible workflow.

FixLab is designed for applications with a React frontend and .NET backend. Application-specific commands, paths, environments, and browser journeys stay in a small repository-owned profile, so FixLab remains product-neutral.

FixLab runs through Agency Copilot or directly through GitHub Copilot CLI. It does not bundle or fork either runtime.

At a glance

Get started

1. Install a supported runtime

Agency is the default compatibility runtime:

agency --version
agency copilot

For direct mode, install and authenticate GitHub Copilot CLI, then use --runtime copilot or set FIXLAB_RUNTIME=copilot.

2. Install and initialize FixLab

npm install --global github:MonaDevAI/FixLab
fixlab chat

When no dashboard is running, chat asks for the local repository path. For a new or incomplete repository it opens the interactive onboarding agent first; after the profile becomes ready, it starts the loopback dashboard and connects. Ask it in plain language to onboard the repository, diagnose a UI or API bug, run the profile-defined React/.NET validation, and create or update the pull request. The repository-path form fixlab C:\path\to\application remains available for a direct Agency-like interactive agent session.

Example UI request:

Reproduce this React UI bug, make the smallest fix, run focused tests and
Playwright, capture evidence, and create or update the PR.

Example API request:

Reproduce this .NET API bug, make the smallest fix, run focused tests and
build, start the backend when required, verify the HTTP behavior, and create
or update the PR.

For explicit plan-first onboarding without entering the interactive shell:

fixlab onboard C:\path\to\application

The first onboarding run creates the repository-owned profile and stops for review. After configuring that profile, rerun to inspect the setup plan, then approve dependency restoration, Playwright setup, browser authentication, and dashboard startup explicitly:

fixlab onboard C:\path\to\application --yes --authenticate --start-dashboard --runtime copilot

On Windows, when Node/npm command resolution may be inconsistent, use the plan-first bootstrap from a FixLab clone:

pwsh -File scripts/install-fixlab.ps1 -Repository C:\path\to\application
pwsh -File scripts/install-fixlab.ps1 -Repository C:\path\to\application -Yes

The bootstrap discovers NVM for Windows, honors an exact repository Node pin, tests a real npm operation, and invokes the selected npm.cmd by absolute path. It never installs Node unless -InstallNode is also supplied.

If NVM repeatedly produces an incoherent runtime, install a checksum-verified portable Node runtime without changing the system PATH:

pwsh -File scripts/repair-node-runtime.ps1 -Repository C:\path\to\application
pwsh -File scripts/repair-node-runtime.ps1 -Repository C:\path\to\application -Yes

fixlab init adds the repository profile, packaged prompt commands, and the fixlab-autofix Visual Studio Code agent without overwriting existing files. fixlab dashboard starts the local loopback dashboard and opens it in the system browser. fixlab chat attaches a terminal chat to that dashboard's active job so terminal and browser interactions share one session and evidence record. When no dashboard is running, fixlab chat uses the current onboarded repository or asks for its path, starts the dashboard in the background, and then connects. Streaming activity clears and redraws the fixlab> line so partially typed input remains usable while validation continues. Background activity is buffered until the current input line is submitted. At startup, chat displays the connected repository and lets the user keep it or enter another path; a different repository starts on the next available loopback port. Common operational requests also work as plain English, including start dashboard, show status, show logs, show pull request, show evidence, and switch repository. new bug <details> creates a separate bug-fix job instead of adding guidance to the current job. Waiting jobs can be removed without interrupting the active job by selecting Remove from queue in the dashboard or typing cancel waiting job <position>.

FixLab is not yet published to the public npm registry or merged into the official GitHub Copilot plugin marketplace. Until marketplace review is complete, install it directly from this GitHub repository.

3. Start with validation-only mode

Validate an existing pull request without changing its source or updating the pull request:

fixlab prepare
fixlab setup-playwright
fixlab authenticate
fixlab validate --pr 123

See the installation guide, getting-started guide, and repository onboarding guide for complete setup instructions.

How it works

Bug, enhancement, or pull request
              |
              v
      Repository profile
              |
              v
 Intake -> Diagnosis -> Isolation -> Fix or validation
              |
              v
 Tests -> Local applications -> Browser journey
              |
              v
 Evidence, risks, and pull-request outcome

Every required stage must pass or be explicitly recorded as skipped with a visible risk. FixLab never reports a skipped or timed-out gate as successful.

What FixLab provides

• Repository-aware diagnosis that reads project instructions, inspects the effective diff, and focuses on relevant symbols and tests.
• Isolated execution using a dedicated Git worktree, owned ports, logs, and child processes.
• Focused validation through repository-defined lint, test, type-check, build, API, and browser commands.
• Early draft pull requests that become visible after focused regression checks while independent builds and browser validation continue.
• Playwright evidence including measurable assertions, screenshots, traces, failures, and explicit data-source behavior.
• Resumable workflows for authentication, genuine blockers, manual validation, and focused follow-up instructions.
• Pull-request readiness based on completed gates, effective-diff review, remaining risks, and preserved evidence.

FixLab supports three primary modes:

Example requests:

• "Validate pull request 123 without changing it."
• "Reproduce this frontend defect and capture evidence."
• "Find the smallest safe fix and run the affected tests."
• "Start the React and .NET applications and test this browser journey."
• "Prepare a pull request with the validation evidence."

Safe by design

• Application-specific behavior remains in the application repository.
• Local services bind to 127.0.0.1.
• Playwright runs on the developer or runner machine, not a shared FixLab server.
• Only FixLab-owned processes and artifact directories may be stopped or removed.
• Credentials, browser state, private endpoints, and customer data are never stored in source, prompts, logs, or durable caches.
• Authentication, unsafe-data access, deployment, and pull-request publication remain human-controlled.

Read the complete security model.

Current availability

The current GitHub release is v0.7.1. It includes:

• The dependency-free FixLab CLI.
• An Agent Plugins 1.0 package for GitHub Copilot CLI.
• An Agency-compatible agent.
• A single-user local dashboard.
• Repository onboarding templates and React/.NET examples.
• Manual and Azure DevOps work-item intake.
• Focused validation, browser evidence, queueing, metrics, and recovery.
• Command-aware summaries that retain redacted evidence while reducing the output sent back into an agent session.

The dashboard is local and bound to 127.0.0.1. FixLab does not currently provide a hosted multi-user broker, shared dashboard, or managed runner service. Detailed queue, intake, caching, metrics, authentication, runtime, and evidence behavior is documented in Architecture and Getting started.

Develop FixLab

Install reproducibly and run the repository completion gate:

./scripts/setup.sh
npm run validate

On Windows:

pwsh -File scripts/setup.ps1
npm run validate

Run the plugin from this checkout:

agency copilot --plugin-dir . --agent fixlab:fixlab
copilot --plugin-dir . --agent fixlab:fixlab

Documentation

Versioned behavior contracts are in specs/v1, and a generic repository profile is available at templates/repository-profile.json.