Parallel agent infrastructure for Claude Code. Modeled after the OS process model, it distributes, monitors, and reaps issues via independent Workers.
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 -->|Agent tool| R[Reviewer<br/>subagent]
R -->|return approved| O
O -->|cleanup + notify| H
| 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 |
| completion record | worker-state.sh (TERMINATED + result:detail) |
| 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 (dual-path: 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 non-TERMINATED state 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.
Claude Code's dynamic /workflows also runs agents in parallel, so the two can look interchangeable. They are not — the boundary rule is: state that must survive the session belongs to cekernel; fan-out that completes within a session belongs to /workflows (in one sentence: cekernel persists, /workflows fans out). If your task is an issue lifecycle that spans CI waits, human review, and retries over hours or days, use cekernel; if it is a wide parallel pass that starts and finishes inside one session (e.g. a migration sweep or a multi-file analysis), use /workflows. See ADR-0015 for the full analysis.
| Axis | cekernel | /workflows |
|---|---|---|
| Use for | Lifecycles that outlive a session (issue → PR → CI → review → merge) | Fan-out that completes within one session |
| Survives the session | Yes — OS processes, files, git worktrees | No — a run dies with its session |
| Time horizon | Hours–days (CI waits, human review, retries) | One session's wall-clock |
| Identity | Issue number = PID; named branches and PRs | Anonymous agent index |
| Trigger | Event-driven (state file, cron/at, human) | Single deterministic run |
.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 a claude --bg background session
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, state, backend, Type)
spawn-worker.sh # Spawn Worker (thin wrapper for spawn.sh --agent worker)
watch-logs.sh # Real-time Worker log monitoring
watch.sh # Monitor process completion (state file + crash detection)
process-status.sh # List active Worker processes
scheduler/
at-backend.sh # At backend adapter (launchd/atd)
at-backends/
atd.sh # Linux/WSL atd backend
launchd.sh # macOS launchd backend (plist + one-shot cleanup)
at.sh # /at command handler (register/list/cancel)
cron-backend.sh # Cron backend adapter (launchd/crontab)
cron-backends/
crontab.sh # Linux/WSL crontab backend
launchd.sh # macOS launchd backend (plist + cron expr parser)
cron.sh # /cron command handler (register/list/cancel)
preflight.sh # Registration preflight checks
registry.sh # Schedule registry CRUD
wrapper.sh # Runner script generator
shared/
backend-adapter.sh # Backend abstraction layer (wezterm/tmux/headless)
backends/
headless.sh # Headless backend implementation
tmux.sh # tmux backend (attach-only visualization pane)
wezterm.sh # WezTerm backend (attach-only visualization pane)
bg-session.sh # Shared claude --bg session core (spawn/liveness/stop)
checkpoint-file.sh # Checkpoint file helpers for suspend/resume
claude-json-helper.sh # ~/.claude.json trust entry read/write helper
claude-bg.sh # Shared claude --bg session helpers (agents --json query, capture)
claude-session-id.sh # Orchestrator Claude Code session ID persistence (orchestrator.claude-session-id)
desktop-notify.sh # OS-native notification helper
issue-lock.sh # Repo × issue lockfile (duplicate Worker prevention)
load-env.sh # Environment profile loader (multi-layer search)
resolve-repo-root.sh # Resolve repository root from any subdirectory
session-id.sh # Session ID generation + IPC directory derivation
task-file.sh # Local task file extraction (session memory: page cache)
transcript-locator.sh # Transcript discovery for post-mortem analysis (ADR-0013)
worker-priority.sh # Worker priority (nice value) management
worker-state.sh # Worker process state management
process/
check-signal.sh # Check for pending signal (Worker-side)
clear-resume-marker.sh # Clear resume marker after successful resume
create-checkpoint.sh # Create checkpoint file for suspend/resume
notify-complete.sh # Process → Orchestrator completion notification
phase-transition.sh # Atomic phase boundary: signal check + state write
worker-state-write.sh # Write Worker state from Worker side
skills/
at/
SKILL.md # /at skill — one-shot schedule management
cron/
SKILL.md # /cron skill — recurring schedule management
dispatch/
SKILL.md # /dispatch skill — batch-process ready-labeled issues
orchctl/
SKILL.md # /orchctl skill — Worker control interface (orchctl.sh)
orchestrate/
SKILL.md # /orchestrate skill — issue delegation
postmortem/
SKILL.md # /postmortem skill — transcript-based post-mortem analysis
probe/
SKILL.md # /probe skill — namespace detection diagnostic
references/
namespace-detection.md # Canonical namespace detection logic
postmortem-patterns.md # Post-mortem detection patterns (ADR-0013)
triage.md # Canonical issue triage protocol
setup/
SKILL.md # /setup skill — interactive runtime initialization
unix-architect/
SKILL.md # /unix-architect skill — ADR authoring and review
tests/
ctl/*.bats # Control script tests (orchctl, spawn-orchestrator)
helpers/
assertions.bash # Assertion helpers (bats)
orchestrator/*.bats # Orchestrator script tests
scheduler/*.bats # Scheduler script tests
shared/*.bats # Shared helper tests
process/*.bats # Process script tests
| Tool | Purpose | Required |
|---|---|---|
| Claude Code | Runtime for Worker agents | Yes |
| jq | ~/.claude.json trust entry manipulation, JSON parsing | Yes |
| gh | Issue retrieval, PR creation/merge | Yes |
| alerter | macOS desktop notifications (richer than osascript) | No |
| WezTerm | Worker window launch/management (wezterm backend) | No* |
| tmux | Worker pane management (tmux backend) | No* |
| git | Worktree creation/management | Yes |
| bats-core | Test framework (development only) — brew install bats-core; CI pins v1.13.0 | No (dev) |
* One backend is required: headless (default), WezTerm, or tmux. Set CEKERNEL_BACKEND env var to select. Headless requires no terminal.
cekernel is primarily designed for monorepo structures. While it may work with other setups, monorepo is the tested and expected configuration.
Recommended for target repositories:
- CI should be set up (unit tests, integration tests, e2e tests). Workers rely on CI to verify their changes.
- CD (continuous deployment) is optional — cekernel only handles the implement → PR → CI → review → merge lifecycle.
Backend support:
| Backend | Status |
|---|---|
| WezTerm | Stable |
| Headless | Stable |
| tmux | Stable |
Scheduler backend support:
| Backend | Platform | Status |
|---|---|---|
| launchd | macOS | Verified — /cron and /at tested on macOS with real launchd execution |
| crontab | Linux/WSL | Untested — unit tests pass, but no live execution verification yet |
| atd | Linux/WSL | Untested — unit tests pass, but no live execution verification yet |
Cross-repository issues: If you manage issues in a separate meta-repository, run /orchestrate from the implementation repository (worktrees, branches, and PRs are created there) and pass the full path or URL of the issue:
/cekernel:orchestrate /org/planning/issues/123
# or
/cekernel:orchestrate https://github.com/org/planning/issues/123The issue repository is extracted from the reference and propagated via spawn-worker.sh --repo org/planning, so the Worker reads and comments on the correct issue while implementing in the current repository.
If you use --permission-mode auto, declare the meta-repository as a trusted external dependency so the auto-mode classifier does not block gh writes targeting it:
Note: Cross-repository issue resolution has not been extensively tested. Please open an issue if you encounter any problems.
Issues and feedback are always welcome.
Install from the Claude Code plugin marketplace:
# 1. Add marketplace
/plugin marketplace add clonable-eden/plugins
# 2. Install cekernel plugin
/plugin install cekernel@clonable-eden-pluginsSet up the runtime state directory (one-time, no sudo required):
/cekernel:setupThis interactively creates the runtime directory structure (ipc/, locks/, logs/, runners/, schedules.json) and writes a user profile to ~/.config/cekernel/envs/default.env. Required for /cron, /at skills and IPC.
# 1. Update marketplace repository
/plugin marketplace update
# 2. Update plugin
/plugin update
# 3. Restart Claude Code to applyNote:
/plugin updatealone may not update the marketplace local clone. Always run/plugin marketplace updatefirst.
Create a
.gitignoreissue — Add.worktreesand.cekernel*to your repository's.gitignore. Create a GitHub issue for this task.Let cekernel close it — Start Claude Code and run:
/cekernel:orchestrate <issue-number>
Use
--envto select your preferred backend (e.g.,--env headless). This will spawn a Worker that implements the change, creates a PR, and verifies CI.
This gives you a quick end-to-end verification that cekernel is working correctly in your repository.
cekernel is configured via CEKERNEL_* environment variables. See envs/README.md for the full catalog.
Named profiles (.env files) provide coherent sets of defaults for common scenarios:
| Profile | Use case |
|---|---|
default.env | Default settings (headless, 5 processes) |
wezterm.env | WezTerm backend |
tmux.env | tmux backend |
headless.env | Terminal-free execution (CI, cron) |
Select a profile via CEKERNEL_ENV:
export CEKERNEL_ENV=headless # default: "default"Profiles are loaded with multi-layer priority (lowest → highest):
- Script defaults (
${VAR:-default}) - Plugin profile (
envs/${CEKERNEL_ENV}.env) - Project override (
.cekernel/envs/${CEKERNEL_ENV}.env) - User profile (
~/.config/cekernel/envs/${CEKERNEL_ENV}.env) - Explicit environment variables
Projects can override plugin defaults by placing .env files in .cekernel/envs/. These survive /plugin update. See ADR-0006 for design details.
If using the WezTerm backend, see config/README.md for plugin setup.
| Skill | Purpose |
|---|---|
/setup | Interactive runtime setup (first-time) |
/orchestrate | Issue delegation and parallel processing |
/dispatch | Batch-process ready-labeled issues |
/orchctl | Process control and monitoring |
/cron | Recurring schedule management (launchd/crontab) |
/at | One-shot schedule management (launchd/atd) |
/postmortem | Transcript-based post-mortem analysis |
/unix-architect | ADR authoring and architectural review |
In plugin mode, prefix with cekernel: (e.g., /cekernel:orchestrate). See each skill's SKILL.md for details.
For versioning and release procedures, see the CLAUDE.md Versioning section.
Worker / Orchestrator agent definitions have tools configured, granting access to:
| Tool | Purpose |
|---|---|
Read | File reading |
Edit | File editing |
Write | File writing |
Bash | All Bash commands including git, gh, shell scripts |
spawn-worker.sh launches Workers with claude --agent ${CEKERNEL_AGENT_WORKER}.
The agent name is resolved dynamically: cekernel:worker in plugin mode, worker in local mode.
The --agent flag applies the agent definition's tools.
Tool auto-approval (without permission prompts) is delegated to the target repository's .claude/settings.json.
cekernel does not hardcode tool permissions.
Note that agents and skills use different frontmatter key names:
- Agents (
agents/*.md):tools - Skills (
skills/*/SKILL.md):allowed-tools
Repositories using cekernel need to configure tool permissions in .claude/settings.json.
Workers automatically read this configuration file within the worktree and operate without permission prompts.
{
"permissions": {
"allow": [
"Bash",
"Edit",
"Write",
"Read"
],
"deny": [
"Bash(sudo *)",
"Bash(rm -rf /)",
"Bash(rm -rf /*)"
]
}
}List tools that Workers should use in allow, and explicitly deny dangerous commands in deny.
Each repository can freely customize allowed tools and commands.
cekernel defines only the lifecycle (spawn → PR → CI → review → merge → notify → cleanup).
When Workers actually write code, they fully follow the target repository's CLAUDE.md and project conventions. If cekernel rules conflict with the target repository's conventions, the target repository always takes precedence.
cekernel authority Target repository authority
───────────────── ──────────────────────────
When to create PR How to implement
When to verify CI Coding conventions
When to merge Test policies / lint rules
When to notify commit message format
PR template
Merge strategy
Branch naming conventions
Issue link syntax
If the target repository has no CLAUDE.md, Workers infer conventions from existing code, commits, and PRs.