This is the how-to companion to an architecture review of ProxiBlue's AI-agent tooling. The review explains what the pieces are and why; this explains how to stand up your own version.
It comes in two halves:
- Part 1 — the plugin stack. Four open-source Claude Code plugins you can install directly (ProxiBlue, MIT/Apache). These give you memory, orchestration, multi-agent coordination, and a code graph.
- Part 2 — the patterns. The higher-value, opinionated parts (deterministic guards, a test gate, a self-measurement layer, off-site backups, version discipline) are described as reference patterns you reproduce yourself. They're simple shell + cron; the value is in the design, which is fully documented here.
Everything below is provider-agnostic in principle, but the concrete examples assume Claude Code (Anthropic's terminal agent) on Linux + Docker, which is the tested combination.
- Docker + docker compose.
- Node (for Claude Code) and Claude Code itself — and pin the version (see Pattern 9; do not auto-update).
- A container-based dev environment if you work on real projects — the reference setup uses DDEV, but the patterns don't depend on it.
- CLI:
git jq openssl curl python3, and rclone (for off-site backups).
All four live on GitHub under ProxiBlue/… and install through Claude Code's
plugin marketplace mechanism. Add the marketplace once, then enable the plugins
in your Claude settings (~/.claude/settings.json → enabledPlugins).
A shared, cross-session memory that remembers decisions, incidents, and vendor verdicts over time, not just facts. Runs a Neo4j database + an MCP server, fed by ingestion pipelines (tickets, email, session transcripts). Facts carry validity intervals, so superseded decisions stay queryable as history.
- Needs: Docker (Neo4j + MCP compose ships with the plugin), an LLM for entity extraction (a cheap cloud tier like Claude Haiku is the pragmatic default), and an embedder.
- Start here if you want the single highest-leverage addition: durable memory.
Wraps the HCF planning framework (markshust/hcf) and adds a pipeline of review
agents that fire at named phases around implementation: a devil's advocate
that attacks the plan before code is written, a security quorum (three agents
— static analyst, adversarial tester, defensive auditor — that must agree), plus
code-graph and knowledge-graph reviewers. Run its wire command per project to
enrol the agents.
A threaded message store that lets agents in different projects coordinate (claim-based task ownership, escalation, kill switches). Also the basis for cron-driven headless agents that pick up tickets and ship PRs unattended.
A queryable index of code structure — callers, dependents, and (for Magento) dependency-injection wiring and plugin chains — so the agent answers "what would this change break" from structure, not text search.
Install pattern (all four): add the ProxiBlue marketplace to
~/claude-plugins-central/…/known_marketplaces.json (or via /plugin marketplace add), then /plugin install <name>@<marketplace>, then list them
under enabledPlugins in settings.json. Each plugin's README covers its own
compose files and configuration.
These are the disciplined core. Each is a small amount of shell + cron; the value is the design. Build your own — they're intentionally simple.
Don't write generic style guides. Every time the agent fails in a costly way,
write a rule from that specific incident, and record the incident in the
rule. Make them checklists, not prose: banned phrases, mandated report formats,
explicit stop-triggers. Keep the always-loaded set small; load heavier rules only
when relevant (Claude Code's paths: frontmatter attaches a rule when the agent
opens a matching file, at zero cost until then).
Enforce invariants with code, not instructions. A written rule is followed "most of the time" — fine for style, fatal for "never push to production." Use Claude Code hooks (shell scripts that run before/after each tool call and can block it, exit code 2). Reference guards worth building:
- a merge guard (block merging a staging branch the wrong direction),
- a push guard (block pushes to protected branches),
- a ticket-comment guard (force AI comments through a helper that keeps them terse),
- a debug guard (block print-debugging edits, steer to a real debugger).
Each guard prints instructions to the agent on block, and cannot be bypassed from inside the session — the bypass is an env var set before the agent starts.
A PreToolUse hook on git commit/push that blocks unless there's recorded
evidence the tests passed at exactly this code state. A PostToolUse hook
records test runs, fingerprinting the working-tree state; any later edit
invalidates the evidence, so the agent can't test-then-tweak-then-commit.
- Hard-won gotcha: verify your harness's hook payload shape empirically. On the tested version, the PostToolUse Bash payload has no exit-code field and fires only for exit-0 commands — assume that and re-check on every harness update. (Discovered by live-firing; a synthetic test had passed against a wrong assumption.)
- Add a changed-line coverage check to catch tests that pass without exercising the change; mutation testing (e.g. Infection for PHP) is the stronger version.
- Debug it by live-firing against a real headless agent session, not by trusting unit tests.
"Cheap writers, dynamic skeptics." Pin cheap/fast models for mechanical work and code writing; reserve top-tier models for judgment, review, and security. Let the operator dial review depth by switching the session model, with no config edits.
Split memory by whether it must never fail to load. Hard rules and pointers go in flat files that auto-load every session. Rich domain knowledge goes in the graph (pb-graphiti), queried on demand. Write a discipline that the agent must exhaust several search strategies before claiming "not in the graph" — the usual failure is bad searching, not missing data.
Answer "is any of this actually working?" with three independent checks feeding one dashboard:
- Rule evals — an executable suite that replays each rule's origin incident against the live agent and scores compliance (e.g. stage a repo with a broken change + failing test, ask the agent to investigate, assert it enumerates its own changes first and cites evidence). Run before every version bump.
- Usage telemetry — mine your real session transcripts weekly; count how often each guard actually fired. A guard idle for months is a pruning candidate; a spike is workflow friction.
- Config-drift detection — a weekly sweep that checks every project still matches the intended config (right version, guards actually mounted) and alerts on deviation. Feed all three into a single static HTML dashboard regenerated by cron.
Deliver actionable alerts (job failed, drift, dead self-check) three ways: a desktop popup for when you're present, an email for when you're away, and a persistent log on the dashboard so a missed popup is still findable. Keep passive weekly digests in a quieter channel so the urgent alerts keep meaning something. Put a heartbeat on every scheduled job so a silently-dead cron turns red on the dashboard you already open — the dead-man's switch, with no separate watcher.
Whatever data isn't reconstructable (a knowledge graph, say): dump it nightly, encrypt locally (openssl AES-256), and push the ciphertext to object storage (Backblaze B2 via rclone is cheap and reliable; avoid providers whose only headless path is a deprecated protocol). Two rules:
- Test the restore, don't assume it. Download, decrypt, and diff against the original. A backup nobody has restored is a hope.
- The decryption passphrase must live off-machine (a password manager). If its only copy is on the disk that dies, the backups are undecryptable.
If you centralise your rules/hooks/config in one repo and bind-mount it into each project's container (so one fix propagates everywhere), watch the file-vs-directory distinction:
- Directory bind-mounts reflect edits live — the container resolves files by name on each open, so a changed file inside is seen immediately.
- Single-file bind-mounts go stale on edit. Most editors (and many tools) save via atomic-replace (write temp, rename over) which changes the file's inode; the mount still points at the old, now-unlinked inode until the container restarts.
So dir-mount your config folders, not individual files, and edits are live
without a restart. If you must file-mount a single file, either edit it in
place (a > redirect truncates-and-writes, preserving the inode) or accept a
container restart to apply it. This is a subtle one — a hook that "isn't firing"
after you wired it is usually just a stale single-file mount, not a broken hook.
The agent tool changes behaviour between releases in ways that silently break tuned config. Pin the version, auto-update off. But model the pin as a dated decision in a tracked file, with a daily check that escalates when it goes stale (by age or by falling too far behind the latest release). Gate any move on your rule-eval suite passing against the new version first. That way you trail the latest release deliberately, for stability, rather than by neglect.
A single dispatcher command behind one cron entry per cadence keeps the operable surface small. The reference schedule:
- nightly: back up + encrypt + push data off-site; push your tooling repos to a remote.
- daily: regenerate the dashboard; check for new agent-tool releases; check the version pin's age.
- weekly: config-drift sweep; usage-telemetry pass; backburner reminders.
- monthly: run the full rule-eval suite.
- a few times a day: a health check that alerts if any scheduled job's heartbeat has gone stale.
- Try to do a forbidden thing (bare push to a protected branch) → a guard blocks it with instructions.
- Commit code with no test evidence → the test gate blocks it.
- Open the dashboard → collectors green, guard-fire counts non-zero.
- Run the rule-eval suite → all pass on your pinned version.
- Push a backup, then download + decrypt it → byte-identical to the original.
- pb-graphiti (memory) — highest leverage, immediately useful.
- The guards (Pattern 2) + the test gate (Pattern 3) — the safety floor.
- Version pinning (Pattern 9) — cheap, prevents a whole class of surprises.
- pb-hcf (orchestration) once you're doing multi-step features.
- The measurement layer + alerting (Patterns 6–7) — once you have enough guards to be worth measuring.
- Off-site backups (Pattern 8) — the day your graph holds anything you'd miss.
Start small. Every rule and guard should come from a real failure you hit — that is what makes them trustworthy, and it's the whole method in one sentence.
By ProxiBlue · proxiblue.com.au. The four plugins referenced are open source under github.com/ProxiBlue. This is the setup companion to an architecture review of the same stack.