The agentic workflow
Remote control setup
Claude Code is Anthropic's CLI coding agent. It reads and edits files, runs shell commands, uses git, and opens pull requests. I run it as a persistent service on the Pi. The Claude iOS app connects to it, so from my phone I can send tasks and they execute on the Pi.
In practice: I send "add a /uses page listing the homelab hardware," a pull request shows up on GitHub a few minutes later, and eventually a merge notification arrives. Never opened a laptop.
Making it reliable rather than a party trick involves a few design decisions.
Worktrees
Every task runs in its own git worktree, which is a separate working directory on its own branch that shares the same repo history. Agents working in parallel are literally in different directories on different branches. They can't step on each other's files.
Main stays clean. Tasks start from a known-good state, work in isolation, and come back via PR. If something goes sideways, delete the worktree.
Maker/verifier split
The agent that wrote the code can't reliably check whether the code is correct. It has a reasoning trail, and reviewing its own output tends to be consistent with that trail, including its mistakes.
The fix is a separate, independent agent, with no memory of the original task, reviews the output against the goal. Different session, context, and no shared assumptions. Every PR gets this second pass before it merges.
Memory
The model resets between sessions. To avoid re-deriving the same things every time, the environment does the remembering.
The base layer is AGENTS.md, one file of operating instructions that's always in
context: who I am, the machines and their IP addresses, the git conventions, the cleanup
procedures, how to talk to me. It's written to be harness-agnostic (plain
markdown, no tool-specific features) so the same rules hold whether the agent runs in Claude
Code on the Pi, Cursor on the laptop, or a cron script. Cursor reads AGENTS.md
natively; Claude Code picks it up through a one-line CLAUDE.md shim. One source of
truth, every tool.
Each active project has a STATE.md: verified facts, general rules, open failures,
lessons, last-session summary. Read it at session start, update before closing. The verified
facts section is the most useful one, since it's things confirmed correct, not guesses. "The runner uses
Node 24." "Cloudflare Tunnel ingress is configured via a config file, not the dashboard." Learned
those the hard way once.
Skills are markdown files for procedures, like how to do a Pi health check, how
to clean up disk, and so on. They live in .claude/skills/ (a symlink shared across
tools, so Claude and Cursor read the same set). The key property is that they accumulate failure
modes. Every non-obvious breakage adds a "never do X, Y happened" entry. A Skill that's been
running for a month looks very different from the first draft.
STATE.md is project-scoped, so it dies with the project. Skills travel across projects. Procedural lessons go in Skills.
And every meaningful session ends with an entry appended to CHANGELOG.md, a terse,
dated log of what changed and which files it touched. It's the audit trail: when something
breaks three weeks later, the changelog says what last went near it.
The pipeline
Task finishes → commit to worktree branch → push → open PR → Opus reviews and commits any fixes → typecheck runs → squash merge → deploy fires. Fully automated. I get a merge notification, or a failure alert if something breaks.
The compound effect
There are two versions of "AI self-improvement." The weight-level kind, where the model updates its own weights from experience, isn't real in any production model today. The environment-level kind, where the system around the model accumulates knowledge, is real and buildable now.
The model is stateless. STATE.md and the Skills aren't. Sessions compound instead of repeating. After a few months the environment knows things (which runner version breaks the build, which dashboard is a trap for a specific config) and doesn't re-learn them.
Not a smarter model. A system that stops making the same mistakes.