Mimir 🧠

Mimir is an autonomous Go-Aware AI Evaluation Engine and CLI tool designed to automatically analyze, plan, solve, and validate GitHub issues across Go repositories. It leverages deep codebase intelligence and LLMs to operate as an intelligent coding assistant capable of autonomously resolving complex software engineering tasks.

Key Features

• Deep Repository Intelligence: Mimir doesn't just read files; it statically analyzes Go codebases to build deterministic package maps, function maps, interface implementations, test correlations, and call graphs.
• Issue Analysis & Deterministic Retrieval: Semantically analyzes GitHub issues using an LLM, then identifies the most relevant codebase files to patch using a strict, multi-factor deterministic scoring engine (keyword matching, function overlap, test association).
• Autonomous Planning & Patching: Generates technical implementation plans, drafts code patches targeting specific functions, and executes peer-review cycles against repository conventions.
• Self-Healing Validation Loop: Automatically runs go test to analyze test impact. If tests fail, Mimir enters a self-healing loop to re-evaluate and correct the code.
• PR Generation & Branching: Once validation passes, Mimir automatically checks out a dedicated local feature branch and generates a professional, Conventional Commits-style pull request summary (title and body).
• Interactive Error Handling: Fail gracefully with interactive terminal prompts allowing you to (r)etry failing AI steps, (c)ontinue/skip past them, or (a)bort the workflow without losing generated reports.

Prerequisites & Configuration

Before running Mimir, you must provide an API key for a supported LLM provider in a .env file at the root of the project:

# Create a .env file and add ONE of the following providers:

# Option A: Google Gemini
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-2.5-flash

# Option B: OpenAI
OPENAI_API_KEY=your_openai_api_key

# Option C: Azure OpenAI
AZURE_OPENAI_API_KEY=your_azure_api_key
ENDPOINT=https://your-resource.openai.azure.com/
DEPLOYMENT=gpt-4o
API_VERSION=2024-02-15-preview

Installation

# Install dependencies
npm install

# Build the project
npm run build

Usage

Mimir operates primarily as a CLI tool that targets specific GitHub issues.

Run on a Target Repository (Recommended)

You can point Mimir to any GitHub repository using the -r (or --repo) flag, passing the issue number you want it to solve:

# Format: npm run dev -- -r <owner>/<repo> -i <issue_number>
npm run dev -- -r expressjs/express -i 5000

Run on the Default Repository

If you omit the repository flag, Mimir defaults to operating on the gin-gonic/gin repository:

# Resolves issue #2148 on gin-gonic/gin
npm run dev -- -i 2148

Run in Server Mode

Mimir also ships with an Express server mode:

npm run dev -- serve

Generated Artifacts

After a workflow completes (or if you skip execution via the interactive prompt), Mimir dumps its thought processes into the reports/ directory:

• reports/issue-analysis.json: The extracted keywords, scope, and semantic analysis of the issue.
• reports/repo-map.json: A static map of the cloned target repository.
• reports/retrieval.json: The files surfaced by the deterministic retrieval engine with heuristic scoring reasons.
• reports/plan.json: The technical implementation plan and list of target files.
• reports/changes.json: The AI's generated reasoning, confidence scores, and raw patches for each file.
• reports/patch.diff: The combined unified diff patch for all code modifications.
• reports/function-changes.json: A mapping of which specific functions were modified in the patch.
• reports/validation.json: The results and timing of the Go-Aware validation test run.
• reports/pr.md: A fully generated GitHub pull request title and body summarizing the work done.