Avirixa Project Doctor

Avirixa Project Doctor — Setup. Run. Repair. Trace.

Setup. Run. Repair. Trace.

Avirixa Project Doctor is a local-first VS Code developer tool for understanding and working with unfamiliar projects. Prepare a workspace, run or debug its frontend and backend, diagnose common problems, and trace code flow across the stack without leaving VS Code.

Built for React, Vite, Node.js, Python, FastAPI, and .NET projects—including mixed frontend/backend repositories.

Why Avirixa?

⚡ Set up with confidence — detect project components and review every proposed setup action before it runs.
▶️ Run the right component — use isolated frontend and backend terminals with commands derived from real project evidence.
🐞 Debug naturally — keep using normal VS Code breakpoints and the native debugger, with no generated launch.json.
🩺 Find actionable problems — inspect project health, environment, dependencies, configuration, and runtime failures.
🔎 See editor diagnostics automatically — view errors and warnings from installed language services without starting a manual scan.
🔗 Follow full-stack execution — trace a UI action through HTTP, FastAPI, services, dependencies, and database boundaries.

Get Started

Open a project folder in VS Code.
Select the Avirixa icon in the Activity Bar.
Choose an action under SETUP, RUNTIME, FIX, CODE, or FLOW.
Review any proposed command or file change before approving it.

Nothing runs automatically when VS Code opens.

⚡ Setup

Avirixa setup guide — open a project, choose Setup Project, then review and approve

Setup Current Project

Avirixa detects supported components in the open workspace and prepares a reviewable setup plan. Detection is based on project files—not folder-name guessing—and can identify:

Node package managers and dependency manifests
Python runtimes, dependency files, and virtual environments
Environment templates and missing local environment files
Multiple frontend and backend components in one repository

Mutating operations are previewed and require explicit approval. Existing .env files are never overwritten.

Clone & Setup

Clone a validated Git repository URL, open the cloned project, and continue through the same reviewable setup workflow. Git operations happen only after a user starts the command.

▶️ Runtime

Avirixa runtime guide — independent frontend and backend run and debug actions

Run Frontend

Avirixa detects the component directory, package manager, and available package.json development script before starting it in the dedicated Avirixa - Frontend terminal.

Run Backend

For FastAPI, Avirixa inspects Python source to locate the actual application module and instance (or a supported factory). It also prefers a component-local virtual-environment interpreter before falling back to another Python runtime. The server runs in the dedicated Avirixa - Backend terminal.

Frontend and backend terminals are isolated. Starting one does not stop, replace, activate an environment in, or send commands to the other. Development servers remain running until the user stops them or closes their terminal.

Debug

Debug Frontend uses VS Code's built-in JavaScript debugger for detected React/Vite development servers.
Debug Backend uses the native VS Code Python debugger for supported Python/FastAPI applications.
Developer-created breakpoints remain fully under the developer's control.
Avirixa creates no breakpoints and generates no launch.json.
Duplicate debug sessions for the same component are prevented.

Avirixa does not currently provide automatic Stop or Restart controls.

🩺 Fix

Avirixa diagnostics guide — project health, safe repairs, and automatic code diagnostics

Avirixa calculates a deterministic Project Health result from local project evidence and reports common setup, dependency, environment, configuration, Git, and runtime problems—without AI.

Supported repairs appear as bounded Safe Quick Fixes. A repair runs only after the user reviews and approves it. Runtime diagnostics can classify startup failures from Avirixa-owned terminal commands and recognize recovery while the development server continues running.

There is no automatic destructive Fix All.

🔎 Code

The CODE area automatically mirrors errors and warnings reported by installed VS Code language services. Diagnostics are grouped by severity and file, and each item opens the exact source range.

No manual scan is required.
JavaScript, TypeScript, JSX, TSX, Python, and other languages work when a diagnostic provider is installed.
CODE is read-only and never automatically rewrites source code.
Run Build / Type Checks opens VS Code's native build-task workflow after confirmation.
Format Selected Code applies edits from the configured VS Code formatter only to the explicit editor selection.

