Bashagt

https://github.com/zhihumomo/bashagt
Admin
Bashagt is a pure-Bash LLM agent kernel with zero runtime dependencies designed to provide an...
Tokens:13,284
Snippets:115
Trust Score:6.6
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Bashagt installation steps overview

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Overview of the three-step installation process for Bashagt on any platform. The final step runs the installer script.

```text
1. Get the script   →   2. Install dependencies   →   3. ./bashagt --install
```

--------------------------------

### Run interactive Bashagt session for daily development

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Start an interactive Bashagt session in the terminal and ask questions about the codebase, such as tracing call chains, mapping dependencies, or adding comments. No window switching or plugin installation is needed.

```bash
$ bashagt
bashagt> Where does PaymentService.process() get called in this project?
bashagt> Map out the dependency graph of everything under src/auth/
bashagt> Add Chinese comments to every endpoint in UserController
```

--------------------------------

### Start interactive conversation with bashagt

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Starts the interactive Bashagt conversation. The output shows the startup banner with model, endpoint, author, and version, followed by example prompts and the /help slash command.

```bash
$ bashagt

  ██████╗  █████╗ ███████╗██╗  ██╗ █████╗  ██████╗ ████████╗
  ██╔══██╗██╔══██╗██╔════╝██║  ██║██╔══██╗██╔════╝ ╚══██╔══╝
  ██████╔╝███████║███████╗███████║███████║██║  ███╗   ██║
  ██╔══██╗██╔══██║╚════██║██╔══██║██╔══██║██║   ██║   ██║
  ██████╔╝██║  ██║███████║██║  ██║██║  ██║╚██████╔╝   ██║
  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝    ╚═╝

  Model: deepseek-v4-pro[1m]           Thinking: status
  Endpoint: api.deepseek.com/anthropic
  Author: Lucas                        Version: preview-0.1

  > /help          # View built-in slash commands
  > Analyze the performance bottleneck in this code
  > Find all callers of login()
  > Write unit tests for this module
```

--------------------------------

### Install WSL on Windows

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Install WSL from PowerShell or CMD as Administrator. This installs Ubuntu by default; reboot and enter the WSL terminal to continue.

```powershell
wsl --install
```

--------------------------------

### Clone and install Bashagt on macOS

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Clone the repository and run the installer on macOS. The installer auto-detects the terminal app (Terminal.app, iTerm2, Warp) and binds Cmd+G or Cmd+T hotkeys.

```bash
git clone https://github.com/zhihumomo/bashagt.git
cd bashagt
./bashagt --install
```

--------------------------------

### Run Bashagt installer on Linux

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Run the one-click installer. It copies bashagt to ~/.bashagt/, creates a symlink at ~/.local/bin/bashagt, generates ~/.bashagt/settings.json, and registers hotkeys (Ctrl+G for bash, Ctrl+T for zsh).

```bash
./bashagt --install
```

--------------------------------

### Install dependencies in WSL

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Update package lists and install jq and curl inside the WSL Ubuntu environment.

```bash
sudo apt update
sudo apt install jq curl
```

--------------------------------

### Install Homebrew and dependencies on macOS

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Install Homebrew (if needed) and then install bash, jq, and curl on macOS. Homebrew-installed bash is at /opt/homebrew/bin/bash (Apple Silicon) or /usr/local/bin/bash (Intel).

```bash
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install bash jq curl
```

--------------------------------

### Clone Bashagt repository on Linux

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Clone the Bashagt repository and change into the project directory. This is the second step of the Linux installation guide.

```bash
git clone https://github.com/zhihumomo/bashagt.git
cd bashagt
```

--------------------------------

### Install termux-api package

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Installs the Termux-API command-line tools, enabling Bashagt to invoke Android system APIs for phone control. Requires the Termux:API companion app from F-Droid.

```bash
pkg install termux-api
```

--------------------------------

