apoc 0.3.0

Agentic process control for LLMs
Documentation

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

cargo install apoc --version 0.3.0
apoc skill install
apoc version

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.

apoc process list --selector match:node --sort memory --limit 20
apoc process select port:5173/tcp
apoc process tree name:vite
apoc process files pid:4242
apoc process sockets --listening --protocol tcp
apoc process probe pid:4242
apoc process sample --selector match:node --count 5 --interval-ms 250

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:

apoc process query '{
  "all":[{"command_regex":"node|bun"}],
  "any":[{"port":5173},{"actor":"release-agent"}],
  "not":[{"name":"Code Helper"}],
  "sort":"memory",
  "limit":20
}'

Recorded relationships power causal questions without invented explanations:

apoc process why pid:4242
apoc process impact pid:4242
apoc process owner pid:4242
apoc process related pid:4242
apoc process changed pid:4242
apoc process context pid:4242 --events 50

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.

apoc process signal name:vite TERM --idempotency-key deploy-91/term
apoc process stop port:5173/tcp --timeout-ms 2000 --force \
  --idempotency-key deploy-91/free-port
apoc process pause pgid:4242 --idempotency-key debug-7/pause
apoc process resume pgid:4242 --idempotency-key debug-7/resume

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.

apoc execution command /usr/bin/printf \
  --arg '%s\\n' \
  --arg apocalypse \
  --purpose 'verify formatted output' \
  --idempotency-key release-91/verify-output \
  --label workflow=release

apoc execution start /usr/bin/python3 \
  --arg -m \
  --arg http.server \
  --arg 8000 \
  --name docs \
  --purpose 'serve documentation for review' \
  --max-attempts 3 \
  --retry-backoff-ms 500 \
  --timeout-ms 300000

apoc execution list --limit 20
apoc execution list --limit 20 --cursor NEXT_CURSOR --status completed
apoc execution get EXECUTION_ID
apoc execution attach EXECUTION_ID --tail-bytes 65536
apoc execution input EXECUTION_ID $'status\\n'
apoc execution signal EXECUTION_ID HUP
apoc execution wait EXECUTION_ID --timeout-ms 30000
apoc execution cancel EXECUTION_ID --timeout-ms 2000

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.

{
  "commands": [
    { "id": "unit", "argv": ["cargo", "test", "--lib"] },
    { "id": "types", "argv": ["cargo", "check", "--all-targets"] },
    { "id": "format", "argv": ["cargo", "fmt", "--", "--check"] }
  ],
  "max_parallel": 3,
  "fail_fast": true
}
apoc execution batch --file commands.json --idempotency-key verify-91/batch

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.

[
  { "id": "produce", "argv": ["/usr/bin/printf", "apocalypse"] },
  { "id": "uppercase", "argv": ["/usr/bin/tr", "[:lower:]", "[:upper:]"] }
]
apoc execution pipeline --file pipeline.json --idempotency-key release-91/pipeline

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.

apoc session open --actor release-agent --ttl-ms 60000
apoc session heartbeat SESSION_ID --ttl-ms 60000

apoc reservation acquire port tcp/5173 session/SESSION_ID
apoc reservation acquire path /absolute/worktree session/SESSION_ID

apoc execution start cargo \
  --arg test \
  --owner session \
  --session SESSION_ID

apoc session close SESSION_ID --timeout-ms 2000

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.

apoc code run '
  const [processes, sockets, tests] = await Promise.all([
    apoc.process_list({ selector: "match:node", limit: 20 }),
    apoc.process_sockets({ listening: true, protocol: "tcp", limit: 100 }),
    apoc.execution_command({
      executable: "cargo",
      arg: ["test"],
      purpose: "verify the current worktree"
    })
  ]);
  return { processes, sockets, tests };
'

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.

apoc code start 'return await apoc.execution_list({});'
apoc code get EXECUTION_ID
apoc code cancel EXECUTION_ID
apoc code artifact EXECUTION_ID ARTIFACT_ID

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.

apoc provider add-mcp-http github https://example.test/mcp \
  --secret-header authorization=env:GITHUB_AUTHORIZATION
apoc provider add-openapi logistics https://example.test/openapi.json \
  --base-url https://example.test/api
apoc provider add-mcp-stdio macos \
  "$PWD/extensions/macos/.build/release/apoc-macos"

apoc provider doctor macos
apoc provider refresh macos
apoc capability search 'focus a macOS window'
apoc action run macos clipboard_read
apoc action run macos window_focus --input '{"pid":4242,"index":0}'

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.

apoc receipt list --limit 20
apoc receipt get RECEIPT_ID

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.

apoc event query --after 0 --limit 100
apoc event watch --after CURSOR --timeout-ms 30000
apoc event export --after 0 --format jsonl
apoc event payload PAYLOAD_ID
apoc event pin PAYLOAD_ID
apoc event prune-payloads --max-age-ms 2592000000

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 daemon start
apoc daemon status
apoc daemon stop

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.