# Teaching Script — DD-17: PicoClaw — The Edge-Hardware Harness

**Deep-Dive**: DD-17 · **Duration**: 60 minutes · **Word count**: ~3,100 words (~140 wpm)
**Use**: Verbatim transcript with [SLIDE N] cues. Each cue marks the slide change.

---

[SLIDE 1] Title

Welcome to Deep-Dive 17. This is PicoClaw — the edge-hardware harness. Thirty thousand stars on GitHub, MIT license, Go single-binary. By the end of this hour, you will understand the only harness in the roster that physically interacts with the world.

Here is what makes PicoClaw different from every other harness we have covered. It is from Sipeed — a Shenzhen-based hardware company that makes RISC-V and AI-camera products. MaixCAM, LicheeRV, NanoKVM. PicoClaw is their play to put a capable agent on their own low-cost hardware. It cross-compiles to x86_64, ARM64, MIPS, RISC-V, and LoongArch. It claims to run on ten-dollar hardware.

But the headline is not the cross-compilation. The headline is hardware-native tools.

[SLIDE 2] The thesis — the only harness that physically interacts with the world

The defining contribution is this: PicoClaw ships `i2c`, `spi`, and `serial` tools in `pkg/tools/hardware/` with per-OS implementations. These tools let the agent directly read sensors and drive peripherals on physical hardware. No other harness in the roster offers this.

The details matter. I2C addresses are validated to 7-bit — the range is 0x03 to 0x77. Per-transaction byte caps are enforced: 256 bytes for I2C, 4096 bytes for SPI. Hardware writes require `confirm: true`. This is real engineering, not a toy demo.

There is also a MaixCAM channel — a TCP-socket channel for Sipeed MaixCAM AI cameras. MaixCAM sends image frames over TCP and PicoClaw analyzes them with vision models. The agent acts as a vision and IoT backend on the hardware.

And there is co-branded physical hardware. A LicheeRV-Claw board is sold on AliExpress. This is not just a software project — it is a hardware ecosystem play.

The load-bearing claim for this deep-dive: PicoClaw is the only harness that physically interacts with the world, and that capability creates a novel attack surface no other harness has. A compromised agent can read sensors, enumerate devices, or drive peripherals. We will come back to that attack surface — it is the most important security insight in this deep-dive.

[SLIDE 3] Thin agent kernel, thick ecosystem

Now let me resolve the most common misreading of PicoClaw. The project is marketed as "ultra-lightweight." And the runtime footprint is genuinely small — sub-second boot on 0.6 gigahertz hardware. But the Go codebase is 868 files, approximately 218 thousand lines of code. That is not a tiny codebase.

The correct framing is: thin agent kernel, thick ecosystem. The kernel is deliberately thin so it runs on ten-dollar hardware. Tiny Markdown prompts — SOUL.md is 351 bytes, AGENT.md is 1,278 bytes. A registry of about 22 tools. Append-only JSONL memory. That is the kernel.

The ecosystem around the kernel is thick because the desktop use case wants it. Twenty-plus channels. Ten-plus LLM providers. MCP client with tool discovery. A skills system with a marketplace. Subagents, spawn, delegate. Cron. Hooks — observer, interceptor, approval. A React web dashboard. System-tray UI. Voice — ASR and TTS. WebRTC media. Process isolation.

The two layers are decoupled. Edge builds can shed the thick ecosystem. When you read "ultra-lightweight," read it as a deployment claim — it runs on ten-dollar hardware — not as a code-organization claim. The codebase is medium-thick; the runtime footprint on edge hardware is thin.

[SLIDE 4] Turn-boundary context trimming

Now the memory and context story, because this is where PicoClaw does something right that most harnesses get wrong.

The context-management insight is shared with Hermes. If you split a tool-call sequence mid-stream, you break the model. If you orphan an `assistant+ToolCalls` message from its `tool results` — if the model sees a dangling tool call with no response — it gets confused.

PicoClaw's answer is turn-boundary trimming. Before the LLM call, it runs a proactive budget check: `isOverContextBudget`. That sums message tokens plus tool-definition tokens plus an output reserve. If over budget, `trimHistoryToFitContextWindow` cuts at safe Turn boundaries.

A Turn is a complete unit: user message, LLM iterations, response. When the trimmer cuts, it removes whole Turns. A Turn that contains a tool-call sequence — assistant plus ToolCalls followed by tool results — stays intact. The pair is never split.

This is the same insight as Hermes's context management, implemented in Go. PicoClaw pays the cost of doing it right. It scores four out of five on Module 3, Context — and that score is earned.

[SLIDE 5] Append-only JSONL memory (crash-safe)

The short-term memory store is append-only JSONL. Each session is two files. The first is `{key}.jsonl` — one message per line. The second is `{key}.meta.json` — a summary and a truncation offset.

The load-bearing design choice: messages are never physically deleted. When `TruncateHistory` runs, it does not delete lines from the JSONL file. It bumps a skip offset in the meta.json. On the next read, the skipped messages are ignored. The file only grows by appending.

This is crash-safe. Append-only writes never corrupt existing lines. A partial line at the end of the file — the result of a process kill mid-write — is ignored on recovery. Truncation is logical, not physical. You lose at most one line on a crash.

For concurrency, there are 64 sharded mutexes. Sessions are sharded by key hash, so concurrent sessions do not contend on a single global lock. This is solid engineering.

