LLM Local Assistant - VS Code Extension

A powerful VS Code extension that brings autonomous AI agent capabilities to your local machine. Break down complex tasks into structured multi-step plans, execute them automatically, and stay in control with the ability to review and reject plans before execution.

Latest Release: v1.2.0 - Enhanced AI Planning with Auto-Correction ✨
📚 Contributing: See CONTRIBUTING.md for development guide.

✨ Key Features

🧠 Autonomous Planning (Phase 2 - NEW!)

Break complex tasks into structured multi-step plans
Review plans before execution
Automatic error recovery with retry logic

🤖 Agent Mode Commands

/plan <task> - Generate multi-step action plans with LLM
/approve - Execute approved plans sequentially
/reject - Discard plans without execution
/read <path> - Read files from workspace
/write <path> - Generate and write file content
/git-commit-msg - Generate conventional commit messages
/git-review - AI-powered code review of staged changes
/explain <path> - Analyze and explain code (NEW in v1.2.0)
Auto-Correction - LLM suggestions for command mistakes (NEW in v1.2.0)

💻 Local & Private

🔒 Works with Ollama, LM Studio, vLLM - no external APIs
🚀 Fast local LLM inference with streaming support
⚙️ Fully configurable (endpoint, model, temperature, timeout)
💬 Conversation context maintained per session
✅ Production-ready with comprehensive error handling

📊 Project Status & Version History

Latest: v1.2.0 (December 2025) - Enhanced AI Planning with Auto-Correction & Code Understanding ✅

v1.2.0 Features:

✅ Smart Auto-Correction - Automatically fix and suggest command corrections with LLM
✅ Codebase Awareness - Understand project structure, dependencies, and frameworks
✅ Code Explanation - /explain command for detailed code analysis and documentation
✅ Shell Environment Fix - Fixed npm/command PATH resolution on macOS
✅ Enhanced Error Handling - Better error messages and recovery strategies

Phase 2: Multi-Step Planning & Autonomous Execution

✅ Planner Module - LLM-based task decomposition into structured plans
✅ Executor Module - Sequential execution with automatic retry (up to 2 attempts per step)
✅ Observer System - Real-time progress tracking
✅ Error Recovery - Intelligent error handling with helpful feedback
✅ 32+ Unit Tests - >85% code coverage
✅ Full Type Safety - TypeScript strict mode, 0 errors
✅ Backward Compatible - All v1.0 commands unchanged

Phase 1 Foundation (v1.0.0):

💬 Local LLM chat with streaming support
📁 File operations (read, write, suggestwrite)
🔀 Git integration (commit messages, code review)
🔒 100% private, offline-first design
92 unit tests with 100% pass rate

What's New in Phase 2

Autonomous Planning & Execution Workflow:

Describe a task: /plan create a React component with tests
Review the plan: See breakdown of steps (read, generate, write)
Approve execution: /approve to run all steps sequentially
Monitor progress: Real-time status for each step
Handle errors: Automatic retry or manual investigation

Real-World Use Cases:

🚀 Refactoring modules (analyze, generate, test, verify)
📝 Generating documentation (read code, analyze, write docs)
🏗️ Creating project structures (multiple files, configs, tests)
🔄 Multi-step code transformations (analyze, plan, execute)

📸 Workflow Screenshots

1. Planning View - Multi-Step Decomposition

Phase 2 Planning

Shows /plan command breaking down a task:

LLM analyzes request and creates structured plan
Step-by-step action breakdown (read, write operations)
Detailed descriptions for each step
Ready for approval: /approve to execute

2. Plan Steps - Review Before Execution

Phase 2 Plan Steps

Shows the generated plan ready for review:

Multi-step action sequence (typically 2-5 steps)
Each step shows action, path, and description
User controls: /approve to execute or /reject to cancel
Transparent decision point before running

3. Execution View - Real-Time Progress

Phase 2 Execution

Shows /approve executing the plan:

Step-by-step execution with real-time status
Progress indicator (Step X of Y)
Step output and results displayed inline
Automatic error recovery with retry logic

4. Error Recovery - Automatic Retry Handling

Phase 2 Error Recovery

Shows error handling and recovery:

Step failure detection with clear error message
Automatic retry mechanism triggered (up to 2 attempts)
Detailed error information for troubleshooting
User has control to proceed or abort

5. Completed Workflow - Results Summary

Phase 2 Workflow Complete

Shows successful plan completion:

Summary of completed steps
Files created and modifications made
Ready for next task or manual review
Full chat history maintained

6. Git Integration - Autonomous Commit Messages

Git Integration

