{"id":50469929,"url":"https://github.com/shunobies/lean-ai","last_synced_at":"2026-06-01T10:00:36.227Z","repository":{"id":341940076,"uuid":"1172110870","full_name":"shunobies/lean-ai","owner":"shunobies","description":"Local AI (LLM) Ollama Tool and Extension. It's a hammer /approve /reject are your friends.","archived":false,"fork":false,"pushed_at":"2026-05-31T21:38:07.000Z","size":5833,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-31T23:13:04.455Z","etag":null,"topics":["agentic-ai","agentic-workflow","ai-agents","chatgpt-api","claude-api","llm","vscode-extension","vscodium-extension"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shunobies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T00:32:26.000Z","updated_at":"2026-05-31T21:38:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shunobies/lean-ai","commit_stats":null,"previous_names":["shunobies/lean-ai"],"tags_count":140,"template":false,"template_full_name":null,"purl":"pkg:github/shunobies/lean-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shunobies%2Flean-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shunobies%2Flean-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shunobies%2Flean-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shunobies%2Flean-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shunobies","download_url":"https://codeload.github.com/shunobies/lean-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shunobies%2Flean-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33753934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-workflow","ai-agents","chatgpt-api","claude-api","llm","vscode-extension","vscodium-extension"],"created_at":"2026-06-01T10:00:21.350Z","updated_at":"2026-06-01T10:00:36.221Z","avatar_url":"https://github.com/shunobies.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lean AI\n\n**Your codebase already has an architect. It just needs tools.**\n\nLean AI is an agentic coding assistant that reads your project, plans changes, and executes them — all inside your editor. Give it a task in plain English, review the plan, and watch it work.\n\nRun it fully local with [Ollama](https://ollama.com), or connect to OpenAI and Anthropic when you need heavier reasoning. Switch between models mid-session from the UI. No cloud account required to get started.\n\n![Example](Example.png)\n\n## Why Lean AI?\n\n- **Plan first, then execute** — a 6-phase planning pipeline reads your codebase, traces data flow across files, and produces a structured plan before touching any code. You approve (or revise) before anything changes. Thinking and content tokens stream in real-time during every planning phase so you can follow the agent's reasoning as it works.\n- **Learns from your corrections** — every time you reject a plan, every time a test fix works, every TDD dispute, Lean AI extracts a short lesson and offers it to you as an inline chip in the chat (\"Remember this?\"). Confirmed lessons are read back into future planning so the tool stops repeating the same mistakes. [Curated Memory](docs/curated-memory.md)\n- **Training archive for future fine-tuning** — every workflow decision is captured locally in an append-only archive behind a fail-closed secrets scrubber. Opt in to export via a bearer-token API when you're ready to ship a LoRA adapter for your expert model. [Training Pipeline](docs/training.md)\n- **Multi-provider flexibility** — Ollama for free local inference, OpenAI for GPT-4o, Anthropic for Claude. Switch from the dropdown without restarting. Use cheap local models for small fixes, cloud models for hard problems.\n- **Dual-model pipeline** — run a fast local model for codebase exploration and code execution, then automatically hand off to a cloud model (Claude, GPT-4o) for reasoning-heavy planning phases and complex fix attempts. Save cloud tokens for the decisions that matter.\n- **Role tuning per model** — Lean AI can calibrate the `request`, `primary`, and `expert` roles to the exact model assigned to each one, persist the winning contract under `.lean_ai/role_tuning/`, and automatically reuse it on future runs. Tuned guidance is applied as a scoped prompt override, so one model can behave differently from another without replacing your global prompt customizations.\n- **Local Refiner** — when using cloud providers, a local Ollama model pre-processes your prompts: enriches them with private reference library context, strips sensitive data, and structures vague requests into detailed specs. Your proprietary docs never leave your machine. [Learn more](docs/reference-library.md)\n- **Zero prompt engineering** — chat mode helps you refine ideas into detailed tasks. Project context and framework guides teach the LLM your codebase conventions automatically.\n- **Reference library** — drop your internal docs (PDF, EPUB, Word, Markdown) into `.lean_ai/reference/` and the agent uses them for better plans without leaking content to cloud APIs.\n- **UI verification** — the agent can screenshot web pages or desktop GUIs (Tkinter, Qt, Swing, JavaFX, Electron) and analyse layout with a local vision model. Useful for planning UI changes, discussing layout with the agent, or diagnosing visual regressions that pass a type-check but look broken. [Learn more](docs/ui-verification.md)\n- **Built-in code quality** — after every execution, Lean AI runs your project's linter and tests automatically. Failures are fed back to the LLM for self-correction. Lint, test, and format commands are auto-detected from your project files — zero configuration needed. When a test command is available, the agent writes tests alongside code changes.\n- **Git-native workflow** — every task runs on its own branch. Approve to merge, reject to discard. Your main branch stays clean.\n- **19 scaffold recipes** — bootstrap new projects (FastAPI, Next.js, Laravel, Rails, and more) with a single command.\n\n## Quick Start\n\n### 1. Install the extension\n\n**VS Code / VSCodium:** Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=lean-ai.lean-ai) or [OpenVSX](https://open-vsx.org/extension/lean-ai/lean-ai).\n\n**JetBrains IDEs** (IntelliJ, PyCharm, WebStorm, CLion, etc.): See the [JetBrains Plugin guide](jetbrains-plugin/README.md) for build and install instructions.\n\nOn first activation, the extension automatically creates a Python virtual environment and installs the backend server — no manual setup required.\n\n### 2. Install Ollama and pull a model\n\nDownload [Ollama](https://ollama.com) and pull a model:\n\n```bash\nollama pull qwen3-coder:30b\n```\n\n\u003e **Cloud models:** Ollama also supports cloud-hosted models. Pull one with `ollama pull model-name:cloud`, then run `ollama run model-name:cloud` and follow the link to connect your Ollama Cloud account. Once linked, select the cloud model from the Lean AI dropdown — it works the same as a local model.\n\n### 3. Open a project and run `/init`\n\nType `/init` in the chat panel to index your workspace and generate project context. Then describe what you want built.\n\n## Building from Source\n\nIf you prefer to build from source instead of installing from the marketplace:\n\n### Backend\n\n```bash\ncd backend\npip install -e \".[dev]\"\n```\n\nFor voice features on Ubuntu 26.04 or any environment where `python3` is already 3.14+, create the backend virtualenv with Python 3.13 first. The current `voice` extra depends on `kokoro-onnx`, which does not yet support Python 3.14.\n\n```bash\nsudo apt install portaudio19-dev build-essential\ncd backend\npython3.13 -m venv .venv\nsource .venv/bin/activate\npython -m pip install --upgrade pip setuptools wheel\npython -m pip install -e \".[voice]\"\n```\n\nIf you're running the extension against that source checkout, set `lean-ai.backendDir` to the `backend/` directory and `lean-ai.pythonPath` to `backend/.venv/bin/python`.\n\nNeed cloud providers or reference library support? See [optional extras](docs/configuration.md#installation-extras).\n\nStart the server manually:\n\n```bash\nuvicorn lean_ai.main:app --reload --port 8422\n```\n\n### Extension\n\n```bash\ncd extension \u0026\u0026 npm install \u0026\u0026 npm run build\nnpx vsce package --no-dependencies\n```\n\nInstall the generated `.vsix` file: **Extensions** sidebar \u003e `...` menu \u003e **Install from VSIX...**\n\nWhen building from source, set `lean-ai.backendDir` or `lean-ai.pythonPath` in the extension settings — the automatic installer is skipped when either setting is explicitly configured.\n\n## How It Works\n\n```\nYou: \"Add user authentication with JWT tokens\"\n                    |\n          [Chat refines the idea]\n                    |\n          [6-phase planning pipeline]\n            scope -\u003e files -\u003e design -\u003e risks -\u003e plan\n                    |\n          [You review and approve]\n                    |\n          [Agent executes step-by-step]\n            creates files, edits code, writes tests\n                    |\n          [Post-execution validation]\n            auto-format -\u003e lint fix -\u003e lint check -\u003e test\n            failures fed back to LLM for self-correction\n                    |\n          [Changes committed on a branch]\n            /approve to merge, /reject to discard\n```\n\n**Three common modes:**\n- **`/agent`** — full planning pipeline for features and refactors\n- **`/fix`** — skip planning, let the agent explore and fix directly\n- **`/request`** — skip planning with a request-oriented role tuned for research, drafting, and open-ended tasks\n\nSee [Architecture](docs/architecture.md) for the full breakdown.\n\n## Role Tuning\n\nLean AI can tune the three main model roles independently:\n\n- **Request** — used by chat refinement and `/request`\n- **Primary** — used by planning phases 1-2, normal execution, and primary-path fix work\n- **Expert** — used by planning phases 3-5, expert-path fix work, plan revision, and final validation escalation\n\nOn the first run for a given `role + model`, Lean AI performs a lightweight calibration pass, selects the best role framing for that model, stores the result in `.lean_ai/role_tuning/`, and writes a model-scoped prompt override into `.lean_ai/prompts.yaml`.\n\nIf you want to prewarm those artifacts on one machine and share them with teammates, run `/tune-roles`. That command explicitly tunes the active `primary`, `request`, and `expert` role assignments (including primary fallbacks when a dedicated request/expert model is not configured), writes the same `.lean_ai/role_tuning/*.json` profiles plus `.lean_ai/prompts.yaml`, and lets you commit just those sharable files for reuse on other machines with the same provider/model IDs.\n\nThat tuned result is reused until one of the inputs changes:\n\n- the role's work summary\n- the relevant compiled base prompts\n- the role-tuning composition version\n\nManual prompt customization still works. Global overrides remain the fallback layer, and a matching model-scoped override wins only for that specific role/model pair.\n\n## Slash Commands\n\n| Command | What it does |\n|---|---|\n| `/init` | Index workspace and generate project context |\n| `/tune-roles` | Prewarm sharable role-tuning artifacts for the active role assignments |\n| `/agent` | Send a task to the planning pipeline |\n| `/fix` | Skip planning, fix directly with full tool access |\n| `/approve` | Merge the agent's branch |\n| `/reject` | Discard the agent's branch |\n| `/style` | Generate style guide from CSS/templates |\n| `/skill \u003cname\u003e \u003ctask\u003e` | Load a local skill from `.lean_ai/skills/\u003cname\u003e/instructions.md` and apply it to the task |\n| `/request \u003ctask\u003e` | Skip planning, open-ended task with full tool access |\n| `/resume [session_id]` | Resume a previous session |\n| `/help` | Show this help |\n| `/interview-prep` | Convert a .docx resume and tailor it for a specific role |\n| `/batch-prep` | Tailor resumes + cover letters for many roles in one run |\n| `/ats-check [slug]` | Keyword gap report comparing resume to the job description |\n| `/thank-you [slug]` | Draft a post-interview thank-you note |\n| `/recruiter-reply` | Draft a reply to a recruiter's cold outreach |\n| `/negotiate [slug]` | Research market comp and build a negotiation brief |\n| `/analyse-rejection [slug]` | Post-mortem a rejection with concrete takeaways |\n| `/log-applied [slug]` | Append a tracker row and commit the application folder to git |\n| `/mock-interview [slug]` | Interactive Q\u0026A practice with rubric scoring |\n| `/note` | Save a note (auto-categorized by project) |\n| `/scaffold` | Bootstrap a new project |\n| `/memories` | Manually trigger memory extraction from the last completed workflow session |\n| `/reboot` | Restart the backend server |\n\n## Configuration\n\nCreate a `backend/config.yaml` file (or use the extension's settings panel):\n\n```yaml\n# Provider: ollama, openai, or anthropic\nllm_provider: ollama\n\n# Local model (default)\nollama_model: \"qwen3-coder:30b\"\nollama_context_window: 128  # 128k — shorthand for 131072\n\n# Cloud API keys — encrypt with: python -m lean_ai encrypt-key \u003ckey\u003e\nopenai_api_key: \"enc:gAAAAABf...\"\nanthropic_api_key: \"enc:gAAAAABf...\"\n```\n\nEnvironment variables (`LEAN_AI_*`) and legacy `.env` files also work. See [configuration priority](docs/configuration.md).\n\n### Dual-model setup (save cloud tokens)\n\nUse a local model for the bulk of the work and a cloud model only for planning and complex fixes:\n\n```yaml\nllm_provider: ollama\nollama_model: \"qwen3-coder:30b\"\n\n# Expert: cloud model for planning phases 3-5 and final fix retry\nexpert_llm_provider: anthropic\nanthropic_api_key: \"enc:gAAAAABf...\"\nanthropic_expert_model: \"claude-opus-4-6\"\n```\n\nThe expert model only runs for planning phases 3–5 (design + risk synthesis, plan assembly, verification) and the final validation fix retry. All codebase exploration, implementation, and routine tool calls use the primary local model.\n\n\u003e **Note:** the cloud provider's Python SDK must be installed even when the primary provider is Ollama — run `pip install -e \".[dev,anthropic]\"` or `pip install -e \".[dev,openai]\"` as appropriate, then restart the server.\n\n### All-local three-model setup\n\nUse three different local models matched to each role:\n\n```yaml\nollama_model: \"qwen3-coder:30b\"\n\n# Expert: larger model for planning and complex reasoning\nollama_model_expert: \"qwen3-coder-next:80b\"\n\n# Request: smaller model for chat conversation and prompt building\nrequest_llm_provider: openai\nopenai_base_url: \"http://localhost:11434/v1\"\nopenai_request_model: \"gpt-oss:20b\"\n```\n\nSee the [full configuration reference](docs/configuration.md) for all options.\n\n## Documentation\n\n| Guide | Description |\n|---|---|\n| [Configuration](docs/configuration.md) | All environment variables, extension settings, and model setup |\n| [Architecture](docs/architecture.md) | Planning pipeline, workflow modes, tools, and internals |\n| [Example Flow](docs/example-flow.md) | End-to-end walkthrough of a real session with every guardrail called out |\n| [Reference Library \u0026 Refiner](docs/reference-library.md) | Private docs, RAG enrichment, and cloud privacy |\n| [UI Verification](docs/ui-verification.md) | Vision-backed screenshot analysis for web pages and desktop GUIs |\n| [API Reference](docs/api-reference.md) | REST endpoints and WebSocket protocol |\n| [Extension Guide](docs/extension.md) | VSCode/VSCodium setup, commands, and settings |\n| [JetBrains Plugin](jetbrains-plugin/README.md) | IntelliJ, PyCharm, WebStorm, CLion, and all JetBrains IDEs |\n| [Prompt Customization](docs/prompt-customization.md) | Global and model-scoped prompt overrides, including role tuning |\n| [Skills Guide](docs/skills.md) | How `/skill` works and how to author high-quality skills |\n| [Modelfile Guide](docs/modelfile.md) | Customizing Ollama models with persistent rules |\n| [llama-server Guide](docs/llama-server.md) | Using llama.cpp as an alternative to Ollama |\n| [Regulated Environments](docs/regulated-environments.md) | Self-hosted deployment for HIPAA, SOX, GDPR, ITAR, and air-gapped networks |\n\n## Requirements\n\n- Python 3.10+\n- Node.js 18+ (for the extension)\n- At least one LLM provider:\n  - **Ollama** with a capable model (e.g., `qwen3-coder:30b`) — free, local, no account needed\n  - **OpenAI** API key (GPT-4o, etc.)\n  - **Anthropic** API key (Claude, etc.)\n\nOllama is always required for inline predictions and embeddings, even when using cloud providers.\n\n## Technology Stack\n\n| Layer | Technology |\n|---|---|\n| Backend | Python, FastAPI, aiosqlite |\n| LLM providers | Ollama, OpenAI, Anthropic |\n| Code analysis | tree-sitter (13 languages) |\n| Search | Whoosh BM25F + embedding RRF |\n| VS Code Extension | TypeScript, VSCode API |\n| JetBrains Plugin | Kotlin, IntelliJ Platform SDK, JCEF |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshunobies%2Flean-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshunobies%2Flean-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshunobies%2Flean-ai/lists"}