red-agent

v1.0.4

Published

5 months ago

A minimal CLI coding agent powered by Groq with local tools and safety guardrails

0High
0Medium
0Low

muhammed_amer__

ai agent cli groq coding-agent llm automation developer-tools

Red

A minimal CLI coding agent powered by Groq that automates development tasks with local tools and built-in safety guardrails.

What is Red?

Red is a lightweight coding agent that runs in your terminal. It can:

Read files and explore directories
Edit files with find-and-replace
Run shell commands
Make autonomous decisions about which tools to use
Ask for approval before any destructive actions

Quick Start

Global Installation

npm install -g red-agent

Setup

Get a Groq API key from console.groq.com
Set your API key:

export GROQ_API_KEY=your_api_key_here

Or create a .env file in your project:

GROQ_API_KEY=your_api_key_here
GROQ_MODEL=openai/gpt-oss-120b  # Optional: default model

Run Red:

red

Usage

Basic Workflow

$ red
Red Agent v1.0.0
Type your request and press Enter. Ctrl+C to exit.

You: Fix the bug in auth.js where users can't log in with email

[Agent thinks...]
[Agent requests to read auth.js]
[Agent identifies the issue]
[Agent asks approval to edit auth.js]

Approve this edit? (y/n): y

[Agent applies fix]
[Agent runs tests to verify]

Task completed!

Example Tasks

Refactor code:

You: Refactor all the functions in utils.js to use async/await instead of callbacks

Add features:

You: Add input validation to the user registration endpoint

Debug issues:

You: Find out why the server is crashing on startup and fix it

Local Development

If you want to contribute or modify Red:

Clone and Install

git clone https://github.com/iamAmer/red.git
cd red
npm install

Build

npm run build

This compiles TypeScript from src/ to dist/.

Run Locally

npm start

Or link it globally for testing:

npm link
red

How It Works

Red is built on three core components:

1. Tools (Actions)

Red has access to four essential tools:

readFileContent(path) - Read file contents
listDirectory(path) - List files and directories
editFile(path, find, replace) - Replace text in files
runCommand(command, cwd?) - Execute shell commands

2. Autonomy (Loop)

The agent runs in a loop:

Think - Analyze the current state
Act - Choose and execute tools
Observe - Process tool outputs
Repeat - Continue until task is complete

3. Guardrails (Safety)

Before any destructive action (edits, commands), Red:

Shows you exactly what it wants to do
Waits for your approval (y/n)
Only proceeds if you confirm

Project Structure

red/
├── src/
│   ├── agent.ts              # CLI entrypoint
│   ├── agent/
│   │   ├── approvals.ts      # User approval prompts for destructive actions
│   │   ├── groq.ts           # Groq client configuration
│   │   ├── loop.ts           # Main agent loop with tool execution
│   │   ├── state.ts          # Conversation state management
│   │   └── tools.schema.ts   # Tool schemas for the model
│   └── tools/
│       ├── editFile.ts       # Find and replace in files
│       ├── index.ts          # Tool exports
│       ├── listDirectory.ts  # Directory listing
│       ├── readFileContent.ts # File reading
│       └── runCommand.ts     # Shell command execution
├── dist/                     # Compiled JavaScript (generated)
│   └── agent.js              # ← Must have shebang for CLI
├── node_modules/
├── .npmignore                # Exclude src/ from npm package
├── package.json              # Package metadata and configuration
├── tsconfig.json             # TypeScript configuration
├── README.md                 # This file
├── LICENSE                   # ISC License
├── CHANGELOG.md              # Version history
└── .env                      # API keys (gitignored)

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GROQ_API_KEY | Yes | - | Your Groq API key | | GROQ_MODEL | No | openai/gpt-oss-120b | Groq model to use |

Supported Models

Red works with any Groq model that supports function calling:

openai/gpt-oss-120b (default, fast and capable)
llama-3.3-70b-versatile
mixtral-8x7b-32768
gemma2-9b-it

Safety Features

Approval Gates

Red will always ask before:

Editing any file
Running any shell command
Making changes to your filesystem

What Red Won't Do

Red is designed to be safe by default. It will refuse to:

Run destructive commands without approval
Edit files without showing you the exact changes
Continue if you deny an approval request

Troubleshooting

"GROQ_API_KEY is not set"

Solution: Export the environment variable or create a .env file:

export GROQ_API_KEY=your_key_here

"Command not found: red"

Solution: Make sure Red is installed globally:

npm install -g red-agent

Or if developing locally:

npm link

Agent is stuck in a loop

Solution: Press Ctrl+C to stop. Red has a max iteration limit, but you can always interrupt manually.

Tool execution fails

Solution: Check that:

File paths are correct (absolute or relative to current directory)
You have read/write permissions
Commands are valid for your OS

Performance Tips

Token Usage

Red uses Groq's API, which is fast and cost-effective. To optimize:

Be specific in your requests
Break large tasks into smaller chunks
Review and approve actions promptly

Context Management

For large codebases:

Start Red in the specific directory you want to work in
Give focused, specific instructions
Use Red for one task at a time

Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request