Tamoz: an agent that makes sense of the world and acts on it

$ tamoz --root . --allow-changes --check 'test=rake test' "Fix the failing parser test"
[discovery] read 4 files            → evidence only, no changes proposed
[plan]      action plan reviewed    → bound to digest 9f2c17…
[effect]    diff staged  lib/parser.rb (+6 −2)  → approval required, run paused
$ tamoz resolve 1f4a --approve
[patch]     atomic apply            → checkpoint committed (SQLite)
[check]     rake test               → green; verification recorded

Tamoz is a durable agent framework for Ruby. The idea behind it is plain: an agent should be able to do real work without losing its mind when something goes wrong. A single turn runs as a graph over a SQLite checkpoint store, so it survives a kill -9, picks up from the last committed step, and figures out what happened to an interrupted side effect instead of guessing. It won't act without a plan you can read first, and it won't touch a file without your approval.

I built it in the least exciting order on purpose. Evaluation came before behavior, deterministic execution before persistence, persistence before anything model-driven. That makes it slower to demo than most frameworks, and I'm fine with that. The whole point is that you can look inside and see where the edges are. Even the "what's released" status is generated by running the tests, not written by me in a hopeful paragraph.

Three repos, one job each

On its own, Tamoz is deliberately narrow. It's the part that thinks: it reads a sealed, versioned snapshot of a situation and answers with a decision or an intent. It never touches the serial port, the PWM loop, or a safety stop. That's someone else's job, on purpose. Two sibling repos handle the rest:

• Agentic Stream (Go, Apache-2.0) is the always-on side. It processes events as they arrive, builds the situations Tamoz reads, and runs the policy that decides what's actually allowed to happen.
• Streams Simulator (Go, MIT) is a world I can replay on demand. It keeps "what really happened" separate from "what the system was told," then scores the agent against the truth.

That split is the whole point. The model is allowed to say "cool things down" (bounded_cooling). It is never allowed to pick the exact PWM value or how long the motor runs. Policy owns the physical envelope, every time.

How it's put together

Under the hood it's a monorepo of small gems, each one installing with only what it actually needs. Checkpoints, interrupts, effect journals, leases, audit trails: those are the building blocks, not features I bolted on afterward. There's no third-party agent library doing the thinking; the model connection is my own, pinned to a digest and speaking a plain OpenAI-compatible protocol. The reference app, Tamoz Agent, can only act through a plan-review-act loop, inside a workspace it's allowed to touch, with one sealed set of capabilities. A skill or a tool description can ask for more power, but it can never hand itself any.

I wired it to a real motor

I wanted to watch the boundary hold on actual hardware, so I connected the wider system to an Arduino and a small motor. Tamoz proved that a real model could select a bounded cooling mode without choosing PWM or timing. In a separate hardware run, deterministic policy produced a bounded command and the motor spun before an explicit safe-stop returned the board to a safe state.

What actually happened: I watched the motor run under a governed direct-serial command (bounded PWM, a 10-second lease, and an explicit safe-stop). What's still work in progress: the reviewed Tamoz-to-Agentic Stream conversion seam, the full live loop end to end, the complete fault-and-recovery matrix, independent sensors confirming motion, and a long soak run.

Why I built it

Most agent demos look great right up until they hit the edges: the same side effect fires twice, a crash leaves things half-done, edits land without anyone reviewing them, and there's no record of what happened or why. I got tired of treating all of that as cleanup you do later. In Tamoz it's the starting requirement. Effects are assumed to run at-least-once unless I can prove otherwise, and anything genuinely ambiguous stops and asks a human rather than quietly retrying.

If you want to poke at it

A few places I'd open first:

• The graph engine: checkpointed, deterministic, with interrupts and reducers so a run can pause and resume without drifting.
• The SQLite layer that holds the checkpoints, the effect journal, leases, backups, and audit trail.
• Tamoz Agent's plan-review-act loop, its sealed capabilities, and sessions that survive across restarts.
• The episode worker and the Situation boundary: the seam where Tamoz meets the stream.
• Governed MCP, layered durable memory, bounded self-healing, and the approval engine driven by policy-as-data.
• The evals: scorecards and a requirements audit that's regenerated by running each named test.

Why it's here

Tamoz is the clearest version of something I keep coming back to: if you want an agent to be trusted, you have to give it contracts, a way to recover, something to watch, and gates it has to pass. It's early (0.1.0.alpha.1, gaps and all, written down where you can see them), but the direction is already there in the code, the docs, and a physical boundary being tested one claim at a time.