Buff — AI-Native Coding Assistant for the Terminal

Buff is an AI-powered coding assistant that lives in your terminal. It integrates with multiple LLM providers — OpenAI, Anthropic, Gemini, DeepSeek, MiniMax, and more — to help you write, understand, debug, and refactor code without leaving the command line.

$ buff ask "Explain this TypeScript utility type"
$ buff review src/auth.ts
$ buff edit src/routes.ts -i "Add input validation"
$ buff commit
$ buff run "npm test" --no-confirm

Table of Contents

• Buff — AI-Native Coding Assistant for the Terminal
  • Table of Contents
  • Features
  • Installation
    • Requirements
  • Quick Start
    • 1. Configure a Provider
    • 2. Set Your Default Provider
    • 3. Start Using It
  • CLI Commands
    • Chat Features
    • Shell Completion
  • | ↑ / ↓ | Scroll multiline input |
  • Configuration
    • Environment Variables
    • Project Custom Instructions (.buffrules)
    • Chat Theme Configuration
    • CLI Config Commands
    • Config File Precedence
  • Supported Providers
  • Prompt Templates
  • Safety
  • Memory System
  • Session Management
  • Troubleshooting
    • Quick Diagnostics
    • Common Issues
    • Need More Help?
  • Development
    • Pull Requests
  • Documentation
  • Getting Help
  • License

Features

• Multi-provider support — OpenAI GPT-4o, Anthropic Claude, Google Gemini, DeepSeek V4, MiniMax M2.5, Ollama (local), OpenRouter, and any OpenAI-compatible endpoint
• Streaming responses — Real-time token-by-token output with plain-text thinking indicator and automatic non-streaming fallback
• Built-in tools — Filesystem operations, git integration, and terminal commands with safety checks
• Context-aware — Reads your working directory, git status, and project files automatically
• Session management — Persistent conversation history with search, export, and rename
• Long-term memory — Remembers your preferences and coding style across sessions
• Plugin system — Extend with custom commands, tools, and lifecycle hooks. Includes example plugins (code-review, frontend-design)
• Prompt templates — Built-in templates for explain, review, refactor, fix, test, and optimize
• Safety guards — Blocked/dangerous command detection prevents accidental destructive operations
• Full Ink/React Chat UI — buff chat renders with React-based terminal UI (Ink v7 + React 19) featuring streaming responses with real-time syntax-highlighted markdown, tool call output, collapsible context/tools panels (Ctrl+E / Ctrl+T), keyboard shortcuts, and a help overlay
• Configurable Themes — 8 preset color schemes (dark, light, oled, solarized-dark/light, nord, dracula, monokai) with OS-level dark/light auto-detection, config overrides for any color, and a /theme slash command for live switching inside chat
• Custom Instruction File (.buffrules) — Project-level .buffrules file with coding conventions, architectural patterns, and AI preferences. Automatically loaded from the project root (walks up parent directories). Injected into system prompts for chat, ask, explain, review, fix, edit, and commit commands
• Image/Multimodal Input — Pass images via buff ask -i screenshot.png "What's wrong?" or /add-image image.png in chat. Supported models: GPT-4o, Claude Sonnet 4, Gemini 2.5. Formats: PNG, JPG, GIF, WebP, BMP
• Semantic Code Search — buff search "find auth handlers" finds relevant code using embeddings and cosine similarity, with caching and chunking
• Git Conflict Resolver — buff resolve reads conflicted files, understands both sides of the merge, and suggests a resolution with explanations
• Pre-commit Hook — buff precommit reviews staged files and can block commits on critical issues; buff install-hook installs it as a git hook
• AI Rename & Generate — buff rename renames symbols across files; buff generate creates boilerplate code (components, modules, tests) from a description
• File Watcher — buff watch "src/**/*.ts" -- npm test watches files for changes and runs a command on change. Pattern filtering, debouncing, and cross-platform shell support
• Auto-Refresh Context in Chat — buff chat automatically re-gathers project context (git status, package info) when files change, keeping the AI aware of your latest edits
• Batch Mode — buff batch "Add JSDoc" src/**/*.ts applies an AI prompt across multiple files with glob pattern matching, per-file diff preview, and auto-apply via -y / --yes or --no-confirm
• MCP Support — Model Context Protocol server and client for tool interoperability
• Plugin System — Extend with custom commands, tools, and lifecycle hooks. Includes example plugins (code-review, frontend-design)
• Diagnostics — buff doctor runs health checks on your environment, config, and providers
• Slash Commands — /help, /clear, /model, /theme, /add-image — all with tab-completion and inline descriptions
• Windows stability — buff chat is fully stable and reliable on Windows
• Shell Completion — buff completion bash|zsh|fish generates tab-completion scripts covering all 30 commands, options, provider names, model names, and file paths
• REPL command suggestions — Tab-completion for slash commands with descriptions shown as inline suggestions in buff chat

