@clipboard-health/groundcrew 4.9.0 → 4.10.0

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  Dispatch your ticket backlog to AI coding agents. One git worktree per ticket, sandboxed by default.
+  Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.
 </p>
 
 <p align="center">
@@ -17,16 +17,22 @@
 </p>
 
 <p align="center">
-  <img alt="Groundcrew picking up tickets and running coding agents in parallel" src="./static/demo.gif" width="800">
+  <a href="./static/demo.tape"><img alt="Groundcrew dispatching tickets into tmux panes with coding agents running in parallel" src="./static/demo.gif" width="800"></a>
+</p>
+
+<p align="center">
+  VHS source: <a href="./static/demo.tape">static/demo.tape</a>.
 </p>
 
 Groundcrew watches assigned tickets, creates isolated worktrees, launches agent CLIs in dedicated terminals, and leaves each ticket's work on its own PR-ready branch. For the backstory, read _[Tickets to pull requests while you sleep](https://www.clipboardworks.com/resources/blog/tickets-to-pull-requests-while-you-sleep)_.
 
 ## Why
 
+- **Local.** Agents run on your machine with your tools, shell, and credentials. That makes them more steerable than remote agents, and easy to nudge when they drift.
+- **Interactive.** Each ticket launches the real `claude` or `codex` CLI in its own terminal pane, not a wrapper that approximates it. Watch any session live and take over when you need to.
 - **One worktree per ticket.** Agents work in parallel without stepping on each other.
+- **Sandboxed by default.** Safehouse or Docker Sandboxes isolate each agent on the host; `none` is an explicit escape hatch.
 - **Pluggable ticket sources.** Linear by default; Jira and local files via [ticket sources](./docs/ticket-sources.md).
-- **Local-first isolation.** Safehouse, Docker Sandboxes, or an explicit `none` escape hatch.
 - **Multi-agent routing.** Ships `claude` and `codex` presets; bring your own CLI in config.
 
 ## Prerequisites
@@ -83,8 +89,7 @@ crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.
           [--runner <auto|safehouse|sdx|none>] [--model <claude|codex>]
 crew doctor                                              # check setup
 crew status [<TICKET>]                                   # inspect current state or one ticket
-crew run                                                 # one-shot orchestration
-crew run --watch                                         # poll forever
+crew run [--watch]                                       # one-shot or --watch forever
 crew start <TICKET>                                      # provision + launch one ticket now
 crew stop <TICKET> [--reason <text>]                     # stop workspace, keep worktree
 crew resume <TICKET>                                     # reopen a paused ticket
@@ -106,15 +111,18 @@ export default {
     projectDir: "~/dev",
     knownRepositories: ["OWNER/REPO"],
   },
-  local: {
-    runner: "auto",
-  },
   models: {
     default: "claude",
     definitions: {
       claude: {},
     },
   },
