Nexus Code CLI: A highly customizable, lightweight, and open-source coding CLI powered by Groq/OpenAI-compatible for instant iteration.

Overview •
Installation •
Usage •
Development •
Nexus (.nexus & Natural Language)

https://github.com/user-attachments/assets/5902fd07-1882-4ee7-825b-50d627f8c96a

Overview

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 (/models to see available models). Simply activate the CLI by typing groq in your terminal. Use Groq Code CLI in any directory just like you would with any other coding CLI. Use it in this directory to have it build and customize itself!

A few customization ideas to get started:
- New slash commands (e.g. /mcp, /deadcode, /complexity, etc.)
- Additional tools (e.g. web search, merge conflict resolver, knowledge graph builder, etc.)
- Custom start-up ASCII art
- Change the start-up command
- Anything you can think of!

Installation

$3

``bash
git clone https://github.com/build-with-groq/groq-code-cli.git
cd groq-code-cli
npm install
npm run build
npm link # Enables the nexus command in any directory
`

`bash


Run this in the background during development to automatically apply any changes to the source code


npm run dev
`

$3

`bash

Using npx, no installation required (once published)

npx nexus-code-cli@latest
`

$3

`bash

Once published to npm

npm install -g nexus-code-cli@latest
`

Usage

`bash

Start chat session

nexus
`

$3

`bash
nexus [options]

Options:
-t, --temperature Temperature for generation (default: 1)
-s, --system Custom system message
-d, --debug Enable debug logging to debug-agent.log in current directory
-h, --help Display help
-V, --version Display version number
`

$3

On first use, start a chat:

`bash
groq
`

And type the /login command:

!Login
>Get your API key from the Groq Console here

This creates a .groq/ folder in your home directory that stores your API key, default model selection, and any other config you wish to add.

You can also set your API key for your current directory via environment variable:
`bash
export GROQ_API_KEY=your_api_key_here
`

$3


- /help - Show help and available commands
- /login - Login with your credentials
- /model - Select your Groq model
- /clear - Clear chat history and context
- /reasoning - Toggle display of reasoning content in messages
- /mcp - Manage MCP servers and inspect discovered tools
- /tasks - Manage tasks in a simple UI overlay

$3

Set environment variables to use an OpenAI-compatible endpoint instead of Groq:

`bash
export OPENAI_API_KEY=sk-...


Optional custom base URL (defaults to https://api.openai.com/v1)


export OPENAI_BASE_URL=https://api.openai.com/v1
`

Precedence: if OPENAI_API_KEY is set, the CLI will use the OpenAI-compatible API. Otherwise it falls back to GROQ_API_KEY (or /login).




Development

$3


`bash

Run this in the background during development to automatically apply any changes to the source code

npm run dev
`

$3

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

$3

`
groq-code-cli/
├── src/
│ ├── commands/
│ │ ├── definitions/ # Individual command implementations
│ │ │ ├── clear.ts # Clear chat history command
│ │ │ ├── help.ts # Help command
│ │ │ ├── login.ts # Authentication command
│ │ │ ├── mcp.ts # MCP helper command (list/connect/tools)
│ │ │ ├── model.ts # Model selection command
│ │ │ └── reasoning.ts # Reasoning toggle command
│ │ ├── base.ts # Base command interface
│ │ └── index.ts # Command exports
│ ├── core/
│ │ ├── agent.ts # AI agent implementation
│ │ └── cli.ts # CLI entry point and setup
│ ├── tools/
│ │ ├── tool-schemas.ts # Tool schema definitions
│ │ ├── tools.ts # Tool implementations
│ │ └── validators.ts # Input validation utilities
│ ├── ui/
│ │ ├── App.tsx # Main application component
│ │ ├── components/
│ │ │ ├── core/ # Core chat TUI components
│ │ │ ├── display/ # Auxiliary components for TUI display
│ │ │ └── input-overlays/ # Input overlays and modals that occupy the MessageInput box
│ │ └── hooks/
│ └── utils/
│ ├── constants.ts # Application constants
│ ├── file-ops.ts # File system operations
│ ├── local-settings.ts # Local configuration management
│ └── markdown.ts # Markdown processing utilities
├── docs/
├── package.json
├── tsconfig.json
└── LICENSE
`

TL;DR: Start with src/core/cli.ts (main entry point), src/core/agent.ts, and src/ui/hooks/useAgent.ts (bridge between TUI and the agent). Tools are in src/tools/, slash commands are in src/commands/definitions/, and customize the TUI in src/ui/components/.

$3

$3

- /agent: abre el gestor de agentes (lista y activa perfiles de .nexus/agents).
- /rules: abre el gestor de reglas (lista y adjunta reglas de .nexus/rules).
- /tasks: abre el gestor de tareas (crear, marcar completado, guardar/cargar).
- /mcp: abre el gestor MCP (servidores y tools descubiertas).

Create .nexus/mcp.servers.json:

`
[
{ "name": "example", "command": "node", "args": ["./server.js"], "cwd": "." }
]
`

Then in the CLI:

- /mcp list
- /mcp connect example
- /mcp tools (tools appear as mcp__example__ and can be called by the model)

$3

#### Adding New Tools

Tools are AI-callable functions that extend the CLI's capabilities. To add a new tool:

1. Define the tool schema in src/tools/tool-schemas.ts:
`typescript
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: 'Parameter description' }
},
required: ['param1']
}
}
};
`

2. Implement the tool function in src/tools/tools.ts:
`typescript
export async function yourToolName(param1: string): Promise {
// Your implementation here
return createToolResponse(true, result, 'Success message');
}
`

3. Register the tool in the TOOL_REGISTRY object and executeTool switch statement in src/tools/tools.ts.

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

#### Adding New Slash Commands

Slash commands provide direct user interactions. To add a new command:

1. Create command definition in src/commands/definitions/your-command.ts:
`typescript
import { CommandDefinition, CommandContext } from '../base.js';

export const yourCommand: CommandDefinition = {
command: 'yourcommand',
description: 'What your command does',
handler: ({ addMessage }: CommandContext) => {
// Your command logic here
addMessage({
role: 'system',
content: 'Command response'
});
}
};
`

2. Register the command in src/commands/index.ts by importing it and adding to the availableCommands array.

#### Changing Start Command
To change the start command from groq, change "groq" in "bin" of package.json to your global command of choice.

Re-run npm run build and npm link`.

Contributing and Support

Improvements through PRs are welcome!

For issues and feature requests, please open an issue on GitHub.

#### Share what you create with Groq on our socials!

$3

- OpenRouter Support - rahulvrane