Overview • Installation • Usage • MCP Integration • Development

🎉 Enhanced Fork: This is an enhanced version of the original Groq Code CLI with additional features including MCP integration, developer tools, and a refreshed purple-turquoise color scheme. All credit for the original codebase goes to the Groq team.

• Overview
• What's New
• Installation
• Usage
  • Authentication
  • Available Commands
  • Developer Tools
• MCP Integration
  • Brave Search MCP Server
  • Setup MCP Servers
  • Available MCP Servers
• Development
• Changelog
• Credits

Coding CLIs are everywhere. The Groq Code CLI is different. It is a blueprint, a building block, for developers looking to leverage, customize, and extend a CLI to be entirely their own. Leading open-source CLIs are all fantastic, inspiring for the open-source community, and hugely rich in features. However, that's just it: they are gigantic. Feature-rich: yes, but local development with such a large and interwoven codebase is unfriendly and overwhelming. This is a project for developers looking to dive in.

Groq Code CLI is your chance to make a CLI truly your own. Equipped with all of the features, tools, commands, and UI/UX that's familiar to your current favorite CLI, we make it simple to add new features you've always wanted. By massively cutting down on bloat and code mass without compromising on quality, you can jump into modifying this CLI however you see fit. By leveraging models on Groq, you can iterate even faster. Simply activate the CLI by typing groq in your terminal.

This enhanced fork adds powerful features on top of the original Groq Code CLI:

• Interactive Server Management: Type /mcp for interactive server selection with arrow keys
• Automatic API Key Management: Secure API key input, automatically saved to config
• Dynamic Path Support: Use {{cwd}} placeholder for current working directory
• Custom Brave Search Server: Built-in web/news/local search (official package doesn't exist!)
• Connect to External Servers: Filesystem, GitHub, Google Maps, Postgres, Slack, and more
• MCP Tools: mcp_connect, mcp_call_tool, mcp_read_resource, mcp_list
• Auto-Discovery: Automatically discover tools, resources, and prompts

• Git Operations: Status, diff, log, add, commit, branch management
• TODO Extraction: Find all TODO/FIXME/HACK/NOTE/BUG/XXX comments
• Dependency Analysis: Check package versions and outdated dependencies
• New Commands: /context, /todos, /init, /mcp

• Purple-Turquoise Theme: Beautiful gradient (#9D4EDD → #00F5FF)
• Enhanced Banner: Smooth color transitions in ASCII art
• Updated Badges: Color-coordinated documentation

# Clone this enhanced version
git clone https://github.com/mcrao/groq-code-cli-enhanced.git
cd groq-code-cli-enhanced

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (enables `groq` command)
npm link

Note: Replace mcrao/groq-code-cli-enhanced with your actual repository URL.

# Run in background during development for auto-rebuild
npm run dev

To use the original Groq Code CLI (without enhancements):

# Using npx, no installation required
npx groq-code-cli@latest

# Or install globally
npm install -g groq-code-cli@latest

# Start chat session
groq

groq [options]

Options:
  -t, --temperature <temp>      Temperature for generation (default: 1)
  -s, --system <message>        Custom system message
  -d, --debug                   Enable debug logging
  -p, --proxy <url>             Proxy URL (http/https/socks5)
  -h, --help                    Display help
  -V, --version                 Display version

On first use, type /login and enter your API key:

Get your API key from the Groq Console here

This creates a ~/.groq/ folder storing your API key and configuration.

Environment variable alternative:

export GROQ_API_KEY=your_api_key_here

Supports HTTP/HTTPS/SOCKS5 proxies:

# CLI flag (highest priority)
groq --proxy http://proxy:8080
groq --proxy socks5://proxy:1080

# Environment variables
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=socks5://proxy:1080

Priority: --proxy > HTTPS_PROXY > HTTP_PROXY

Git Operations (git_operations)

• Check status, view diffs, commit history
• Stage files and create commits
• List and switch branches

TODO Extraction (extract_todos)

• Find TODO, FIXME, HACK, NOTE, BUG, XXX comments
• Group by file or filter by type
• Track technical debt

Dependency Analysis (analyze_dependencies)

• View all dependencies and versions
• Check for outdated packages
• Works with package.json

MCP Integration (mcp_connect, mcp_call_tool, mcp_read_resource, mcp_list)

• Connect to external MCP servers
• Access filesystem, GitHub, Google Maps, Slack tools
• Extend AI capabilities

MCP (Model Context Protocol) connects AI to external tools and data sources.

# Check MCP status and open interactive selector
groq
> /mcp

# The interactive UI will:
# 1. Show all available servers
# 2. Let you select with arrow keys
# 3. Prompt for API key if needed
# 4. Save config automatically
# 5. Connect to the server

🆕 Custom Implementation Included!

Since the official @modelcontextprotocol/server-brave-search package doesn't exist, we built a complete custom MCP server.

One-Time Setup:

# 1. Build the Brave Search MCP server
cd mcp-servers/brave-search
npm install
npm run build
cd ../..

# 2. Get your Brave API key
# Visit: https://brave.com/search/api/

# 3. Connect via Groq CLI
npm start
> /mcp
> Select: brave-search (arrow keys + Enter)
> Paste your Brave API key
> Press Enter

Available Tools:

• brave_web_search - General web search
• brave_news_search - News articles with timestamps
• brave_local_search - Local businesses and places

Example Usage:

> Search for latest AI developments
> Find news about quantum computing
> Search for coffee shops in San Francisco

Troubleshooting:

• Build failed? Run cd mcp-servers/brave-search && npm install && npm run build
• Connection failed? Check ls mcp-servers/brave-search/dist/index.js exists
• API key issues? Get fresh key from https://brave.com/search/api/

Interactive Setup (Recommended):

1. Type /mcp to open server selector
2. Use arrow keys (↑↓) to navigate
3. Press Enter to select server
4. Enter API key if prompted (Ctrl+H to show/hide)
5. Server automatically connects

Manual Configuration:

Edit ~/.groq/mcp-config.json:

{
  "servers": {
    "filesystem": {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{cwd}}"],
      "enabled": true
    },
    "github": {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      },
      "enabled": false
    },
    "brave-search": {
      "name": "brave-search",
      "command": "node",
      "args": ["{{project_root}}/mcp-servers/brave-search/dist/index.js"],
      "env": {
        "BRAVE_API_KEY": "your_key_here"
      },
      "enabled": false
    }
  }
}

