The Problem

Developers who want a conversational AI on $10‑class SBCs (RISC‑V, ARM, x86) lack a Go‑native, sub‑10 MB runtime. Existing agents are heavyweight Python/TS stacks that exceed the memory budget of cheap boards, making on‑device inference impractical.

What This Does

picoclaw is a Go program that bundles a voice‑to‑text transcriber, a set of “skills” (GitHub, weather, tmux, etc.), and multiple chat channels (Discord, Telegram, Feishu, MaixCam). The binary lives in cmd/picoclaw/main.go and pulls configuration from config.example.json. Core logic resides in the pkg/ tree:

  • pkg/agent/loop.go – the agent event loop (NewAgentLoop, Run, Stop).
  • pkg/channels/manager.go – creates and starts channel implementations (NewManager, StartAll, StopAll).
  • pkg/skills/loader.go – discovers and loads skill packages (LoadSkillsForContext, BuildSkillsSummary).

The repository is pure Go (33 source files) with a small shell helper (skills/tmux/scripts/find‑sessions.sh). Assets are only media for the README.

How It Is Wired

  1. Entry point – main in cmd/picoclaw/main.go:70 is the only top‑level start. It parses CLI flags, calls loadConfig (via getConfigPath) and then initChannels.
  2. Configuration – loadConfig (pkg/config/config.go) reads config.example.json into a Config struct used by every module.
  3. Channel manager – initChannels (cmd/picoclaw/main.go) constructs a Manager (pkg/channels/manager.go). It registers concrete channel types (discord.go, telegram.go, maixcam.go, …) and invokes StartAll. Each channel’s Start (e.g., pkg/channels/discord.go:48) spawns a goroutine that calls SetTranscriber and begins message handling.
  4. Agent loop – NewAgentLoop (pkg/agent/loop.go) creates the core loop; Run is called from main after channels are up. Run processes inbound messages, routes them through the skill loader (LoadSkillsForContext), and uses pkg/voice/transcriber.go to turn audio into text.
  5. Logging hub – logMessage (pkg/logger/logger.go) is the highest‑fan‑in function (called from 20 places) and therefore the widest blast‑radius for any change. Other frequently used utilities are Close (13 callers) and InfoC/ErrorCF (≈9 callers each).
  6. Shutdown – Stop on the manager and agent loop propagate setRunning(false) and close all channel connections.

The internal call graph contains 337 intra‑repo edges; no circular imports are present, but deep nesting (max depth 8) and duplicated 6‑line blocks appear in main.go, loader.go, and several channel files, making those modules harder to modify safely.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/picoclaw
cd picoclaw

# Build the binary (Makefile provides a build target)
make build          # or: go build -o picoclaw ./cmd/picoclaw

# Copy the example config and edit as needed
cp config.example.json config.json
# Edit config.json – set API keys, channel tokens, etc.

# Run the assistant
./picoclaw --config config.json

The binary reads config.json at startup; missing keys will cause early termination with a logged error.

Real‑World Use

A home‑automation hub on a LicheeRV‑Nano can run ./picoclaw as a systemd service. The Discord channel receives voice commands via a connected microphone, the transcriber converts them, the skill loader matches “turn on lights” to a custom HTTP provider, and the response is posted back to Discord—all without exceeding the 10 MB memory ceiling.

Code Health & Issues

  • High – cognitive load – deep nesting (max depth 8) in cmd/picoclaw/main.go, pkg/skills/loader.go, pkg/channels/discord.go.
  • High – duplicated code – 19 similar 6‑line blocks across 6 files (e.g., main.go, installer.go).
  • Medium – oversized file – cmd/picoclaw/main.go holds 941 lines.
  • Medium – high branching – skills/tmux/scripts/find‑sessions.sh has 26 branches in 90 lines.
  • High – CI missing – no .github/workflows or other CI config for 33 source files.
  • Medium – Dependabot missing – only go.mod present, no auto‑update bot.
  • Medium – large binary asset – assets/picoclaw_detect_person.mp4 (5 MB) should be moved to Git LFS or external storage.
  • Medium – test coverage – 1 test file vs 33 source files (≈3 % coverage).

All findings are derived from static analysis; no additional issues were inferred.

The Bottom Line

picoclaw delivers a functional, Go‑native AI assistant that fits on ultra‑low‑cost hardware, but the codebase suffers from maintainability problems (deep nesting, duplicated logic) and lacks production safeguards (CI, dependency bots, adequate tests). It is suitable for teams comfortable refactoring Go code and willing to add the missing DevOps tooling.