Architecture Decision Records

Vault CLI & Agent Tool Access

Vault File Access from Voice Mode

Telnyx Voice & SMS Notification Channel

Opus Token Reduction Across joelclaw

Memory System — Next Phase

Notification Triage Classes

Telegram Rich Notifications with Inline Keyboards

Gateway Proactive Telegram Notifications

Memory Proposal Auto-Triage Pipeline

Integrate Community Skill Patterns

Inngest Monitor Pi Extension

Friction auto-fix — bias towards action

ADR-0021 Phase 4 (Friction) detects recurring friction patterns from Qdrant observations and creates Todoist tasks for Joel to review. The pipeline works — 10 patterns detected on first successful …

Evaluate Elixir/BEAM as joelclaw Backbone

Client-Side Search with Pagefind

joelclaw.com has ~80 pages of content (10 articles, 63 ADRs, 7 discoveries) with no search. Users can only browse by section (Writing, Cool, ADRs, Network) or scroll through listings. As the site g…

Heartbeat-Driven Task Triage

pi-tools Enhancement Cycle — Commit Tool, Web Extractors, MCQ

After evaluating oh-my-pi (`can1357/oh-my-pi`) as a potential replacement for stock pi, we decided to stay on stock pi and cherry-pick patterns into pi-tools (see ADR-0059 for LSP, ADR-0060 for swa…

Inngest-Backed Swarm/DAG Multi-Agent Orchestration

`ralph-loop` executes PRD stories **sequentially** — one codex session per story, linear chain. This works for implementation loops but can't express:

Multi-Language LSP Extension for pi-tools

The current `ts-check` extension in pi-tools is unreliable. It spawns a tsgo LSP process per project root but frequently fails to return useful diagnostics, hover info times out, and the JSON-RPC l…

58. Streamed NDJSON Protocol for Agent-First CLIs

Skill Pack Distribution — Install from Source

Personal Relationship Management — People as First-Class Entities

Granola Meeting Intelligence Pipeline

joelclaw Native App — iPhone, Watch, CarPlay

Event-emitter prompts and the Agency triage principle

The gateway extension delivers Inngest events to the pi session as user messages. Previously, ALL events were wrapped in a generic template:

Email Port — Hexagonal Architecture with Dual Adapters

Tailscale Funnel as Public Ingress for Webhooks

Gateway session resume via fixed file path and codex model pinning

Two operational issues were discovered simultaneously:

Gateway TUI via WebSocket

Webhook Gateway for External Service Integration

Todoist as Async Conversation Channel

TypeScript Things CLI via joelclaw Tasks Subcommand

Task Management via Ports and Adapters

Private-First PDS with Bento Bridge

Agent Voice Conversations via Self-Hosted LiveKit

Telegram Rich Replies, Outbound Media, and Agent Voice

First-Class Media Handling from Connected Channels

Google Workspace Access via gogcli

Self-host Convex as the real-time data layer for joelclaw.com

joelclaw.com is a statically-generated Next.js 16 site with MDX content. It has no database, no auth, no real-time features. Joel wants to add:

Embed pi as a library in a joelclaw gateway daemon

The current central gateway session (ADR-0036) runs pi inside tmux, managed by launchd. A gateway extension injects events via `sendUserMessage()`. This works for Redis-based notifications but has …

Layered watchdog for gateway heartbeat failure detection

The central gateway session (ADR-0036) receives heartbeats from an Inngest cron every 15 minutes. But if Inngest itself goes down — the server crashes, the worker dies, Redis becomes unreachable, o…

Central + satellite session routing for gateway events

ADR-0018 established a Redis event bridge between Inngest functions and pi sessions. The initial implementation pushed every event to a single shared `joelclaw:events:main` list. This worked for on…

Flux Operator for GitOps cluster management

Cluster state is currently applied manually via `kubectl apply -f`. The k8s manifests live in `~/Code/joelhooks/joelclaw/k8s/` and are applied by hand or by agents running kubectl commands. There's…

VictoriaMetrics + Grafana monitoring stack for Kubernetes

The Talos cluster has no monitoring. We observe the system via `kubectl get pods`, `talosctl dashboard`, and application logs. There's no metrics collection, no dashboards, no alerting.

Kubernetes persistent storage: Ceph Rook vs SeaweedFS vs local-path

The Talos cluster currently uses **local-path-provisioner** for PVCs. This was added manually (ADR-0029) because Talos doesn't bundle a storage provisioner. It works: Redis, Qdrant, and Inngest all…

Adopt Cilium Gateway API instead of Ingress

The cluster currently uses NodePort services directly — no Ingress controller at all. If/when we need proper HTTP routing (TLS termination, host-based routing, path routing), the traditional answer…

Replace Flannel + kube-proxy with Cilium

The Talos cluster (`joelclaw`) currently runs with the default CNI: **Flannel** + **kube-proxy**. This is the simplest path — Talos bundles Flannel out of the box and it works with zero config.

Replace Docker Desktop with Colima + Talos for container runtime

`panda` (Mac Mini M4 Pro, 64 GB) runs 24/7 as a headless server managed via Tailscale SSH. The container runtime powers the k3d cluster (`joelclaw`), which runs Redis, Qdrant, and Inngest as Kubern…

Align Inngest Rig with SDK Best Practices

Video Content Pipeline Expansion — Clip Segmentation + Content Repurposing

joelclaw's video pipeline currently handles **ingest only**: download → transcribe → enrich vault note. The output is a single vault note with a wall-of-text transcript and an AI-generated summary.…

Background agents: async task dispatch via Inngest with file inbox notifications

Network architecture: start with what works, grow as needed

Taxonomy-enhanced session search with SKOS concept layer

590 agent sessions were generated in 48 hours (37 Pi, 381 Claude Code, 172 Codex). These contain every decision, debugging insight, architecture discussion, and configuration change that happened o…

Docker Sandbox for Agent Loops

Agent loop iterations (IMPLEMENTOR, TEST-WRITER) currently spawn `codex exec` and `claude -p` directly on the host machine via `Bun.spawn()`. This means:

Adopt comprehensive agent memory system

Agents on this system lose conversational nuance between sessions. Memory is the critical missing capability — without it, every session starts from zero, hard-won debugging insights evaporate, use…

Rename events from imperative commands to past-tense notifications

The system-bus event names are a mix of two styles:

Adopt pi-native gateway pattern with Redis event bridge for system orchestration

ADR-0010 established the need for a central system loop gateway — an autonomous orchestrator that runs SENSE→ORIENT→DECIDE→ACT→LEARN and chose a hybrid event-driven + cron heartbeat approach. It le…

Parallel Story and Subtask Execution in Agent Loops

The current agent loop (ADR-0015) is rigidly sequential: one story at a time, one agent per step, pipeline flow. The planner picks the next unpassed story, the chain runs plan→test→implement→review…

Idempotency Guards for Loop Event Chain

The agent loop event chain (ADR-0015) has no protection against parallel execution. Duplicate `agent/loop.start` events — from accidental double-fires, CLI retries, or stale Inngest replays — creat…

Loop architecture: TDD flow with separated roles

The current agent loop (ADR-0005) has a backwards flow: implement → write tests → check results. This causes systemic failures:

LLM-powered judge evaluation

The judge function (ADR-0005) makes pass/fail decisions based solely on whether typecheck + lint + tests succeed. It has no understanding of whether the implementation actually satisfies the accept…

Planner generates PRD from goal

The agent loop requires a hand-crafted `prd.json` before it can start. Writing PRDs is the bottleneck — each one requires understanding the codebase, scoping stories to be small enough for a single…

Redis-Backed PRD State for Agent Loops

The agent loop pipeline (ADR-0005) runs a PLANNER → IMPLEMENTOR → REVIEWER → JUDGE cycle across stories defined in a PRD. Originally, loop state — which stories have passed, which are being retried…

9. Rename `igs` CLI to `joelclaw`

Add post-loop retrospective for skill evolution and memory ingestion

ADR-0005 established the durable PLANNER → IMPLEMENTOR → REVIEWER → JUDGE loop. ADR-0007 improved loop execution quality (Docker isolation, duration tracking, stricter controls). The system can now…

Adopt Inngest multi-agent pipeline for durable autonomous coding loops

joelclaw needs the ability to execute long-running autonomous coding workloads — send an event, go AFK, wake up to stacked PRs with every iteration traceable. No durable autonomous coding loop exis…

0004 — AT Protocol as Bedrock

Build joelclaw instead of deploying OpenClaw

ADR-0002 assumed OpenClaw would be the orchestration layer for the personal assistant system. After 6 sessions of infrastructure work, the system has evolved beyond what OpenClaw provides in severa…

Adopt architecture decision records

Architecture decisions in this project are made implicitly — through code, conversations, and tribal knowledge. When a new contributor (human or AI agent) joins the codebase, there is no record of …