yoclaw 1.2.0

Secure, single-binary AI agent orchestrator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

<p align="center">
  <img src="assets/banner.png" alt="yoclaw banner" width="100%">
</p>

<p align="center">
  <a href="https://crates.io/crates/yoclaw">crates.io</a> ·
  <a href="https://docs.rs/yoclaw">Docs</a> ·
  <a href="https://github.com/yologdev/yoclaw">GitHub</a> ·
  <a href="https://deepwiki.com/yologdev/yoclaw">DeepWiki</a> ·
  <a href="https://github.com/yologdev/yoclaw/issues">Issues</a> ·
  <a href="https://github.com/yologdev/yoclaw/releases">Releases</a>
</p>

<p align="center">
  <a href="https://crates.io/crates/yoclaw"><img src="https://img.shields.io/crates/v/yoclaw?logo=rust&logoColor=white&label=crates.io" alt="crates.io"></a>
  <a href="https://github.com/yologdev/yoclaw/actions"><img src="https://img.shields.io/github/actions/workflow/status/yologdev/yoclaw/ci.yml?label=CI&logo=github" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license MIT"></a>
  <a href="https://docs.rs/yoclaw"><img src="https://img.shields.io/docsrs/yoclaw?label=docs&logo=rust&logoColor=white" alt="docs"></a>
  <a href="https://github.com/yologdev/yoclaw/commits/master"><img src="https://img.shields.io/github/last-commit/yologdev/yoclaw" alt="last commit"></a>
</p>

---

# yoclaw: Single-Binary AI Agent

**yoclaw** is a minimal, secure alternative to [OpenClaw](https://github.com/anthropics/openclaw) — a single Rust binary that turns any LLM into a persistent, tool-using agent on messaging platforms. Built on [yoagent](https://github.com/yologdev/yoagent).

No Docker. No Redis. No infrastructure. One binary, one config file.

## Core Capabilities

- **Pluggable channels** — Telegram today, Discord/Slack next. Add new platforms by implementing one trait.
- **SQLite persistence** — Conversations, message queue, long-term memory (FTS5), and audit logs in a single file.
- **Crash recovery** — Messages are queued before processing. Kill -9, restart, nothing lost.
- **Security policies** — Tool permissions, shell deny patterns, path/host allowlists, per-tool enable/disable.
- **Budget tracking** — Token and turn limits per day/session with automatic enforcement.
- **Skills system** — Drop markdown files into `~/.yoclaw/skills/` to teach your agent new capabilities.
- **Worker delegation** — Configure named sub-agents with different models for specialized tasks.
- **Long-term memory** — Full-text search over stored facts, preferences, and context.

## Quick Start

```bash
# Build
cargo build --release

# Initialize config directory
./yoclaw init

# Edit config with your keys
vim ~/.yoclaw/config.toml

# Run
ANTHROPIC_API_KEY=sk-ant-... TELEGRAM_BOT_TOKEN=123:ABC... ./yoclaw
```

## Configuration

```toml
[agent]
provider = "anthropic"
model = "claude-opus-4-6"
api_key = "${ANTHROPIC_API_KEY}"

[agent.budget]
max_tokens_per_day = 1_000_000
max_turns_per_session = 50

[agent.workers.research]
model = "claude-sonnet-4-20250514"
system_prompt = "You are a research assistant."
max_turns = 15

[channels.telegram]
bot_token = "${TELEGRAM_BOT_TOKEN}"
allowed_senders = [123456789]
debounce_ms = 2000

[security]
shell_deny_patterns = ["rm -rf", "sudo", "chmod 777"]
```

Customize the persona in `~/.yoclaw/persona.md`.

## Adding Skills

```bash
mkdir -p ~/.yoclaw/skills/my-skill
cat > ~/.yoclaw/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill does
tools: [http]
---

Instructions for the agent when this skill is relevant.
EOF
```

Skills requiring disabled tools are automatically excluded.

## Inspect

```bash
yoclaw inspect                    # Queue, sessions, budget, audit
yoclaw inspect --skills           # Loaded skills and their tool requirements
yoclaw inspect --workers          # Configured worker sub-agents
yoclaw inspect --session tg-123   # Filter audit by session
```

## Architecture

```
Telegram → Coalescer → Queue (SQLite) → Conductor → Agent (yoagent) → Response → Telegram
                                            ↓
                                     Security Policy
                                     Budget Tracker
                                     Memory (FTS5)
                                     Worker Delegation
```

The Conductor owns a single yoagent `Agent` and switches between sessions by saving/loading conversation state. All tool calls pass through `SecureToolWrapper` for policy enforcement and audit logging.

## Project Structure

```
src/
├── main.rs              CLI + event loop
├── config.rs            TOML config with env var expansion
├── conductor/           Agent orchestration + workers
├── channels/            Messaging platform adapters
├── db/                  SQLite: tape, queue, memory, audit
├── security/            Policy enforcement + budget tracking
└── skills/              Skill loading with capability filtering
```

## Requirements

- Rust 1.75+
- [yoagent](https://crates.io/crates/yoagent) v0.5.1+

## License

[MIT](LICENSE)