GitHub - aaurelions/agent51: A ultra-lightweight AI agent that communicates with the OpenRouter API and executes shell commands.

Agent51 (Agent 51mpson)

`~# npx agent51 how are you`

An ultra-lightweight AI agent that communicates with the OpenRouter API, executes shell commands, and offers opinions you'd probably expect from a resident of Springfield. Woo Hoo!

Features

🤖 Tool Calling: Executes shell commands to perform tasks, manipulate files, and interact with your system.
☁️ Zero Install: Runs directly from the cloud with npx. No installation is needed. It's like getting a free donut.
🧠 Conversation Memory: Remembers the context of your conversation, even if you were just talking about flamin' Moes.
🍩 Simpson-like Personality: Get quirky, enthusiastic, and sometimes lazy responses. D'oh!
🎨 Customizable Output: Use command-line flags to control exactly what you see—commands, output, or just the agent's final answer.

Prerequisites

Node.js: Required to run npx.
OpenRouter API Key: The agent needs this to think. Get a free key from OpenRouter.ai.

Quick Start

Getting started is easier than stealing cable.

1. Set Your API Key

You gotta pay for the good stuff, man. Set your OpenRouter API key as an environment variable.

On macOS / Linux:

export OPENROUTER_API_KEY="your_openrouter_api_key_here"

On Windows:

$env:OPENROUTER_API_KEY="your_openrouter_api_key_here"

2. Run with NPX

That's it! No installation is needed. Run this command to start the interactive session:

The first time you run it, npx will ask for permission to download the package. Just say yes!

Usage

Once the agent is running, type your questions or commands at the 🍩: prompt and press Enter.

Interactive Mode

Simply run npx agent51 to start a conversation.

One-Shot Mode

You can also pass a prompt directly from the command line for a single response. The agent will execute the task and exit. This works with or without quotes.

# With quotes (one argument)
npx agent51 "list all files in the current directory and subdirectories"

# Without quotes (multiple arguments)
npx agent51 list all files in the current directory and subdirectories

Command-Line Options

Customize the agent's output using the following flags. By default, the Command, its Output, and the final Agent response are all displayed.

You can hide specific parts of the output to suit your needs.

Flag	Alias	Description	Example
`--no-command`	`-c`	Hides the executed shell command box.	`npx agent51 -c "what is my ip"`
`--no-output`	`-o`	Hides the shell command's output box.	`npx agent51 -o "create a test file"`
`--no-agent`	`-a`	Hides the agent's final response box.	`npx agent51 -a "list files"`

Output Customization Examples

Show only the final agent response: Useful for when you only care about the answer, not the process.

npx agent51 --no-command --no-output "what is the current date"
# Or with aliases
npx agent51 -co "what is the current date"

Show only the command and its output (scripting mode): Useful if you want to see what the agent does without its commentary.
```
npx agent51 --no-agent "list all node_modules"
# Or with alias
npx agent51 -a "list all node_modules"
```

Show only the command: Useful for quickly seeing what command the agent would run.

npx agent51 --no-output --no-agent "how would you delete temp.txt"
# Or with aliases
npx agent51 -oa "how would you delete temp.txt"

Exiting the Agent

When you've had enough shenanigans, you can close the agent in two ways:

Type one of the exit commands: exit, quit, or close.
Press Ctrl+C at any time.

License

This project is released under the CC0 - "No Rights Reserved" license. You are free to use, modify, and distribute it for any purpose.