Installation

npm install -g ai-coder-cli

This installs the buff command globally.

Requirements

• Node.js >= 22.0.0
• npm >= 10.x
• An API key for at least one LLM provider

Quick Start

1. Configure a Provider

# Interactive setup
buff login

# Or configure a specific provider directly
buff login openai
buff login anthropic
buff login gemini
buff login deepseek
buff login minimax

You'll be prompted for your API key. Keys are stored securely in ~/.buff/config.json.

Alternatively, set environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."
export DEEPSEEK_API_KEY="sk-..."
export MINIMAX_API_KEY="..."

2. Set Your Default Provider

buff provider openai -m gpt-4o

3. Start Using It

# Ask a question
buff ask "How do I create a Zod schema for user input?"

# Explain a file
buff explain src/routes.ts

# Review code
buff review src/auth.ts

# Fix an issue
buff fix src/parser.ts -i "Null reference when input is empty"

# Generate a commit message
buff commit

# Run a command with safety checks
buff run "npm test"

CLI Commands

| Command | Description | Example | | -------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- | | ask | Ask a single question and get a response | buff ask "What is a monad?" | | chat | Start an interactive chat session (full Ink/React UI with streaming, themes, slash commands) | buff chat | | explain | Explain code in detail | buff explain src/utils.ts | | review | Perform a thorough code review | buff review src/auth.ts | | rename | Rename a symbol across files using AI | buff rename oldName newName | | generate | Generate boilerplate code from a description | buff generate component "Button" | | resolve | Resolve git merge conflicts using AI | buff resolve | | precommit | Review staged files and block on critical issues | buff precommit | | install-hook | Install/remove pre-commit git hook | buff install-hook | | edit | Edit a file using AI with diff preview | buff edit src/routes.ts -i "Add validation" | | fix | Fix bugs or issues in code | buff fix src/parser.ts --issue "Null crash" | | commit | Generate a git commit message from diff | buff commit --staged | | run | Execute terminal commands with safety checks | buff run "npm test" | | models | List available models | buff models openai | | provider | View or switch the default provider | buff provider gemini -m gemini-2.5-flash | | login | Configure API keys for providers | buff login anthropic | | logout | Remove API keys for providers | buff logout openai | | configure | View or modify configuration | buff configure --set verbose=true | | sessions | Manage conversation sessions | buff sessions list | | memory | Manage long-term memory | buff memory set language TypeScript | | history | View chat history | buff history 20 | | batch | Apply an AI prompt across multiple files (-y / --yes to auto-apply) | buff batch "Add JSDoc" src/**/*.ts | | watch | Watch files for changes, optionally run a command on change | buff watch "src/**/*.ts" -- npm test | | search | Semantic code search via natural language | buff search "find auth handlers" | | doctor | Run diagnostics and health checks | buff doctor | | mcp | MCP server/client mode | buff mcp | | init | Initialize project-level config | buff init -p openai -m gpt-4o | | update | Check for updates | buff update | | ink | Legacy Ink demo (same as buff chat) | buff ink | | completion | Generate shell completion scripts | buff completion bash |

