Aura

Aura is an AI coding assistant that runs on your machine. It indexes your codebase, understands your code structure, and helps you implement features through a VS Code extension.

What Can You Do With It?

Start a coding task from a GitHub issue

Command: "Aura: Start Story from Issue"
→ Paste: https://github.com/org/repo/issues/42
→ Aura creates a git worktree and branch
→ Opens a new VS Code window in that worktree
→ Shows the issue context and lets you chat with the agent

Chat to implement features

The workflow panel has a chat interface. You describe what you want:

"Add a Redis cache to the UserService"

The agent reads your codebase, writes the code, and shows you what changed. You can review, ask for modifications, or continue with the next task.

Index your codebase for context

Aura indexes your code two ways:

1. Text search - Finds relevant code snippets when you ask questions
2. Code graph - Understands types, methods, and relationships (C# via Roslyn, other languages via Tree-sitter)

When you ask the agent to implement something, it automatically searches your codebase for relevant context.

Use local or cloud LLMs

Works with:

• Ollama - Run models locally (llama3, codellama, mistral, etc.)
• OpenAI - GPT-4, GPT-4o
• Azure OpenAI - Your own Azure deployment

Configure in appsettings.json:

{
  "Llm": {
    "Provider": "ollama",
    "Model": "llama3.2"
  }
}

Define custom agents

Agents are Markdown files. Create a new .md file in agents/ and it's immediately available:

# My Custom Agent

## System Prompt
You are an expert in...

## Capabilities
- code-review
- documentation

## Provider
openai/gpt-4o

No restart required - agents hot-reload.

Work on multiple tasks in parallel

Each workflow runs in its own git worktree - a separate directory with its own branch, sharing the same .git history. This means:

• Start a feature, get blocked, start another feature - no stashing, no branch switching
• Each VS Code window is isolated - changes in one don't affect the other
• No risk of git corruption - worktrees are a native git feature
• When done, merge the branch and delete the worktree

main repo:     ~/projects/myapp/           (main branch)
workflow 1:    ~/projects/myapp-worktrees/add-caching/    (feature/add-caching)
workflow 2:    ~/projects/myapp-worktrees/fix-auth-bug/   (feature/fix-auth-bug)

You can have any number of workflows in progress, each with its own chat history and file changes, without conflicts.

---

Developer Module Features

The Developer Module provides workflow automation for coding tasks:

Feature	Description
Workflows	Track a coding task from start to PR
Git worktrees	Each workflow gets an isolated branch and directory
GitHub integration	Create workflows from issues, sync status back
Step execution	Break work into steps, execute with different agents
Assisted mode	Review each step before proceeding
Autonomous mode	Let the agent run multiple steps automatically
Chat history	Conversation persists across sessions
Build-fix loops	Iteratively build and fix errors until success

MCP Server for GitHub Copilot

Aura exposes your indexed codebase to GitHub Copilot via MCP (Model Context Protocol). This means Copilot can:

• Search your codebase semantically ("find authentication code")
• Navigate code relationships (callers, implementations, derived types)
• Understand your project's structure before suggesting code

Configure in VS Code settings.json:

{
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": ".github/copilot-instructions.md" }
  ],
  "mcp": {
    "servers": {
      "aura": {
        "url": "http://localhost:5300/mcp"
      }
    }
  }
}

Build-Fix Loops

The agent can run iterative build-fix cycles until your code compiles:

You: "Build this and fix any errors"

Agent: 🔨 Building... ❌ 3 errors
       → Fixing CS1002: Missing semicolon...
       → Fixing CS0246: Type not found...
       🔨 Rebuilding... ✅ Build succeeded

Works for C#, Rust, TypeScript, Go, and Python.

Architecture Visualization

Generate diagrams of your codebase:

You: "Show me the class hierarchy for UserService"

Agent: ```mermaid
       classDiagram
           IUserService <|.. UserService
           UserService --> ICacheService
           UserService --> IUserRepository
       ```

Supports dependency graphs, class hierarchies, and call graphs.

Supported Languages

Code indexing and agents work with:

Language	Indexing	Coding Agent
C#	Roslyn (full semantic)	✅
TypeScript	Tree-sitter	✅
Python	Tree-sitter	✅
Rust	Tree-sitter	✅
Go	Tree-sitter	✅
F#	Tree-sitter	✅
PowerShell	Tree-sitter	✅

---

Getting Started

Prerequisites

• .NET 9.0 SDK
• Docker or Podman (for PostgreSQL)
• Ollama (for local LLM) or OpenAI API key

Install

# Clone the repository
git clone https://github.com/johnazariah/aura.git
cd aura

# Build everything
dotnet build

# Start the services (PostgreSQL + API)
dotnet run --project src/Aura.AppHost

VS Code Extension

1. Open the extension/ folder in VS Code
2. Press F5 to launch with the extension
3. Or build and install: .\scripts\Build-Extension.ps1

First Run

1. Ensure Aura service is running (check system tray or Windows Services)
2. Open VS Code with the extension installed
3. Open a folder with code you want to index
4. Run command: "Aura: Index Workspace"
5. Run command: "Aura: Create Workflow" to start a coding task

---

Configuration

LLM Providers

Edit appsettings.json or set environment variables:

Ollama (local, default):

{ "Llm": { "Provider": "ollama", "Model": "llama3.2", "BaseUrl": "http://localhost:11434" } }

OpenAI:

{ "Llm": { "Provider": "openai", "Model": "gpt-4o", "ApiKey": "sk-..." } }

Azure OpenAI:

{ "Llm": { "Provider": "azure", "Endpoint": "https://xxx.openai.azure.com", "DeploymentName": "gpt-4o", "ApiKey": "..." } }

GitHub Integration

To create workflows from GitHub issues and create PRs:

$env:GITHUB_TOKEN = "ghp_..."

---

Key Features

Stories from GitHub Issues

Start work directly from a GitHub issue:

Command: "Aura: Start Story from Issue"
→ Paste: https://github.com/org/repo/issues/42
→ Aura creates a git worktree and branch
→ Opens VS Code in the isolated worktree

Operational Patterns

Step-by-step playbooks for complex operations:

• comprehensive-rename - Rename domain concepts across the codebase
• generate-tests - Comprehensive test generation with language-specific guidance

Workflow Verification

Before completing a workflow, Aura runs verification checks:

• Build verification (dotnet build, npm build, cargo build, etc.)
• Test verification (runs your test suite)
• Reports pass/fail before finalizing

Agent Reflection

Agents can self-critique their responses for higher quality output:

## Metadata
- **Reflection**: true

---

Project Structure

src/
├── Aura.Foundation/       # Core: LLM, RAG, agents, database
├── Aura.Module.Developer/ # Workflows, git, code analysis
├── Aura.Api/              # HTTP API
└── Aura.AppHost/          # .NET Aspire orchestration

extension/                 # VS Code extension
agents/                    # Agent definitions (Markdown)
prompts/                   # Prompt templates (Handlebars)
patterns/                  # Operational patterns for complex tasks

---

Documentation

Getting Started:

• Installation Guide
• First Run
• Quick Start

User Guide:

• Workflows
• Operational Patterns
• MCP Tools
• Code Indexing
• Use Cases

Configuration:

• LLM Providers
• Settings Reference
• Creating Agents

License

MIT - see LICENSE