+  defaults: {
+    hooks: {
+      // No-op placeholder; replace with your repo's setup, e.g. "npm ci".
+      prepareWorktree: "true",
+    },
+  },
 } satisfies Config;
 ```
 
@@ -143,6 +151,12 @@ node --run crew:op -- run --watch
 
 Both forms discover config through cosmiconfig. Source edits in `src/**` are picked up on the next invocation. Requires Node >= 24.
 
+Regenerate the README demo with VHS:
+
+```bash
+./static/render-demo.sh
+```
+
 ## License
 
 [MIT](./LICENSE)

package/clearance-allow-hosts

@@ -64,8 +64,9 @@ raw.githubusercontent.com
 release-assets.githubusercontent.com
 results-receiver.actions.githubusercontent.com
 
-# npm registry + package website
+# npm/Conda registries + package websites
 api.npmjs.org
+conda.anaconda.org
 registry.npmjs.org
 www.npmjs.com
 
@@ -83,6 +84,9 @@ formulae.brew.sh
 hub.docker.com
 index.docker.io
 json.schemastore.org
+mise-versions.jdx.dev
 nx.dev
+playwright.azureedge.net
+registry.terraform.io
 sourcegraph.com
 vitest.dev

package/crew.config.example.ts

@@ -35,6 +35,15 @@ export default {
       // },
     },
   },
+  // Repo-preparation hook: runs after each worktree is created and before the
+  // agent launches. The default below is a no-op placeholder. Replace it with
+  // your repo's setup, e.g. "npm ci" or "uv sync --dev --frozen". A repo-local
+  // `.groundcrew/config.json` hooks.prepareWorktree overrides this per repo.
+  defaults: {
+    hooks: {
+      prepareWorktree: "true",
+    },
+  },
   // Everything below is optional — defaults shown for reference. Uncomment
   // and edit to override.
   //
@@ -59,14 +68,6 @@ export default {
   //
   // git: { remote: "origin", defaultBranch: "main" },
   //
-  // // Fallback repo-preparation hook for repos that do not define
-  // // `.groundcrew/config.json` hooks.prepareWorktree. Repo-local config wins.
-  // defaults: {
-  //   hooks: {
-  //     prepareWorktree: "test ! -f package-lock.json || npm ci",
-  //   },
-  // },
-  //
   // orchestrator: {
   //   maximumInProgress: 4,
   //   pollIntervalMilliseconds: 120_000,

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuKH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA8E/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8KH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAgF/C"}

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@
 import { existsSync, statSync } from "node:fs";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { loadConfig, } from "../lib/config.js";
+import { loadConfigWithSource, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
 import { gatedModels } from "../lib/usage.js";
@@ -15,6 +15,11 @@ import { resolveWorkspaceKind } from "../lib/workspaces.js";
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
 const MAX_TOKENS_PER_CMD = 2;
 const BUILT_IN_MODEL_NAMES = ["claude", "codex"];
+const CONFIG_SOURCE_LABELS = {
+    env: "GROUNDCREW_CONFIG",
+    project: "project",
+    xdg: "global XDG",
+};
 async function checkCmd(cmd, required, hint) {
     const path = await which(cmd);
     const resolvedHint = path ?? hint;
@@ -148,8 +153,10 @@ export async function doctor() {
     writeOutput("=================");
     let config;
     try {
-        config = await loadConfig();
-        writeOutput("[ok] config loaded");
+        const { config: loadedConfig, source } = await loadConfigWithSource();
+        config = loadedConfig;
+        const sourceLabel = CONFIG_SOURCE_LABELS[source.kind];
+        writeOutput(`[ok] config loaded — ${source.filepath} (${sourceLabel})`);
     }
     catch (error) {
         writeOutput(`[--] config: ${errorMessage(error)}`);

package/dist/lib/config.d.ts

@@ -241,6 +241,15 @@ export interface ResolvedConfig {
         file: string;
     };
 }
+export type ConfigSourceKind = "env" | "project" | "xdg";
+export interface ConfigSource {
+    kind: ConfigSourceKind;
+    filepath: string;
+}
+export interface LoadedConfig {
+    config: Readonly<ResolvedConfig>;
+    source: Readonly<ConfigSource>;
+}
 /**
  * Single source of truth for "is preLaunchEnv asking us to forward anything?"
  *
@@ -258,5 +267,6 @@ export declare function hasPreLaunchEnv(definition: Pick<ModelDefinition, "preLa
  * not enabled from an arbitrary unknown label like `agent-typo`.
  */
 export declare function isBuiltInModelNotEnabled(config: Pick<ResolvedConfig, "models">, name: string): boolean;
+export declare function loadConfigWithSource(): Promise<Readonly<LoadedConfig>>;
 export declare function loadConfig(): Promise<Readonly<ResolvedConfig>>;
 //# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.js

@@ -606,26 +606,28 @@ async function discoverUserConfig() {
         if (!existsSync(overridePath)) {
             fail(`GROUNDCREW_CONFIG=${overridePath} not found`);
         }
-        return await loadAt(overridePath);
+        const result = await loadAt(overridePath);
+        return { result, source: { kind: "env", filepath: result.filepath } };
     }
     const project = await explorer.search(process.cwd());
     if (project !== null && project.isEmpty !== true) {
-        return project;
+        return { result: project, source: { kind: "project", filepath: project.filepath } };
     }
     const xdgPath = findXdgConfigFile();
     if (xdgPath !== undefined) {
-        return await loadAt(xdgPath);
+        const result = await loadAt(xdgPath);
+        return { result, source: { kind: "xdg", filepath: result.filepath } };
     }
     // Throw directly so oxlint's `consistent-return` rule sees a
     // terminating statement; it doesn't track `fail()`'s `never` return.
     throw new Error(`groundcrew config: no crew config found. Create crew.config.ts in your project root, or ${xdgConfigPath("groundcrew", "crew.config.ts")}, or set GROUNDCREW_CONFIG.`);
 }
 let cached;
