@phnx-labs/agents-cli 1.20.4 → 1.20.5

package/dist/commands/tmux.js

@@ -0,0 +1,415 @@
+/**
+ * `agents tmux` — terminal multiplexer integration.
+ *
+ * Why this exists: the swarmify VS Code extension was hand-rolling tmux
+ * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
+ * Lifting the orchestration into the CLI gives one source of truth that the
+ * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
+ * call into.
+ *
+ * Surface mirrors `agents pty`:
+ *   agents tmux check
+ *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
+ *   agents tmux attach <name>
+ *   agents tmux list [--json]
+ *   agents tmux has <name>
+ *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
+ *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
+ *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
+ *   agents tmux info <name>    [--json]
+ *   agents tmux kill <name>
+ *   agents tmux kill-all       [--yes]
+ */
+import chalk from 'chalk';
+import * as path from 'path';
+import { setHelpSections } from '../lib/help.js';
+import { assertTmuxAvailable, attachTmux, capturePane, createSession, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, killAll, killSession, listSessions, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
+/** Register the `agents tmux` command tree. */
+export function registerTmuxCommands(program) {
+    const tmux = program
+        .command('tmux')
+        .description('Persistent terminal-multiplexer sessions for agents. Survive editor restarts, share with other tools.');
+    setHelpSections(tmux, {
+        examples: `
+      # Verify tmux is installed
+      agents tmux check
+
+      # Start a detached agent session
+      agents tmux new claude-debug --cmd "agents run claude" --cwd ~/code/myrepo
+
+      # Attach (replaces this shell with the tmux client)
+      agents tmux attach claude-debug
+
+      # Inspect remotely without attaching
+      agents tmux capture claude-debug --lines 200
+
+      # Send a slash command from a script
+      agents tmux send claude-debug "/clear"
+
+      # Clean up
+      agents tmux kill claude-debug
+    `,
+        notes: `
+      Storage:
+        Shared server socket: ~/.agents/.cache/helpers/tmux/server.sock
+        Per-session meta:     ~/.agents/.cache/helpers/tmux/<name>.json
+
+      Session names accept [A-Za-z0-9_-] up to 64 characters. tmux disallows
+      '.' and ':' in names since those address windows and panes.
+
+      Existing tmux sessions you started outside of agents-cli are NOT
+      visible here unless you point them at the same socket via --socket.
+    `,
+    });
+    // ─── check ──────────────────────────────────────────────────────────────────
+    const checkCmd = tmux
+        .command('check')
+        .description('Check whether tmux is installed and report its version.')
+        .option('--json', 'Output as JSON');
+    checkCmd.action((opts) => {
+        const installed = isTmuxInstalled();
+        const version = installed ? getTmuxVersion() : null;
+        if (opts.json) {
+            console.log(JSON.stringify({ installed, version, socket: getDefaultSocketPath() }));
+            return;
+        }
+        if (installed) {
+            console.log(chalk.green('tmux:'), version ?? '(version unknown)');
+            console.log(chalk.gray(`socket: ${getDefaultSocketPath()}`));
+        }
+        else {
+            console.log(chalk.yellow('tmux is not installed.'));
+            console.log(chalk.gray(process.platform === 'darwin'
+                ? '  Install with: brew install tmux'
+                : '  Install with: apt install tmux (or your distro equivalent)'));
+            process.exit(1);
+        }
+    });
+    // ─── new ────────────────────────────────────────────────────────────────────
+    const newCmd = tmux
+        .command('new <name>')
+        .description('Start a detached tmux session running a command. The session persists until killed.')
+        .option('-c, --cmd <command>', 'Command to launch in the first pane (sh -c). Omit for an empty shell.')
+        .option('-d, --cwd <dir>', 'Working directory for the first pane')
+        .option('-w, --width <n>', 'Initial window width in columns (tmux clamps to client size on attach)')
+        .option('-h, --height <n>', 'Initial window height in rows')
+        .option('-s, --source <source>', 'Provenance label: cli|extension|teams|external', 'cli')
+        .option('--label <k=v...>', 'Free-form labels (repeatable)', collectLabel, {})
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--replace', 'Kill any existing session with the same name first')
+        .option('--attach-existing', 'Return the existing session if one with this name already exists')
+        .option('--json', 'Output session meta as JSON');
+    setHelpSections(newCmd, {
+        examples: `
+      # Detached agent session
+      agents tmux new claude-debug --cmd "agents run claude"
+
+      # Reuse the session if it already exists (idempotent)
+      agents tmux new pair --cmd "agents run claude" --attach-existing
+
+      # Replace a stale session
+      agents tmux new pair --cmd "agents run claude" --replace
+    `,
+    });
+    newCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const meta = await createSession({
+                name,
+                cmd: opts.cmd,
+                cwd: opts.cwd ? path.resolve(opts.cwd) : undefined,
+                width: opts.width ? parseInt(opts.width, 10) : undefined,
+                height: opts.height ? parseInt(opts.height, 10) : undefined,
+                source: validateSource(opts.source),
+                labels: Object.keys(opts.label).length > 0 ? opts.label : undefined,
+                socket: opts.socket,
+                replace: !!opts.replace,
+                attachExisting: !!opts.attachExisting,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(meta));
+            }
+            else {
+                console.log(meta.name);
+            }
+        });
+    });
+    // ─── attach ─────────────────────────────────────────────────────────────────
+    const attachCmd = tmux
+        .command('attach <name>')
+        .description('Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d).')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    attachCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const socket = opts.socket ?? getDefaultSocketPath();
+            if (!(await hasSession(name, socket))) {
+                console.error(chalk.red(`No tmux session named "${name}".`));
+                process.exit(1);
+            }
+            if (!process.stdout.isTTY) {
+                console.error(chalk.red('attach requires a TTY. Run this from an interactive shell.'));
+                process.exit(1);
+            }
+            const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${name}`] });
+            process.exit(code);
+        });
+    });
+    // ─── list ───────────────────────────────────────────────────────────────────
+    const listCmd = tmux
+        .command('list')
+        .alias('ls')
+        .description('List live tmux sessions on the shared server. Prunes stale meta files as a side effect.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--json', 'Output as JSON');
+    listCmd.action(async (opts) => {
+        await guardTmux(async () => {
+            const sessions = await listSessions({ socket: opts.socket });
+            if (opts.json) {
+                console.log(JSON.stringify(sessions));
+                return;
+            }
+            if (sessions.length === 0) {
+                console.log(chalk.gray('No tmux sessions.'));
+                return;
+            }
+            for (const s of sessions) {
+                const age = formatAge(Date.now() / 1000 - s.createdAtTmux);
+                const cmd = s.meta?.cmd ? chalk.gray(`  ${truncate(s.meta.cmd, 60)}`) : '';
+                const attached = s.attached ? chalk.green(' [attached]') : '';
+                console.log(`  ${chalk.bold(s.name)}  ${s.windows}w  ${age}${attached}${cmd}`);
+            }
+        });
+    });
+    // ─── has ────────────────────────────────────────────────────────────────────
+    tmux
+        .command('has <name>')
+        .description('Exit 0 if a session with this name exists, 1 otherwise. Useful in shell scripts.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .action(async (name, opts) => {
+        await guardTmux(async () => {
+            const exists = await hasSession(name, opts.socket);
+            process.exit(exists ? 0 : 1);
+        });
+    });
+    // ─── split ──────────────────────────────────────────────────────────────────
+    const splitCmd = tmux
+        .command('split <name> <direction>')
+        .description('Split the active pane of a session. Direction: h (left/right) or v (top/bottom).')
+        .option('-c, --cmd <command>', 'Command to launch in the new pane')
+        .option('-d, --cwd <dir>', 'Working directory for the new pane')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--json', 'Output as JSON (returns new pane id like %3)');
+    setHelpSections(splitCmd, {
+        examples: `
+      # Split horizontally (panes side-by-side) and start a second agent
+      agents tmux split team h --cmd "agents run codex"
+
+      # Split vertically (panes stacked) — empty shell
+      agents tmux split team v
+    `,
+    });
+    splitCmd.action(async (name, direction, opts) => {
+        await guardTmux(async () => {
+            if (direction !== 'h' && direction !== 'v') {
+                console.error(chalk.red(`Invalid direction "${direction}". Use h or v.`));
+                process.exit(1);
+            }
+            const paneId = await splitPane({
+                name,
+                direction,
+                cmd: opts.cmd,
+                cwd: opts.cwd ? path.resolve(opts.cwd) : undefined,
+                socket: opts.socket,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ paneId }));
+            }
+            else {
+                console.log(paneId);
+            }
+        });
+    });
+    // ─── send ───────────────────────────────────────────────────────────────────
+    const sendCmd = tmux
+        .command('send <target> <keys>')
+        .description('Send keystrokes to a session. Target is "name" or "name:pane" (e.g. team:%2 or team:1).')
+        .option('--no-enter', 'Do not append Enter after the keys')
+        .option('--raw', 'Send literally (-l) without tmux key-name interpretation (C-c, Enter, etc.)')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    setHelpSections(sendCmd, {
+        examples: `
+      # Type a command into the session and press Enter
+      agents tmux send team "echo hello"
+
+      # Send Ctrl-C to interrupt
+      agents tmux send team "C-c"
+
+      # Send literal text (no key-name interpretation)
+      agents tmux send team "C-c" --raw
+
+      # Target a specific pane
+      agents tmux send team:%2 "ls -la"
+    `,
+    });
+    sendCmd.action(async (target, keys, opts) => {
+        await guardTmux(async () => {
+            const { name, pane } = splitTarget(target);
+            await sendKeys({
+                name,
+                pane,
+                keys,
+                noEnter: !opts.enter,
+                raw: !!opts.raw,
+                socket: opts.socket,
+            });
+        });
+    });
+    // ─── capture ────────────────────────────────────────────────────────────────
+    const captureCmd = tmux
+        .command('capture <target>')
+        .description('Print the contents of a pane. Target is "name" or "name:pane".')
+        .option('-l, --lines <n>', 'Include this many extra history lines above the visible screen')
+        .option('--ansi', 'Keep ANSI escape codes (default strips them)')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    setHelpSections(captureCmd, {
+        examples: `
+      # See current screen
+      agents tmux capture team
+
+      # Include the last 500 history lines
+      agents tmux capture team --lines 500
+
+      # Target a specific pane
+      agents tmux capture team:%3
+    `,
+    });
+    captureCmd.action(async (target, opts) => {
+        await guardTmux(async () => {
+            const { name, pane } = splitTarget(target);
+            const text = await capturePane({
+                name,
+                pane,
+                lines: opts.lines ? parseInt(opts.lines, 10) : undefined,
+                ansi: !!opts.ansi,
+                socket: opts.socket,
+            });
+            process.stdout.write(text);
+            if (!text.endsWith('\n'))
+                process.stdout.write('\n');
+        });
+    });
+    // ─── info ───────────────────────────────────────────────────────────────────
+    const infoCmd = tmux
+        .command('info <name>')
+        .description('Show provenance for a session (cmd, cwd, created_at, source, labels).')
+        .option('--json', 'Output as JSON');
+    infoCmd.action(async (name, opts) => {
+        const meta = readSessionMeta(name);
+        if (!meta) {
+            console.error(chalk.yellow(`No meta for "${name}" (session may exist but wasn't created via agents tmux).`));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(meta, null, 2));
+            return;
+        }
+        printMeta(meta);
+    });
+    // ─── kill ───────────────────────────────────────────────────────────────────
+    const killCmd = tmux
+        .command('kill <name>')
+        .description('Kill one tmux session. Idempotent — exits 0 even if the session was already gone.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    killCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const killed = await killSession(name, opts.socket);
+            if (!killed) {
+                console.log(chalk.gray(`No session "${name}" — nothing to do.`));
+            }
+        });
+    });
+    // ─── kill-all ───────────────────────────────────────────────────────────────
+    const killAllCmd = tmux
+        .command('kill-all')
+        .description('Kill every session on the shared server and remove the socket. Requires --yes.')
+        .option('--yes', 'Confirm — required, no interactive prompt')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    killAllCmd.action(async (opts) => {
+        await guardTmux(async () => {
+            if (!opts.yes) {
+                console.error(chalk.red('Refusing to kill-all without --yes.'));
+                process.exit(1);
+            }
+            const n = await killAll(opts.socket);
+            console.log(chalk.gray(`Killed ${n} session${n === 1 ? '' : 's'}.`));
+        });
+    });
+}
+// ─── helpers ──────────────────────────────────────────────────────────────────
+/** Wrap a command action so tmux-specific errors render cleanly instead of throwing. */
+async function guardTmux(fn) {
+    try {
+        assertTmuxAvailable();
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof TmuxUnavailableError) {
+            console.error(chalk.red(err.message));
+            process.exit(127);
+        }
+        if (err instanceof TmuxSessionError) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        if (err instanceof TmuxCommandError) {
+            console.error(chalk.red(err.message));
+            process.exit(err.code ?? 1);
+        }
+        throw err;
+    }
+}
+/** Parse `name` or `name:pane` (pane may be `%id` or a numeric index). */
+function splitTarget(target) {
+    const idx = target.indexOf(':');
+    if (idx === -1)
+        return { name: target };
+    return { name: target.slice(0, idx), pane: target.slice(idx + 1) || undefined };
+}
+function validateSource(s) {
+    if (s === 'cli' || s === 'extension' || s === 'teams' || s === 'external')
+        return s;
+    return 'cli';
+}
+function collectLabel(value, acc) {
+    const eq = value.indexOf('=');
+    if (eq === -1)
+        return acc;
+    acc[value.slice(0, eq)] = value.slice(eq + 1);
+    return acc;
+}
+function formatAge(secs) {
+    if (secs < 60)
+        return `${Math.max(0, Math.floor(secs))}s`;
+    const m = Math.floor(secs / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+function printMeta(m) {
+    console.log(`  ${chalk.bold('name')}       ${m.name}`);
+    console.log(`  ${chalk.bold('socket')}     ${m.socket}`);
+    console.log(`  ${chalk.bold('createdAt')}  ${new Date(m.createdAt).toISOString()}`);
+    console.log(`  ${chalk.bold('source')}     ${m.source}`);
+    if (m.cwd)
+        console.log(`  ${chalk.bold('cwd')}        ${m.cwd}`);
+    if (m.cmd)
+        console.log(`  ${chalk.bold('cmd')}        ${m.cmd}`);
+    if (m.labels) {
+        for (const [k, v] of Object.entries(m.labels)) {
+            console.log(`  ${chalk.bold('label')}      ${k}=${v}`);
+        }
+    }
+}

package/dist/commands/trash.d.ts

@@ -1,10 +1,10 @@
 /**
  * `agents trash` — list and restore soft-deleted version directories.
  *
- * `removeVersion` moves a version dir to ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/
+ * `removeVersion` moves a version dir to ~/.agents/.history/trash/versions/<agent>/<version>/<timestamp>/
  * instead of hard-deleting. These commands let the user inspect what's there
  * and put a soft-deleted version back. The trash never auto-expires; only
- * `rm -rf ~/.agents-system/trash/` removes bytes from disk.
+ * `rm -rf ~/.agents/.history/trash/` removes bytes from disk.
  */
 import type { Command } from 'commander';
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -143,7 +143,7 @@ export function registerTrashCommands(program) {
     });
     trash
         .command('restore <target>')
-        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents-system/versions/')
+        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
         .action((target) => {
         const parsed = parseAgentVersion(target);
         if (!parsed) {

package/dist/commands/versions.js

@@ -461,11 +461,11 @@ export function registerVersionsCommands(program) {
     useCmd.action(async (agentArg, versionArg, options) => {
         try {
             const skipPrompts = options.yes || !isInteractiveTerminal();
-            // Auto-pull ~/.agents-system if it's a git repo with remote (silent on success)
+            // Auto-pull ~/.agents/.system if it's a git repo with remote (silent on success)
             const agentsDir = getAgentsDir();
             const pullResult = await tryAutoPull(agentsDir);
             if (pullResult.pulled) {
-                console.log(chalk.gray('Synced ~/.agents-system from remote'));
+                console.log(chalk.gray('Synced ~/.agents/.system from remote'));
             }
             // Support both "claude 2.0.65" and "claude@2.0.65" formats
             let agent;

package/dist/commands/view.js

@@ -8,15 +8,15 @@ import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
-import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
+import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
-import { PLUGINS_CAPABLE_AGENTS } from '../lib/agents.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
 import { listProfiles, profileSummary } from '../lib/profiles.js';
+import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
@@ -519,6 +519,11 @@ async function showInstalledVersions(filterAgentId) {
     if (filterAgentId && versionManaged.length > 0) {
         const defaultVersion = getGlobalDefault(filterAgentId);
         if (defaultVersion) {
+            const manifest = loadManifest(filterAgentId, defaultVersion);
+            const cwd = process.cwd();
+            if (manifest && !isStale(manifest, filterAgentId, defaultVersion, cwd)) {
+                return;
+            }
             const available = getAvailableResources();
             const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
             const projectOnly = getProjectOnlyResources();
@@ -750,10 +755,10 @@ async function showAgentResources(agentId, requestedVersion) {
         }
     }
     renderSection('MCP Servers', agentData.mcp);
-    if (WORKFLOW_CAPABLE_AGENTS.includes(agentId)) {
+    if (isCapable(agentId, 'workflows')) {
         renderSection('Workflows', agentData.workflows);
     }
-    if (PLUGINS_CAPABLE_AGENTS.includes(agentId)) {
+    if (isCapable(agentId, 'plugins')) {
         const plugins = discoverPlugins().filter(p => pluginSupportsAgent(p, agentId));
         console.log(chalk.bold('\nPlugins\n'));
         if (plugins.length === 0) {

package/dist/commands/workflows.js

@@ -5,8 +5,9 @@ import * as os from 'os';
 import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
 import { resolveAgentName, agentLabel } from '../lib/agents.js';
+import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { WORKFLOW_CAPABLE_AGENTS, discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
+import { discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
 import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
@@ -210,7 +211,7 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = await resolveAgentTargetsAutoInstalling(options.agents, WORKFLOW_CAPABLE_AGENTS, { yes: options.yes });
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, capableAgents('workflows'), { yes: options.yes });
                 if (!result) {
                     console.log(chalk.gray('Cancelled.'));
                     return;
@@ -219,7 +220,7 @@ Examples:
                 versionSelections = result.versionSelections;
             }
             else {
-                const result = await promptAgentVersionSelection(WORKFLOW_CAPABLE_AGENTS, {
+                const result = await promptAgentVersionSelection(capableAgents('workflows'), {
                     skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;

package/dist/commands/worktree.d.ts

@@ -10,11 +10,10 @@
  *   agents worktree release   <terminal-id>   -> removes if clean + merged
  *   agents worktree prune                     -> removes every clean+merged one
  *
- * Worktrees live at <repo>/.history/worktrees/<terminal-id>, on a branch
- * named agent/<terminal-id>. The branch starts at HEAD of the parent repo.
- * .history/ mirrors the agents-cli runtime-state convention at ~/.agents/.history/
- * but scoped to the repo. .agents/ is reserved for project resources
- * (skills, hooks, commands) per the agents-cli DotAgents repo layout.
+ * Worktrees live at <repo>/.agents/worktrees/<terminal-id>, on a branch
+ * named agents/<terminal-id>. The branch starts at HEAD of the parent repo.
+ * This matches the agent-system rule that keeps all coding-agent worktrees
+ * under the repo-local .agents/ state directory.
  */
 import type { Command } from 'commander';
 export declare function registerWorktreeCommands(program: Command): void;

package/dist/commands/worktree.js

@@ -6,8 +6,8 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 const execFileAsync = promisify(execFile);
-const WORKTREE_SUBDIR = path.join('.history', 'worktrees');
-const BRANCH_PREFIX = 'agent/';
+const WORKTREE_SUBDIR = path.join('.agents', 'worktrees');
+const BRANCH_PREFIX = 'agents/';
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
     process.exit(code);
@@ -165,7 +165,7 @@ export function registerWorktreeCommands(program) {
       agents worktree prune
     `,
         notes: `
-      Worktrees live at <repo>/.history/worktrees/<terminal-id> on branch agent/<terminal-id>.
+      Worktrees live at <repo>/.agents/worktrees/<terminal-id> on branch agents/<terminal-id>.
       Use --force on 'release' to skip safety checks (DANGEROUS — discards unpushed work).
     `,
     });
@@ -198,7 +198,7 @@ export function registerWorktreeCommands(program) {
         }
     });
     wt.command('prune')
-        .description('Try to release every agent worktree under .history/worktrees/. Skips dirty or unpushed ones.')
+        .description('Try to release every agent worktree under .agents/worktrees/. Skips dirty or unpushed ones.')
         .option('--root <path>', 'Repo root (defaults to current working directory)')
         .option('--dry-run', 'Report what would be removed without touching anything')
         .action(async (opts) => {