Skip to content

Commit 4151991

Browse files
CrazyBoyMCrazyBoyM
committed
Symlink-based installer, README section reorder, doc fixes
Install: replace PATH-append with symlink-first strategy (/usr/local/bin -> ~/.local/bin -> shell config fallback), gateway-first post-install instructions, symlink cleanup on uninstall. README: reorder Engines before Providers, add engine field to config example, fix architecture diagram and directory structure to match actual UI files, fix CN stale test count.
1 parent 918f1d9 commit 4151991

4 files changed

Lines changed: 398 additions & 317 deletions

File tree

‎README.md‎

Lines changed: 147 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ Pure-shell AI agent runtime. No Node.js, no Python, no compiled binaries.
2121
<a href="#quick-start">Quick Start</a> &middot;
2222
<a href="#features">Features</a> &middot;
2323
<a href="#web-dashboard">Dashboard</a> &middot;
24-
<a href="#providers">Providers</a> &middot;
2524
<a href="#engines">Engines</a> &middot;
25+
<a href="#providers">Providers</a> &middot;
2626
<a href="#channels">Channels</a> &middot;
2727
<a href="#architecture">Architecture</a> &middot;
2828
<a href="README_CN.md">&#x4E2D;&#x6587;</a>
@@ -224,6 +224,144 @@ PUT /api/env Save API keys
224224

225225
</details>
226226

227+
## Engines
228+
229+
BashClaw has a pluggable engine layer that determines how agent tasks are executed. Each agent can use a different engine.
230+
231+
### Claude Engine (Recommended)
232+
233+
The **claude** engine delegates execution to [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). It reuses your existing Claude subscription -- no API keys needed, no per-token cost.
234+
235+
```sh
236+
# Set claude as the default engine
237+
bashclaw config set '.agents.defaults.engine' '"claude"'
238+
239+
# Use it
240+
bashclaw agent -m "Refactor this function for readability"
241+
```
242+
243+
**How it works:**
244+
- Invokes `claude -p --output-format json` as a subprocess
245+
- Claude Code handles the tool loop with its native tools (Read, Write, Bash, Glob, Grep, etc.)
246+
- BashClaw-specific tools (memory, cron, spawn, agent_message) are bridged via `bashclaw tool <name>` CLI calls
247+
- Session state tracked in both BashClaw JSONL and Claude Code's native session
248+
- Hooks bridged via `--settings` JSON injection
249+
250+
**Requirements:** `claude` CLI installed and authenticated (`claude login`).
251+
252+
<details>
253+
<summary><strong>Claude engine configuration</strong></summary>
254+
255+
```json
256+
{
257+
"agents": {
258+
"defaults": {
259+
"engine": "claude",
260+
"maxTurns": 50
261+
},
262+
"list": [
263+
{
264+
"id": "coder",
265+
"engine": "claude",
266+
"engineModel": "opus",
267+
"maxTurns": 30
268+
}
269+
]
270+
}
271+
}
272+
```
273+
274+
| Config Field | Description |
275+
|-------------|-------------|
276+
| `engine` | `"claude"` to use Claude Code CLI |
277+
| `engineModel` | Override model (e.g. `"opus"`, `"sonnet"`, `"haiku"`). If empty, uses your subscription's default. |
278+
| `maxTurns` | Max agentic turns per invocation |
279+
280+
| Environment Variable | Default | Purpose |
281+
|---------------------|---------|---------|
282+
| `ENGINE_CLAUDE_TIMEOUT` | `300` | Timeout (seconds) for Claude CLI execution |
283+
| `ENGINE_CLAUDE_MODEL` | -- | Override model (alternative to `engineModel` in config) |
284+
285+
</details>
286+
287+
### Builtin Engine
288+
289+
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.
290+
291+
```sh
292+
# Builtin is the default engine (no config change needed)
293+
export ANTHROPIC_API_KEY="sk-ant-..."
294+
bashclaw agent -m "hello"
295+
```
296+
297+
**How it works:**
298+
- Calls provider APIs directly (Anthropic, OpenAI, Google, and 15 more)
299+
- Runs BashClaw's own tool loop (max iterations configurable via `maxTurns`)
300+
- Handles context overflow with automatic compaction, model fallback, and session reset
301+
- Three API formats: Anthropic (`/v1/messages`), OpenAI-compatible (`/v1/chat/completions`), Google (`/v1beta/.../generateContent`)
302+
303+
### Auto Engine
304+
305+
Set `engine` to `"auto"` to let BashClaw detect: uses `claude` if the CLI is installed, otherwise falls back to `builtin`.
306+
307+
```sh
308+
bashclaw config set '.agents.defaults.engine' '"auto"'
309+
```
310+
311+
### Tool Mapping (Claude Engine)
312+
313+
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:
314+
315+
| BashClaw Tool | Claude Code Tool | Method |
316+
|---------------|-----------------|--------|
317+
| `web_fetch` | WebFetch | native |
318+
| `web_search` | WebSearch | native |
319+
| `shell` | Bash | native |
320+
| `read_file` | Read | native |
321+
| `write_file` | Write | native |
322+
| `list_files` | Glob | native |
323+
| `file_search` | Grep | native |
324+
| `memory` | -- | `bashclaw tool memory` |
325+
| `cron` | -- | `bashclaw tool cron` |
326+
| `agent_message` | -- | `bashclaw tool agent_message` |
327+
| `spawn` | -- | `bashclaw tool spawn` |
328+
329+
### Mixed Engine Configuration
330+
331+
Different agents can use different engines:
332+
333+
```json
334+
{
335+
"agents": {
336+
"defaults": { "engine": "claude" },
337+
"list": [
338+
{
339+
"id": "coder",
340+
"engine": "claude",
341+
"engineModel": "opus"
342+
},
343+
{
344+
"id": "chat",
345+
"engine": "builtin",
346+
"model": "gpt-4o"
347+
},
348+
{
349+
"id": "local",
350+
"engine": "builtin",
351+
"model": "llama-3.3-70b-versatile"
352+
}
353+
]
354+
}
355+
}
356+
```
357+
358+
**Both engines share the same:**
359+
- Lifecycle hooks (before_agent_start, pre_message, post_message, agent_end)
360+
- Session persistence (JSONL)
361+
- Workspace loading (SOUL.md, MEMORY.md, BOOT.md, IDENTITY.md)
362+
- Security layer (rate limiting, tool policies, RBAC)
363+
- Config format (`maxTurns`, tool allow/deny lists, tool profiles)
364+
227365
## Providers
228366

