BraveCode AI CLI

A free, open-source AI coding CLI with 6 specialized agents, 12+ developer tools, and free model access — all for $0/month with no API keys required.

Features

Free Models — No API Keys Required

| Model | Best For | |-------|----------| | Codestral | Code generation, completions | | Mistral Large | General tasks | | DeepSeek-R1 | Complex reasoning, debugging | | DeepSeek-V3 | Balanced performance | | Voxtral | Audio processing | | Ministral | Fast responses |

12 Built-in Tools

| Tool | Purpose | |------|---------| | bash | Execute shell commands | | read | Read file contents | | write | Create/overwrite files | | edit | Modify existing files | | grep | Search file contents | | glob | Find files by pattern | | browser | Automate web browsers | | webfetch | Fetch URL content | | curl | Make HTTP requests | | todowrite | Manage task lists | | websearch | Search the web | | task | Delegate to subagents |

6 Specialized Agents

| Agent | Purpose | Model | |-------|---------|-------| | Build | Full development access | Codestral | | Plan | Read-only architecture review | Codestral | | Debug | Bug investigation | DeepSeek-R1 | | Testing | Test writing | Codestral | | Security | Vulnerability audit | DeepSeek-R1 | | API Security | API penetration testing | DeepSeek-R1 |

Safety-First Design

• Permission System — Allow/ask/deny for tool execution
• Git Snapshots — Automatic before every file edit
• One-Command Undo — Revert any change instantly
• Context Compaction — Stay within token limits

Installation

npm install -g @bravecode/cli

Or via npx (no install required):

npx @bravecode/cli chat

Quick Start

# Start interactive chat
bravecode

# Run a single command
bravecode run "add error handling to the login function"

# Select a model
bravecode select

# View available models
bravecode models

# List all tools
bravecode tools

# List all agents
bravecode agents

Commands

| Command | Description | |---------|-------------| | bravecode | Start interactive chat | | bravecode chat | Start chat session | | bravecode run <prompt> | Run a single prompt | | bravecode models | List available models | | bravecode providers | List providers | | bravecode select | Interactive model selection | | bravecode tools | List available tools | | bravecode agents | List available agents | | bravecode open <file> | Open file in editor | | bravecode fetch <url> | Fetch URL content | | bravecode init | Initialize AGENTS.md | | bravecode config | View/edit configuration | | bravecode mcp | Manage MCP servers | | bravecode plugins | Manage plugins | | bravecode share | Share conversation | | bravecode update | Update CLI |

Configuration

BraveCode AI stores configuration in ~/.bravecode/config.json.

# View config
bravecode config

# Set a value
bravecode config set editor.theme dark

# Get a value
bravecode config get provider.default

Providers

Configure additional providers in ~/.bravecode/config.json:

{
  "providers": {
    "openrouter": {
      "name": "OpenRouter",
      "apiKey": "sk-or-...",
      "baseUrl": "https://openrouter.ai/api/v1"
    }
  }
}

Default Models

BraveCode AI uses free models by default:

• Codestral — Code generation and completions
• Mistral Large — General tasks
• DeepSeek-R1 — Reasoning and debugging

No API keys required for default models.

Tools in Detail

File Operations

# Read a file
bravecode run "read src/index.ts"

# Write a file
bravecode run "create a hello world Python script"

# Edit a file
bravecode run "add error handling to src/api.ts"

Web Automation

# Search the web
bravecode run "search for React 19 new features"

# Fetch a URL
bravecode run "fetch https://api.example.com/data"

# Open a browser
bravecode run "open https://github.com in a browser"

Task Management

# Create a todo list
bravecode run "create a todo list for building a REST API"

# Mark items complete
bravecode run "mark the first todo as complete"

Multi-Agent Workflows

# Start with build agent
bravecode agents build

# Switch to debug agent
bravecode agents debug

# Use plan agent for architecture
bravecode agents plan

Subagent Delegation

Agents can delegate tasks to other agents:

You: Refactor the authentication module and add tests

Build Agent:
1. Delegates refactoring to Build agent
2. Delegates test writing to Testing agent
3. Delegates security review to Security agent
4. Combines results

Plugin System

Create custom tools and hooks:

# Install a plugin
bravecode plugins install @bravecode/plugin-linter

# List installed plugins
bravecode plugins list

Creating Plugins

// ~/.bravecode/plugins/my-plugin/index.ts
export const plugin = {
  name: 'my-plugin',
  tools: [
    {
      name: 'my-tool',
      description: 'My custom tool',
      execute: async (args) => {
        return { result: 'Hello from my tool!' };
      }
    }
  ],
  hooks: {
    beforeToolCall: async (tool, args) => {
      console.log(`About to call ${tool.name}`);
    }
  }
};

MCP Integration

Connect to external tool servers:

# Add an MCP server
bravecode mcp add my-server npx @modelcontextprotocol/server-filesystem /path/to/dir

# List MCP servers
bravecode mcp list

# Remove an MCP server
bravecode mcp remove my-server

Cross-Platform Support

• Linux — Full support
• macOS — Full support
• Windows — Full support (via Git Bash, WSL, or native)

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/brave-code-tech/brave-ai.git
cd brave-ai

# Install dependencies
npm install

# Build the CLI
npm run build

# Run in development
npm run dev

Project Structure

brave-ai/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── index.ts            # Public exports
│   ├── provider.ts         # LLM provider manager
│   ├── autoModel.ts        # Auto-model selection
│   ├── core/
│   │   ├── agent/          # Agent system
│   │   ├── tool/           # Tool implementations
│   │   ├── permission/     # Permission system
│   │   ├── snapshot/       # Git snapshots
│   │   ├── config/         # Configuration
│   │   ├── context/        # Context compaction
│   │   ├── mcp/            # MCP integration
│   │   ├── plugin/         # Plugin system
│   │   ├── share/          # Sharing
│   │   ├── update/         # Auto-update
│   │   └── tui/            # Terminal UI
│   └── ...
├── scripts/
│   ├── build.js            # Build script
│   └── postinstall.js      # Post-install setup
├── package.json
├── tsconfig.json
└── BUILD-AGENTIC-AI-VIBE-CODING-CLI.md  # Architecture

Build

# Build for production
npm run build

# Output: dist/cli.cjs

Testing

# Run tests
npm test

# Run specific test
npm test -- --grep "tool name"

Architecture

See BUILD-AGENTIC-AI-VIBE-CODING-CLI.md for the complete architecture document.

Contributing

1. Fork the repository
2. Create a 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

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation
• Follow existing code style

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: bravecode.dev

Acknowledgments

• Vercel AI SDK — AI SDK for model integration
• Commander.js — CLI framework
• Ink — React for CLI
• Codero — Free model API

Built with TypeScript, Node.js, and a passion for accessible AI coding tools.