cekernel

cekernel

Parallel agent infrastructure for Claude Code. Modeled after the OS process model, it distributes, monitors, and reaps issues via independent Workers.

Concept

graph LR
    H[Human / Scheduler] -->|/orchestrate<br/>/dispatch| O[Orchestrator<br/>main working tree]
    O -->|spawn-worker.sh| W[Worker<br/>git worktree]
    W -->|notify ci-passed| O
    O -->|spawn-reviewer.sh| R[Reviewer<br/>same worktree]
    R -->|notify approved| O
    O -->|cleanup + notify| H

OS Analogy

OS	kernel
init / scheduler	Orchestrator
process	Worker
fork + exec	spawn-worker.sh
address space	git worktree
process states	worker-state.sh (NEW/RUNNING/WAITING/SUSPENDED/TERMINATED)
nice / priority	--priority flag + worker-priority.sh
IPC pipe	named pipe (FIFO)
IPC namespace	session (CEKERNEL_SESSION_ID)
SIGTERM	send-signal.sh TERM
SIGSTOP / SIGCONT	send-signal.sh SUSPEND / spawn-worker.sh --resume
SIGKILL	cleanup-worktree.sh --force
SIGALRM / watchdog	CEKERNEL_WORKER_TIMEOUT + escalation (TERM → grace → force-kill)
waitpid	watch.sh (triple-path: FIFO + state file + crash detection)
zombie reaping	health-check.sh + cleanup-worktree.sh
core dump / checkpoint	.cekernel-checkpoint.md (suspend/resume)
systemctl	orchctl.sh / /orchctl skill
device drivers	backend-adapter.sh (wezterm/tmux/headless)
/etc/default/	load-env.sh + env profiles
PID	issue number
/var/log/	${CEKERNEL_IPC_DIR}/logs/
syslog	Lifecycle event log writes
tail -f / journalctl	watch-logs.sh
log rotation	Logs deleted by cleanup-worktree.sh
page cache	.cekernel-task.md (issue data pre-extracted at spawn)
ulimit -u (max processes)	CEKERNEL_MAX_ORCH_CHILDREN
ps aux	process-status.sh
process scheduler	Orchestrator queuing logic (priority queue + preemption)
semaphore	Concurrency guard via FIFO count
flock / mutex	issue-lock.sh (repo × issue lockfile)
cron / systemd timer	/cron skill + OS-native schedulers (launchd/crontab)
at (one-shot job)	/at skill + OS-native schedulers (launchd/atd)
/var/	~/.local/var/cekernel/ (runtime state)

For details on logging, IPC, and resource governance, see internals.md.

Structure

.claude-plugin/
  plugin.json              # Plugin manifest
.github/
  CODEOWNERS               # Code owners definition
  workflows/
    cekernel-tests.yml     # CI test workflow
    auto-approve-renovate.yml # Auto-approve Renovate PRs
    plugin-release-tag.yml # Release tag automation
agents/
  orchestrator.md          # Orchestrator protocol definition
  probe.md                 # Namespace detection diagnostic agent
  reviewer.md              # Reviewer protocol definition (Orchestrator subagent)
  worker.md                # Worker protocol definition
config/
  Makefile                 # WezTerm plugin install/uninstall
  README.md                # WezTerm backend setup guide
  wezterm.cekernel.lua     # WezTerm plugin (Worker layout via user-var event)
docs/
  adr/                     # Architecture Decision Records
  claude-code-constraints.md  # Claude Code platform constraints reference
  internals.md             # Logging, IPC, resource governance details
  tdd.md                   # Test-driven development guide
  unix-philosophy.md       # UNIX philosophy reference
envs/
  default.env              # Default profile (headless, 5 processes)
  headless.env             # Headless profile (headless, 5 workers)
  tmux.env                 # tmux backend profile
  wezterm.env              # WezTerm backend profile
  README.md                # Environment variable catalog
RELEASE_NOTES.md           # Structured release notes
scripts/
  ctl/
    orchctl.sh             # Worker control interface (systemctl for cekernel)
    spawn-orchestrator.sh  # Spawn Orchestrator as independent OS process
  orchestrator/
    cleanup-worktree.sh    # Remove worktree + branch + logs
    health-check.sh        # Detect zombie Workers
    send-signal.sh         # Send signal (TERM/SUSPEND) to a running Worker
    spawn.sh               # Common process spawning logic (concurrency guard, FIFO, state, backend, Type)
    spawn-worker.sh        # Spawn Worker (thin wrapper for spawn.sh --agent worker)
    spawn-reviewer.sh      # Spawn Reviewer (wrapper for spawn.sh --agent reviewer)
    watch-logs.sh          # Real-time Worker log monitoring
    watch.sh               # Monitor process completion (FIFO + state file + crash detection)
    process-status.sh       # List active processes (Workers and Reviewers)
  scheduler/
    at-backend.sh          # At backend adapter (launchd/atd)
    at-backends/
      atd.sh               # Linux/WSL atd backend