Dynamic Paths:

• {{cwd}} - Replaced with current working directory
• Makes configuration portable across machines

More servers: modelcontextprotocol/servers

Filesystem Operations:

> Read the package.json file
> Create a new file called notes.txt
> List all TypeScript files

GitHub Integration:

> List my GitHub repositories
> Create an issue in my repo
> Show recent commits

Brave Search (Custom Server):

> Search for TypeScript best practices
> Find latest news on climate change
> Search for restaurants near Central Park

Combined Workflows:

> Connect to MCP servers, read API docs, and create a GitHub issue summarizing them

• MCP operations require user approval (except mcp_list)
• API keys stored in ~/.groq/mcp-config.json with permissions 0o600
• Never commit mcp-config.json to version control
• Rotate API keys regularly

# Auto-rebuild on changes
npm run dev

npm run build      # Build TypeScript to dist/
npm run dev        # Build in watch mode

groq-code-cli/
├── src/
│   ├── commands/           # Slash command implementations
│   ├── core/               # Agent and CLI entry point
│   ├── tools/              # AI-callable tool functions
│   ├── ui/                 # Terminal UI components (React + Ink)
│   └── utils/              # Utilities (file ops, settings, MCP manager)
├── mcp-servers/            # Custom MCP server implementations
│   └── brave-search/       # Brave Search MCP server
├── docs/                   # Documentation assets
├── package.json
├── tsconfig.json
└── LICENSE

Entry Points:

• src/core/cli.ts - Main CLI entry point
• src/core/agent.ts - AI agent implementation
• src/ui/hooks/useAgent.ts - TUI-agent bridge

1. Define schema in src/tools/tool-schemas.ts:

export const YOUR_TOOL_SCHEMA: ToolSchema = {
  type: 'function',
  function: {
    name: 'your_tool_name',
    description: 'What your tool does',
    parameters: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: 'Description' }
      },
      required: ['param1']
    }
  }
};

2. Implement in src/tools/tools.ts:

export async function yourToolName(param1: string): Promise<ToolResult> {
  // Implementation
  return createToolResponse(true, result, 'Success');
}

3. Register in TOOL_REGISTRY and executeTool in src/tools/tools.ts

4. Add schema to ALL_TOOL_SCHEMAS in src/tools/tool-schemas.ts

1. Create src/commands/definitions/your-command.ts:

import { CommandDefinition, CommandContext } from '../base.js';

export const yourCommand: CommandDefinition = {
  command: 'yourcommand',
  description: 'Description',
  handler: ({ addMessage }: CommandContext) => {
    addMessage({ role: 'system', content: 'Response' });
  }
};

2. Register in src/commands/index.ts

Change "groq" in package.json "bin" field to your preferred command:

"bin": {
  "your-command": "./dist/core/cli.js"
}

Then: npm run build && npm link

• Interactive server selection with /mcp command
• Automatic API key management (save, update, secure input)
• Dynamic {{cwd}} path placeholder
• Custom Brave Search MCP server (web/news/local search)
• 4 new MCP tools: mcp_connect, mcp_call_tool, mcp_read_resource, mcp_list
• Support for filesystem, GitHub, Google Maps, Postgres, Slack servers

• Purple-turquoise gradient theme (#9D4EDD → #00F5FF)
• Enhanced ASCII art banner
• Updated badges and documentation

• Added @modelcontextprotocol/sdk@^1.20.0
• New src/utils/mcp-manager.ts singleton
• MCP server management infrastructure
• Comprehensive error handling

• Git Operations: status, diff, log, add, commit, branch
• TODO Extraction: Find TODO/FIXME/HACK/NOTE/BUG/XXX
• Dependency Analysis: Check versions, outdated packages

• /context - Show project context size
• /todos - Extract TODO comments
• /init - Generate project context

• Added simple-git@^3.28.0
• 3 new tool schemas and implementations
• Enhanced startup banner

• Core CLI functionality
• Basic tools and commands

This enhanced edition is built on top of the excellent Groq Code CLI by the Groq team.

Original Project: build-with-groq/groq-code-cli License: MIT

• MCP (Model Context Protocol) integration with interactive management
• Custom Brave Search MCP server implementation
• Git operations, TODO extraction, dependency analysis
• Purple-turquoise gradient color scheme
• Additional slash commands and comprehensive inline documentation

All enhancements maintain the MIT license and spirit of the original project.

Improvements through PRs are welcome!

Original Project:

• Groq Code CLI: build-with-groq/groq-code-cli
• Share what you create with Groq on X/Twitter!

Featured Community Creations:

• OpenRouter Support - rahulvrane
• This Enhanced Edition - MCP & Developer Tools

Made with ⚡ by the community • Built on Groq