@elhu/pit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 pit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+# pit
+
+[![CI](https://github.com/elhu/pit/actions/workflows/ci.yml/badge.svg)](https://github.com/elhu/pit/actions/workflows/ci.yml)
+
+A tmux-based orchestrator that automates parallel AI coding agent sessions.
+
+`pit` manages git worktrees, tmux windows, and agent TUIs (Claude Code or opencode),
+driving each agent through a ticket loop powered by [beads](https://github.com/anomalyco/beads)
+for issue tracking. The primary consumer of `pit` is an LLM in an orchestrator session --
+the human talks to the model, the model calls `pit`.
+
+```
+                    +-----------------+
+                    |  Orchestrator   |
+                    |  (LLM session)  |
+                    +--------+--------+
+                             |
+                         pit CLI
+                             |
+                    +--------+--------+
+                    |     Daemon      |
+                    | (Unix socket)   |
+                    +--------+--------+
+                             |
+              +--------------+--------------+
+              |              |              |
+        +-----+-----+ +-----+-----+ +-----+-----+
+        | Worktree 1 | | Worktree 2 | | Worktree 3 |
+        | tmux win 1 | | tmux win 2 | | tmux win 3 |
+        |  Agent TUI | |  Agent TUI | |  Agent TUI |
+        +------------+ +------------+ +------------+
+```
+
+---
+
+> **WARNING: EXPERIMENTAL SOFTWARE**
+>
+> ```
+>     _____
+>    /     \
+>   | () () |
+>    \  ^  /
+>     |||||
+>     |||||
+> ```
+>
+> **This software is highly experimental.** It is under active development, APIs will
+> change without notice, and things will break.
+>
+> **This software deliberately bypasses AI agent security features.** `pit` launches
+> Claude Code with `--dangerously-skip-permissions`, which disables ALL permission
+> checks -- file writes, shell commands, network access, everything. Agents execute
+> arbitrary commands without human confirmation.
+>
+> **This software is for people who like taking risks.** If you are not comfortable
+> with autonomous AI agents running shell commands in your codebase without asking
+> first, this is not for you. If "move fast and break things" makes you nervous
+> rather than excited, look elsewhere.
+>
+> **This software is built using itself.** `pit` is developed with `pit` -- the
+> codebase is almost entirely written by AI coding agents orchestrated by `pit`. If
+> running AI-generated code makes you uncomfortable, this is not for you.
+>
+> **This software will burn through tokens.** `pit` runs autonomous agents that work
+> fast but are not frugal. Multiple agents running in parallel, each looping through
+> tickets, each with full context windows. Monitor your API usage. You have been
+> warned twice now.
+>
+> **Do NOT use `pit` on untrusted repositories or with untrusted ticket content.** The
+> agents will execute whatever they're told to, without confirmation. You have been
+> warned.
+
+---
+
+## Philosophy
+
+`pit` is opinionated software. It encodes a specific workflow for AI-assisted development
+and does not try to be all things to all people.
+
+**The core belief:** the quality of autonomous AI coding comes down to the quality of
+the tickets. `pit`'s prompt loop is deliberately simplistic -- "find the next ticket and
+work on it" -- because all the nuance, context, and constraints should live in the
+tickets themselves. If you write vague tickets, you get vague results. If you write
+detailed, unambiguous tickets with clear acceptance criteria, agents can execute
+independently.
+
+**Context is cleared between tickets.** When an agent finishes a ticket, `pit` clears
+its conversation context before sending the next one. Each ticket starts fresh -- the
+agent has no memory of previous tickets. This means tickets must be self-contained:
+include all relevant context, file paths, and constraints in the ticket itself. In
+practice this is rarely a problem if your tickets are well-written, and it prevents
+context window pollution from accumulating over a long epic.
+
+### The Intended Workflow
+
+1. **Write requirements.** Start with a set of high-level requirements for the feature
+   or project you want to build.
+
+2. **Refine into detailed beads.** Break the requirements down into highly detailed
+   beads tickets. Each ticket should contain enough context for a coding agent to pick
+   it up and execute independently -- the problem statement, relevant file paths,
+   expected behavior, edge cases, and constraints. This is where you invest your time.
+
+3. **Set up your AGENTS.md.** Your project's AGENTS.md (or equivalent agent
+   instructions file) should contain the "landing the plane" instructions -- quality
+   gates to run, what to commit, when to push, coding conventions. This is the
+   persistent context every agent session gets. `pit` injects its orchestrator
+   instructions here via `pit init`.
+
+4. **Let `pit` run.** `pit start --epics <epic-id>` spins up agents and they work through
+   tickets autonomously. Monitor with `pit status`, intervene when agents pause.
+
+5. **Merge and clean up.** Once an epic is done, the human operator (or an agent you
+   instruct) merges the worktree branch back to main, runs quality gates, pushes, and
+   calls `pit teardown` to clean up all `pit` artifacts.
+
+`pit` does not try to be smart about what agents do. It manages the plumbing -- worktrees,
+tmux sessions, idle detection, ticket cycling -- and gets out of the way. The
+intelligence lives in your tickets and your AGENTS.md.
+
+## How It Works
+
+1. You set up an epic (a group of tickets) using [beads](https://github.com/anomalyco/beads)
+2. You run `pit start --epics <epic-id>`
+3. `pit` creates one git worktree + tmux window + agent TUI per epic
+4. Each agent autonomously loops: pick ticket, work on it, commit, push, pick next
+5. You monitor with `pit status`, intervene with `pit pause`/`pit resume`
+6. When an epic completes, you merge the worktree branch back
+
+Agents work in isolated git worktrees so they don't interfere with each other or your
+main checkout. Each agent has its own branch, its own files, its own tmux window.
+
+## Watching and Intervening
+
+`pit` runs agents inside a tmux session (named `pit` by default). You can attach to it
+at any time to watch agents work in real time:
+
+```bash
+tmux attach -t pit
+```
+
+Use tmux's normal window-switching keys (`Ctrl-b n` / `Ctrl-b p`) to move between
+epic windows. Each window is named `epic-<id>` and shows the agent's TUI.
+
+From any terminal (you don't need to be attached to tmux), you can:
+
+```bash
+# Check what all agents are doing
+pit status --pretty
+
+# Read an agent's recent output without attaching to tmux
+pit log my-epic --lines 100
+
+# Pause an agent that's going in circles
+pit pause my-epic
+
+# Resume with specific guidance
+pit resume my-epic --message "The config file is in src/config.ts, not lib/config.ts"
+
+# Resume without a message (re-prompts with the next ticket)
+pit resume my-epic
+```
+
+You can also install tmux integrations for quicker access:
+
+```bash
+pit install-keybinding    # Binds prefix+R to resume and prefix+H to pause the current epic
+pit install-status        # Appends #{@pit-status} to the tmux status bar
+```
+
+## Prerequisites
+
+- **Node.js** >= 24
+- **tmux** installed and available in PATH
+- **beads** (`bd`) installed and available in PATH
+- **An AI coding agent**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) or [opencode](https://opencode.ai) (`opencode`)
+- A git repository with beads epics and tickets set up
+
+## Install
+
+```bash
+npm install -g pit
+```
+
+Or clone and build from source:
+
+```bash
+git clone https://github.com/anomalyco/pit.git
+cd pit
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize pit in your project (injects orchestrator instructions into AGENTS.md)
+pit init
+
+# 2. Optionally configure pit (or just use defaults)
+cat > .pit.json << 'EOF'
+{
+  "agent": "auto",
+  "baseBranch": "main"
+}
+EOF
+
+# 3. Make sure you have beads epics set up
+bd list
+
+# 4. Start agents for one or more epics
+pit start --epics my-epic-id
+
+# 5. Monitor progress
+pit status
+pit status --pretty
+
+# 6. Read agent output
+pit log my-epic-id
+
+# 7. Pause/resume as needed
+pit pause my-epic-id
+pit resume my-epic-id --message "Try a different approach for the auth module"
+
+# 8. Clean up when done
+pit teardown
+```
+
+## CLI Reference
+
+All commands output JSON by default (for LLM consumption). Add `--pretty` for
+human-readable output.
+
+| Command                   | Description                                                 |
+| ------------------------- | ----------------------------------------------------------- |
+| `pit init`                | Inject orchestrator instructions into AGENTS.md             |
+| `pit start --epics <ids>` | Start agent sessions for given epic IDs                     |
+| `pit status`              | Show status of all running epics                            |
+| `pit log <epic>`          | Capture agent's recent terminal output                      |
+| `pit pause <epic>`        | Pause a running epic                                        |
+| `pit resume <epic>`       | Resume a paused epic (optionally with `--message`)          |
+| `pit stop [epic]`         | Stop epic(s), transition to done                            |
+| `pit add <epic>`          | Add an epic to a running session                            |
+| `pit teardown [epic]`     | Tear down epics and clean up resources                      |
+| `pit cleanup`             | Garbage-collect stale session directories                   |
+| `pit daemon <cmd>`        | Manage the background daemon (start/stop/status/restart)    |
+| `pit install-keybinding`  | Install tmux keybindings for quick resume (R) and pause (H) |
+| `pit install-status`      | Append `#{@pit-status}` to the tmux status bar              |
+
+For detailed flag reference, examples, and edge cases, see [docs/cli.md](docs/cli.md).
+
+## Configuration
+
+`pit` reads `.pit.json` from the project root. CLI flags override file values.
+
+```jsonc
+{
+  // Which coding agent to run in each tmux window.
+  //   "auto"        - tries opencode first, falls back to claude-code
+  //   "opencode"    - use opencode (https://opencode.ai)
+  //   "claude-code" - use Claude Code (https://docs.anthropic.com/en/docs/claude-code)
+  "agent": "auto",
+
+  // Model passed to the agent CLI. Format depends on the agent:
+  //   Claude Code: "claude-sonnet-4-20250514", "claude-opus-4-20250514", etc.
+  //   opencode:    "anthropic/claude-sonnet-4-20250514", etc.
+  // null = let the agent use its default model.
+  "model": null,
+
+  "worktreeDir": ".worktrees", // Where git worktrees are created
+  "baseBranch": "main", // Branch worktrees are created from
+  "tmuxSession": "pit", // tmux session name
+
+  "clearDelay": 2000, // Ms to wait after clearing agent context
+  "initDelay": 5000, // Ms to wait for agent TUI to start
+  "ticketTimeout": null, // Minutes before auto-pausing a ticket (null = no limit)
+}
+```
+
+| Field           | Default        | Description                                                      |
+| --------------- | -------------- | ---------------------------------------------------------------- |
+| `agent`         | `"auto"`       | Agent type: `auto`, `opencode`, or `claude-code`                 |
+| `model`         | `null`         | Model to pass to the agent CLI (null = agent default)            |
+| `worktreeDir`   | `".worktrees"` | Directory for git worktrees                                      |
+| `baseBranch`    | `"main"`       | Base branch for worktrees                                        |
+| `tmuxSession`   | `"pit"`        | tmux session name                                                |
+| `clearDelay`    | `2000`         | Ms to wait before clearing agent context after ticket completion |
+| `initDelay`     | `5000`         | Ms to wait before starting the agent after setup                 |
+| `ticketTimeout` | `null`         | Minutes before a ticket auto-pauses the agent (null = disabled)  |
+
+## Security Model
+
+`pit` is designed for autonomous agent operation. This comes with deliberate trade-offs:
+
+- **Claude Code** is launched with `--dangerously-skip-permissions`, bypassing all
+  permission checks. The agent can read/write any file, run any shell command, and
+  make network requests without human approval.
+- **opencode** uses its plugin system for event detection. Permission handling is
+  managed through the plugin bridge.
+- Each agent runs in an **isolated git worktree**, not your main checkout. The
+  worktree is disposable and can be recreated from the base branch.
+- The daemon communicates over a **Unix domain socket** in `/tmp/pit/`. No network
+  exposure.
+
+**This is intentional.** `pit` exists to let agents work autonomously. If you need
+human-in-the-loop approval for every file write, `pit` is the wrong tool.
+
+**Mitigations:**
+
+- Worktree isolation limits blast radius
+- Worktrees are on branches, not main -- you review before merging
+- `pit pause` lets you halt an agent at any time
+- `pit teardown` cleans everything up
+
+## Documentation
+
+| Document                                       | Audience          | Description                                                 |
+| ---------------------------------------------- | ----------------- | ----------------------------------------------------------- |
+| [docs/cli.md](docs/cli.md)                     | Agents + humans   | Detailed per-command reference                              |
+| [docs/architecture.md](docs/architecture.md)   | Agents + humans   | Internal architecture and design                            |
+| [docs/orchestration.md](docs/orchestration.md) | Orchestrator LLMs | How to drive `pit` from an LLM session                      |
+| [AGENTS.md](AGENTS.md)                         | Coding agents     | Conventions and workflow for agents working on `pit` itself |
+
+## Releasing
+
+Releases are published to npm and GitHub Releases automatically by CI when a version
+tag is pushed. Use the release script to bump the version and push the tag:
+
+```bash
+# Patch release (e.g. 1.2.3 -> 1.2.4)
+npm run release -- patch
+
+# Minor release (e.g. 1.2.3 -> 1.3.0)
+npm run release -- minor
+
+# Major release (e.g. 1.2.3 -> 2.0.0)
+npm run release -- major
+
+# Explicit version
+npm run release -- 1.2.3
+```
+
+The script will:
+
+1. Verify a clean working tree and that you're on `main`
+2. Pull latest from origin
+3. Run local quality gates (`npm test`, `npm run test:e2e`, `npm run lint`, `npm run build`)
+4. Bump the version and create a git commit + tag via `npm version`
+5. Push the commit and tag (`git push --follow-tags`), triggering the CI publish workflow
+6. Print a link to GitHub Actions so you can monitor the publish
+
+CI handles the actual `npm publish` and GitHub Release creation — you do not need to
+run `npm publish` manually.
+
+### What CI does automatically
+
+When a `v*` tag is pushed, the [Publish workflow](.github/workflows/publish.yml):
+
+1. Verifies the tag matches the version in `package.json`
+2. Runs quality gates (lint, build, unit tests, E2E tests)
+3. Publishes the package to npm (`npm publish --access public`)
+4. Creates a GitHub Release with auto-generated release notes
+
+### Required secrets
+
+The repository must have an `NPM_TOKEN` secret set in GitHub Actions:
+
+1. Go to [npmjs.com](https://www.npmjs.com) → Account → Access Tokens → Generate New Token
+2. Choose **Automation** token type (bypasses 2FA requirement for CI publishing)
+3. Add the token to GitHub: Repository → Settings → Secrets and variables → Actions → `NPM_TOKEN`
+
+### Verifying a release
+
+Monitor the publish workflow at:
+[https://github.com/elhu/pit/actions/workflows/publish.yml](https://github.com/elhu/pit/actions/workflows/publish.yml)
+
+## License
+
+[MIT](LICENSE)

package/dist/adapters/claude-code.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ClaudeCodeAdapter — implements AgentAdapter for the Claude Code CLI agent.
+ *
+ * Claude Code is a CLI tool (`claude`) that reads instructions from CLAUDE.md
+ * in the worktree. Hooks are installed into .claude/hooks/ and registered in
+ * .claude/settings.local.json for Stop events.
+ *
+ * ## Permission handling
+ *
+ * Claude Code is launched with `--dangerously-skip-permissions` so that the
+ * agent can work autonomously without interactive permission prompts blocking
+ * the tmux session. This flag bypasses **all** permission checks — file writes,
+ * shell commands, network access, etc. — which is acceptable because:
+ *
+ *   1. Each agent runs in an isolated git worktree, not the main checkout.
+ *   2. The worktree is disposable and can be recreated from the base branch.
+ *   3. pit is designed for autonomous agent operation where human approval
+ *      for every tool call would defeat the purpose.
+ *
+ * **Security note:** Do NOT use pit (or this flag) on untrusted repositories
+ * or with untrusted ticket content. The agent will execute arbitrary commands
+ * without confirmation.
+ */
+import type { AgentAdapter } from "./types.js";
+export declare class ClaudeCodeAdapter implements AgentAdapter {
+    readonly name = "claude-code";
+    startCommand(_worktree: string, _env: Record<string, string>, model?: string): string;
+    /** Claude Code is a full-screen TUI; use timeout-based readiness. */
+    readonly readinessPattern: undefined;
+    readonly clearCommand = "/clear";
+    /**
+     * Install the pit hook into the worktree's .claude/hooks/ directory and
+     * register it in .claude/settings.local.json for the Stop event (idle
+     * detection). PermissionRequest hooks are not needed because the agent is
+     * launched with --dangerously-skip-permissions.
+     *
+     * The hook content is embedded as an inline string (CLAUDE_CODE_HOOK_JS) at
+     * build time, so it is always the correct version regardless of where pit is
+     * installed globally (npm link, npm install -g, etc.). Resolving via __dirname
+     * was unreliable because it pointed to the global install's dist directory
+     * rather than the worktree's bundled copy.
+     */
+    installEventBridge(worktreeDir: string, _epic: string): Promise<void>;
+    /**
+     * Write agent instructions to CLAUDE.md using PIT:MANAGED markers.
+     * Creates the section if absent; replaces it if present (idempotent).
+     * Preserves any content outside the managed section.
+     */
+    writeInstructions(worktreeDir: string, content: string): Promise<void>;
+    /**
+     * Check whether the claude CLI is available on PATH.
+     * Returns true if `which claude` exits 0, false otherwise.
+     */
+    checkInstalled(): Promise<boolean>;
+    /**
+     * Wait for Claude Code to be ready using a simple timeout.
+     */
+    waitForReady({ timeoutMs }: {
+        timeoutMs: number;
+    }): Promise<void>;
+    /**
+     * Verify the Claude Code process is running in the given tmux window.
+     *
+     * The tmux pane PID is the shell (zsh/bash), not claude itself.
+     * We walk the process tree rooted at the pane PID and check whether any
+     * descendant process has a comm of "claude" or "node".
+     */
+    verifyRunning(tmuxSession: string, windowName: string): Promise<boolean>;
+}
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/adapters/claude-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc/C,qBAAa,iBAAkB,YAAW,YAAY;IACpD,QAAQ,CAAC,IAAI,iBAAiB;IAE9B,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAKrF,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,YAAa;IAEtC,QAAQ,CAAC,YAAY,YAAY;IAEjC;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C3E;;;;OAIG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC5E;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAQxC;;OAEG;IACG,YAAY,CAAC,EAAE,SAAS,EAAE,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE;;;;;;OAMG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAkB/E"}

package/dist/adapters/claude-code.js

@@ -0,0 +1,166 @@
+/**
+ * ClaudeCodeAdapter — implements AgentAdapter for the Claude Code CLI agent.
+ *
+ * Claude Code is a CLI tool (`claude`) that reads instructions from CLAUDE.md
+ * in the worktree. Hooks are installed into .claude/hooks/ and registered in
+ * .claude/settings.local.json for Stop events.
+ *
+ * ## Permission handling
+ *
+ * Claude Code is launched with `--dangerously-skip-permissions` so that the
+ * agent can work autonomously without interactive permission prompts blocking
+ * the tmux session. This flag bypasses **all** permission checks — file writes,
+ * shell commands, network access, etc. — which is acceptable because:
+ *
+ *   1. Each agent runs in an isolated git worktree, not the main checkout.
+ *   2. The worktree is disposable and can be recreated from the base branch.
+ *   3. pit is designed for autonomous agent operation where human approval
+ *      for every tool call would defeat the purpose.
+ *
+ * **Security note:** Do NOT use pit (or this flag) on untrusted repositories
+ * or with untrusted ticket content. The agent will execute arbitrary commands
+ * without confirmation.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execTmux } from "../tmux.js";
+import { shellQuote } from "../shell-quote.js";
+import { CLAUDE_CODE_HOOK_JS } from "../assets.generated.js";
+import { hasAgentDescendant } from "./process-utils.js";
+/**
+ * Names that indicate Claude Code is running as a descendant process.
+ * Claude Code is distributed as "claude" CLI, but may run via Node.js.
+ */
+const CLAUDE_CODE_COMM_NAMES = new Set(["claude", "node"]);
+const PIT_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/pit-hook.js"`;
+const PIT_HOOK_MARKER = "pit-hook.js";
+const MANAGED_BEGIN = "<!-- PIT:MANAGED:BEGIN -->";
+const MANAGED_END = "<!-- PIT:MANAGED:END -->";
+export class ClaudeCodeAdapter {
+    name = "claude-code";
+    startCommand(_worktree, _env, model) {
+        const base = "claude --dangerously-skip-permissions";
+        return model ? `${base} --model ${shellQuote(model)}` : base;
+    }
+    /** Claude Code is a full-screen TUI; use timeout-based readiness. */
+    readinessPattern = undefined;
+    clearCommand = "/clear";
+    /**
+     * Install the pit hook into the worktree's .claude/hooks/ directory and
+     * register it in .claude/settings.local.json for the Stop event (idle
+     * detection). PermissionRequest hooks are not needed because the agent is
+     * launched with --dangerously-skip-permissions.
+     *
+     * The hook content is embedded as an inline string (CLAUDE_CODE_HOOK_JS) at
+     * build time, so it is always the correct version regardless of where pit is
+     * installed globally (npm link, npm install -g, etc.). Resolving via __dirname
+     * was unreliable because it pointed to the global install's dist directory
+     * rather than the worktree's bundled copy.
+     */
+    async installEventBridge(worktreeDir, _epic) {
+        const hooksDir = path.join(worktreeDir, ".claude", "hooks");
+        await fs.mkdir(hooksDir, { recursive: true });
+        const destPath = path.join(hooksDir, "pit-hook.js");
+        await fs.writeFile(destPath, CLAUDE_CODE_HOOK_JS, "utf8");
+        const settingsPath = path.join(worktreeDir, ".claude", "settings.local.json");
+        let config = {};
+        try {
+            const raw = await fs.readFile(settingsPath, "utf8");
+            config = JSON.parse(raw);
+        }
+        catch {
+            // File does not exist or is invalid JSON — start fresh
+        }
+        // Register the pit hook for the Stop event (agent-idle detection).
+        // PermissionRequest hooks are not needed because Claude Code is launched
+        // with --dangerously-skip-permissions (see startCommand / class doc).
+        const hooks = (config.hooks ?? {});
+        config.hooks = hooks;
+        const pitMatcher = {
+            hooks: [{ type: "command", command: PIT_HOOK_COMMAND }],
+        };
+        for (const event of ["Stop"]) {
+            if (!Array.isArray(hooks[event])) {
+                hooks[event] = [];
+            }
+            const existingEntries = hooks[event];
+            const alreadyInstalled = JSON.stringify(existingEntries).includes(PIT_HOOK_MARKER);
+            if (!alreadyInstalled) {
+                existingEntries.push(pitMatcher);
+            }
+        }
+        await fs.writeFile(settingsPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+    }
+    /**
+     * Write agent instructions to CLAUDE.md using PIT:MANAGED markers.
+     * Creates the section if absent; replaces it if present (idempotent).
+     * Preserves any content outside the managed section.
+     */
+    async writeInstructions(worktreeDir, content) {
+        const mdPath = path.join(worktreeDir, "CLAUDE.md");
+        let existing = "";
+        try {
+            existing = await fs.readFile(mdPath, "utf8");
+        }
+        catch {
+            // File does not exist — will create it
+        }
+        const managedSection = `${MANAGED_BEGIN}\n${content}\n${MANAGED_END}\n`;
+        let updated;
+        if (existing.includes(MANAGED_BEGIN) && existing.includes(MANAGED_END)) {
+            // Replace existing managed section (inclusive of markers)
+            const beginIdx = existing.indexOf(MANAGED_BEGIN);
+            const endIdx = existing.indexOf(MANAGED_END) + MANAGED_END.length;
+            // Include trailing newline if present
+            const afterEnd = existing[endIdx] === "\n" ? endIdx + 1 : endIdx;
+            updated = existing.slice(0, beginIdx) + managedSection + existing.slice(afterEnd);
+        }
+        else if (existing === "") {
+            // Empty file — write managed section directly without leading newlines
+            updated = managedSection;
+        }
+        else {
+            // Non-empty file without markers — append
+            updated = existing + "\n\n" + managedSection;
+        }
+        await fs.writeFile(mdPath, updated, "utf8");
+    }
+    /**
+     * Check whether the claude CLI is available on PATH.
+     * Returns true if `which claude` exits 0, false otherwise.
+     */
+    async checkInstalled() {
+        return new Promise((resolve) => {
+            execFile("which", ["claude"], (err) => {
+                resolve(!err);
+            });
+        });
+    }
+    /**
+     * Wait for Claude Code to be ready using a simple timeout.
+     */
+    async waitForReady({ timeoutMs }) {
+        await new Promise((resolve) => setTimeout(resolve, timeoutMs));
+    }
+    /**
+     * Verify the Claude Code process is running in the given tmux window.
+     *
+     * The tmux pane PID is the shell (zsh/bash), not claude itself.
+     * We walk the process tree rooted at the pane PID and check whether any
+     * descendant process has a comm of "claude" or "node".
+     */
+    async verifyRunning(tmuxSession, windowName) {
+        try {
+            const { stdout } = await execTmux("list-panes", "-t", `${tmuxSession}:${windowName}`, "-F", "#{pane_pid}");
+            const panePid = stdout.trim();
+            if (!panePid)
+                return false;
+            return await hasAgentDescendant(panePid, CLAUDE_CODE_COMM_NAMES);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=claude-code.js.map

package/dist/adapters/claude-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../src/adapters/claude-code.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Adapter factory — resolves the correct AgentAdapter based on the requested
+ * agent name, or auto-detects based on what is installed.
+ */
+import type { AgentAdapter } from "./types.js";
+/**
+ * Resolve an AgentAdapter by name.
+ *
+ * @param agent - "auto" | "opencode" | "claude-code"
+ * @returns The resolved adapter (Promise<AgentAdapter>)
+ *
+ * "auto" tries opencode first, then claude-code. Throws if neither is installed.
+ * Named agents throw if not installed.
+ */
+export declare function resolveAdapter(agent: string): Promise<AgentAdapter>;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAW/C;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCzE"}