apoc
apoc (apocalypse) is a local process and execution control plane for LLMs. It replaces shell-shaped ps, PID bookkeeping, background-job glue, and one-off supervisors with typed tools, exact process identities, durable execution state, resource ownership, and concurrent JavaScript orchestration.
apoc is macOS-first. It acts with the authority of the user who starts it. There are no confirmation prompts, protected-target lists, approval pauses, or embedded model calls. Agents are expected to reason about the truthful destructive and open-world metadata exposed by the tool graph.
Install
apoc skill install embeds the operator contract shipped with this binary, writes its canonical managed copy to ~/.agents/skills/apoc, and links the Codex and Claude skill roots to it. Re-run the command after upgrading. Use apoc skill status to verify every root.
Every command is available through the CLI, MCP, and Code Mode typed command graph. Output supports TOON, JSON, YAML, Markdown, and JSONL.
apoc has no product telemetry, account service, update checker, or automatic network calls. State and execution data remain on the machine. Network access occurs only when the user explicitly configures and invokes an HTTP, MCP, or OpenAPI provider.
Each release includes its complete MIT-licensed source in the crates.io package. Development happens in a private repository, and there is no public issue tracker or support channel.
Process intelligence
A selector is resolved from a fresh native snapshot before every mutation. The resulting identity is BOOT_ID:PID@STARTED_AT_NS, so PID reuse cannot redirect an operation.
Supported selectors are pid:, name:, match: regular expressions, pgid:, port: with optional /tcp or /udp, and all. A bare integer is a PID.
Structured queries combine native process fields, regular expressions, socket ownership, and recorded apoc ownership:
Recorded relationships power causal questions without invented explanations:
Mutations accept a caller idempotency key. Repeating the key returns the original receipt without another OS call. Empty selections fail unless --allow-empty is explicit.
Durable executions
execution is the only public lifecycle abstraction. Direct argv is the default; repeat --arg to preserve boundaries and use --shell only for an intentional /bin/zsh -lc program.
An execution records its versioned specification, repository and worktree state, attempts, exact process identities, output paths, parent execution, session, lease, progress time, and terminal result. An omitted working directory inherits the invoking process's current directory, including through Code Mode; a relative --cwd resolves from that directory. apoc validates and canonicalizes the directory before accepting the execution.
execution command, batch, and pipeline return { execution, replayed, logs }. Their process exit status matches the managed result, while stdout still contains the structured response. logs contains bounded 32 KiB stdout and stderr tails plus explicit truncation flags. Repeating an --idempotency-key with the same normalized request returns the original execution; reusing it for a different request fails before launching anything. execution list returns compact summaries in bounded cursor pages; use execution get for the full record.
Retries and wall-time deadlines are finite. Secret environment values can be referenced as NAME=env:VARIABLE; apoc persists the reference but resolves the value only at launch.
Command groups
Use one batch call when an agent already knows several independent commands. apoc bounds concurrency, records each command as a child execution, and returns a compact failure-oriented parent result. max_parallel defaults to the host's logical CPU count and is limited to 256.
Use a pipeline when stdout must flow between exact-argv stages. apoc creates native operating-system pipes, launches every stage before waiting, keeps stderr separate per child, captures final stdout on the parent, and enables pipefail by default.
The same typed graph exposes structured apoc.execution_batch({...}) and apoc.execution_pipeline({...}) calls in Code Mode. This is the fast path for LLM-generated command sets: one host dispatch replaces a large Promise.all fan-out while preserving child identities, logs, cancellation, and durable results.
Sessions, leases, and reservations
A session groups one agent's work under a heartbeat. Its root lease is session/SESSION_ID. When the heartbeat expires, the daemon releases the lease, cancels session-owned executions, and releases its reservations.
Reservations provide atomic apoc-local ownership for ports, paths, exact processes, devices, and custom keys. reservation wait waits up to 30 seconds. Port reservations also report current native socket conflicts.
Compose concurrent work in JavaScript
Code Mode runs generated JavaScript in isolated QuickJS actors. A bounded pool defaults to min(logical CPUs, 8); set APOC_CODE_WORKERS to override it. Separate programs occupy separate actors, and each program can issue independent host calls concurrently with Promise.all.
Code Mode persists source, immutable capabilities, ordered calls, replay state, result, events, and oversized artifacts. Mutations are logged before replay can pass them and are not repeated. Socket and process I/O runs outside QuickJS on the shared host runtime.
Once apoc accepts an execution, synchronous tools return { execution, replayed, logs }. Launch failures, nonzero exits, timeouts, and cancellations therefore resolve with their terminal execution.status and structured execution.result; they do not reject a surrounding Promise.all. A tool call rejects only when apoc cannot accept the request or determine its result. To stop a JavaScript workflow on an unsuccessful execution, inspect execution.status and throw explicitly, or use execution_batch with fail_fast when composing a command batch.
Saved recipes are JavaScript programs with optional JSON Schema input. MCP and OpenAPI connectors become new Code Mode namespaces after registration.
Capability providers and one-shot actions
Providers extend the same graph through Streamable HTTP MCP, supervised MCP
stdio, or OpenAPI. Provider names become JavaScript namespaces. Configuration
may contain literal headers and environment values; secrets use
PROVIDER:REFERENCE and are resolved only when a client connects or child
starts.
action run and action start generate a safely quoted JavaScript call and use
the durable Code Mode lifecycle. Independent resources run concurrently. Calls
with the same stable id, resource_id, pid, path, or window_id are
ordered; mutations without a stable identity are conservatively ordered across
their provider. Every provider mutation persists an intent before dispatch and
an applied, failed, or unknown receipt afterward.
The built-in command graph can itself serve as MCP stdio with apoc --mcp.
Resolve the installed binary with command -v apoc, then register that absolute path with the agent host. For Codex, use codex mcp add apoc -- ABSOLUTE_APOC_PATH --mcp.
The standalone macOS provider covers native app,
window, Accessibility, input, pasteboard, capture, Shortcuts, URL, AppleScript,
and JXA operations without adding platform dependencies to apoc core.
Causal journal
apoc appends compact, monotonically ordered lifecycle events. Large repeated snapshots are content-addressed and deduplicated. Event metadata survives payload pruning.
Every observed, launched, waited-on, or controlled process is recorded. Mutation intent is durable before the operating-system call; results follow it.
Daemon and state
Commands that need durable ownership auto-start one detached daemon per user.
apoc version reports the installed client and public execution schema. daemon status also reports the running daemon build and schema; null version fields identify a legacy daemon that has not yet been restarted.
| State | Default macOS path |
|---|---|
| Database | ~/Library/Application Support/apoc/apoc.sqlite3 |
| Execution logs | ~/Library/Application Support/apoc/runs/ |
| Daemon log | ~/Library/Application Support/apoc/daemon.log |
| Socket | /tmp/apoc-$UID/apoc.sock |
Set both APOC_HOME and APOC_RUNTIME_DIR for an isolated instance. apoc backs up a non-empty database before each schema migration. The runtime directory is mode 0700; the socket is mode 0600.
See the packaged architecture source for runtime and durability boundaries.