Add always-on messaging through Telegram, Discord, Slack, or Feishu. Channels auto-start with the gateway:
# Example: Telegram
bashclaw config set '.channels.telegram.botToken' '"BOT_TOKEN"'
bashclaw config set '.channels.telegram.enabled' 'true'
bashclaw gateway # web + Telegram both active
BashClaw is shell script -- the agent can read, modify, and reload its own source code at runtime. No compilation, no restart, instant self-bootstrapping.
Bash 3.2: Universal Runtime
Bash 3.2 was released in October 2006 as the last GPLv2-licensed version. Apple froze it on every Mac starting with macOS Leopard (2007) and has shipped 3.2 on every Mac since, because later versions (4.0+) switched to GPLv3 which conflicts with Apple's licensing policy.
BashClaw targets Bash 3.2 deliberately: no declare -A, no mapfile, no |&. This means it runs on:
macOS -- every version since 2007, zero additional installs
Linux -- any distribution (Ubuntu, Debian, Fedora, Alpine, Arch...)
Android Termux -- no root required
Windows -- WSL2, Git Bash, Cygwin
Embedded -- Alpine containers, Raspberry Pi, CI runners, NAS boxes
Features
Web dashboard -- Built-in browser UI for chat, config, and monitoring. First-run setup wizard. No external tools.
Multi-channel -- Telegram, Discord, Slack, Feishu/Lark. Each channel is one shell script. Auto-starts with gateway.
Dual engine -- Claude Code CLI (reuses subscription) or builtin (direct API via curl). Per-agent configurable.
Multi-provider -- 18 providers: Claude, GPT, Gemini, DeepSeek, Qwen, Zhipu, Moonshot, MiniMax, Groq, xAI, Mistral, Ollama, vLLM, and more.
Pure shell -- Zero dependencies beyond bash 3.2, curl, jq. Already on your machine.
Hot config reload -- kill -USR1 the gateway to reload without restart.
Daemon support -- systemd, launchd, Termux boot, crontab fallback.
Tested -- Unit, compatibility, integration. bash tests/run_all.sh.
Web Dashboard
Start the gateway and open http://localhost:18789:
bashclaw gateway
+------------------------------------------------------------------+
| BashClaw Dashboard [Chat] [Status] [Agents] [Sessions] [Config] [Logs]|
+------------------------------------------------------------------+
| |
| You: What's the weather in Tokyo? |
| |
| Agent: Let me check that for you... |
| [tool: web_search] ... |
| Currently 12C and partly cloudy in Tokyo. |
| |
| [____________________________________] [Send] |
+------------------------------------------------------------------+
Chat -- Talk to the agent from the browser. Markdown rendering, syntax highlight.
Status -- Gateway state, active sessions, provider info, engine detection.
Agents -- List and manage configured agents.
Sessions -- Browse all sessions with message counts.
Config -- API keys, model selection, channel status. Keys stored server-side only.
Logs -- Live log viewer with level filtering.
First-run -- If no API key is set, shows a setup overlay on first visit.
Web + Channels + CLI
All three modes share the same config, sessions, and state. Changes in one take effect in the others immediately.
| Mode | Best For | Command |
|------|----------|---------|
| Web | First-time setup, visual config, casual chat | bashclaw gateway then open browser |
| Channels | Always-on team bot, mobile access | bashclaw gateway with channels enabled |
| CLI | Automation, scripting, SSH, CI/CD | bashclaw agent -m "..." or bashclaw agent -i |
REST API
GET /api/status System status
GET /api/config Read config (secrets masked)
PUT /api/config Update config (partial merge)
GET /api/models List models, aliases, providers
GET /api/sessions List active sessions
POST /api/sessions/clear Clear a session
POST /api/chat Send message to agent
GET /api/channels List channels
GET /api/env Check which API keys are set
PUT /api/env Save API keys
| Platform | Access | Notes |
|----------|--------|-------|
| macOS / Linux | localhost:18789 | Full browser experience |
| Android Termux | localhost:18789 in phone browser | Responsive touch UI |
| Cloud server | ssh -L 18789:localhost:18789 server | Port forward |
| Windows WSL2 | localhost:18789 in Windows browser | Auto port forward |
| Headless / CI | CLI only | bashclaw agent -m "..." |
Engines
BashClaw has a pluggable engine layer that determines how agent tasks are executed. Each agent can use a different engine.
Claude Engine (Recommended)
The claude engine delegates execution to Claude Code CLI. It reuses your existing Claude subscription -- no API keys needed, no per-token cost.
# Set claude as the default engine
bashclaw config set '.agents.defaults.engine' '"claude"'
# Use it
bashclaw agent -m "Refactor this function for readability"
How it works:
Invokes claude -p --output-format json as a subprocess
Claude Code handles the tool loop with its native tools (Read, Write, Bash, Glob, Grep, etc.)
BashClaw-specific tools (memory, cron, spawn, agent_message) are bridged via bashclaw tool <name> CLI calls
Session state tracked in both BashClaw JSONL and Claude Code's native session
Hooks bridged via --settings JSON injection
Requirements:claude CLI installed and authenticated (claude login).
| Config Field | Description |
|-------------|-------------|
| engine | "claude" to use Claude Code CLI |
| engineModel | Override model (e.g. "opus", "sonnet", "haiku"). If empty, uses your subscription's default. |
| maxTurns | Max agentic turns per invocation |
| Environment Variable | Default | Purpose |
|---------------------|---------|---------|
| ENGINE_CLAUDE_TIMEOUT | 300 | Timeout (seconds) for Claude CLI execution |
| ENGINE_CLAUDE_MODEL | -- | Override model (alternative to engineModel in config) |
Builtin Engine
The builtin engine calls LLM APIs directly via curl. It supports 18 providers and 25+ pre-configured models, and works with any OpenAI-compatible endpoint.
# Builtin is the default engine (no config change needed)
export ANTHROPIC_API_KEY="sk-ant-..."
bashclaw agent -m "hello"
How it works:
Calls provider APIs directly (Anthropic, OpenAI, Google, and 15 more)
Runs BashClaw's own tool loop (max iterations configurable via maxTurns)
Handles context overflow with automatic compaction, model fallback, and session reset
Three API formats: Anthropic (/v1/messages), OpenAI-compatible (/v1/chat/completions), Google (/v1beta/.../generateContent)
Auto Engine
Set engine to "auto" to let BashClaw detect: uses claude if the CLI is installed, otherwise falls back to builtin.
bashclaw config set '.agents.defaults.engine' '"auto"'
Tool Mapping (Claude Engine)
When using the Claude engine, BashClaw tools are mapped to Claude Code's native equivalents where possible. Tools without a native counterpart are bridged through the CLI:
Config format (maxTurns, tool allow/deny lists, tool profiles)
Providers
The builtin engine supports 18 providers with data-driven routing. All configuration is in lib/models.json -- adding a provider is a JSON entry, no code changes.
Pre-configured Providers and Models
BashClaw ships with 25+ pre-configured models. Set the API key and go:
bashclaw gateway
# Open http://localhost:18789 -- first-run wizard configures API keys
# Chat with the agent in your browser immediately
Multi-channel team bot
# One agent, multiple channels -- all served by a single gateway
bashclaw config set '.channels.telegram.enabled' 'true'
bashclaw config set '.channels.discord.enabled' 'true'
bashclaw config set '.channels.slack.enabled' 'true'
bashclaw gateway
# Messages from all platforms routed to the same agent
Always-on server agent
# Install on a fresh Ubuntu server
curl -fsSL .../install.sh | bash
bashclaw daemon install --enable
# Agent runs 24/7, accessible via Telegram, Discord, Slack, or web dashboard
CI/CD pipeline agent
# In a Dockerfile or CI step (< 10MB overhead)
bashclaw agent -m "Review this diff and suggest improvements" < diff.patch
SSH / headless CLI
bashclaw agent -i
# Interactive REPL for power users. No browser needed.
Testing
bash tests/run_all.sh # all tests
bash tests/run_all.sh --unit # unit tests only
bash tests/run_all.sh --integration # live API tests
bash tests/test_agent.sh # single suite
Troubleshooting
bashclaw doctor # check dependencies, config, API key
bashclaw status # gateway state, session count
bashclaw config show # dump current config
LOG_LEVEL=debug bashclaw agent -m "test" # verbose output
Common issues:
command not found after install -- run source ~/.zshrc (macOS) or source ~/.bashrc (Linux), or open a new terminal
jq: command not found -- the installer auto-installs jq; if it failed, run brew install jq (macOS) or apt install jq (Linux)
Gateway shows no HTTP -- install socat for full HTTP server: brew install socat (macOS) or apt install socat (Linux)
License
MIT
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.