cekernel

KO | EN

gitlite — search

#javascript #react #llm #android #rust #deep-learning #java #cli #vue #awesome-list #security #mcp #ios #openai

(★ 15)

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

cekernel Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# cekernel

![cekernel](https://raw.githubusercontent.com/clonable-eden/cekernel/main/social-preview.png)

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

## Concept

### 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` |
| 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](./docs/internals.md).

### cekernel vs `/workflows`

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](./docs/adr/0015-workflows-boundary.md) 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 |

## 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 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
```

## Dependencies

| Tool | Purpose | Required |
|------|---------|----------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Runtime for Worker agents | Yes |
| [jq](https://jqlang.github.io/jq/) | `~/.claude.json` trust entry manipulation, JSON parsing | Yes |
| [gh](https://cli.github.com/) | Issue retrieval, PR creation/merge | Yes |
| [alerter](https://github.com/vjeantet/alerter) | macOS desktop notifications (richer than osascript) | No |
| [WezTerm](https://wezfurlong.org/wezterm/) | Worker window launch/management (wezterm backend) | No* |
| [tmux](https://github.com/tmux/tmux) | Worker pane management (tmux backend) | No* |
| git | Worktree creation/management | Yes |
| [bats-core](https://bats-core.readthedocs.io/) | 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.

## How to Use

### Prerequisites & Notes

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:

```bash
/cekernel:orchestrate /org/planning/issues/123
# or
/cekernel:orchestrate https://github.com/org/planning/issues/123
```

The 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:

```jsonc
// .claude/settings.local.json
{
  "autoMode": {
    "environment": "Trust this working repo and the meta-repo at org/planning. gh commands targeting either repo are expected operations."
  }
}
```

> **Note**: Cross-repository issue resolution has not been extensively tested. Please [open an issue](https://github.com/clonable-eden/cekernel/issues/new) if you encounter any problems.

Issues and feedback are always welcome.

### Install

Install from the Claude Code plugin marketplace:

```bash
# 1. Add marketplace
/plugin marketplace add clonable-eden/plugins

# 2. Install cekernel plugin
/plugin install cekernel@clonable-eden-plugins
```

### Runtime Setup

Set up the runtime state directory (one-time, no `sudo` required):

```bash
/cekernel:setup
```

This 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.

### Update

```bash
# 1. Update marketplace repository
/plugin marketplace update

# 2. Update plugin
/plugin update

# 3. Restart Claude Code to apply
```

> **Note**: `/plugin update` alone may not update the marketplace local clone.
> Always run `/plugin marketplace update` first.

### First Steps

1. **Create a `.gitignore` issue** — Add `.worktrees` and `.cekernel*` to your repository's `.gitignore`. Create a GitHub issue for this task.

2. **Let cekernel close it** — Start Claude Code and run:

```bash
   /cekernel:orchestrate <issue-number>
   ```

Use `--env` to 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.

## Configuration

cekernel is configured via `CEKERNEL_*` environment variables. See [`envs/README.md`](./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`:

```bash
export CEKERNEL_ENV=headless   # default: "default"
```

Profiles are loaded with multi-layer priority (lowest → highest):

1. Script defaults (`${VAR:-default}`)
2. Plugin profile (`envs/${CEKERNEL_ENV}.env`)
3. Project override (`.cekernel/envs/${CEKERNEL_ENV}.env`)
4. User profile (`~/.config/cekernel/envs/${CEKERNEL_ENV}.env`)
5. Explicit environment variables

Projects can override plugin defaults by placing `.env` files in `.cekernel/envs/`. These survive `/plugin update`. See [ADR-0006](./docs/adr/0006-env-var-catalog-and-profiles.md) for design details.

If using the WezTerm backend, see [`config/README.md`](./config/README.md) for plugin setup.

## Usage

| 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](./CLAUDE.md#versioning).

## Worker Permissions

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`

## Project Configuration

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.

```json
{
  "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.

## Constraint: Separation of Authority

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.

cekernel

cekernel Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

cekernel

cekernel Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README