For detailed help on any command:

buff <command> --help

Chat Features

buff chat provides a rich interactive experience with Ink/React rendering, streaming responses, and the following slash commands:

| Command | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | /help | Show available commands and keyboard shortcuts | | /theme <name> | Switch theme — mode (dark, light, system) or preset (nord, dracula, monokai, oled, solarized-dark, solarized-light) | | /theme list | List all available themes | | /theme status | Show current theme settings | | /model <name> | Switch the active model | | /provider <name> | Switch the active provider | | /reset | Reset conversation to initial state (clears history) | | /context | Show currently loaded project context | | /files | List files added as context | | /edit | Open current input in external text editor ($EDITOR) | | /refresh | Manually refresh the project context (auto-refreshes on file changes) | | /exit | Quit the chat session |

Shell Completion

buff completion generates tab-completion scripts for Bash, Zsh, and Fish:

# Generate and source the script (temporary for current session)
source <(buff completion bash)     # Bash
source <(buff completion zsh)      # Zsh
buff completion fish | source      # Fish

# Permanent installation
buff completion bash >> ~/.bashrc                         # Bash
mkdir -p ~/.zsh/completion && buff completion zsh > ~/.zsh/completion/_buff       # Zsh
echo "fpath=(~/.zsh/completion \$fpath)" >> ~/.zshrc && compinit                 # enable in zshrc
mkdir -p ~/.config/fish/completions && buff completion fish > ~/.config/fish/completions/buff.fish  # Fish

The completions cover all 30 commands, their options (--model, --provider, --image, --no-stream, etc.), provider names, common model names, file paths, and sub-arguments.

Keyboard shortcuts:

| Shortcut | Action | | --------- | ---------------------- | | Ctrl+C | Exit chat | | Ctrl+E | Toggle context panel | | Ctrl+T | Toggle tools panel | | Enter | Submit message | | ↑ / ↓ | Scroll multiline input |

Configuration

Configuration is stored in ~/.buff/config.json. Project-level overrides can be placed in .buff.json in your project root.

Environment Variables

| Variable | Purpose | | -------------------- | ----------------------------- | | OPENAI_API_KEY | API key for OpenAI | | ANTHROPIC_API_KEY | API key for Anthropic | | GEMINI_API_KEY | API key for Google Gemini | | DEEPSEEK_API_KEY | API key for DeepSeek | | MINIMAX_API_KEY | API key for MiniMax | | OPENROUTER_API_KEY | API key for OpenRouter | | CUSTOM_API_KEY | API key for custom endpoints | | CUSTOM_BASE_URL | Base URL for custom endpoints |

Project Custom Instructions (.buffrules)

Create a .buffrules file in your project root to define coding conventions, architectural patterns, and preferences the AI should follow. This is similar to .cursorrules or .clinerules.

The file is automatically loaded when buff is run in or below that directory (walks up parent directories). Its content is injected into all AI prompts — chat, ask, explain, review, fix, edit, and commit.

# .buffrules — Example

## Coding Conventions
- Use TypeScript strict mode
- Prefer interfaces over types
- Use named exports, not default exports
- Follow React hooks conventions (prefix with "use")
- Use `import type` for type-only imports

## Architecture
- Feature-based directory structure
- Shared utilities go in `src/utils/`
- API layer in `src/api/` with React Query
- Components in `src/components/`

## Testing
- Write tests for all new code
- Use Vitest for unit tests
- Use Testing Library for component tests
- Aim for >80% coverage

Chat Theme Configuration

Customize the chat appearance by adding theme settings to your config. You can use a named preset for quick switching, set a base mode (dark/light/system), and optionally override individual colors.