229367
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.
@@ -375,144 +513,6 @@ The builtin engine supports three API formats. Most providers use OpenAI-compati
375513

376514
Any service that implements one of these formats works out of the box.
377515

378-
## Engines
379-
380-
BashClaw has a pluggable engine layer that determines how agent tasks are executed. Each agent can use a different engine.
381-
382-
### Claude Engine (Recommended)
383-
384-
The **claude** engine delegates execution to [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). It reuses your existing Claude subscription -- no API keys needed, no per-token cost.
385-
386-
```sh
387-
# Set claude as the default engine
388-
bashclaw config set '.agents.defaults.engine' '"claude"'
389-
390-
# Use it
391-
bashclaw agent -m "Refactor this function for readability"
392-
```
393-
394-
**How it works:**
395-
- Invokes `claude -p --output-format json` as a subprocess
396-
- Claude Code handles the tool loop with its native tools (Read, Write, Bash, Glob, Grep, etc.)
397-
- BashClaw-specific tools (memory, cron, spawn, agent_message) are bridged via `bashclaw tool <name>` CLI calls
398-
- Session state tracked in both BashClaw JSONL and Claude Code's native session
399-
- Hooks bridged via `--settings` JSON injection
400-
401-
**Requirements:** `claude` CLI installed and authenticated (`claude login`).
402-
403-
<details>
404-
<summary><strong>Claude engine configuration</strong></summary>
405-
406-
```json
407-
{
408-
"agents": {
409-
"defaults": {
410-
"engine": "claude",
411-
"maxTurns": 50
412-
},
413-
"list": [
414-
{
415-
"id": "coder",
416-
"engine": "claude",
417-
"engineModel": "opus",
418-
"maxTurns": 30
419-
}
420-
]
421-
}
422-
}
423-
```
424-
425-
| Config Field | Description |
426-
|-------------|-------------|
427-
| `engine` | `"claude"` to use Claude Code CLI |
428-
| `engineModel` | Override model (e.g. `"opus"`, `"sonnet"`, `"haiku"`). If empty, uses your subscription's default. |
429-
| `maxTurns` | Max agentic turns per invocation |
430-
431-
| Environment Variable | Default | Purpose |
432-
|---------------------|---------|---------|
433-
| `ENGINE_CLAUDE_TIMEOUT` | `300` | Timeout (seconds) for Claude CLI execution |
434-
| `ENGINE_CLAUDE_MODEL` | -- | Override model (alternative to `engineModel` in config) |
435-
436-
</details>
437-
438-
### Builtin Engine
439-
440-
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.
441-
442-
```sh
443-
# Builtin is the default engine (no config change needed)
444-
export ANTHROPIC_API_KEY="sk-ant-..."
445-
bashclaw agent -m "hello"
446-
```
447-
448-
**How it works:**
449-
- Calls provider APIs directly (Anthropic, OpenAI, Google, and 15 more)
450-
- Runs BashClaw's own tool loop (max iterations configurable via `maxTurns`)
451-
- Handles context overflow with automatic compaction, model fallback, and session reset
452-
- Three API formats: Anthropic (`/v1/messages`), OpenAI-compatible (`/v1/chat/completions`), Google (`/v1beta/.../generateContent`)
453-
454-
### Auto Engine
455-
456-
Set `engine` to `"auto"` to let BashClaw detect: uses `claude` if the CLI is installed, otherwise falls back to `builtin`.
457-
458-
```sh
459-
bashclaw config set '.agents.defaults.engine' '"auto"'
460-
```
461-
462-
### Tool Mapping (Claude Engine)
463-
464-
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:
465-
466-
| BashClaw Tool | Claude Code Tool | Method |
467-
|---------------|-----------------|--------|
468-
| `web_fetch` | WebFetch | native |
469-
| `web_search` | WebSearch | native |
470-
| `shell` | Bash | native |
471-
| `read_file` | Read | native |
472-
| `write_file` | Write | native |
473-
| `list_files` | Glob | native |
474-
| `file_search` | Grep | native |
475-
| `memory` | -- | `bashclaw tool memory` |
476-
| `cron` | -- | `bashclaw tool cron` |
477-
| `agent_message` | -- | `bashclaw tool agent_message` |
478-
| `spawn` | -- | `bashclaw tool spawn` |
479-
480-
### Mixed Engine Configuration
481-
482-
Different agents can use different engines:
483-
484-
```json
485-
{
486-
"agents": {
487-
"defaults": { "engine": "claude" },
488-
"list": [
489-
{
490-
"id": "coder",
491-
"engine": "claude",
492-
"engineModel": "opus"
493-
},
494-
{
495-
"id": "chat",
496-
"engine": "builtin",
497-
"model": "gpt-4o"
498-
},
499-
{
500-
"id": "local",
501-
"engine": "builtin",
502-
"model": "llama-3.3-70b-versatile"
503-
}
504-
]
505-
}
506-
}
507-
```
508-
509-
**Both engines share the same:**
510-
- Lifecycle hooks (before_agent_start, pre_message, post_message, agent_end)
511-
- Session persistence (JSONL)
512-
- Workspace loading (SOUL.md, MEMORY.md, BOOT.md, IDENTITY.md)
513-
- Security layer (rate limiting, tool policies, RBAC)
514-
- Config format (`maxTurns`, tool allow/deny lists, tool profiles)
515-
516516
## Channels
517517

