🤖 Coder

A powerful, zero-dependency, cross-platform CLI coding agent powered by Google Gemini, Groq, Mistral, OpenRouter, NVIDIA NIM, and GitHub Models with native tool execution and a clean, minimal Apple-inspired design.

Features

• Apple-Inspired Design: A clean, high-contrast, minimalist terminal UI styled in elegant monochrome greys and whites.
• Multi-Provider AI Engine: Query models from Gemini API, Groq, Mistral, OpenRouter, NVIDIA NIM, or GitHub Models.
• Auto-Rotation & Fallbacks: Automatically rotates to backup models within a provider family if a server error or rate-limit is hit.
• Smart Rate-Limit Throttling: Implements smart background cooldown timers between requests to prevent hitting provider Requests Per Minute (RPM) limits without disrupting the user experience.
• Global CLI Execution: Install once and run anywhere via coder-agent (or the coder / gemini-agent / groq-agent compatibility aliases).
• 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.
• Context Persistence: Local JSON-based persistent configuration stored in ~/.coder-config.json for key management and default model settings.
• Interactive REPL & Single-Shot Modes:
  • Start the interactive shell with coder-agent.
  • Execute a direct command: coder-agent "build a quicksort function in python" (exits upon completion).

Installation

Install globally via npm:

npm install -g coder-agent

Or execute directly without installation:

npx coder-agent

Setup & Configuration

The agent requires at least one API Key to function. By default, it uses the Gemini API Key.

1. Interactive Bootstrapping

Simply run coder-agent. If no key is configured, the CLI will interactively prompt you for a Gemini key and offer to save it globally.

2. Environment Variables

You can export provider API keys as environment variables:

export GEMINI_API_KEY=AIzaSy...
export GROQ_API_KEY=gsk_...
export MISTRAL_API_KEY=...
export OPENROUTER_API_KEY=sk-or-...
export NVIDIA_API_KEY=nvapi-...
export GITHUB_TOKEN=github_pat_...

3. REPL Commands (Config File)

Inside the interactive REPL session, use the /key command to save API keys globally:

/key                          # View active API key status for all providers
/key <api_key>                # Save your Gemini API Key globally
/key <provider> <api_key>     # Save key for a specific provider (e.g. /key groq gsk_...)

Usage & Arguments

REPL Mode

Start an interactive pair programming session:

coder-agent

Single-Shot Prompt Mode

Run a prompt directly from the shell:

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

CLI Command Options

• -h, --help — Show the help screen.
• -v, --version — Show version information.
• --model <name> — Set the default model globally.
• --set-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 groq/llama-3.3-70b-specdec) | | /key [provider] [key] | View stored API keys or save keys globally | | /clear | Wipe conversation memory | | /status | Show active model and memory usage details | | /help | Show command summary | | /exit | Quit Coder |

Popular Models Supported

To use a model from a different provider, prefix the model name with provider/:

• Google Gemini (Default):
  • gemini-2.5-flash — Default, highly capable & fast (1M+ context).
  • gemini-2.5-pro — High reasoning model, superb for complex coding.
  • gemini-3.5-flash — Newest generation, ultra-fast.
• Groq (groq/):
  • groq/llama-3.3-70b-specdec — Blazing fast reasoning.
  • groq/gemma-2-9b-it — Lightweight, fast open-weights.
• Mistral (mistral/):
  • mistral/codestral — SOTA open coding model.
• OpenRouter (openrouter/):
  • openrouter/qwen/qwen-2.5-coder-32b-instruct:free — Popular free-tier coding model.
  • openrouter/deepseek/deepseek-r1:free — Powerful reasoning/thinking model.
• NVIDIA NIM (nvidia/):
  • nvidia/qwen-2.5-coder-32b-instruct — NVIDIA-optimized coding model.
  • nvidia/deepseek-r1 — High-speed reasoning model.
• GitHub Models (github/):
  • github/claude-3.5-sonnet — Claude 3.5 Sonnet (requires GitHub token).
  • github/gpt-4o — OpenAI GPT-4o.

macOS & Linux Troubleshooting

If you encounter permission errors on macOS or Linux (such as EACCES: permission denied or zsh: permission denied):

1. Run Directly using Node

If global linking fails or is blocked by system directory permissions, you can skip npm link and run the build file directly using Node.js:

npm run build
node dist/index.js

2. Fix Executable Permissions

If you get a "permission denied" when executing the bin file directly, ensure it has executable rights:

chmod +x dist/index.js

(Note: The npm run build task now automatically applies the correct Unix execution permission (755) on macOS/Linux environments).

3. Avoid npm link EACCES failures

If npm link fails because your standard global folder belongs to root:

• Use nvm (Recommended): Installing Node.js via nvm places Node and npm in your home directory where you have full ownership.
• Adjust npm global prefix: Change npm's default path to your home folder:

  mkdir ~/.npm-global
  npm config set prefix '~/.npm-global'

  Then add export PATH=~/.npm-global/bin:$PATH to your shell profile (~/.zshrc or ~/.bashrc).

License

MIT