{
  "themePreset": "nord",
  "themeMode": "system",
  "theme": {
    "primary": "#bd93f9",
    "accent": "#50fa7b",
    "bg": "#282a36"
  }
}

Options:

| Field | Type | Default | Description | | ------------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | themePreset | preset name | none | Named theme preset — applies all 22 colors at once. Overrides themeMode. One of: dark, light, oled, solarized-dark, solarized-light, nord, dracula, monokai | | themeMode | "dark" | "light" | "system" | "dark" | Base color scheme. Only used when no themePreset is set. "system" auto-detects from Windows registry, macOS defaults, or Linux GTK_THEME | | theme | object | {} | Partial color overrides — any of the 22 color fields can be specified on top of a preset or mode |

Available color fields: primary, accent, error, success, warning, muted, bg, subtle, userMessage, aiMessage, systemMessage, toolMessage, codeKeyword, codeString, codeNumber, codeComment, codeType, codeFunction, codeProperty, codeOperator, codePunctuation

Priority (highest to lowest):

1. Inline /theme slash command overrides (live, in-session)
2. Config file themePreset / themeMode / theme overrides
3. Default dark preset

You can switch themes interactively inside buff chat using the /theme command. Changes are persisted to your config file automatically:

/theme nord            # Switch to Nord preset
/theme dark            # Switch to dark mode
/theme light           # Switch to light mode
/theme list            # List all available presets
/theme status          # Show current active settings

Available presets:

| Preset | Description | | ----------------- | ------------------------------------------- | | dark (default) | Cyan/violet on dark background | | light | Indigo/violet on light background | | oled | True-black background for OLED displays | | solarized-dark | Solarized dark — warm earth tones on dark | | solarized-light | Solarized light — warm earth tones on light | | nord | Arctic, bluish pastel palette | | dracula | Dark with vibrant purple/green accents | | monokai | High-contrast with bold pink/green |

CLI Config Commands

# View current config
buff configure

# Set values
buff configure --set defaultProvider=anthropic
buff configure --set verbose=true
buff configure --set logLevel=debug

# Output as JSON (for scripting)
buff configure --json

# Reset to defaults
buff configure --reset

# Set project-level config (creates .buff.json)
buff configure --project --set defaultModel=gpt-4o-mini

Config File Precedence

1. Environment variables (highest priority)
2. Project-level .buff.json
3. Global ~/.buff/config.json
4. Built-in defaults (lowest priority)

Supported Providers

| Provider | ID | Models | Auth | | ----------------- | ------------ | ---------------------------------------------------- | ------------ | | OpenAI | openai | GPT-4o, GPT-4o-mini, o1, o1-mini, o3-mini | API key | | Anthropic | anthropic | Claude Sonnet 4, Claude 3.5 Haiku, Claude 3.5 Sonnet | API key | | Google Gemini | gemini | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash | API key | | DeepSeek | deepseek | DeepSeek V4 Pro, DeepSeek V4 Flash | API key | | MiniMax | minimax | MiniMax M2.5, MiniMax M2.5 High-Speed | API key | | OpenRouter | openrouter | 200+ models via single API | API key | | Ollama | ollama | Any local model (Llama 3, Mistral, etc.) | None (local) | | Custom | custom | Configurable OpenAI-compatible endpoint | Optional |

Prompt Templates

Built-in templates for common tasks:

buff explain  # Explain code
buff review   # Code review
buff fix      # Fix bugs
buff commit   # Git commit messages

# All available templates:
explain, review, refactor, fix, test, optimize, commit, pr_summary

Safety

The buff run command and terminal tools include built-in safety checks:

• Blocked commands — rm -rf /, sudo, mkfs, shutdown, reboot, format (cannot be executed)
• Dangerous commands — rm -r, git push, git reset --hard, npm publish (require confirmation)
• Timeout — Commands are automatically killed after a configurable timeout (default: 30s)