518518
Each channel is a standalone shell script under `channels/`.
@@ -599,10 +599,10 @@ bashclaw gateway
599599
+------+------+ +-------+-------+ +-------+-------+
600600
| http_handler | | SSRF filter | | plugin.sh |
601601
| ui/index.html| | rate limiting | | skills.sh |
602-
| OpenAI API | | pairing codes | | hooks.sh (14) |
603-
| REST API (9) | | tool policies | | autoreply.sh |
604-
+--------------+ | RBAC + audit | | boot.sh |
605-
+---------------+ | dedup.sh |
602+
| ui/style.css | | pairing codes | | hooks.sh (14) |
603+
| ui/app.js | | tool policies | | autoreply.sh |
604+
| REST API (9) | | RBAC + audit | | boot.sh |
605+
+--------------+ +---------------+ | dedup.sh |
606606
+---------------+
607607
```
608608

@@ -673,7 +673,9 @@ bashclaw/
673673
gateway/
674674
http_handler.sh # HTTP request handler + REST API
675675
ui/
676-
index.html # single-file SPA (CSS+JS inline, 6 tabs)
676+
index.html # dashboard page
677+
style.css # dark/light theme, responsive
678+
app.js # vanilla JS single-page app
677679
tools/ # external tool scripts
678680
tests/
679681
framework.sh # test runner
@@ -778,6 +780,7 @@ Config file: `~/.bashclaw/bashclaw.json`
778780
{
779781
"agents": {
780782
"defaults": {
783+
"engine": "auto",
781784
"model": "claude-opus-4-6",
782785
"maxTurns": 50,
783786
"contextTokens": 200000,

0 commit comments

Comments
 (0)