-export async function loadConfig() {
+export async function loadConfigWithSource() {
     if (cached) {
         return cached;
     }
-    const result = await discoverUserConfig();
+    const { result, source } = await discoverUserConfig();
     const { filepath, isEmpty } = result;
     const userConfig = result.config;
     if (isEmpty === true || !isPlainObject(userConfig)) {
@@ -636,6 +638,13 @@ export async function loadConfig() {
     const resolved = applyDefaults(userConfig);
     validate(resolved);
     setLogFile(resolved.logging.file);
-    cached = Object.freeze(resolved);
+    cached = Object.freeze({
+        config: Object.freeze(resolved),
+        source: Object.freeze(source),
+    });
     return cached;
 }
+export async function loadConfig() {
+    const loadedConfig = await loadConfigWithSource();
+    return loadedConfig.config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -84,7 +84,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "@vitest/coverage-v8": "4.1.7",
     "cspell": "10.0.0",
-    "dependency-cruiser": "17.4.2",
+    "dependency-cruiser": "17.4.3",
     "husky": "9.1.7",
     "jscpd": "4.2.4",
     "knip": "6.14.2",

package/static/demo-fixture.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Semantic ANSI colors. Actual hues are defined by the VHS theme in demo.tape,
+# so content and chrome stay in sync: green = orchestrator, yellow = codex,
+# blue = claude, bright-black = dim chrome.
+c_reset=$'\033[0m'
+c_dim=$'\033[90m'
+c_green=$'\033[32m'
+c_amber=$'\033[33m'
+c_blue=$'\033[34m'
+
+export PS1="\[${c_green}\]groundcrew\[${c_dim}\] on \[${c_reset}\]main \[${c_green}\]\$\[${c_reset}\] "
+
+tmux rename-window 'crew run --watch'
+tmux set-option -g status off
+tmux set-option -g pane-border-status top
+tmux set-option -g pane-border-format ' #{?#{m:codex*,#{pane_title}},#[fg=#fbbf24],#{?#{m:claude*,#{pane_title}},#[fg=#60a5fa],#[fg=#77d94e]}}#[bold]#{pane_title}#[default] '
+tmux set-option -g pane-border-style 'fg=#3f3f46'
+tmux set-option -g pane-active-border-style 'fg=#77d94e'
+tmux set-option -g remain-on-exit on
+
+printf '\033]2;groundcrew\033\\'
+
+demo_agent_script="$(mktemp "${TMPDIR:-/tmp}/groundcrew-vhs-agent.XXXXXX")"
+trap 'rm -f "${demo_agent_script}"' EXIT
+cat >"${demo_agent_script}" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+ticket="${1}"
+model="${2}"
+title="${3}"
+worktree="${4:-groundcrew-${ticket}}"
+branch="groundcrew/${ticket}"
+
+reset=$'\033[0m'
+bold=$'\033[1m'
+dim=$'\033[90m'
+green=$'\033[32m'
+case "${model}" in
+  codex) accent=$'\033[33m' ;;
+  claude) accent=$'\033[34m' ;;
+  *) accent=$'\033[32m' ;;
+esac
+
+printf '\033]2;%s %s\033\\' "${model}" "${ticket}"
+printf '%s%s%s    clipboard/groundcrew\n' "${dim}" 'repo' "${reset}"
+printf '%s%s%s  %s\n\n' "${dim}" 'branch' "${reset}" "${branch}"
+sleep 0.4
+printf '%s$%s %s%s%s %s< prompts/%s.txt%s\n\n' "${dim}" "${reset}" "${accent}" "${model}" "${reset}" "${dim}" "${ticket}" "${reset}"
+sleep 0.5
+printf '%sTicket%s    %s\n' "${dim}" "${reset}" "${title}"
+sleep 0.4
+printf '%sWorktree%s  %s~/dev/c/%s%s\n\n' "${dim}" "${reset}" "${dim}" "${worktree}" "${reset}"
+sleep 0.5
+printf '%sReading repo context...%s\n' "${dim}" "${reset}"
+sleep 0.5
+printf '%sEditing in isolated branch...%s\n' "${dim}" "${reset}"
+sleep 0.5
+printf '%sRunning verification...%s\n' "${dim}" "${reset}"
+sleep 0.5
+printf '%s%s✓ Ready for review.%s\n' "${green}" "${bold}" "${reset}"
+
+while :; do
+  sleep 60
+done
+SH
+chmod +x "${demo_agent_script}"
+
+demo_ts_second=18
+
+demo_log() {
+  printf '%s[15:23:%02d]%s %s\n' "${c_dim}" "${demo_ts_second}" "${c_reset}" "${1}"
+  demo_ts_second=$((demo_ts_second + 1))
+}
+
+crew() {
+  if [[ "${1:-}" != "run" || "${2:-}" != "--watch" ]]; then
+    printf '%s\n' 'demo supports: crew run --watch'
+    return 2
+  fi
+
+  local pane_one
+
+  demo_log "${c_dim}Linear viewer ·${c_reset} Rocky Warren"
+  sleep 0.5
+  demo_log "${c_dim}Slots${c_reset} 0/3 ${c_dim}· dispatching${c_reset} ${c_amber}ENG-184${c_reset}${c_dim},${c_reset} ${c_blue}ENG-217${c_reset}"
+  sleep 0.6
+
+  demo_log "${c_dim}Worktree${c_reset} web-ENG-184 ${c_dim}→${c_reset} groundcrew/ENG-184"
+  sleep 0.5
+  pane_one="$(
+    tmux split-window -d -h -p 42 -P -F '#{pane_id}' -- \
+      "${demo_agent_script} ENG-184 codex 'Add Jira ticket source docs' web-ENG-184"
+  )"
+  sleep 0.7
+  demo_log "${c_green}✓${c_reset} ${c_amber}ENG-184${c_reset} launched ${c_dim}·${c_reset} ${c_amber}codex${c_reset}"
+  sleep 0.7
+
+  demo_log "${c_dim}Worktree${c_reset} api-ENG-217 ${c_dim}→${c_reset} groundcrew/ENG-217"
+  sleep 0.5
+  tmux split-window -d -v -p 50 -t "${pane_one}" -P -F '#{pane_id}' -- \
+    "${demo_agent_script} ENG-217 claude 'Fix flaky status output' api-ENG-217" >/dev/null
+  sleep 0.7
+  demo_log "${c_green}✓${c_reset} ${c_blue}ENG-217${c_reset} launched ${c_dim}·${c_reset} ${c_blue}claude${c_reset}"
+  sleep 0.7
+
+  demo_log "${c_dim}Queue clear · next poll in 60s${c_reset}"
+  sleep 8
+}

