@orgloop/agentctl 1.0.1 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Universal agent supervision interface. Monitor and control AI coding agents from a single CLI.
 
-agentctl reads from native sources (Claude Code's `~/.claude/` directory, running processes) and provides a standard interface to list, inspect, stop, launch, and resume agent sessions. It never replicates state — it reads what's actually happening.
+agentctl reads from native sources (Claude Code's `~/.claude/` directory, Pi's `~/.pi/` directory, running processes) and provides a standard interface to list, inspect, stop, launch, and resume agent sessions. It never replicates state — it reads what's actually happening.
 
 ## Layer Model
 
@@ -48,6 +48,9 @@ agentctl peek <session-id>
 # Launch a new Claude Code session
 agentctl launch -p "Read the spec and implement phase 2"
 
+# Launch a new Pi session
+agentctl launch pi -p "Refactor the auth module"
+
 # Stop a session
 agentctl stop <session-id>
 
@@ -57,13 +60,79 @@ agentctl resume <session-id> "fix the failing tests"
 
 Session IDs support prefix matching — `agentctl peek abc123` matches any session starting with `abc123`.
 
+### Parallel Multi-Adapter Launch
+
+Launch the same prompt across multiple adapters (or the same adapter with different models). Each gets its own git worktree and runs in isolation:
+
+```bash
+# Launch across 3 adapters
+agentctl launch \
+  --adapter claude-code \
+  --adapter codex \
+  --adapter pi \
+  --cwd ~/code/mono \
+  -p "Implement the caching layer"
+
+# Launched 3 sessions (group: g-a1b2c3):
+#   claude-code  → ~/code/mono-try-g-a1b2c3-cc
+#   codex        → ~/code/mono-try-g-a1b2c3-codex
+#   pi           → ~/code/mono-try-g-a1b2c3-pi
+```
+
+Same adapter with different models:
+
+```bash
+agentctl launch \
+  --adapter claude-code --model claude-opus-4-6 \
+  --adapter claude-code --model claude-sonnet-4-5 \
+  --adapter codex \
+  --cwd ~/code/mono \
+  -p "Refactor the auth module"
+```
+
+Groups show up in `agentctl list` automatically:
+
+```bash
+agentctl list
+# ID        Status   Model           Group      CWD                          Prompt
+# f3a1...   running  opus-4-6        g-x1y2z3   ~/mono-try-g-x1y2z3-cc-opus  Refactor...
+# 8b2c...   running  sonnet-4-5      g-x1y2z3   ~/mono-try-g-x1y2z3-cc-son   Refactor...
+# c4d3...   done     gpt-5.2-codex   g-x1y2z3   ~/mono-try-g-x1y2z3-codex    Refactor...
+
+# Filter by group
+agentctl list --group g-x1y2z3
+```
+
+### Matrix Files
+
+For advanced sweep configurations, use a YAML matrix file:
+
+```yaml
+# matrix.yaml
+prompt: "Implement the caching layer"
+cwd: ~/code/mono
+matrix:
+  - adapter: claude-code
+    model:
+      - claude-opus-4-6
+      - claude-sonnet-4-5
+  - adapter: codex
+```
+
+```bash
+agentctl launch --matrix matrix.yaml
+# Launches 3 sessions: claude-code×opus, claude-code×sonnet, codex
+```
+
+Array values in `model` are expanded via cross-product.
+
 ## CLI Reference
 
 ### Session Management
 
 ```bash
 agentctl list [options]
-  --adapter <name>     Filter by adapter (claude-code, openclaw)
+  --adapter <name>     Filter by adapter (claude-code, codex, opencode, pi, pi-rust, openclaw)
   --status <status>    Filter by status (running|stopped|idle|error)
   -a, --all            Include stopped sessions (last 7 days)
   --json               Output as JSON
@@ -81,6 +150,9 @@ agentctl launch [adapter] [options]
   --spec <path>        Spec file path
   --cwd <dir>          Working directory
   --model <model>      Model to use (e.g. sonnet, opus)
+  --adapter <name>     Adapter to launch (repeatable for parallel launch)
+  --matrix <file>      YAML matrix file for advanced sweep launch
+  --group <id>         Filter by launch group (for list command)
   --force              Override directory locks
 
 agentctl stop <id> [options]
@@ -114,6 +186,29 @@ agentctl locks [options]
   --json               Output as JSON
 ```
 
+### Worktree Management
+
+Manage git worktrees created by parallel launches or `--worktree` flag:
+
+```bash
+agentctl worktree list <repo>
+  --json               Output as JSON
+
+agentctl worktree clean <path> [options]
+  --repo <path>        Main repo path (auto-detected if omitted)
+  --delete-branch      Also delete the worktree's branch
+```
+
+Example:
+
+```bash
+# List all worktrees for a repo
+agentctl worktree list ~/code/mono
+
+# Clean up a worktree and its branch
+agentctl worktree clean ~/code/mono-try-g-a1b2c3-cc --delete-branch
+```
+
 ### Lifecycle Hooks
 
 Hooks are shell commands that run at specific points in a session's lifecycle. Pass them as flags to `launch` or `merge`:
@@ -146,6 +241,8 @@ Hook scripts receive context via environment variables:
 | `AGENTCTL_ADAPTER` | Adapter name (e.g. `claude-code`) |
 | `AGENTCTL_BRANCH` | Git branch (when using `--worktree`) |
 | `AGENTCTL_EXIT_CODE` | Process exit code (in `--on-complete`) |
+| `AGENTCTL_GROUP` | Launch group ID (in parallel launches) |
+| `AGENTCTL_MODEL` | Model name (when specified) |
 
 Hooks run with a 60-second timeout. If a hook fails, its stderr is printed but execution continues.
 
@@ -268,7 +365,7 @@ scrape_configs:
 
 agentctl is structured in three layers: the **CLI** parses commands and formats output, the **daemon** provides persistent state (session tracking, directory locks, fuse timers, Prometheus metrics), and **adapters** bridge to specific agent runtimes. The CLI communicates with the daemon over a Unix socket at `~/.agentctl/agentctl.sock`.
 
-All session state is derived from native sources — agentctl never maintains its own session registry. The Claude Code adapter reads `~/.claude/projects/` and cross-references running processes; other adapters connect to their respective APIs. This means agentctl always reflects ground truth.
+All session state is derived from native sources — agentctl never maintains its own session registry. The Claude Code adapter reads `~/.claude/projects/` and cross-references running processes; the Pi adapter reads `~/.pi/agent/sessions/` JSONL files; other adapters connect to their respective APIs. This means agentctl always reflects ground truth.
 
 ## Adapters
 
@@ -278,6 +375,42 @@ agentctl uses an adapter model to support different agent runtimes.
 
 Reads session data from `~/.claude/projects/` and cross-references with running `claude` processes. Detects PID recycling via process start time verification. Tracks detached processes that survive wrapper exit.
 
+### Codex CLI
+
+Reads session data from `~/.codex/sessions/` and cross-references with running `codex` processes. Supports `codex exec` non-interactive mode for launching headless sessions. Detects PID recycling via process start time verification, same as the Claude Code adapter.
+
+```bash
+# Launch a Codex session
+agentctl launch codex -p "implement the feature"
+
+# Launch with specific model
+agentctl launch codex -p "fix the bug" --model gpt-5.2-codex
+```
+
+### OpenCode
+
+Reads session data from `~/.local/share/opencode/storage/` and cross-references with running `opencode` processes. Supports headless execution via `opencode run`.
+
+OpenCode stores sessions as individual JSON files organized by project hash (SHA1 of the working directory path):
+
+- **Session files**: `storage/session/<projectHash>/<sessionId>.json` — session metadata (title, directory, timestamps, summary)
+- **Message files**: `storage/message/<sessionId>/<messageId>.json` — individual messages with token counts, cost, and model info
+- **Part files**: `storage/part/<messageId>/` — message content parts
+
+The adapter detects PID recycling via process start time verification, tracks detached processes that survive wrapper exit, and supports prefix matching for session IDs.
+
+Launch sessions with `agentctl launch opencode -p "your prompt"`.
+
+### Pi
+
+Reads session data from `~/.pi/agent/sessions/` and cross-references with running `pi` processes. Pi stores sessions as JSONL files organized by cwd slug — each file starts with a `type:'session'` header containing metadata (id, cwd, provider, modelId, thinkingLevel, version).
+
+Detects PID recycling via process start time verification. Tracks detached processes that survive wrapper exit. Persists session metadata in `~/.pi/agentctl/sessions/` for status checks after the launching wrapper exits.
+
+Launch uses Pi's print mode (`pi -p "prompt"`) for headless execution. Resume launches a new Pi session in the same working directory since Pi doesn't have a native `--continue` flag.
+
+Requires the `pi` binary (npm: `@mariozechner/pi-coding-agent`) to be available on PATH.
+
 ### OpenClaw
 
 Connects to the OpenClaw gateway via WebSocket RPC. Read-only — sessions are managed through the gateway.
@@ -339,8 +472,17 @@ npm run lint          # biome check
 src/
   cli.ts                         # CLI entry point (commander)
   core/types.ts                  # Core interfaces
+  launch-orchestrator.ts         # Parallel multi-adapter launch orchestration
+  matrix-parser.ts               # YAML matrix file parser + cross-product expansion
+  worktree.ts                    # Git worktree create/list/clean
+  hooks.ts                       # Lifecycle hook runner
+  merge.ts                       # Git commit/push/PR for sessions
   adapters/claude-code.ts        # Claude Code adapter
+  adapters/codex.ts              # Codex CLI adapter
   adapters/openclaw.ts           # OpenClaw gateway adapter
+  adapters/opencode.ts           # OpenCode adapter
+  adapters/pi.ts                 # Pi coding agent adapter
+  adapters/pi-rust.ts            # Pi Rust adapter
   daemon/server.ts               # Daemon: Unix socket server + HTTP metrics
   daemon/session-tracker.ts      # Session lifecycle tracking
   daemon/lock-manager.ts         # Directory locks

package/dist/adapters/claude-code.js

@@ -5,6 +5,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
+import { readHead, readTail } from "../utils/partial-read.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_CLAUDE_DIR = path.join(os.homedir(), ".claude");
 // Default: only show stopped sessions from the last 7 days
@@ -129,10 +130,11 @@ export class ClaudeCodeAdapter {
         await fs.mkdir(this.sessionsMetaDir, { recursive: true });
         const logPath = path.join(this.sessionsMetaDir, `launch-${Date.now()}.log`);
         const logFd = await fs.open(logPath, "w");
+        // Capture stderr to the same log file for debugging launch failures
         const child = spawn("claude", args, {
             cwd,
             env,
-            stdio: ["ignore", logFd.fd, "ignore"],
+            stdio: ["ignore", logFd.fd, logFd.fd],
             detached: true,
         });
         // Fully detach: child runs in its own process group.
@@ -148,7 +150,7 @@ export class ClaudeCodeAdapter {
         if (pid) {
             resolvedSessionId = await this.pollForSessionId(logPath, pid, 5000);
         }
-        const sessionId = resolvedSessionId || crypto.randomUUID();
+        const sessionId = resolvedSessionId || (pid ? `pending-${pid}` : crypto.randomUUID());
         // Persist session metadata so status checks work after wrapper exits
         if (pid) {
             await this.writeSessionMeta({
@@ -348,12 +350,12 @@ export class ClaudeCodeAdapter {
             catch {
                 continue;
             }
-            // Read first few lines for prompt and cwd
+            // Read first few lines for prompt and cwd (only first 8KB, not entire file)
             let firstPrompt = "";
             let sessionCwd = "";
             try {
-                const content = await fs.readFile(fullPath, "utf-8");
-                for (const l of content.split("\n").slice(0, 20)) {
+                const headLines = await readHead(fullPath, 20, 8192);
+                for (const l of headLines) {
                     try {
                         const msg = JSON.parse(l);
                         if (msg.cwd && !sessionCwd)
@@ -540,13 +542,11 @@ export class ClaudeCodeAdapter {
     }
     async parseSessionTail(jsonlPath) {
         try {
-            const content = await fs.readFile(jsonlPath, "utf-8");
-            const lines = content.trim().split("\n");
             let model;
             let totalIn = 0;
             let totalOut = 0;
-            // Read from the end for efficiency — last 100 lines
-            const tail = lines.slice(-100);
+            // Read only the last 64KB for the tail (not entire file)
+            const tail = await readTail(jsonlPath, 100, 65536);
             for (const line of tail) {
                 try {
                     const msg = JSON.parse(line);
@@ -565,7 +565,7 @@ export class ClaudeCodeAdapter {
             }
             // Also scan first few lines for model if we didn't find it
             if (!model) {
-                const head = lines.slice(0, 20);
+                const head = await readHead(jsonlPath, 20, 8192);
                 for (const line of head) {
                     try {
                         const msg = JSON.parse(line);

package/dist/adapters/codex.d.ts

@@ -0,0 +1,72 @@
+import type { AgentAdapter, AgentSession, LaunchOpts, LifecycleEvent, ListOpts, PeekOpts, StopOpts } from "../core/types.js";
+export interface CodexPidInfo {
+    pid: number;
+    cwd: string;
+    args: string;
+    startTime?: string;
+}
+/** Metadata persisted by launch() so status checks survive wrapper exit */
+export interface CodexSessionMeta {
+    sessionId: string;
+    pid: number;
+    startTime?: string;
+    wrapperPid?: number;
+    cwd: string;
+    model?: string;
+    prompt?: string;
+    launchedAt: string;
+}
+export interface CodexAdapterOpts {
+    codexDir?: string;
+    sessionsMetaDir?: string;
+    getPids?: () => Promise<Map<number, CodexPidInfo>>;
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Codex CLI adapter — reads session data from ~/.codex/sessions/
+ * and cross-references with running PIDs.
+ */
+export declare class CodexAdapter implements AgentAdapter {
+    readonly id = "codex";
+    private readonly codexDir;
+    private readonly sessionsDir;
+    private readonly sessionsMetaDir;
+    private readonly getPids;
+    private readonly isProcessAlive;
+    constructor(opts?: CodexAdapterOpts);
+    list(opts?: ListOpts): Promise<AgentSession[]>;
+    peek(sessionId: string, opts?: PeekOpts): Promise<string>;
+    status(sessionId: string): Promise<AgentSession>;
+    launch(opts: LaunchOpts): Promise<AgentSession>;
+    /**
+     * Poll the launch log file for up to `timeoutMs` to extract the session/thread ID.
+     * Codex outputs {"type":"thread.started","thread_id":"..."} early in its JSONL stream.
+     */
+    private pollForSessionId;
+    stop(sessionId: string, opts?: StopOpts): Promise<void>;
+    resume(sessionId: string, message: string): Promise<void>;
+    events(): AsyncIterable<LifecycleEvent>;
+    /**
+     * Discover all Codex sessions by scanning ~/.codex/sessions/ recursively.
+     * Sessions are stored as: sessions/YYYY/MM/DD/rollout-<datetime>-<session-id>.jsonl
+     */
+    private discoverSessions;
+    /** Recursively find all .jsonl files under a directory */
+    private findJsonlFiles;
+    /** Parse a Codex session JSONL file to extract session info */
+    private parseSessionFile;
+    private buildSession;
+    private isSessionRunning;
+    private processStartedAfterSession;
+    private findMatchingPid;
+    private findSession;
+    private findPidForSession;
+    writeSessionMeta(meta: Omit<CodexSessionMeta, "startTime">): Promise<void>;
+    readSessionMeta(sessionId: string): Promise<CodexSessionMeta | null>;
+    /**
+     * Synchronous-style read of session metadata (reads from cache/disk).
+     * Used by isSessionRunning which is called in a tight loop.
+     * Falls back to null if not found.
+     */
+    private readSessionMetaSync;
+}