Shows Phase 1 git integration commands:

/git-commit-msg analyzing staged changes
AI-generated conventional commit message
Professional message format ready to use
Can also use /git-review for code analysis

📋 Prerequisites

Local LLM Server (Required)

You need one of:

Ollama (Recommended)

ollama run mistral
# Server at: http://localhost:11434

LM Studio

Download: https://lmstudio.ai
Start local server on: http://localhost:8000

vLLM

python -m vllm.entrypoints.openai.api_server \
  --model mistral-7b-instruct-v0.2 \
  --port 11434

🚀 Getting Started

Quick Install (One Command)

From VS Code Marketplace (Easiest):

code --install-extension odanree.llm-local-assistant

Or search for "LLM Local Assistant" in VS Code Extensions marketplace: https://marketplace.visualstudio.com/items?itemName=odanree.llm-local-assistant

See docs/INSTALL.md for detailed platform-specific setup, troubleshooting, and development instructions.

🚀 Development & Building

Build

npm run compile        # Single build
npm run watch         # Auto-rebuild on changes
npm run package       # Production VSIX package

Testing

npm test              # Run all 120+ tests
npm run test:watch   # Auto-run on changes
npm run test:coverage # Coverage report

Debug

# Launch in VS Code debug mode
F5

# Then interact with extension:
- Type messages to chat
- Use /plan, /approve, /reject
- Check console for debug output

Source Code Structure

src/
├── extension.ts           # Command routing, UI orchestration
├── planner.ts            # Plan generation with thinking phase
├── executor.ts           # Step execution with retry logic
├── llmClient.ts          # LLM API abstraction
├── gitClient.ts          # Git operations
├── webviewContent.ts     # Chat UI HTML/CSS/JS
├── *.test.ts             # 120+ unit tests
└── vitest.setup.ts       # Test configuration

System

/help - Show available commands
```
/help
```

🤖 Phase 2 Commands Guide

Planning & Execution

`/plan <task>`

Analyze a task and create a structured multi-step plan

You: /plan create a React component with unit tests

LLM: 📋 **Plan Created** (5 steps, 8.3s thinking)

STEP 1: read
  Read example React components to understand style

STEP 2: write  
  Generate TypeScript React component with hooks

STEP 3: write
  Generate Jest unit tests for component

STEP 4: run
  Execute npm test to verify tests pass

STEP 5: write
  Create documentation for component

Ready to execute? Use **/approve** or **/reject**

What it does:

Uses LLM thinking phase to analyze your request
Breaks task into 3-10 atomic steps
Each step is one of: read, write, run, or suggestwrite
Generates step descriptions explaining the action

`/approve`

Execute the current plan step-by-step

You: /approve

LLM: ⚙️ **Executing Plan** (5 steps)

✅ STEP 1: read (127ms)
   Read example React components

✅ STEP 2: write (3.2s)
   Generated MyComponent.tsx (284 lines)

✅ STEP 3: write (2.1s)
   Generated MyComponent.test.tsx (156 lines)

⚠️ STEP 4: run (1.8s)
   npm test - Retry 1 of 2
   ✅ Retry succeeded, tests pass

✅ STEP 5: write (890ms)
   Generated COMPONENT.md

✅ **Plan completed successfully** (7.9 seconds)

Features:

Executes steps sequentially
Automatic retry (up to 2 times) on step failure
Real-time progress with elapsed time
Shows output for each step
Continues on success, stops on unrecoverable error

`/reject`

Discard the current plan without executing

You: /reject

LLM: ❌ Plan discarded. What would you like to do?

File Operations (Phase 1 - Still Available)

`/read <path>`

/read src/main.ts

Read and display file contents with syntax highlighting.

`/write <path> [prompt]`

/write src/greeting.ts write a TypeScript function that greets users with their name

Generate file content via LLM and write to disk.

`/suggestwrite <path> [prompt]`

/suggestwrite src/config.ts add validation for the API endpoint

LLM suggests changes, you review the diff before writing.

Git Integration (Phase 1 - Still Available)

`/git-commit-msg`

Generate conventional commit message from staged changes

/git-commit-msg

Analyzes all staged diffs and generates a message following the pattern:

<type>(<scope>): <description>

[optional body with detailed changes]

`/git-review`

AI-powered code review of staged changes

/git-review

Reviews staged changes and provides:

Potential issues or bugs
Code quality suggestions
Security considerations
Style recommendations

🏗️ Architecture & Design

Why This Design?

Three-Module Agent Loop

User Request
    ↓
[PLANNER] → Breaks task into structured steps
    ↓
[REVIEW] → You see plan, decide to approve/reject
    ↓
