Basher

Basher is a CLI AI Agent that interacts with OpenAI-compatible LLM API for executing coding tasks.

The only tool Basher ever uses is Bash. Whether it’s finding, reading, or editing files, Basher always generates a small Bash script to get the job done.

Installation

To use Basher, ensure you have Python 3 installed. Basher only uses Python standard library. No other Python dependencies are required.

But Basher depends on these command line utils:

• rg
• fd

Please make sure you have installed them.

Usage

First, you can create an AGENTS.md as context file.

To run Basher, you'll need to set a few environment variables prior to execution:

Environment Variables

• BASHER_API_ENDPOINT: The API endpoint for the OpenAI-compatible LLM service. e.g. https://openrouter.ai/api/v1/.
• BASHER_API_KEY: Your API key for authenticating with the LLM service.
• BASHER_MODEL: The model to use for interaction. e.g. moonshotai/kimi-k2.5.
• BASHER_REASONING: (Optional) Reasoning effort level: xhigh, high, medium, low, minimal, or none

Run

You can run the Basher CLI from your terminal like this:

export BASHER_API_KEY='your_api_key_here'
python basher.py 'your task here`'

Sandbox Security

Basher executes arbitrary Bash commands generated by LLM, which can be dangerous without proper isolation. We recommend running Basher inside a sandbox to protect your system.

This project provides a basher.firejail.profile for use with Firejail, a Linux security sandbox. The profile ensures that:

• Basher can only modify files in your current working directory;
• Basher cannot read other files in your home directory (your browser cookies, passwords, etc. are safe);

Usage

Run Basher with Firejail:

firejail --profile=basher.firejail.profile python basher.py "your task here"