About

Imported from joelhooks/joelclaw (skills/koko/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill koko. Copyright stays with the author.

Koko Development

Name: koko
Author: joelhooks

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.

ADR	Title	Status	URL
0114	Elixir/BEAM/Jido Migration	proposed	joelclaw.com/adrs/0114-elixir-beam-jido-migration
0115	Koko Project Charter	proposed	joelclaw.com/adrs/0115-koko-project-charter
0116	Redis Bridge Protocol	proposed	joelclaw.com/adrs/0116-koko-redis-bridge-protocol
0117	First Workloads	proposed	joelclaw.com/adrs/0117-koko-first-workloads
0118	Shadow Executor	proposed	joelclaw.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

Koko is read-only (Phase 1). PubSub observer only. No LPUSH drain, no authoritative writes.
Shadow results only. Write to joelclaw:koko:shadow:<function> in Redis or local files. Never to Typesense, Todoist, gateway, or any production state.
If Koko crashes, nothing breaks. The TypeScript stack doesn't depend on it.
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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/joelhooks-joelclaw-koko/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

joelhooks-joelclaw-koko.ocm.jsonjson

{
  "ocm": "1",
  "id": "joelhooks-joelclaw-koko",
  "kind": "skill",
  "name": "koko",
  "description": "Develop and extend Koko — the Elixir/OTP agent living alongside joelclaw. Covers OTP patterns, Redis bridge protocol, shadow execution, and workload implementation.",
  "publisher": "joelhooks",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "elixir",
      "beam",
      "otp",
      "koko",
      "agent",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Develop and extend Koko — the Elixir/OTP agent living alongside joelclaw. Covers OTP patterns, Redis bridge protocol, shadow execution, and workload implementation."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/joelhooks/joelclaw",
      "path": "skills/koko/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/joelhooks/joelclaw/blob/HEAD/skills/koko/SKILL.md",
      "key": "joelhooks/joelclaw/skills/koko/SKILL.md"
    }
  },
  "instructions": "# Koko Development\n\nUse this skill when working on the Koko Elixir project — the BEAM co-resident agent alongside joelclaw.\n\n## When to Use\n\n- Building new GenServers, supervisors, or event handlers in Koko\n- Implementing workloads (health pulse, event digest, shadow executor)\n- Wiring Koko to new Redis channels or joelclaw events\n- Debugging OTP supervision trees or process crashes\n- Comparing Koko shadow results against TypeScript equivalents\n\nTriggers: `koko`, `elixir agent`, `beam`, `otp`, `shadow executor`, `koko workload`, `koko event`, `mix`\n\n## Project Location\n\n- **Repo**: `~/Code/joe",
  "cost": {
    "context_tokens": 976
  }
}

Fetch it by URL: GET /api/v1/registry/joelhooks-joelclaw-koko/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.