Blu

Blu is a Go-powered terminal UI that brings AI-assisted coding directly into your command line. It connects to leading models and gives them tools to read, analyze, and modify your codebase from an elegant TUI built with Bubble Tea.

Overview

Blu is a Go-powered terminal UI that transforms your command line into an intelligent development environment. It connects to leading AI models and provides them with powerful tools to read, analyze, and modify your codebase - all from an elegant TUI built with Bubble Tea.

Key capabilities:

• Chat with AI models that can see and edit your files
• Execute bash commands through AI suggestions
• Apply complex code refactors automatically
• Get real-time LSP diagnostics and code intelligence
• Manage multiple conversation sessions with full context
• Use Model Context Protocol (MCP) servers for extensibility

Quick Start

Installation

Via npm (recommended):

npm install -g @get-blu/blu-code

Via raw script:

curl -fsSL https://raw.githubusercontent.com/Get-Blu/blu-code/main/install | bash

From source:

git clone https://github.com/Get-Blu/blu-code.git
cd blu-code
go build -o blu
blu

Setup

1. Set your API key(s):

export ANTHROPIC_API_KEY="your-key-here"
# or OPENAI_API_KEY, GEMINI_API_KEY

2. Create a .blu.json config file (optional):

{
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 8192
    }
  },
  "autoCompact": true
}

3. Launch Blu:

blu

Features

Multi-Model Support

Switch between Claude, GPT, Gemini, or any OpenAI-compatible endpoint. Use different models for different tasks within the same session.

Intelligent File Operations

• Glob patterns: Find files matching complex patterns
• Smart grep: Search across your codebase with regex
• Atomic edits: Apply precise diffs and patches
• Batch operations: Modify multiple files in one go

Development Tools

• LSP Integration: Real-time diagnostics and code intelligence via Language Server Protocol
• Command execution: Run bash commands directly from chat
• MCP Support: Extend with Model Context Protocol servers
• Version control aware: Understands your git context

Productivity Features

• Session management: Switch between multiple conversations (Ctrl+S)
• Custom commands: Create reusable prompt templates (Ctrl+K)
• Auto-compaction: Intelligent context window management
• SQLite persistence: Full local history storage
• Interactive sidebar: Visualize file changes in real-time

Usage

Basic Workflow

1. Start a conversation: Launch blu and ask a question
2. Let AI explore: Blu can read files, search your codebase, and understand context
3. Review changes: See proposed file modifications in the sidebar
4. Apply or reject: Accept changes you want, skip the rest

Documentation

Comprehensive documentation is available in the docs/ directory:

• Introduction
• Getting Started
• Configuration
• Key Bindings
• Architecture

Detailed Features

• AI Chat
• File Operations
• LSP Intelligence
• MCP Servers
• Session Management

Guides

• Best Practices
• Troubleshooting

Keyboard Shortcuts

Global Shortcuts

| Shortcut | Action | | -------- | ------------------------------------------------------- | | Ctrl+C | Quit application | | Ctrl+? | Toggle help dialog | | ? | Toggle help dialog (when not in editing mode) | | Ctrl+L | View logs | | Ctrl+S | Switch session | | Ctrl+K | Command dialog | | Ctrl+O | Toggle model selection dialog | | Ctrl+P | Toggle provider selection (API key configuration) | | Esc | Close current overlay/dialog or return to previous mode |

Chat Page Shortcuts

| Shortcut | Action | | -------- | --------------------------------------- | | Ctrl+N | Create new session | | Ctrl+X | Cancel current operation/generation | | i | Focus editor (when not in writing mode) | | Esc | Exit writing mode and focus messages |

Editor Shortcuts

| Shortcut | Action | | ------------------- | ----------------------------------------- | | Ctrl+S | Send message (when editor is focused) | | Enter or Ctrl+S | Send message (when editor is not focused) | | Ctrl+E | Open external editor | | Esc | Blur editor and focus messages |

Session Dialog Shortcuts

| Shortcut | Action | | ---------- | ---------------- | | ↑ or k | Previous session | | ↓ or j | Next session | | Enter | Select session | | Esc | Close dialog |

Model Dialog Shortcuts

| Shortcut | Action | | ---------- | ----------------- | | ↑ or k | Move up | | ↓ or j | Move down | | ← or h | Previous provider (within model dialog) | | → or l | Next provider (within model dialog) | | Esc | Close dialog |

Provider & API Key Dialog Shortcuts

| Shortcut | Action | | -------- | -------------------- | | ↑ / ↓ | Move up/down | | Enter | Select provider | | Esc | Close dialog | | Enter | Save API key (input) |

Permission Dialog Shortcuts

| Shortcut | Action | | ----------------------- | ---------------------------- | | ← or left | Switch options left | | → or right or tab | Switch options right | | Enter or space | Confirm selection | | a | Allow permission | | A | Allow permission for session | | d | Deny permission |

Logs Page Shortcuts

| Shortcut | Action | | ------------------ | ------------------- | | Backspace or q | Return to chat page |

Configuration

Place .blu.json in your home directory (~/.blu.json) or project root:

{
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 8192,
      "temperature": 0.7
    },
    "summarizer": {
      "model": "gpt-4o-mini",
      "maxTokens": 2048
    }
  },
  "autoCompact": true,
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

Supported Models

Anthropic (Claude):

• claude-3.7-sonnet - Recommended for coding (supports reasoning)
• claude-3.5-sonnet - Fast and highly capable
• claude-4.6-opus - Next-gen flagship capability

OpenAI:

• o3-ultra - Latest reasoning flagship
• gpt-5.3-codex - Specialized for agentic coding
• gpt-4o - Balanced speed and intelligence

Google:

• gemini-3-deep-think - Advanced reasoning and engineering
• gemini-2.0-flash - High-speed intelligence
• gemini-1.5-pro - Large context window

DeepSeek:

• deepseek-v3 - High performance open-weights model
• deepseek-r1 - Reasoning focused model

Environment Variables

| Variable | Purpose | |----------|---------| | ANTHROPIC_API_KEY | Claude API access | | OPENAI_API_KEY | GPT-4 API access | | GEMINI_API_KEY | Gemini API access | | BLU_DEBUG=true | Enable debug logging | | BLU_CONFIG=/path/to/.blu.json | Custom config location |

Troubleshooting

Blu won't start

• Check your API keys are set
• Verify Go 1.21+ is installed
• Try blu --debug for detailed logs

AI can't see my files

• Ensure you're running Blu from your project directory
• Check file permissions
• Verify paths in error messages

Context window errors

• Enable autoCompact in config
• Start a new session for fresh context
• Use more concise prompts

Building from Source

# Clone the repository
git clone https://github.com/Get-Blu/blu-code.git
cd blu-code

# Install dependencies
go mod download

# Build
go build -o blu

# Run tests
go test ./...

# Install globally
sudo mv blu /usr/local/bin/

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Credits

Blu builds on the excellent work of many open-source projects:

• Bubble Tea - Excellent TUI framework
• Lip Gloss - Style definitions for TUI
• Go-GitHub - GitHub API client
• Sqlite3 - Local persistence

License

Distributed under the MIT License. See LICENSE for more information.

Created by Garv Agnihotri