RubyClaw
Self-building agent harness · Ruby · stdlib only
It writes its own tools. Then it checks them.
RubyClaw is a small, self-building AI agent harness in Ruby. You give it a model and a shell; it configures itself on a new machine, grows its own tools and verifies them before trusting them, keeps its work outside the chat, and asks before it acts.
What it does
A harness with opinions, and rules it cannot break.
-
Writes its own tools — verified before trust
Ask for something it cannot do and it writes a new tool. Not on trust: syntax-checked, loaded in a throwaway child process, and exercised with real arguments before it is promoted. A failure goes back to the model, not to you as a broken harness.
-
Work that outlives the chat
Chat history is context, not the source of truth. A task is a record in one of eight states, with illegal moves refused, an append-only event log, artifacts tied to their task, and approvals waiting on a person — all plain files you can read and edit.
-
Keeps standing commitments
A responsibility starts work on its own. A heartbeat pass resumes, retries a bounded number of times, and parks an approval when a person is needed — and on an ordinary pass it makes no model call at all.
-
Asks before it acts — default-deny
One file,
policy.yml, decides per action whether the agent may just do it (auto), must ask (ask), may never (block), or is not the actor at all (human_only). It is checked before anything runs, and anything unmatched isask, neverauto. The agent can never grant its own approvals. -
Tells you when it needs you
It reports through the chat you already use, under a per-responsibility reporting policy, and never to a chat that is not on the allowlist. A send that fails waits in a durable queue and is retried on the next pass.
-
Read-only Scout
A keyless web search and a one-URL read, GET-only by construction: every other verb is refused before a socket is opened. Fetched pages arrive marked as untrusted data, not instructions.
-
One command, no gems, no build step
Stdlib only at runtime. One entry point that configures itself on a new machine: a few questions, then a prompt. On Linux it installs a prebuilt Ruby if you have none.
-
Schedules itself, survives a reboot
Its own work goes into your crontab — no root, no systemd. It comes back after a reboot and runs as a service, and it can update itself from upstream selectively.
And it runs on a Raspberry Pi Zero W — one core, 426 MB of RAM.
How it works
From a request it cannot fulfil to work it can trust.
-
Write
The model asks for something it cannot do, and writes a tool for it.
-
Verify
Syntax check, load in a throwaway child process, then exercised with real arguments.
-
Promote
Only then is it written under
instance/tools/, committed, and loaded live. -
Do the work
Tasks live in one of eight states, with every accepted move one line in the event log.
-
Ask first
The policy is checked before the action runs. A held action parks a real approval and waits for a person.
-
Report
What the pass did reaches a person through the chat, or waits in the queue until it can.
Install
One entry point. Nothing to bundle.
Clone it and run it. The entry point configures itself: a few questions, then a prompt. There is nothing to install first and nothing to compile.
- No gems at runtime — the stores are JSON on disk, not SQLite.
- On Linux x86-64 and arm64 it installs a prebuilt Ruby if you have none; elsewhere bring Ruby 3.1+.
- Tested on a Raspberry Pi 4 and on a Pi Zero W (one core, 426 MB RAM).
$ git clone https://github.com/hatumai/RubyClaw.git && cd RubyClaw
$ ./rubyclawLicense
Free for noncommercial use.
RubyClaw is free for noncommercial use under the PolyForm Noncommercial License 1.0.0 — personal projects, study, research, hobby work, charity, and evaluating it.
Commercial use requires a paid license, arranged by contact. It is an honour system: no license keys, no telemetry, no enforcement — just the obligation and your word.