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