🔗 Flow

Avirixa FLOW guide — trace UI action through frontend, HTTP, FastAPI, services, and database

FLOW is Avirixa's full-stack code-navigation feature. It combines the active VS Code language service with conservative, bounded static analysis to show paths such as:

Register.jsx
    ↓
authService.register()
    ↓
POST /api/auth/register
    ↓
FastAPI register()
    ↓
service
    ↓
database

Depending on available source evidence, FLOW can connect:

Frontend UI callers and event handlers
Frontend services and project-owned HTTP wrappers
HTTP method and route
FastAPI endpoint
Injected dependencies
Backend services and related methods
Database, framework, and external-library boundaries

Results appear in a compact, numbered native tree. Expand only the stages and calls you want to inspect. Dynamic code that cannot be resolved confidently is left unresolved instead of being guessed.

🔒 Safety and Privacy

Project analysis runs locally against the open workspace.
Avirixa does not transmit project source or analysis to an Avirixa service.
README files and arbitrary project text are never treated as commands.
Setup and repair use structured, allowlisted actions.
Workspace mutations require explicit approval.
Existing configuration and environment files are protected from overwrite.
.env values are never read or displayed during environment detection.
Searches are bounded and exclude dependency, VCS, virtual-environment, cache, and generated directories.
FLOW and CODE analysis are read-only.
Runtime diagnostics redact common credential-shaped output before storage.

Network access can still occur after an explicit user action—for example, when a package manager contacts its registry, Git contacts a requested repository, or Winget contacts a configured source.

Requirements

VS Code 1.85 or newer
Git for Clone & Setup
Node.js and the project's package manager for Node-based setup/runtime actions
Python for Python setup/runtime actions
Microsoft Python Debugger extension for Python/FastAPI debugging

On Windows, Avirixa can offer trusted Winget Python installation choices when a compatible runtime is missing. Installation still requires explicit approval.

Commands

Open the Command Palette with Ctrl+Shift+P and search for Avirixa.

Avirixa: Setup Project
Avirixa: Clone & Setup
Avirixa: Run Frontend
Avirixa: Run Backend
Avirixa: Debug Frontend
Avirixa: Debug Backend
Avirixa: Scan Code
Avirixa: Format Selected Code
Avirixa: Run Build / Type Checks
Avirixa: Scan Project
Avirixa: Find Flow
Avirixa: Diagnose Project
Avirixa: Refresh
Avirixa: Create Virtual Environment
Avirixa: Install Dependencies
Avirixa: Create Basic .gitignore

Context menus also provide actions for opening FLOW source and viewing FIX or runtime details. Internal argument-bearing commands remain hidden from the Command Palette.

Settings

Avirixa uses normal VS Code settings:

akProjectDoctor.autoAnalyze
akProjectDoctor.showGitStatus
akProjectDoctor.showHealthScore
akProjectDoctor.excludedFolders

Historical akProjectDoctor.* setting and command identifiers are retained for compatibility; all visible product labels use Avirixa.

Known Limitations

Frontend browser debugging currently targets detected React/Vite development servers and requires a Chromium-based browser supported by VS Code's built-in JavaScript debugger.
CODE displays diagnostics from installed language tooling but does not repair source code. Formatting requires a formatter registered for the language.
C# debugging is not implemented.
Highly dynamic imports, URLs, decorators, wrappers, or runtime-generated code may not be statically traceable.
FLOW quality partly depends on the language services installed in VS Code.
Runtime diagnosis depends on terminal execution events exposed by the current VS Code version and shell integration.
Automatic Node.js runtime installation is not supported.

Development

npm install
npm run compile
npm test

Press F5 in this repository to open an Extension Development Host.

Publisher

Ajithkumar