🐺 BeastCLI

The Ultimate AI-Powered Coding Agent for Developers

✨ What is BeastCLI?

BeastCLI is a powerful, open-source AI coding agent that brings intelligent automation to your terminal. It leverages cutting-edge AI models from NVIDIA NIM, OpenRouter, OpenAI, Gemini, Ollama, and 200+ providers via OpenAI-compatible API. Built with TypeScript, React, and Ink for a beautiful terminal experience.

🎯 Core Features

• 🤖 Multi-Provider AI — NVIDIA NIM, OpenRouter, OpenAI, Gemini, Ollama, Mistral, Codex, and 200+ models via OpenAI-compatible API
• ⚡ Built with Bun — Fast startup and blazing performance
• 🛠️ 21 Native Tools — Calculator, UUID, Weather, Currency, QR Code, YouTube Transcripts, and more — no API keys needed!
• 📡 Real-time Streaming — Live token output and tool progress
• 🎨 Rich Terminal UI — Colored output with an Ink-based React interface
• 🔌 MCP Server Support — Connect to Model Context Protocol servers for extended capabilities
• 💾 Local Model Support — Run with Ollama, fully offline and free
• 🦁 Permission Modes — Guidance, AutoPilot, Control, Observe — switch with Ctrl+S
• 🚀 NVIDIA Rate Limiting — 40 RPM support with exponential backoff
• 🔄 Coordinator Mode — Spawn worker sub-agents for parallel task execution
• ⏰ Cron Scheduling — Schedule recurring tasks with /loop
• 📝 Skills System — Extensible skills for batch processing, code review, simplify, and more
• 🧠 Memory & Context — Session memory, context collapse, and compact mode for long conversations
• 🔍 Auto-Debug & Auto-Fix — Built-in debugging assistance and automatic fix suggestions
• 📊 Analytics & Observability — OpenTelemetry integration, token estimation, usage stats
• 🌐 Web Intelligence — Web search, web fetch with Crawl4AI fallback, and news tools
• 🔑 GitHub Integration — PR reviews, issue management, branch handling, and GitHub App installation
• 📦 Plugin System — Extensible plugin architecture for custom functionality

🚀 Quick Start

Installation

npm install -g @simpletoolsindia/beastcli

Launch

beastcli

That's it! BeastCLI will guide you through the initial setup.

⚡ Quick Provider Setup

NVIDIA NIM (Fast GPU Inference)

# Get your API key from https://ngc.nvidia.com/
export NVIDIA_API_KEY=nvapi-your-key-here
export OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1
export OPENAI_MODEL=nvidia/llama-3.3-nemotron-70b-instruct

beastcli

OpenRouter (200+ Models)

# Get your API key from https://openrouter.ai/
export OPENROUTER_API_KEY=sk-or-v1-xxx
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
export OPENAI_MODEL=anthropic/claude-3.5-sonnet

beastcli

Ollama (Local — Free & Offline)

# Install Ollama from https://ollama.ai/
ollama pull llama3.2
ollama pull mistral

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3.2

beastcli

OpenAI (GPT-4)

# Get your API key from https://platform.openai.com/
export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_MODEL=gpt-4o

beastcli

🏗️ Provider Configuration

BeastCLI supports 7 providers with a guided interactive setup:

Using /provider Command (Interactive)

/provider          # Open interactive provider manager — choose provider, set model, API key

The /provider wizard shows:

• Current provider and model in use
• Saved profile name
• Choice of: Auto (detects Ollama or guides OpenAI setup), Ollama, OpenAI-compatible, Gemini, Mistral, Codex, Codex OAuth, or Clear saved profile

Using /provider setup (Quick CLI)

/provider setup nvidia     # Configure NVIDIA NIM (fast GPU inference)
/provider setup openrouter # Configure OpenRouter (200+ models)
/provider setup ollama     # Configure Ollama (local, free)
/provider setup openai     # Configure OpenAI (GPT-4)
/provider setup status     # View all provider key statuses

Environment Variables

Switching Providers (Runtime)

Simply run /provider at any time — BeastCLI will show the current provider and let you switch. Provider profiles are saved to ~/.beastcli/beastcli-profile.json and persist across sessions.

🛠️ 21 Native Tools (No API Keys Needed!)

All native tools work without any API configuration:

View All Tools

/tools        # List all available tools
/tools search # Search for specific tools

🦁 Permission Modes

BeastCLI features four permission modes for different use cases:

Switching Modes

• Ctrl+S — Cycle through all modes
• Shift+Tab — Toggle between Guidance and AutoPilot
• /permissions — View current mode

📁 Project Setup

Create a New Project

mkdir my-project && cd my-project
beastcli

Project Configuration

BeastCLI automatically looks for configuration in:

• ./.beastcli/settings.json — Project settings
• ./.beastcli/skills/ — Project-specific skills
• ~/.beastcli/settings.json — User settings
• ~/.beastcli/skills/ — User skills

🔌 MCP Server Support

Connect to Model Context Protocol servers for extended capabilities:

/mcp add <server-name>   # Add MCP server
/mcp list                # List connected servers
/mcp remove <name>       # Remove server
/mcp auth                # Manage MCP authentication

⏰ Skills System

Extensible skills that enhance BeastCLI's capabilities:

View All Skills

/skills              # List all available skills
/skills install <name> # Install a skill

🎮 Slash Commands

General

Git Operations

Agent & Tasks

Search & Navigation

Utilities

⌨️ Keyboard Shortcuts

🎨 Customization

Themes

/theme                  # View themes
/theme set dark         # Set dark theme
/theme set light        # Set light theme
/theme set midnight     # Set midnight theme

Output Styles

/output-style           # View output styles
/output-style set <name> # Set style

Status Line

/statusline             # Configure status line

🔧 Configuration Files

settings.json

{
  "permissions": "ask",
  "model": "nvidia/llama-3.3-nemotron-70b-instruct",
  "theme": "dark",
  "outputStyle": "default"
}

.env File

Create ~/.beastcli/.env for persistent environment variables:

NVIDIA_API_KEY=nvapi-your-key
OPENROUTER_API_KEY=sk-or-v1-xxx
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=anthropic/claude-3.5-sonnet

🐛 Troubleshooting

Initial prompt too large?

If you're using a third-party provider (NVIDIA NIM, OpenRouter, Ollama, etc.) and the initial prompt feels large, enable Tool Search to defer 21 native tools:

export ENABLE_TOOL_SEARCH=true

This saves approximately ~6,000 tokens per request by loading native tools (Calculator, UUID, Weather, QR Code, etc.) on-demand instead of upfront. When you need a native tool, just ask — BeastCLI will fetch its schema automatically.

Provider Issues

/doctor                  # Run diagnostics
/provider setup status   # Check provider status

Common Problems

NVIDIA Rate Limited?

• Wait 60 seconds (default 40 RPM limit)
• Or configure via /rate-limit-options

OpenRouter Slow?

• Try a different model
• Check API status at openrouter.ai

Ollama Not Found?

• Install from ollama.ai
• Run ollama serve to start server
• Try ollama pull llama3.2

📊 Architecture

┌──────────────────────────────────────────────┐
│                  BeastCLI CLI                  │
├──────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────────┐       │
│  │  Commands   │  │      Tools       │       │
│  │  (90+ cmds) │  │  Native / CLI /  │       │
│  └─────────────┘  │  MCP / Agent     │       │
│  ┌─────────────┐  └──────────────────┘       │
│  │   Skills    │  ┌──────────────────┐       │
│  │  (12 built) │  │    Coordinator    │       │
│  └─────────────┘  │  (Multi-Agent)   │       │
├──────────────────────────────────────────────┤
│  ┌──────────────────────────────────────┐    │
│  │        AI Provider Layer              │    │
│  │  NVIDIA │ OpenRouter │ OpenAI │      │    │
│  │  Gemini │ Ollama │ Mistral │ Codex  │    │
│  │  200+ OpenAI-compatible providers    │    │
│  └──────────────────────────────────────┘    │
├──────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────────┐       │
│  │    MCP      │  │   Services       │       │
│  │  Servers    │  │  Analytics,      │       │
│  │             │  │  RateLimits,     │       │
│  │             │  │  Plugins, LSP     │       │
│  └─────────────┘  └──────────────────┘       │
└──────────────────────────────────────────────┘

🤝 Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

📄 License

MIT License — see LICENSE file for details.

Built with ❤️ by SimpleTools India
GitHub • NPM • Discord