package/static/demo.tape

@@ -0,0 +1,42 @@
+# cspell:ignore noprofile norc ttyd
+
+Output static/demo.gif
+Require bash
+Require ffmpeg
+Require tmux
+Require ttyd
+
+Set Shell "bash"
+Set Width 1320
+Set Height 560
+Set FontSize 16
+Set FontFamily "Menlo"
+Set Padding 16
+Set Margin 40
+Set MarginFill "#0a0a0b"
+Set WindowBar Colorful
+Set BorderRadius 12
+Set TypingSpeed 35ms
+Set CursorBlink false
+Set Theme '{ "background": "#18181b", "foreground": "#e4e4e7", "cursor": "#77d94e", "selection": "#3f3f46", "black": "#27272a", "red": "#fb7185", "green": "#77d94e", "yellow": "#fbbf24", "blue": "#60a5fa", "magenta": "#c084fc", "cyan": "#34d399", "white": "#e4e4e7", "brightBlack": "#52525b", "brightRed": "#fda4af", "brightGreen": "#a3e635", "brightYellow": "#fcd34d", "brightBlue": "#93c5fd", "brightMagenta": "#d8b4fe", "brightCyan": "#6ee7b7", "brightWhite": "#fafafa" }'
+
+Hide
+Type "tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true"
+Enter
+Type "tmux -f /dev/null -L groundcrew-demo new-session -s groundcrew -- /bin/bash --noprofile --norc"
+Enter
+Type "source static/demo-fixture.sh"
+Enter
+Type "clear"
+Enter
+Show
+
+Sleep 1.0
+Type "crew run --watch"
+Sleep 0.4
+Enter
+Sleep 9
+
+Hide
+Type "tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew"
+Enter

package/static/render-demo.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# cspell:ignore ttyd
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo_dir="$(cd -- "${script_dir}/.." && pwd)"
+cd "${repo_dir}"
+
+for required_command in vhs ttyd tmux ffmpeg; do
+  if ! command -v "${required_command}" >/dev/null 2>&1; then
+    printf 'Missing required command: %s\n' "${required_command}" >&2
+    exit 127
+  fi
+done
+
+tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true
+
+log_file="$(mktemp)"
+trap 'rm -f "${log_file}"' EXIT
+
+for attempt in 1 2 3; do
+  rm -f "${log_file}"
+
+  if VHS_NO_SANDBOX="${VHS_NO_SANDBOX:-1}" vhs static/demo.tape 2>&1 | tee "${log_file}"; then
+    exit 0
+  fi
+
+  status="${PIPESTATUS[0]}"
+  tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true
+
+  if ! grep -Eq 'could not open ttyd|ERR_CONNECTION_REFUSED' "${log_file}"; then
+    exit "${status}"
+  fi
+
+  if [[ "${attempt}" -eq 3 ]]; then
+    exit "${status}"
+  fi
+
+  sleep "${attempt}"
+done