[EXECUTOR] → Runs steps sequentially with retry
    ↓
[OBSERVER] → Monitors progress, provides feedback

Key Design Decisions:

Planner → Executor Separation
- You always review before execution
- Plan can be rejected without side effects
- Clear visibility into what will happen
Sequential Execution with Retry
- Each step runs to completion before next
- Automatic retry (up to 2 times) on failure
- Stops on unrecoverable errors
Observable Progress
- Real-time output for each step
- Elapsed time and performance metrics
- Detailed error messages guide investigation
Atomic Steps
- Each step is one of: read, write, run, suggestwrite
- No partial execution or rollback needed
- Simple state management

Module Responsibilities

Planner (src/planner.ts - 366 lines)

Analyzes user task
Generates execution plan as JSON
Validates steps are valid action types
Returns readable plan summary

Executor (src/executor.ts - 503 lines)

Executes steps sequentially
Implements each action type (read, write, run)
Handles errors and retries
Provides progress callbacks for UI

Extension (src/extension.ts - 385 lines)

Routes commands to Planner/Executor
Manages webview chat UI
Handles approval/rejection UI
Orchestrates the agent loop

Error Handling & Recovery

Automatic Retry Pattern

for (let attempt = 1; attempt <= maxRetries; attempt++) {
  try {
    return await executeStep(step);
  } catch (error) {
    if (attempt === maxRetries) throw error;
    logRetry(step, attempt, error);
  }
}

Error Categories & Handling

Transient (retry): Network timeouts, temporary file locks
Unrecoverable (stop): File not found, syntax errors, permissions
Information (continue): Warnings logged but execution continues

Error Message Strategy

Always show specific error details
Suggest corrective actions (💡 prefix)
Include affected file paths and line numbers

🎯 Use Cases & Examples

Example 1: Refactor Module with Tests

You: /plan refactor src/auth.js to use async/await and add comprehensive tests

LLM Creates Plan:
  1. Read src/auth.js (analyze current implementation)
  2. Write src/auth.js (generate refactored async/await version)
  3. Write src/auth.test.js (generate test suite)
  4. Run npm test (verify tests pass)
  5. Write docs/REFACTOR.md (document changes)

You: /approve
→ 5 steps execute in 12.4 seconds
→ All tests pass
→ Documentation created

Example 2: Generate Project Structure

You: /plan create a new TypeScript project structure for an Express API

LLM Creates Plan:
  1. Read examples/project-template (reference structure)
  2. Write src/index.ts (create main server file)
  3. Write src/routes/api.ts (create API routes)
  4. Write src/middleware/auth.ts (create auth middleware)
  5. Write tests/api.test.ts (create tests)
  6. Write README.md (create documentation)

You: /approve
→ Complete project scaffolding in seconds

Example 3: Implement Feature with Documentation

You: /plan add a rate-limiting feature to the API

LLM Creates Plan:
  1. Read current middleware structure
  2. Write src/middleware/rateLimit.ts (implementation)
  3. Write docs/RATE_LIMITING.md (docs)
  4. Write tests/rateLimit.test.ts (tests)

You: /approve
→ Feature fully implemented with tests and docs

📦 Installation & Configuration

Quick Start

Start your LLM server

# Ollama (recommended)
ollama run mistral

# LM Studio
# Open LM Studio → Select model → Start local server

# vLLM
python -m vllm.entrypoints.openai.api_server --model mistral-7b

Install extension
- Open VS Code Extensions (Ctrl+Shift+X)
- Search "LLM Local Assistant"
- Click Install
Configure endpoint (if not using defaults)
- Open VS Code Settings (Ctrl+,)
- Set llm-assistant.endpoint: http://localhost:11434
- Set llm-assistant.model: mistral
Test connection
- Click LLM Assistant in status bar
- Run "Test Connection" command
- ✅ Should show "Connection successful"

See docs/INSTALL.md for platform-specific setup.

Configuration Reference

Setting	Default	Description
`llm-assistant.endpoint`	`http://localhost:11434`	LLM server URL
`llm-assistant.model`	`mistral`	Model name to use
`llm-assistant.temperature`	`0.7`	Response randomness (0-1)
`llm-assistant.maxTokens`	`2048`	Max response length
`llm-assistant.timeout`	`60000`	Request timeout (ms)

Supported LLM Servers

Server	Endpoint	Setup
Ollama	`http://localhost:11434`	`ollama run mistral`
LM Studio	`http://localhost:8000`	Start local server in UI
vLLM	`http://localhost:8000`	Python server
OpenAI Compatible	Custom URL	Any OpenAI-compatible endpoint