And here is the rare-discipline part. PicoClaw ships `cmd/membench` — a memory benchmark harness using the LoCoMo long-conversation benchmark. They actually evaluate their own memory layer. Most harnesses this young assert their memory works. PicoClaw measures it. That is a sign of engineering maturity that the pre-1.0 label does not capture.

[SLIDE 6] The novel hardware attack surface

Now the most important security insight in this deep-dive. PicoClaw's hardware tools create a novel attack surface no other harness has.

Consider the two paths. The write path: an agent wants to write to I2C address 0x48. The confirm gate fires. The operator must approve. The byte cap is enforced. The 7-bit address is validated. This is a necessary defense.

The read path: a prompt-injected agent emits an I2C read. There is no confirm gate on reads. There is no approval required. The agent silently reads every sensor on the bus. It can enumerate devices. It can exfiltrate physical-environment data — temperature, pressure, whatever the sensors report.

The confirm gate on writes is necessary but insufficient. The reads are ungated. A prompt-injected agent can silently read every sensor on the I2C bus without triggering any approval.

The fix is ZeroClaw's autonomy-level model from DD-16. Treat all hardware tools as medium-to-high risk. Require explicit approval for reads, not just writes. Add an audit trail. The confirm-on-writes-only gate is the starting point, not the ending point.

This is the dual-use insight the deep-dive is teaching: a capability that is genuinely valuable — hardware interaction — is also a novel attack surface. The defense is not to remove the capability. The defense is to gate it correctly.

[SLIDE 7] Pre-1.0 reality check

Now the honest caveat. PicoClaw is pre-1.0. The current release is v0.2.9. The README itself warns, "Do not deploy to production before v1.0" and notes "there may be unresolved security issues."

The security gaps are concrete. macOS isolation is not implemented — the `pkg/isolation/` module surfaces macOS as an unsupported config rather than silently failing. The main picoclaw process is unsandboxed on every platform — the child-process sandbox only applies to spawned children, not the orchestrator itself. And the hardware read path is ungated, as we just covered.

The RAM claim is also hedged. The headline says "less than 10 megabytes RAM." The README now says, "Recent builds may use 10 to 20 megabytes of RAM. Resource optimization is planned after feature stabilization." Boot is still sub-second on 0.6 gigahertz hardware — that part is solid. But the RAM-under-load claim is aspirational, not current.

Read pre-1.0 literally. PicoClaw's value is the edge and hardware bet. It is not production security, and the project says so itself. Do not deploy PicoClaw where security matters until v1.0 ships AND the sandboxing gaps close.

[SLIDE 8] Score: 28/60

Let us score it. PicoClaw earns twenty-eight out of sixty on the twelve-module rubric.

The wins: Module 2, Tools, at four out of five. Hardware-native tools are unique in the roster. No competitor offers I2C, SPI, or Serial. Module 3, Context, at four out of five — turn-boundary trimming and the proactive context-budget check. Module 4, Memory, at three out of five — append-only JSONL with the LoCoMo evaluation.

The losses: Module 5, Sandbox, at two out of five. No macOS isolation. Main process unsandboxed. Module 9, Verification, at two out of five — limited. Module 6, Permission, at three out of five — restrict-to-workspace, shell patterns, and hooks, but the hardware read path is ungated.

If you are keeping notes, the headline is: best-in-class tool surface for hardware, solid context management, underdeveloped sandbox and security.

[SLIDE 9] 3 things it does better, 3 things to fix

Three things PicoClaw does better. One: hardware-native tools — I2C, SPI, Serial. The only harness that reads sensors and drives peripherals. No competitor offers this. Two: edge deployment — cross-compiles to RISC-V, MIPS, LoongArch. Runs on ten-dollar SBCs. The co-branded LicheeRV-Claw is a real product. Three: memory benchmarking — ships `cmd/membench` using the LoCoMo benchmark. Actually evaluates its own memory layer. Rare discipline.

Three things to fix. One: security. Pre-1.0 with acknowledged gaps. macOS isolation absent. Main process unsandboxed. The project itself says do not deploy to production. Two: hardware tool safety. I2C and SPI access needs ZeroClaw-level autonomy gating. Reading sensors should be medium-risk; writing should be high-risk with mandatory approval. The read path is currently ungated. Three: memory footprint. Ten to twenty megabytes actual versus less than ten megabytes claimed. Optimize after feature stabilization, as the project plans.

[SLIDE 10] What you can now do

Let us close with what you should be able to do now.

One: explain PicoClaw's defining contribution — hardware-native tools — and why it is the only harness that physically interacts with the world.

Two: distinguish the thin agent kernel from the thick ecosystem, and explain why "ultra-lightweight" describes runtime footprint, not codebase size.

Three: analyze the append-only JSONL memory and turn-boundary trimming as the Go implementation of Hermes's context-management insight.

Four: evaluate the novel hardware attack surface. Explain why the write-only confirm gate is necessary but insufficient — the read path is ungated.

Five: score PicoClaw — twenty-eight out of sixty. Explain the wins — Tools and Context — and the losses — Sandbox and Verification. And judge when to build on it: for hardware and IoT work where the agent must interact with physical devices, not for security-sensitive deployments.

The lab: you will build a minimal simulation of PicoClaw's turn-boundary trimming and append-only JSONL memory. Then you will simulate the hardware attack surface — model an I2C bus with sensors, confirm that an injected agent can silently read sensors, and implement the ZeroClaw-level autonomy fix.

That is PicoClaw. Next is DD-18, MetaClaw — the continual-learning proxy. A different harness, a different bet, but the same engineering discipline lens.

---

End of script.