### Install dependencies on Linux distributions

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Install jq and curl (and bash on Alpine) on various Linux distributions. Most Linux distributions ship bash 4.0 or newer; verify with `bash --version`.

```bash
# Debian / Ubuntu
sudo apt install jq curl

# RHEL / CentOS / Fedora
sudo dnf install jq curl

# Arch Linux
sudo pacman -S jq curl

# Alpine Linux
sudo apk add jq curl bash
```

--------------------------------

### Live demo request for /stats command

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Example user request in the live demo: asking Bashagt to add a /stats slash command. Bashagt will locate the slash command registration and statistics variables, then insert the implementation and run a syntax check.

```text
bashagt> Add a /stats slash command that shows token usage and API call count for this session
```

--------------------------------

### Install Termux dependencies for Bashagt

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Updates Termux package lists and installs the core dependencies required by Bashagt: bash, jq, curl, git, and coreutils. Verifies the installed bash version (Termux defaults to bash 5.x).

```bash
pkg update && pkg upgrade

# Install core dependencies
pkg install bash jq curl git coreutils

# Verify bash version (Termux installs bash 5.x by default)
bash --version
```

--------------------------------

### Self-evolution workflow example

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Illustrates the self-evolution workflow: Bashagt reads its own source, uses edit_file to modify it, runs the script to verify, and confirms success. This is the same process used for modifying user project code.

```text
You say: "Add a --version flag"
         ↓
Bashagt: Reads its own main() function to understand argument parsing
         ↓
Bashagt: Uses the edit_file tool to insert a --version branch at the right spot
         ↓
Bashagt: Runs ./bashagt --version with the bash tool to verify
         ↓
Bashagt: Confirms success, reports done ✅
```

--------------------------------

### Install iSH dependencies for Bashagt

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Updates the Alpine package index and installs the core dependencies for Bashagt on iSH: bash, jq, curl, git, and coreutils. Verifies the bash version.

```bash
# Update package index (iSH uses the Alpine package manager)
apk update
apk add bash jq curl git coreutils

# Verify bash version
bash --version
```

--------------------------------

### Daemon API with bashagt --run and curl

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Starts the Bashagt daemon on port 9655 and demonstrates the HTTP API: creating a session, sending a message, and subscribing to SSE streaming. The session ID is used in the message and stream endpoints.

```bash
# Start the service
bashagt --run --port 9655

# Create a session
curl -X POST http://localhost:9655/v1/session/new

# Send a message
curl -X POST http://localhost:9655/v1/session/{id} \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

# SSE streaming subscription
curl -N http://localhost:9655/v1/session/{id}/stream
```

--------------------------------

### Launch Bashagt in various modes

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Launch commands for Bashagt. Includes interactive mode, oneshot mode, streaming oneshot, HTTP daemon, debug mode, and update. See Usage Examples below for details on each mode.

```bash
# Interactive conversation mode (default)
bashagt

# Oneshot mode — pipe input, output result, exit
echo "Explain this code" | bashagt --oneshot

# Streaming oneshot mode — pure JSONL output, ideal for script parsing
echo "Analyze this log" | bashagt --oneshot --stream

# Start HTTP daemon (default port 9655)
bashagt --run

# Foreground debug mode (daemon + logs to terminal)
bashagt --run --debug --port 9655

# Update to the latest version
./bashagt --update
```

--------------------------------

### Use Bashagt as a backend API service with curl

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Start Bashagt as a daemon on port 9655 and call its HTTP API to create sessions, send messages, and stream responses via SSE. Works from any language that can make HTTP requests.

```bash
# Start the daemon
bashagt --run --port 9655

# Call from your app (any language — if it can HTTP, it can call)
curl -X POST http://localhost:9655/v1/session/new          # Create session
curl -X POST http://localhost:9655/v1/session/{id} \        # Send message
  -d '{"message": "Parse this JSON and generate TypeScript types"}'
curl -N http://localhost:9655/v1/session/{id}/stream         # SSE streaming response
```

