CodeMedic: Autonomous AI-Powered Build Error Detection & Auto-Repair CLI Tool

CodeMedic is an autonomous, AI-powered developer CLI tool and autonomous agent designed for automatic build error detection, linting error repair, and test suite debugging. It executes your build pipeline, parses compiler and linter output (including TypeScript, ESLint, and Jest errors), invokes an LLM to generate surgical code fixes, applies them safely with local backups, and re-runs validation checks — repeating the loop until your project builds successfully or the attempt limit is reached.

Built for developers who want zero-downtime repair cycles, automated CI/CD recovery, and production-grade error resolution without manual debugging.

Why CodeMedic?

Modern applications fail at build and deployment time for reasons that are repetitive, predictable, and ultimately fixable by a knowledgeable agent. CodeMedic bridges the gap between raw compiler output and working code — automatically.

• No more debugging the same TypeScript error twice. The agent reads the stack trace, finds the file, generates the fix, and verifies it.
• Safe by design. Every file modified gets a .opspilot.bak backup before any change is applied.
• Model agnostic. Works with DeepSeek, Claude, Gemini, GPT-4o, Llama, or any model available on OpenRouter.
• Feedback loop included. The LangGraph state machine retries intelligently until the build passes or the max attempts threshold is hit.

How it Works

codemedic rescue
      |
      v
 Run Build + Lint + Tests
      |
      v
 Any failures? ---- No ---> Build already passing. Exit cleanly.
      |
     Yes
      |
      v
 Capture and parse error logs
      |
      v
 Prompt selected LLM via LangGraph Agent
      |
      v
 Parse structured fix suggestion (JSON)
      |
      v
 Apply search-and-replace patch (with .bak backup)
      |
      v
 Re-run build to verify the fix
      |
      v
 Build fixed? --- Yes ---> Print fix details. Exit success.
      |
      No
      |
      v
 Max attempts reached? -- Yes ---> Exit with failure logs.
      |
      No
      |
      +-------------------> Prompt LLM again (next attempt)

Key Features

| Feature | Description | |---|---| | Autonomous repair loop | Runs analyze, patch, verify in a stateful LangGraph graph | | Multi-model support | DeepSeek, Claude, GPT-4o, Gemini, Llama via OpenRouter | | Framework detection | Automatically identifies your project's tooling setup | | Safe file patching | Every modified file receives a .opspilot.bak backup | | Error type parsing | Parses TypeScript, ESLint, and Jest error formats | | Dry-run mode | Analyze and report without writing any files | | Local model config | Save preferred model to .codemedicrc per project | | Markdown Reports | Automatically generates a detailed Markdown report at codemedic-report.md in the target project path and outputs clickable file URLs in the terminal to open them instantly. |

Installation

Install globally from the NPM registry:

npm install -g codemedic

Setup

CodeMedic requires an OpenRouter API key to call AI models. Set it as an environment variable before running any command.

Linux / macOS:

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

Windows (PowerShell):

$env:OPENROUTER_API_KEY="your_openrouter_api_key_here"

Or create a .env file in the project root you are targeting:

OPENROUTER_API_KEY=your_openrouter_api_key_here

Commands

codemedic hunt

Run build, lint, and test checks. Reports all failures without modifying any files.

codemedic hunt --path /path/to/your/project

codemedic rescue

Run the full AI-powered repair loop. Detects build failures, generates precise code patches, applies them, and verifies the result.

codemedic rescue --path /path/to/your/project

Options:

| Flag | Short | Default | Description | |---|---|---|---| | --path <dir> | -p | . | Path to the target project | | --max-attempts <n> | -n | 3 | Maximum AI fix iterations before giving up | | --dry-run | | false | Analyze only — no files will be written |

codemedic vibe

Interactively select which AI model to use. Fetches the current model list from OpenRouter, lets you pick one, and saves the selection to a local .codemedicrc config file.

codemedic vibe

Supported models (curated list, plus custom entry):

• DeepSeek V3 / DeepSeek R1
• Anthropic Claude 3.5 Sonnet
• Google Gemini 2.5 Pro / Flash
• OpenAI GPT-4o
• Meta Llama 3.3 Instruct

Configuration

CodeMedic reads a .codemedicrc JSON file in your target project directory to pick up model preferences:

{
  "model": "deepseek/deepseek-chat"
}

This file is created automatically when you run codemedic vibe.

Reports

Every time you run codemedic hunt or codemedic rescue, a detailed Markdown report is generated at codemedic-report.md in the target project directory. The tool prints a clickable absolute file URL and path directly to your terminal. Clicking the link instantly opens the report inside your active IDE editor with full syntax styling and Markdown Preview. The report includes:

• Pipeline Summary: Clear status checklist of your project's Build, Lint, and Test suites.
• Detailed Error Outputs: Full error logs from any failing checks.
• AI Brain Details: The exact OpenRouter model used.
• Token Usage: Accumulated prompt and completion tokens used for the run.
• Applied Fixes (for rescue): The root cause, explanation, and before/after search-replace code diffs of any patches applied.

Development Setup

Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo.

Prerequisites

• Node.js 18 or later
• pnpm

Install

pnpm install

Build all packages

pnpm build

Run commands locally without installing globally

pnpm hunt --path ./demo-project
pnpm rescue --path ./demo-project
pnpm vibe

Monorepo package structure

| Package | Role | |---|---| | packages/cli | CLI entrypoint (Commander) | | packages/core | Orchestrates build and fix flow | | packages/agents | LangGraph state machine (analyze, patch, verify) | | packages/ai-provider | OpenRouter HTTP client | | packages/analyzers | Runs build/lint/test and parses output | | packages/patcher | Applies search-and-replace patches with backup | | packages/prompts | LLM prompt templates | | packages/config | Env loading and local .codemedicrc config store | | packages/shared | Shared TypeScript types |

Error Handling

CodeMedic provides clear, actionable output for common failure modes:

| Error | Message | |---|---| | Invalid API key (401) | Prompts you to check your OPENROUTER_API_KEY | | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance | | Model not found | Displays the invalid model ID and suggests running codemedic vibe | | Patch not applied | Reports exact mismatch between AI suggestion and file content | | Max attempts reached | Exits cleanly with the last error log for manual review |

Author

Deeksha Verma

• GitHub: @Deeksha-verma
• LinkedIn: Deeksha Verma
• Email: [email protected]