Lunaris — Local-First Autonomous AI Agent for VS Code

An autonomous coding agent powered by your local machine, monitored and controlled from anywhere.

Lunaris is a VS Code extension that gives you a fully autonomous, privacy-first AI pair programmer. By default, it runs entirely on your local hardware via Ollama so your code never leaves your machine. It can also be configured to connect to cloud models (such as Gemini or Claude) via the optional Deep Space Relay, giving you complete flexibility over where your data is processed.

Optionally, connect to Mission Control to monitor and interact with your agent remotely from your phone or another machine.

Features

• Autonomous Agent Loop — reads files, writes code, runs tests, and self-corrects from linter errors without manual intervention
• Local Inference — all AI processing happens on your machine via Ollama. No API keys required.
• Inline Autocomplete — fast, streaming code completions powered by a dedicated local model (FIM)
• Planning Mode — structured implementation plans with Accept/Reject review before execution
• Browser Automation — open pages, click elements, take screenshots, and evaluate JavaScript in a real browser
• Model Context Protocol (MCP) — extend the agent's capabilities with local stdio or remote SSE MCP servers to access additional tools and resources
• Agent Delegation — define specialised sub-agents (.lunaris/agents/) and delegate tasks between them
• Custom Tools — register workspace-specific tools via JSON schemas (.lunaris/tools/)
• Voice Input — speak your architectural plans instead of typing them
• Deep Space Relay — remote monitoring and interaction via the Mission Control PWA
• Background Tasks — queue and execute tasks from Mission Control while you're away
• Session Memory — learns from past sessions and loads context automatically on startup

Getting Started

1. Install Ollama

Download and install Ollama for your operating system.

2. Pull a Model

# Recommended chat model (tool-calling capable)
ollama pull qwen2.5-coder:7b

# Recommended autocomplete model (fast, FIM-optimised)
ollama pull deepseek-coder:base

3. Install the Extension

You can install the Lunaris extension from the VS Code Marketplace or by using the official installer CLI.

Option A: VS Code Marketplace Open the extensions sidebar in VS Code, search for "Lunaris", and click Install. (Note: When installed via the Marketplace, the extension will automatically download and install the Lunaris Engine for your operating system on first startup.)

Option B: Installer CLI Run the official one-line install script for your operating system:

macOS / Linux:

curl -fsSL https://getlunaris.dev/install.sh | bash

Windows (PowerShell):

irm https://getlunaris.dev/install.ps1 | iex

4. Select a Model

Click the model name in the VS Code status bar (bottom) to switch between available models. Lunaris automatically discovers all models from your local Ollama instance.

5. Start Chatting

Open the Lunaris sidebar panel and type your request. The agent will read your codebase, plan changes, execute them, and verify the results autonomously.

6. Setup Voice Prompting

Lunaris supports 100% offline, local speech-to-text.

macOS Users:

brew install sox

Linux Users (Ubuntu/Debian):

sudo apt-get install sox libsox-fmt-all

Linux Users (Arch):

sudo pacman -S sox

Windows Users: Download SoX (Sound eXchange) and ensure the installation directory is added to your system's PATH environment variable.

Once installed, click the microphone icon in the chat panel to speak your instructions. The transcription is processed locally using the whisper-tiny.en ONNX model (which downloads automatically on first use, ~40MB).

Configuration

All settings are available under lunaris.* in VS Code Settings.

Commands

Access via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Agent Rules & Workflows

Lunaris loads contextual instructions from markdown files on disk:

Rules (.lunaris/rules/*.md)

Persistent instructions that are always injected into the system prompt. Use rules to enforce coding standards, architectural patterns, or project-specific constraints.

---
description: Enforce strict typing in all TypeScript files.
---

# Strict Types

- Always use `strict: true` in tsconfig.json
- Never use `any` — prefer `unknown` with type guards
- All function parameters and return types must be explicitly typed

Workflows (.lunaris/workflows/*.md)

Step-by-step procedures that the agent follows when triggered. Workflows are matched by their frontmatter description.

Agents (.lunaris/agents/*.md)

Specialised sub-agents with their own system prompts, models, and delegation rules. The agent fleet can be visually managed via the Manage Agents command.

Global Entities (~/.lunaris/)

Rules, workflows, and agents placed in ~/.lunaris/rules/, ~/.lunaris/workflows/, and ~/.lunaris/agents/ are loaded across all workspaces.

Custom Tools

Register workspace-specific tools by creating JSON schemas in .lunaris/tools/:

{
  "name": "run_tests",
  "description": "Run the project test suite and return results.",
  "parameters": {
    "type": "object",
    "properties": {
      "filter": {
        "type": "string",
        "description": "Optional test name filter."
      }
    }
  },
  "execution": {
    "command": "npm test -- --filter={{filter}}"
  }
}

The agent discovers custom tools automatically and can invoke them like any native tool.

Model Context Protocol (MCP)

Lunaris supports the Model Context Protocol (MCP), allowing you to connect external servers to extend the agent's capabilities with new tools and data resources.

Configuring MCP Servers

You can manage your MCP servers visually by running Cmd+Shift+P -> Lunaris: Manage MCP Servers, or by editing your global settings.json file under lunaris.mcpServers.

Example standard stdio configurations:

"lunaris.mcpServers": {
  "sqlite": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-sqlite",
      "--db-path",
      "/Users/username/data/mydb.db"
    ]
  },
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "--connection-string",
      "postgresql://localhost/mydb"
    ]
  }
}

Example remote SSE configurations:

To connect to a remote MCP server using Server-Sent Events (SSE), set the command to "sse" and provide the SSE endpoint URL as the first argument:

"lunaris.mcpServers": {
  "my-remote-server": {
    "command": "sse",
    "args": [
      "https://mcp-server.example.com/sse"
    ]
  }
}

Any exposed tools from connected servers are automatically registered with the agent and can be invoked during a conversation. Tools are prefixed using the format mcp__<server-name>__<tool-name>.

Deep Space Relay

When connected to the Lunaris API (Mission Control), the extension enables:

1. Live Session Streaming — watch your agent work in real-time from your phone
2. Remote Prompting — send messages to your local agent from anywhere
3. Background Tasks — queue tasks from Mission Control that execute locally
4. Cloud Models — access cloud-hosted models (Mistral, Bedrock) through the relay

To connect:

1. Run Lunaris: Connect to Mission Control from the command palette
2. Enter your API token (stored securely in the OS keychain)
3. The relay status indicator appears in the status bar

Troubleshooting

Ollama not detected

• Ensure Ollama is running: ollama serve
• Check the URL in settings: lunaris.ollamaUrl (default http://localhost:11434)
• Test connectivity: curl http://localhost:11434/api/tags

Models not appearing

• Pull at least one model: ollama pull qwen2.5-coder:7b
• Click the model selector in the status bar to refresh

Autocomplete not working

• Pull a FIM-capable model: ollama pull deepseek-coder:base
• Set lunaris.autocompleteModel to the model name
• Ensure the model supports fill-in-the-middle prompting

Agent gets stuck in a loop

• Click the Stop button in the chat panel
• Reduce lunaris.maxToolCalls to a lower value
• Switch to Planning mode for complex tasks

License

Proprietary. All rights reserved. Refer to the LICENSE file for details.