--------------------------------

### Control phone with Bashagt and Termux-API

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Use Bashagt with Termux-API to control the phone, such as taking photos, sending texts, or getting GPS coordinates. This is a continuation of the Termux mobile coding assistant workflow.

```bash
bashagt> Take a photo and extract any text you find
bashagt> Text "Boss" in my contacts: "Received, working on it"
bashagt> Get my GPS coordinates and tell me the nearest subway station
```

--------------------------------

### Pipe mode with bashagt --oneshot

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Pipes command output into bashagt for one-shot processing. Use --oneshot for single-turn analysis and --stream to stream the response. Examples cover code review, log analysis, and config generation.

```bash
# Code review
git diff HEAD~1 | bashagt --oneshot

# Log analysis
tail -100 /var/log/app.log | bashagt --oneshot

# Config generation
cat schema.json | bashagt --oneshot --stream
```

--------------------------------

### Use Bashagt as a mobile coding assistant in Termux

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Run Bashagt interactively on Termux to quickly verify ideas or patch code on the go. With Termux-API, Bashagt can also control the phone, such as taking photos, sending texts, or getting GPS coordinates.

```bash
$ bashagt
bashagt> Write an awk one-liner to count requests per IP from access.log, sorted descending
bashagt> My Android project is at ~/storage/shared/MyApp — find all deprecated API usage
```

--------------------------------

### Run Bashagt on external storage

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Switches to a project directory on external storage and runs Bashagt. Use this after mounting external storage with termux-setup-storage.

```bash
cd ~/storage/external-1/my-project
bashagt
```

--------------------------------

### Configuration priority order

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Shows the configuration priority order for Bashagt. Later sources override earlier ones.

```text
Defaults  →  ~/.bashagt/settings.json  →  Project .bashagt/settings.json  →  Environment variables
```

--------------------------------

### Run test suite with run_all.sh

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Run the test suite from the test directory. The first command runs unit and integrity tests without an API key; the second runs the full suite including end-to-end tests, which requires an API key.

```bash
cd test
./run_all.sh                # unit + integrity tests (no API needed)
./run_all.sh --all          # full suite including E2E (requires API key)

```

--------------------------------

### Configure Bashagt for air-gapped environments with BASHAGT_API_URL

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Configure Bashagt to use an internal LLM API (e.g., Ollama or vLLM) in air-gapped or offline environments. Requires only bash, jq, and curl, which are available on any serious Linux distribution.

```bash
# Configure the internal API endpoint
export BASHAGT_API_URL="http://192.168.1.100:11434/api/chat"
export BASHAGT_API_KEY="ollama"

# Use as normal
bashagt
```

--------------------------------

### Architecture overview diagram

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

ASCII diagram of the Bashagt architecture, showing the main CLI dispatch, agent loop, run_turn, and dispatch_tool flow, plus the three core subsystems.

```text
┌─────────────────────────────────────────────────────┐
│                    main()                            │
│         (CLI parsing → init → mode dispatch)          │
├─────────────────────────────────────────────────────┤
│  • --install       Initialize system directories      │
│  • --run           Start HTTP daemon                  │
│  • --oneshot       Single-shot pipe mode              │
│  • (default)       Interactive REPL                   │
└────────────────────┬────────────────────────────────┘
                     │
     ┌───────────────▼──────────────────────┐
     │          agent_loop()                 │
     │  Interactive REPL or oneshot entry     │
     └───────────────┬──────────────────────┘
                     │
     ┌───────────────▼──────────────────────┐
     │          run_turn()                   │
     │  User input → API call → response     │
     │         ↓  stop_reason?                │
     │  end_turn ← return to user             │
     │  tool_use → dispatch_tool → loop       │
     └───────────────┬──────────────────────┘
                     │
     ┌───────────────▼──────────────────────┐
     │       dispatch_tool()                  │
     │  24 tools: read_file, write_file,      │
     │  edit_file, bash, agent, web_search,   │
     │  make_todos, skill, request...         │
     └──────────────────────────────────────┘

━━━━━━━━━━━━ Subsystems ━━━━━━━━━━━━

  Memory Network      Sub-Agent System       Hook System
  ┌──────────┐       ┌────────────┐       ┌──────────┐
  │16 engrams│       │11 sys agents│       │ 8 points  │
  │×200 slots│       │ N proj agents│      │ 6 types   │
  │sem search │       │ parallel    │       │ lifecycle │
  │sleep compr│       │ async sched │       │ hot-reload│
  └──────────┘       └────────────┘       └──────────┘
```