✅ Quality & Testing

Test Coverage

120+ unit tests covering all core functionality
>85% code coverage on Planner and Executor modules
100% pass rate on every commit
Tests run on: Linux, macOS, Windows

Coverage by Module:

planner.ts: 17 tests
executor.ts: 15 tests
extension.ts: 36 tests
llmClient.ts: 33 tests
gitClient.ts: 23 tests

Type Safety

TypeScript strict mode enabled
Zero type errors in entire codebase
Explicit types on all public APIs
JSDoc comments on all modules

Error Handling

Specific error detection - Different handling for timeouts, not-found, permission errors
User-friendly messages - Technical details only shown for debugging
Automatic retry logic - Up to 2 retries for transient failures
Timeout handling - Clean cancellation with AbortController

Code Quality

100% ESLint compliant - Clean code standards enforced
Clean git history - 30+ atomic commits showing development progression
Comprehensive documentation - Every module documented with architecture rationale

🔒 Privacy & Security

100% Local & Private

✅ No external APIs - Works completely offline with local LLM
✅ No cloud services - Zero dependencies on external infrastructure
✅ No telemetry - No tracking, analytics, or data collection
✅ No internet required - After model download, works completely offline
✅ Your code stays private - Never sent to external servers

How it works:

Your LLM server runs on your machine (Ollama, LM Studio, vLLM)
Extension sends requests to local server only
All responses processed locally in VS Code
Your code, conversations, and tasks never leave your machine

📚 Documentation

Document	Purpose
README.md (this file)	Overview, features, quick start
ARCHITECTURE.md	Deep dive into design and modules
PROJECT_STATUS.md	Current development status
ROADMAP.md	Future features and phases
CHANGELOG.md	Version history
CONTRIBUTING.md	Developer guide

Phase 2 Deep Dives:

docs/PHASE2_GUIDE.md - Complete Phase 2 specification
docs/PHASE2_INTEGRATION.md - Integration architecture
docs/EXTENSIBILITY_ANALYSIS.md - Extension patterns and examples

🐛 Troubleshooting

Connection Issues

"Cannot connect to endpoint"

Verify LLM server running: ollama serve or LM Studio UI
Check endpoint in settings: llm-assistant.endpoint
Test connection: Click status bar → "Test Connection"
Check firewall: Port 11434 (Ollama) or 8000 (LM Studio) accessible?

"Model not found"

List available models: ollama list
Download if needed: ollama pull mistral
Update settings: llm-assistant.model: mistral

Performance Issues

"Requests timing out"

Increase llm-assistant.timeout (default 60000ms)
Check server resources: CPU, RAM, disk space
Try smaller model: ollama run tinyllama instead of mistral

"Very slow responses"

Use smaller model: ollama pull orca-mini (3.8GB)
Reduce llm-assistant.maxTokens (default 2048)
Check GPU acceleration: Ollama can use CUDA/Metal

LLM Server Setup

Ollama Won't Start

# Mac/Linux: Reinstall
curl -fsSL https://ollama.ai/install.sh | sh

# Windows: Download from https://ollama.ai/download
# Then: ollama run mistral

LM Studio Issues

Download latest: https://lmstudio.ai
Load model in UI
Ensure "Local Server" is started (green dot)
Default port: 8000, check in settings

🎓 Learn More

For Users

How to install and configure: docs/INSTALL.md
Command reference: docs/QUICK_REFERENCE.md
Video tutorial: See demo video

For Developers

Architecture deep dive: ARCHITECTURE.md
Development guide: CONTRIBUTING.md
Phase 2 extensibility: docs/EXTENSIBILITY_ANALYSIS.md
Future roadmap: ROADMAP.md

For Contributors

Clean code patterns: Review src/*.ts files
Test patterns: Review src/*.test.ts files
Git workflow: Check clean commit history with git log --oneline

📊 Project Stats

Metric	Count
Tests	120+
Test Coverage	>85%
Modules	6 core
TypeScript Strict	✅ Yes
Type Errors	0
Commit History	30+ atomic
Versions	2 released

🙏 Contributing

Contributions welcome! See CONTRIBUTING.md for:

Development setup
Code style guidelines
Testing requirements
Pull request process

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-thing)
Code with tests (see existing patterns)
Test locally (npm test)
Commit with clear message (git commit -m "feat: add amazing thing")
Push to your fork
Open PR with description

📄 License

MIT License - See LICENSE file for details

Created by @odanree

🚀 Local AI Agent for VS Code | 🔒 100% Private | ⚡ Autonomous Planning & Execution