🤖 Groq Coding Agent

A powerful, zero-dependency, cross-platform CLI coding agent powered by Groq (llama-3.3-70b-versatile / deepseek-r1) with native tool execution and automatic Google Gemini multi-model fallback.

Features

• Global CLI Execution: Install once and run anywhere via groq-agent or npx groq-agent.
• System Automation Tools:
  • read_file / write_file / patch_file — Segmented reading and patch-based editing.
  • list_directory / find_files — Recursive structure traversal.
  • run_shell — Direct command execution in Windows, macOS, or Linux terminals.
  • web_search — DuckDuckGo instant answers for documentation retrieval.
• Robust API Fallback with Model Rotation: If the Groq API key hits a rate limit (429), the agent automatically falls back to your Gemini API key. If the primary Gemini model (gemini-2.5-flash) is under heavy demand (503), the agent automatically rotates fallback to gemini-2.0-flash, gemini-2.5-flash-lite, and others in sequence.
• Context Persistence: Local JSON-based persistent configuration stored in ~/.groq-agent-config.json for key management and default model settings.
• Interactive REPL & Single-Shot Modes:
  • Start the interactive shell with groq-agent.
  • Execute a direct command: groq-agent "build a quicksort function in python" (exits upon completion).

Installation

Install globally via npm:

npm install -g groq-agent

Or execute directly without installation:

npx groq-agent

Setup & Configuration

The agent requires a Groq API Key. Optionally, you can supply a Gemini API Key to enable seamless rate-limit fallback.

1. Interactive Bootstrapping

Simply run groq-agent. If no key is set, the CLI will interactively prompt you for the key and offer to save it globally.

2. Command Line Flags

You can save your keys globally at any time using flags:

groq-agent --set-key YOUR_GROQ_API_KEY
groq-agent --set-gemini-key YOUR_GEMINI_API_KEY

3. Environment Variables

Alternatively, you can export them as environment variables:

export GROQ_API_KEY=gsk_...
export GEMINI_API_KEY=AIzaSy...

Usage & Arguments

REPL Mode

Start an interactive pair programming session:

groq-agent

Single-Shot Prompt Mode

Run a prompt directly from the shell:

groq-agent "write a binary search script in Python"

CLI Command Options

• -h, --help — Show the help screen.
• -v, --version — Show version info.
• --model <name> — Set the default Groq model globally.
• --set-key <key> — Persist your Groq API Key globally.
• --set-gemini-key <key> — Persist your Gemini API Key globally.
• --memory <scope> — Define memory scope (project, user, or local).

Built-in REPL Commands

Type these commands directly inside the interactive session:

| Command | Description | |---------|-------------| | /model [name] | View active model or switch active model dynamically (e.g. /model deepseek-r1-distill-llama-70b) | | /clear | Wipe conversation memory | | /status | Show active model and memory usage details | | /help | Show command summary | | /exit | Quit the agent |

Popular Models Supported (Groq)

• llama-3.3-70b-versatile (Default, highly capable and extremely fast)
• deepseek-r1-distill-llama-70b (Reasoning model, superb for coding tasks)
• llama-3.1-8b-instant (Ultra-fast, lightweight)
• mixtral-8x7b-32768 (MoE model, larger context)

License

MIT