--------------------------------

### Set API key via environment variable

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Secure approach to set the API key via environment variable. Environment variables take priority over config files (4-tier config: defaults → settings.json → project settings.json → environment variables).

```bash
export BASHAGT_API_KEY="sk-your-api-key-here"
```

--------------------------------

### Configure API key in settings.json

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Configuration file for Bashagt. Edit ~/.bashagt/settings.json with your API details. The default api_url points to DeepSeek, but you can switch to Anthropic official or other OpenAI-compatible endpoints.

```json
{
  "api_url": "https://api.deepseek.com/anthropic",
  "api_key": "sk-your-api-key-here",
  "model": "deepseek-chat",
  "max_tokens": 8192,
  "thinking_budget": 16384
}
```

--------------------------------

### Mount external storage in Termux

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Grants Termux storage permissions and lists the symlinks created under ~/storage/. After running termux-setup-storage, directories like external-1/ (external SD card) and shared/ (internal storage) become accessible.

```bash
# Request storage permission (one-time)
termux-setup-storage

# Afterwards, symlinks become available
ls ~/storage/
#   dcim/       → camera photos
#   downloads/  → download directory
#   external-1/ → external SD card (if present)
#   music/      → music
#   shared/     → internal shared storage
```

--------------------------------

### Troubleshoot production issues with Bashagt over SSH

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

SSH into a production server and run Bashagt interactively to investigate logs and configuration files. No special tools are needed beyond bash, and the entire investigation happens in one terminal session.

```bash
$ ssh production-server
$ cd /var/log/app
$ bashagt

bashagt> What are the top 5 errors in the nginx error log from the last hour?
bashagt> Check /etc/nginx/nginx.conf for anything that could cause a 502
bashagt> Compare the three configs under /etc/nginx/sites-enabled/ — find the inconsistencies
```

--------------------------------

### Verify bash version on macOS

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Verify that the Homebrew-installed bash version is 5.x. Bashagt uses `#!/usr/bin/env bash`, so the Homebrew path must appear before /bin in /etc/paths.

```bash
# Verify version (should show 5.x)
bash --version
```

--------------------------------

### Use Bashagt as an iPhone/iPad terminal companion

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Run Bashagt interactively on iSH (iPhone/iPad) to check code, explain regex, or convert formats. Both interactive and oneshot modes work; API calls go over the network, so response speed matches desktop.

```bash
$ bashagt
bashagt> Check this Python code for potential memory leaks
bashagt> Explain what this regex matches: (?<=@)\w+(?=\.)
bashagt> Convert this JSON to YAML
```

--------------------------------

### Review code diffs with bashagt --oneshot in CI

Source: https://github.com/zhihumomo/bashagt/blob/master/README.md

Pipe git diffs or lint output into Bashagt's oneshot mode for CI/CD code review. Oneshot mode outputs results and exits, making it CI-friendly without a persistent process.

```bash
# Review the most recent commit
git diff HEAD~1 | bashagt --oneshot

# Review the diff between two branches
git diff main...feature-branch | bashagt --oneshot

# Combine with lint output
eslint src/ --format json | bashagt --oneshot
```
Tokens:
Raw