# Run with automatic confirmation (skips danger prompt)
buff run "npm run build" --no-confirm

# Custom timeout
buff run "npm test" --timeout 60000

# Custom working directory
buff run "git status" --cwd /path/to/project

Memory System

Buff has a long-term memory system that remembers your preferences and project context across sessions.

# Set a memory
buff memory set language TypeScript

# Get a memory
buff memory get language

# List all memories
buff memory list

# Search memories
buff memory search TypeScript

# Delete a memory
buff memory delete language

# Clear all memories
buff memory clear

Session Management

Every buff ask, buff chat, and buff edit session is automatically saved.

# List recent sessions
buff sessions list

# View a session
buff sessions view <session-id>

# Search sessions
buff sessions list --search "authentication"

# Export as markdown
buff sessions export <session-id>

# Rename a session
buff sessions rename <session-id> --name "Auth refactor"

# Delete a session
buff sessions delete <session-id>

Troubleshooting

If you encounter problems, here are some quick steps before reaching out for help:

Quick Diagnostics

# Run the built-in health check
buff doctor

# Check your version
buff --version

# Run with verbose logging for detailed output
buff --verbose ask "Hello"

Common Issues

| Issue | Likely Cause | Solution | | --------------------------- | ------------------------------ | ------------------------------------------------------- | | 'buff' is not recognized | Not installed or not in PATH | Run npm install -g . from the project directory | | No API key configured | Missing API key | Run buff login <provider> or set environment variable | | Provider is not available | API unreachable or invalid key | Check your internet connection and API key validity | | Rate limit exceeded | Too many requests | Wait and retry, or check your provider's rate limits | | Token limit exceeded | Context too large | Use /reset in chat or reduce input size |

Need More Help?

For a comprehensive troubleshooting guide with detailed error explanations, FAQ, and environment checks, see SUPPORT.md.

Development

# Clone the repository
git clone https://github.com/zntb/ai-coder-cli
cd ai-coder-cli

# Install dependencies
npm install

# Run in development mode
npm run dev -- ask "Hello"

# Build for production
npm run build

# Run tests
npm test                  # All tests
npm run test:watch        # Watch mode
npm run test:coverage     # With coverage

# Lint and format
npm run lint
npm run lint:fix
npm run format
npm run format:check
npm run typecheck

Pull Requests

Before submitting a pull request, review the PULL_REQUEST_TEMPLATE.md which provides a structured checklist covering:

• Type of change — Categorize as feat, fix, docs, refactor, test, perf, style, or chore
• Test verification — Confirm tests pass, lint is clean, TypeScript compiles
• Code quality — Follows standards, includes tests, has docs, no any types
• Commit style — Conventional Commits format

See CONTRIBUTING.md for the full development workflow and coding standards.

Documentation

| Document | Description | | --------------------------------------------- | -------------------------------------------------------- | | ARCHITECTURE.md | Project structure, module dependencies, design decisions | | CONTRIBUTING.md | Development setup, coding standards, PR process | | CHANGELOG.md | Release history and version notes | | GOVERNANCE.md | Project leadership, roles, decision-making process | | SECURITY.md | Vulnerability reporting guidelines and disclosure policy | | SUPPORT.md | Support channels, FAQ, and troubleshooting guide | | RELEASE.md | Release process, version synchronization, pre-release workflow | | PROVIDER_GUIDE.md | Step-by-step guide to adding a new LLM provider | | PLUGIN_GUIDE.md | Guide to extending Buff with plugins |

Getting Help

• 📖 Documentation — See the Documentation table above
• 🐛 Bug reports — Open a GitHub Issue — choose the bug report template for structured reproduction steps, environment details, and logs
• ✨ Feature requests — Suggest ideas via the feature request template — include the problem, proposed solution, and example usage
• 💬 Discussions — Ask questions and share ideas on GitHub Discussions
• 🔒 Security issues — Report via SECURITY.md (not through public issues)

License

MIT