mcpField
K
koko

koko

github.com/joelhooksDevelopment6536 installsUpdated 1d ago
Repository

About koko

koko is a development skill for the Koko Elixir project, aimed at developers building or debugging its BEAM-based agent. It documents OTP patterns, architecture decisions, and the project's staged, initially read-only integration with joelclaw.

Key features

  1. 01Guidance for GenServers and supervisors
  2. 02Workload and event-handler implementation
  3. 03Redis bridge constraints and phases
  4. 04ADR checks for architectural changes
  5. 05OTP debugging and shadow comparisons

Use cases

  1. 01Adding a Koko workload or event handler
  2. 02Debugging OTP supervision and crashes
  3. 03Changing Redis event integration
  4. 04Comparing shadow results with TypeScript

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/joelhooks/joelclaw --skill koko

After installing, type/kokoin Claude Code to confirm it loaded.

Details

From the project README

Koko Development

Use this skill when working on the Koko Elixir project — the BEAM co-resident agent alongside joelclaw.

When to Use

  • Building new GenServers, supervisors, or event handlers in Koko
  • Implementing workloads (health pulse, event digest, shadow executor)
  • Wiring Koko to new Redis channels or joelclaw events
  • Debugging OTP supervision trees or process crashes
  • Comparing Koko shadow results against TypeScript equivalents

Triggers: koko, elixir agent, beam, otp, shadow executor, koko workload, koko event, mix

Project Location

  • Repo: ~/Code/joelhooks/koko (github.com/joelhooks/koko)
  • Host: Overlook (Mac Mini M4 Pro), accessible via ssh joel@panda
  • AGENTS.md: Full context in repo root

ADR Awareness

Always check relevant ADRs before implementing. Koko's architecture is ADR-driven.

ADRTitleStatusURL
0114Elixir/BEAM/Jido Migrationproposedjoelclaw.com/adrs/0114-elixir-beam-jido-migration
0115Koko Project Charterproposedjoelclaw.com/adrs/0115-koko-project-charter
0116Redis Bridge Protocolproposedjoelclaw.com/adrs/0116-koko-redis-bridge-protocol
0117First Workloadsproposedjoelclaw.com/adrs/0117-koko-first-workloads
0118Shadow Executorproposedjoelclaw.com/adrs/0118-koko-shadow-executor

Before adding a new workload: Check ADR-0117 for the workload plan and ADR-0118 for shadow execution patterns.

Before changing Redis integration: Check ADR-0116 for the bridge protocol and phase boundaries.

Before any architectural change: Propose or update an ADR in ~/Vault/docs/decisions/.

Key Constraints

  1. Koko is read-only (Phase 1). PubSub observer only. No LPUSH drain, no authoritative writes.
  2. Shadow results only. Write to joelclaw:koko:shadow:<function> in Redis or local files. Never to Typesense, Todoist, gateway, or any production state.
  3. If Koko crashes, nothing breaks. The TypeScript stack doesn't depend on it.
  4. Redis at localhost:6379 — k8s NodePort on Overlook.

Development Commands

# Run
cd ~/Code/joelhooks/koko
mix deps.get
mix run --no-halt

# Test
mix test

# Interactive
iex -S mix
Koko.events_seen()

# Format
mix format

# Remote (from another machine)
ssh joel@panda "cd ~/Code/joelhooks/koko && mix run --no-halt"

OTP Patterns to Follow

  • One GenServer per concern — health checker, event accumulator, shadow runner are separate processes
  • Supervisor strategy: one_for_one unless processes are coupled (then rest_for_one)
  • Pattern match event types in handle_info — don't use if/else chains
  • Use Logger.info("[koko]") prefix for all log output
  • Crash early — let supervisors handle recovery, don't defensive-code around failures

Implementation Phases

Phase 1: Passive Observer (current)
  • Subscribe to joelclaw:gateway:events via PubSub ✅
  • Log and classify events ✅
  • Next: Add health pulse GenServer (Workload 1 from ADR-0117)
Phase 2: Dedicated Channel
  • Create joelclaw:koko:events for claimed work
  • TypeScript fans out to Koko: LPUSH joelclaw:koko:events <payload>
  • Koko writes results to joelclaw:koko:results
Phase 3: Shadow Executor
  • Mirror select Inngest functions as Koko GenServers
  • Same inputs, parallel execution, compare results
  • Shadow log at joelclaw:koko:shadow:<function>
Phase 4: Graduation
  • Koko handles a workload more reliably than TypeScript
  • Survived 30 days without manual intervention
  • DX is enjoyable

Comments

Markdown supported