mintree 0.1.2 → 0.1.4

package/README.md

@@ -16,19 +16,13 @@ It is a smaller, opinionated cousin of [santree](https://github.com/santiagotosc
 ## Install
 
 ```bash
-# mintree isn't on npm yet. Install via git clone + npm link — the
-# `npm install -g github:user/repo` flow has a known bug in npm 10+
-# where dependencies don't make it into the global install dir.
-git clone git@github.com:minex-labs/mintree.git ~/dev/mintree
-cd ~/dev/mintree
-npm install
-npm link
+npm install -g mintree
 
-# To upgrade later:
-#   cd ~/dev/mintree && git pull && npm install && npm run build
+# Upgrade later:
+#   npm update -g mintree
 
 # Verify
-mintree --version          # → 0.1.0
+mintree --version          # should match the latest published version
 mintree doctor             # checks toolchain (git, gh, claude, tmux, ...)
 
 # Enable the shell wrapper so `mintree worktree create` and the
@@ -50,6 +44,8 @@ _MT=${XDG_CACHE_HOME:-$HOME/.cache}/mintree/init-bash.bash
 EOF
 ```
 
+> Working on mintree itself? Clone the repo, run `npm install` and `npm link` instead — that wires `mintree` to your local checkout so source edits show up after `npm run build`.
+
 `mintree doctor` should report **all required checks pass** before you continue. The most common gaps are:
 
 - `gh` not authenticated → `gh auth login`

package/dist/commands/dashboard.js

@@ -5,12 +5,12 @@ import TextInput from "ink-text-input";
 import Spinner from "ink-spinner";
 import { execSync } from "child_process";
 import { createRequire } from "module";
-import { findBranchConventionDoc, findMainRepoRoot, getMintreeDir, pathExists, } from "../lib/git.js";
+import { findBranchConventionDoc, findMainRepoRoot, getCurrentBranch, getMintreeDir, pathExists, } from "../lib/git.js";
 import { resolveClaudeBinary } from "../lib/claude.js";
 import { tryExec } from "../lib/exec.js";
 import { ALLOWED_TYPES } from "../lib/branch.js";
-import { runCreate } from "../lib/worktreeCreate.js";
-import { runRemove } from "../lib/worktreeRemove.js";
+import { runCreate, runCreateDetached } from "../lib/worktreeCreate.js";
+import { runRemove, runRemoveByPath } from "../lib/worktreeRemove.js";
 import { buildCreateMarkers, emitMarkers } from "../lib/markers.js";
 import { loadDashboard, } from "../lib/dashboard.js";
 const require = createRequire(import.meta.url);
@@ -160,7 +160,7 @@ function FooterRow({ phase, overlayKind, }) {
         return (_jsx(Box, { children: _jsx(Text, { dimColor: true, children: "q quit" }) }));
     }
     if (overlayKind === "create") {
-        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Tab" }), _jsx(Text, { dimColor: true, children: " switch field   " }), _jsx(Text, { bold: true, children: "\u2190/\u2192" }), _jsx(Text, { dimColor: true, children: " change type   " }), _jsx(Text, { bold: true, children: "Enter" }), _jsx(Text, { dimColor: true, children: " create + work" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Esc" }), _jsx(Text, { dimColor: true, children: " cancel" })] })] }));
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Tab" }), _jsx(Text, { dimColor: true, children: " switch field   " }), _jsx(Text, { bold: true, children: "\u2190/\u2192" }), _jsx(Text, { dimColor: true, children: " toggle branch / cycle type   " }), _jsx(Text, { bold: true, children: "Enter" }), _jsx(Text, { dimColor: true, children: " create + work" })] }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "Esc" }), _jsx(Text, { dimColor: true, children: " cancel" })] })] }));
     }
     if (overlayKind === "remove") {
         return (_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "y/Y" }), _jsx(Text, { dimColor: true, children: " confirm   " }), _jsx(Text, { bold: true, children: "n/Esc" }), _jsx(Text, { dimColor: true, children: " cancel" })] }));
@@ -168,12 +168,21 @@ function FooterRow({ phase, overlayKind, }) {
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "j/k" }), _jsx(Text, { dimColor: true, children: " nav   " }), _jsx(Text, { bold: true, children: "\u21B5" }), _jsx(Text, { dimColor: true, children: " work (resume / create)   " }), _jsx(Text, { bold: true, children: "w" }), _jsx(Text, { dimColor: true, children: " work (always create)   " }), _jsx(Text, { bold: true, children: "d" }), _jsx(Text, { dimColor: true, children: " remove" })] }) }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "r" }), _jsx(Text, { dimColor: true, children: " refresh   " }), _jsx(Text, { bold: true, children: "o" }), _jsx(Text, { dimColor: true, children: " open in browser   " }), _jsx(Text, { bold: true, children: "PgUp/PgDn" }), _jsx(Text, { dimColor: true, children: "/" }), _jsx(Text, { bold: true, children: "wheel" }), _jsx(Text, { dimColor: true, children: " scroll detail   " }), _jsx(Text, { bold: true, children: "q" }), _jsx(Text, { dimColor: true, children: " quit" })] })] }));
 }
 function RemoveOverlayView({ overlay }) {
-    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Remove worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "Branch: " }), _jsx(Text, { color: "cyan", children: overlay.branch })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "State:  " }), overlay.dirty ? (_jsx(Text, { color: "yellow", children: "dirty (uncommitted changes will be lost)" })) : (_jsx(Text, { color: "green", children: "clean" }))] })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsx(Text, { dimColor: true, children: "Removing the worktree leaves the branch and the issue's session_id in place. You can re-attach later with `mintree worktree create`." }) }), _jsx(Box, { marginTop: 1, children: overlay.dirty ? (_jsxs(Text, { children: ["This worktree is dirty. Press ", _jsx(Text, { bold: true, color: "red", children: "Y" }), " to force-remove,", " ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) : (_jsxs(Text, { children: ["Press ", _jsx(Text, { bold: true, color: "green", children: "y" }), " to remove,", " ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
+    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Remove worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "Branch: " }), _jsx(Text, { color: "cyan", children: overlay.branch ?? `(detached) ${overlay.worktreePath}` })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "State:  " }), overlay.dirty ? (_jsx(Text, { color: "yellow", children: "dirty (uncommitted changes will be lost)" })) : (_jsx(Text, { color: "green", children: "clean" }))] })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsx(Text, { dimColor: true, children: "Removing the worktree leaves the branch and the issue's session_id in place. You can re-attach later with `mintree worktree create`." }) }), _jsx(Box, { marginTop: 1, children: overlay.dirty ? (_jsxs(Text, { children: ["This worktree is dirty. Press ", _jsx(Text, { bold: true, color: "red", children: "Y" }), " to force-remove,", " ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) : (_jsxs(Text, { children: ["Press ", _jsx(Text, { bold: true, color: "green", children: "y" }), " to remove,", " ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
 }
 function CreateOverlayView({ overlay, onDescChange, onPromptChange, }) {
     const labelWidth = 14;
-    const branchPreview = `${overlay.type}/${overlay.issue.issue.number}-${overlay.desc}`;
-    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Create worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "type", children: overlay.field === "type" ? "▸ Type:" : "  Type:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "type" ? "cyan" : undefined, bold: overlay.field === "type", children: overlay.type }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "type" && (_jsx(Text, { dimColor: true, children: "   (use ← / → to cycle)" }))] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "desc", children: overlay.field === "desc" ? "▸ Description:" : "  Description:" }) }), _jsx(Box, { children: overlay.field === "desc" ? (_jsx(TextInput, { value: overlay.desc, onChange: onDescChange, placeholder: "kebab-case" })) : (_jsx(Text, { children: overlay.desc || "(empty)" })) })] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "prompt", children: overlay.field === "prompt" ? "▸ Prompt:" : "  Prompt:" }) }), _jsx(Box, { children: overlay.field === "prompt" ? (_jsx(TextInput, { value: overlay.prompt, onChange: onPromptChange, placeholder: "(optional) initial message for Claude" })) : (_jsx(Text, { dimColor: true, children: overlay.prompt || "(optional — Claude starts with no message)" })) })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Branch:" }) }), _jsx(Text, { color: "green", children: branchPreview })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Mode:" }) }), _jsx(Text, { dimColor: true, children: "--work (Claude launches in the new worktree)" })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: ["Suggestion is a kebab of the title (capped at ", SUGGESTED_DESC_MAX_WORDS, " words). Edit it to match your repo's branch conventions."] }), overlay.conventionDoc && (_jsx(Text, { dimColor: true, children: `This repo has \`${overlay.conventionDoc}\` — review it before creating.` }))] }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
+    const isNewBranch = overlay.branchMode === "new";
+    const detachedDesc = kebabize(overlay.issue.issue.title) || `issue-${overlay.issue.issue.number}`;
+    const branchPreview = isNewBranch
+        ? `${overlay.type}/${overlay.issue.issue.number}-${overlay.desc}`
+        : `detached @ ${overlay.currentBranch ?? "(unknown)"}`;
+    const dirPreview = isNewBranch
+        ? `${overlay.issue.issue.number}-${overlay.desc}`
+        : `${overlay.issue.issue.number}-${detachedDesc}`;
+    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Create worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "branchMode", children: overlay.field === "branchMode" ? "▸ Branch:" : "  Branch:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "branchMode" ? "cyan" : undefined, bold: overlay.field === "branchMode", children: isNewBranch
+                                            ? "new"
+                                            : `current (${overlay.currentBranch ?? "?"})` }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "branchMode" && (_jsx(Text, { dimColor: true, children: "   (use ← / → to toggle)" }))] }), isNewBranch && (_jsxs(_Fragment, { children: [_jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "type", children: overlay.field === "type" ? "▸ Type:" : "  Type:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "type" ? "cyan" : undefined, bold: overlay.field === "type", children: overlay.type }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "type" && (_jsx(Text, { dimColor: true, children: "   (use ← / → to cycle)" }))] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "desc", children: overlay.field === "desc" ? "▸ Description:" : "  Description:" }) }), _jsx(Box, { children: overlay.field === "desc" ? (_jsx(TextInput, { value: overlay.desc, onChange: onDescChange, placeholder: "kebab-case" })) : (_jsx(Text, { children: overlay.desc || "(empty)" })) })] })] })), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "prompt", children: overlay.field === "prompt" ? "▸ Prompt:" : "  Prompt:" }) }), _jsx(Box, { children: overlay.field === "prompt" ? (_jsx(TextInput, { value: overlay.prompt, onChange: onPromptChange, placeholder: "(optional) initial message for Claude" })) : (_jsx(Text, { dimColor: true, children: overlay.prompt || "(optional — Claude starts with no message)" })) })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Checkout:" }) }), _jsx(Text, { color: "green", children: branchPreview })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Worktree:" }) }), _jsxs(Text, { dimColor: true, children: [".mintree/worktrees/", dirPreview] })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Mode:" }) }), _jsx(Text, { dimColor: true, children: "--work (Claude launches in the new worktree)" })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [isNewBranch ? (_jsxs(Text, { dimColor: true, children: ["Suggestion is a kebab of the title (capped at ", SUGGESTED_DESC_MAX_WORDS, " words). Edit it to match your repo's branch conventions."] })) : (_jsxs(Text, { dimColor: true, children: ["Detached HEAD at the tip of ", overlay.currentBranch ?? "the current branch", ". No new branch is created \u2014 commit on a new one with `git switch -c` when ready."] })), isNewBranch && overlay.conventionDoc && (_jsx(Text, { dimColor: true, children: `This repo has \`${overlay.conventionDoc}\` — review it before creating.` }))] }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
 }
 function stateChar(state) {
     if (!state)
@@ -296,7 +305,7 @@ function buildDetailLines(d, width) {
     lines.push(blank());
     lines.push([{ text: "⌥ Worktree", bold: true }]);
     if (d.worktree) {
-        for (const w2 of wrapLine(` branch: ${d.worktree.branch}`, w))
+        for (const w2 of wrapLine(` branch: ${d.worktree.branch ?? "(detached HEAD)"}`, w))
             lines.push([{ text: w2, dim: true }]);
         for (const w2 of wrapLine(` path:   ${d.worktree.path}`, w))
             lines.push([{ text: w2, dim: true }]);
@@ -638,6 +647,7 @@ export default function Dashboard() {
                     kind: "remove",
                     issue,
                     branch: issue.worktree.branch,
+                    worktreePath: issue.worktree.path,
                     dirty: issue.worktree.dirty,
                     error: null,
                 },
@@ -655,10 +665,12 @@ export default function Dashboard() {
             overlay: {
                 kind: "create",
                 issue,
+                branchMode: "new",
+                currentBranch: root ? getCurrentBranch(root) : null,
                 type: "feat",
                 desc: kebabize(issue.issue.title) || `issue-${issue.issue.number}`,
                 prompt: "",
-                field: "type",
+                field: "branchMode",
                 error: null,
                 conventionDoc: root ? findBranchConventionDoc(root) : null,
             },
@@ -678,18 +690,28 @@ export default function Dashboard() {
             return;
         }
         // Create overlay from here on.
+        // In "current" branch mode we skip type+desc fields entirely — they have
+        // no meaning when the worktree is going to be detached. Tab cycles
+        // branchMode ⇄ prompt only.
         if (key.tab) {
-            const nextField = overlay.field === "type"
-                ? "desc"
-                : overlay.field === "desc"
-                    ? "prompt"
-                    : "type";
+            const order = overlay.branchMode === "current"
+                ? ["branchMode", "prompt"]
+                : ["branchMode", "type", "desc", "prompt"];
+            const i = order.indexOf(overlay.field);
+            const nextField = order[(i + 1) % order.length];
             setState({
                 ...state,
                 overlay: { ...overlay, field: nextField },
             });
             return;
         }
+        if (overlay.field === "branchMode") {
+            if (key.leftArrow || key.rightArrow || input === "h" || input === "l") {
+                const next = overlay.branchMode === "new" ? "current" : "new";
+                setState({ ...state, overlay: { ...overlay, branchMode: next, error: null } });
+                return;
+            }
+        }
         if (overlay.field === "type") {
             if (key.leftArrow || input === "h") {
                 const idx = ALLOWED_TYPES.indexOf(overlay.type);
@@ -734,20 +756,36 @@ export default function Dashboard() {
     async function confirmCreate(overlay) {
         if (state.phase !== "ready")
             return;
-        const desc = overlay.desc.trim();
-        if (!desc) {
-            setState({
-                ...state,
-                overlay: { ...overlay, error: "Description is required." },
+        const prompt = overlay.prompt.trim();
+        const issueNumber = overlay.issue.issue.number;
+        let result;
+        if (overlay.branchMode === "current") {
+            // Detached worktree off the main repo's current branch. Desc comes
+            // from the issue title (kebabized), not user input — keeping the
+            // "current branch" flow as low-friction as possible.
+            const descKebab = kebabize(overlay.issue.issue.title) || `issue-${issueNumber}`;
+            result = runCreateDetached({
+                issueId: String(issueNumber),
+                descKebab,
+                work: true,
+                ...(prompt.length > 0 ? { prompt } : {}),
+            });
+        }
+        else {
+            const desc = overlay.desc.trim();
+            if (!desc) {
+                setState({
+                    ...state,
+                    overlay: { ...overlay, error: "Description is required." },
+                });
+                return;
+            }
+            const branch = `${overlay.type}/${issueNumber}-${desc}`;
+            result = runCreate(branch, {
+                work: true,
+                ...(prompt.length > 0 ? { prompt } : {}),
             });
-            return;
         }
-        const branch = `${overlay.type}/${overlay.issue.issue.number}-${desc}`;
-        const prompt = overlay.prompt.trim();
-        const result = runCreate(branch, {
-            work: true,
-            ...(prompt.length > 0 ? { prompt } : {}),
-        });
         if (!result.ok) {
             setState({
                 ...state,
@@ -766,7 +804,9 @@ export default function Dashboard() {
     async function confirmRemove(overlay, force) {
         if (state.phase !== "ready")
             return;
-        const result = runRemove(overlay.branch, force);
+        const result = overlay.branch
+            ? runRemove(overlay.branch, force)
+            : runRemoveByPath(overlay.worktreePath, force);
         if (!result.ok) {
             setState({
                 ...state,

package/dist/commands/worktree/work.js

@@ -7,7 +7,6 @@ import { z } from "zod";
 import { randomUUID } from "crypto";
 import { readFileSync, unlinkSync } from "fs";
 import * as path from "path";
-import { parseBranch, isParseError } from "../../lib/branch.js";
 import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getCurrentBranch, pathExists, } from "../../lib/git.js";
 import { getSessionId, setSessionId } from "../../lib/metadata.js";
 import { launchClaude, PERMISSION_MODES } from "../../lib/claude.js";
@@ -61,28 +60,28 @@ function resolve(cwd) {
             hint: "Run `mintree worktree work` from inside `.mintree/worktrees/<issue>-<desc>`.",
         };
     }
-    const branch = getCurrentBranch(cwdAbs);
-    if (!branch) {
-        return {
-            ok: false,
-            message: "Could not determine the current branch (detached HEAD?)",
-        };
-    }
-    const parsed = parseBranch(branch);
-    if (isParseError(parsed)) {
-        return {
-            ok: false,
-            message: `Branch '${branch}' does not match the mintree convention.`,
-            hint: parsed.hint,
-        };
-    }
     // The worktree path that git knows about is the *root* of this checkout.
     // Walk up from cwd until we land directly under .mintree/worktrees/<name>.
     const segmentBeneathWorktreesDir = cwdAbs.slice(worktreesDir.length + 1).split(path.sep)[0];
     const worktreePath = segmentBeneathWorktreesDir
         ? path.join(worktreesDir, segmentBeneathWorktreesDir)
         : cwdAbs;
-    const existing = getSessionId(repoRoot, parsed.issueId);
+    const worktreeDirName = path.basename(worktreePath);
+    // IssueId comes from the worktree dir name, not the branch — that way
+    // detached-HEAD worktrees (the "current branch" path from the dashboard)
+    // still resolve their session_id. Convention guarantees the dir is named
+    // `<issueId>-<desc>` for both attached and detached creates.
+    const issueIdMatch = worktreeDirName.match(/^(\d+)-/);
+    if (!issueIdMatch || !issueIdMatch[1]) {
+        return {
+            ok: false,
+            message: `Worktree directory '${worktreeDirName}' doesn't start with an issue number.`,
+            hint: "Expected `<issue>-<desc>` (e.g. 100-claude-md-inicial).",
+        };
+    }
+    const issueId = issueIdMatch[1];
+    const branch = getCurrentBranch(cwdAbs); // null = detached HEAD, that's fine
+    const existing = getSessionId(repoRoot, issueId);
     let sessionId;
     let resume;
     if (existing) {
@@ -91,7 +90,7 @@ function resolve(cwd) {
     }
     else {
         sessionId = randomUUID();
-        setSessionId(repoRoot, parsed.issueId, sessionId);
+        setSessionId(repoRoot, issueId, sessionId);
         resume = false;
     }
     return {
@@ -99,8 +98,9 @@ function resolve(cwd) {
         data: {
             repoRoot,
             worktreePath,
+            worktreeDirName,
             branch,
-            issueId: parsed.issueId,
+            issueId,
             sessionId,
             resume,
         },
@@ -156,6 +156,7 @@ export default function Work({ options }) {
                 resume: resolved.resume,
                 prompt: effectivePrompt,
                 cwd: resolved.worktreePath,
+                remoteControlName: resolved.worktreeDirName,
             });
             child.on("error", (err) => {
                 setState({
@@ -183,7 +184,7 @@ export default function Work({ options }) {
     const { resolved } = state;
     const sessionShort = resolved.sessionId.slice(0, 8);
     const action = resolved.resume ? "resuming" : "starting";
-    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "mintree worktree work" }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", resolved.branch] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "session: " }), _jsxs(Text, { children: [sessionShort, "\u2026"] }), _jsxs(Text, { dimColor: true, children: [" (", action, ")"] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "permission-mode: " }), _jsx(Text, { children: options.permissionMode })] }), options.prompt && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "initial prompt: " }), _jsxs(Text, { children: ["\"", truncate(options.prompt, 60), "\""] })] })), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cwd: " }), _jsx(Text, { dimColor: true, children: resolved.worktreePath })] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "green", bold: true, children: "\u2713 Launching Claude..." }) })] }));
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "mintree worktree work" }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", resolved.branch ?? `detached @ ${resolved.worktreeDirName}`] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "session: " }), _jsxs(Text, { children: [sessionShort, "\u2026"] }), _jsxs(Text, { dimColor: true, children: [" (", action, ")"] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "permission-mode: " }), _jsx(Text, { children: options.permissionMode })] }), options.prompt && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "initial prompt: " }), _jsxs(Text, { children: ["\"", truncate(options.prompt, 60), "\""] })] })), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cwd: " }), _jsx(Text, { dimColor: true, children: resolved.worktreePath })] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "green", bold: true, children: "\u2713 Launching Claude..." }) })] }));
 }
 function truncate(s, max) {
     if (s.length <= max)

package/dist/lib/claude.d.ts

@@ -14,6 +14,7 @@ export type LaunchClaudeOptions = {
     resume: boolean;
     prompt?: string;
     cwd: string;
+    remoteControlName?: string;
 };
 /**
  * Spawns the Claude CLI with stdio inherited so the child takes over the TTY.

package/dist/lib/claude.js

@@ -60,6 +60,17 @@ export function launchClaude(options) {
     else {
         args.push("--session-id", options.sessionId);
     }
+    // Always launch with Remote Control. Mintree's whole premise is being able
+    // to resume sessions from other devices, so the flag is non-optional —
+    // global `remoteControlAtStartup` becomes irrelevant for mintree-launched
+    // sessions. The optional name = worktree dir, so the RC UI can identify
+    // the session at a glance instead of showing a UUID.
+    if (options.remoteControlName) {
+        args.push("--remote-control", options.remoteControlName);
+    }
+    else {
+        args.push("--remote-control");
+    }
     if (options.prompt && options.prompt.length > 0) {
         args.push("--", promptArg(options.prompt));
     }

package/dist/lib/dashboard.d.ts

@@ -13,7 +13,7 @@ export type GhIssue = {
 };
 export type WorktreeInfo = {
     path: string;
-    branch: string;
+    branch: string | null;
     dirty: boolean;
     ab: AheadBehind | null;
     sessionId?: string;

package/dist/lib/dashboard.js

@@ -26,21 +26,21 @@ export async function fetchAssignedIssues() {
 }
 /**
  * Builds a map from issue id (number, as string) to the matching mintree
- * worktree, parsing each branch with the same `<type>/<issue>-<desc>` regex
- * the create command enforces. Worktrees with branches that don't follow
- * the convention are simply skipped.
+ * worktree. IssueId comes from the worktree dir name (`<issue>-<desc>`)
+ * rather than the branch, so detached worktrees (created via the dashboard's
+ * "current branch" mode) are included alongside the regular branch-based
+ * ones. Worktrees outside `.mintree/worktrees/` are skipped.
  */
 function buildWorktreeIndex(repoRoot) {
     const worktreesRoot = path.resolve(getWorktreesDir(repoRoot));
-    const branchRegex = /^[a-z]+\/(\d+)-/;
+    const dirNameRegex = /^(\d+)-/;
     const index = new Map();
     for (const w of listWorktrees(repoRoot)) {
-        if (!w.branch)
-            continue;
         const wAbs = path.resolve(w.path);
         if (wAbs !== worktreesRoot && !wAbs.startsWith(worktreesRoot + path.sep))
             continue;
-        const m = w.branch.match(branchRegex);
+        const dirName = path.basename(wAbs);
+        const m = dirName.match(dirNameRegex);
         const issueId = m && m[1] ? m[1] : null;
         if (!issueId)
             continue;
@@ -115,9 +115,12 @@ export async function loadDashboard(repoRoot) {
     const metadata = readMetadata(repoRoot);
     // Fetch PRs in parallel for branches that actually have a worktree —
     // issues without one wouldn't have a branch on this user's repo, so we
-    // skip the per-issue gh call for them.
+    // skip the per-issue gh call for them. Detached worktrees (branch=null)
+    // have no PR by definition.
     const prByBranch = new Map();
-    const prFetches = Array.from(worktreesByIssue.values()).map(async (w) => {
+    const prFetches = Array.from(worktreesByIssue.values())
+        .filter((w) => w.branch !== null)
+        .map(async (w) => {
         const pr = await fetchPrForBranch(w.branch);
         if (pr)
             prByBranch.set(w.branch, pr);
@@ -128,7 +131,7 @@ export async function loadDashboard(repoRoot) {
         const worktreeRaw = worktreesByIssue.get(issueId) ?? null;
         const sessionId = metadata.issues[issueId]?.session_id;
         const worktree = worktreeRaw ? { ...worktreeRaw, sessionId } : null;
-        const pr = worktree ? (prByBranch.get(worktree.branch) ?? null) : null;
+        const pr = worktree && worktree.branch ? (prByBranch.get(worktree.branch) ?? null) : null;
         return {
             issue,
             worktree,

package/dist/lib/worktreeCreate.d.ts

@@ -34,3 +34,23 @@ export type CreateResult = {
  * for the work hand-off when relevant.
  */
 export declare function runCreate(branchArg: string, opts: CreateOpts): CreateResult;
+export type CreateDetachedOpts = {
+    issueId: string;
+    descKebab: string;
+    work: boolean;
+    prompt?: string;
+    permissionMode?: PermissionMode;
+};
+/**
+ * Variant of `runCreate` that doesn't create a new branch — the worktree is
+ * checked out in detached HEAD at the tip of the main repo's current branch.
+ * Used by the dashboard's "current branch" overlay mode: lets the user spin
+ * up a worktree off whatever they're on (typically `main`) without forcing
+ * the `<type>/<issue>-<desc>` convention upfront. They can `git switch -c`
+ * later if/when the work warrants a branch.
+ *
+ * Worktree dir naming follows the same `<issueId>-<desc>` shape as the
+ * branch-based flow so `worktree work` can still recover the issueId from
+ * the dir name (where it can't read it from the branch).
+ */
+export declare function runCreateDetached(opts: CreateDetachedOpts): CreateResult;

package/dist/lib/worktreeCreate.js

@@ -3,7 +3,7 @@ import * as os from "os";
 import * as path from "path";
 import { execSync } from "child_process";
 import { parseBranch, isParseError } from "./branch.js";
-import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getInitScriptPath, getDefaultBranch, branchExists, worktreeForBranch, addWorktree, pathExists, isExecutable, } from "./git.js";
+import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getInitScriptPath, getDefaultBranch, getCurrentBranch, branchExists, worktreeForBranch, addWorktree, pathExists, isExecutable, } from "./git.js";
 import { upsertIssue } from "./metadata.js";
 function tryRunInitScript(scriptPath, worktreePath, repoRoot) {
     if (!pathExists(scriptPath))
@@ -182,3 +182,119 @@ export function runCreate(branchArg, opts) {
         permissionMode: opts.permissionMode,
     };
 }
+/**
+ * Variant of `runCreate` that doesn't create a new branch — the worktree is
+ * checked out in detached HEAD at the tip of the main repo's current branch.
+ * Used by the dashboard's "current branch" overlay mode: lets the user spin
+ * up a worktree off whatever they're on (typically `main`) without forcing
+ * the `<type>/<issue>-<desc>` convention upfront. They can `git switch -c`
+ * later if/when the work warrants a branch.
+ *
+ * Worktree dir naming follows the same `<issueId>-<desc>` shape as the
+ * branch-based flow so `worktree work` can still recover the issueId from
+ * the dir name (where it can't read it from the branch).
+ */
+export function runCreateDetached(opts) {
+    const root = findMainRepoRoot();
+    if (!root) {
+        return {
+            ok: false,
+            message: "Not in a git repository.",
+            hint: "Run `git init` and then `mintree init`.",
+        };
+    }
+    if (!pathExists(getMintreeDir(root))) {
+        return {
+            ok: false,
+            message: ".mintree/ not found in this repo.",
+            hint: "Run `mintree init` first.",
+        };
+    }
+    if (!/^\d+$/.test(opts.issueId)) {
+        return { ok: false, message: `Invalid issueId: ${opts.issueId}` };
+    }
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(opts.descKebab)) {
+        return {
+            ok: false,
+            message: `Invalid desc: ${opts.descKebab}`,
+            hint: "Expected kebab-case starting with [a-z0-9].",
+        };
+    }
+    const currentBranch = getCurrentBranch(root);
+    if (!currentBranch) {
+        return {
+            ok: false,
+            message: "Main repo is in detached HEAD — can't determine current branch to fork from.",
+            hint: "Switch the main repo to a branch first (`git switch main`) and try again.",
+        };
+    }
+    const worktreeDirName = `${opts.issueId}-${opts.descKebab}`;
+    const worktreePath = path.join(getWorktreesDir(root), worktreeDirName);
+    if (pathExists(worktreePath)) {
+        return {
+            ok: false,
+            message: `Worktree directory already exists: ${worktreePath}`,
+            hint: "Remove it first or pick a different description.",
+        };
+    }
+    const steps = [];
+    steps.push({
+        kind: "ok",
+        label: "detached worktree",
+        detail: `issue=${opts.issueId}, base=${currentBranch}`,
+    });
+    try {
+        execSync(`git worktree add --detach '${worktreePath.replace(/'/g, `'\\''`)}' '${currentBranch.replace(/'/g, `'\\''`)}'`, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { ok: false, message: `git worktree add --detach failed: ${stderr}` };
+    }
+    steps.push({
+        kind: "ok",
+        label: "checked out detached HEAD",
+        detail: `at tip of ${currentBranch}`,
+    });
+    steps.push({ kind: "ok", label: "worktree created", detail: worktreePath });
+    upsertIssue(root, opts.issueId, { base_branch: currentBranch });
+    steps.push({ kind: "ok", label: "metadata updated", detail: `issue ${opts.issueId}` });
+    const initShPath = getInitScriptPath(root);
+    const initResult = tryRunInitScript(initShPath, worktreePath, root);
+    if (initResult.ran) {
+        steps.push({ kind: "ok", label: "ran .mintree/init.sh", detail: worktreePath });
+    }
+    else if (initResult.error) {
+        steps.push({ kind: "warn", label: "init.sh failed", detail: initResult.error });
+    }
+    else if (!pathExists(initShPath)) {
+        steps.push({ kind: "skip", label: "no init.sh (skipping post-create hook)" });
+    }
+    let promptFile;
+    if (opts.work && opts.prompt && opts.prompt.length > 0) {
+        try {
+            promptFile = writePromptFile(opts.prompt);
+        }
+        catch (err) {
+            steps.push({
+                kind: "warn",
+                label: "failed to stage --prompt for hand-off",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        ok: true,
+        steps,
+        worktreePath,
+        branch: `detached @ ${currentBranch}`,
+        issueId: opts.issueId,
+        base: currentBranch,
+        work: opts.work,
+        promptFile,
+        permissionMode: opts.permissionMode,
+    };
+}

package/dist/lib/worktreeRemove.d.ts

@@ -19,3 +19,10 @@ export type RemoveResult = {
  * resume the same Claude session.
  */
 export declare function runRemove(branchArg: string, force: boolean): RemoveResult;
+/**
+ * Path-keyed counterpart to `runRemove`, used for worktrees that don't have
+ * a parseable branch (detached HEAD ones created via the dashboard's
+ * "current branch" mode). Same dirty/force/prune semantics as runRemove —
+ * just skips the `parseBranch` step and reports the worktree by its path.
+ */
+export declare function runRemoveByPath(worktreePath: string, force: boolean): RemoveResult;

package/dist/lib/worktreeRemove.js

@@ -82,3 +82,71 @@ export function runRemove(branchArg, force) {
         wasDirty: dirty,
     };
 }
+/**
+ * Path-keyed counterpart to `runRemove`, used for worktrees that don't have
+ * a parseable branch (detached HEAD ones created via the dashboard's
+ * "current branch" mode). Same dirty/force/prune semantics as runRemove —
+ * just skips the `parseBranch` step and reports the worktree by its path.
+ */
+export function runRemoveByPath(worktreePath, force) {
+    const root = findMainRepoRoot();
+    if (!root) {
+        return {
+            ok: false,
+            message: "Not in a git repository.",
+            hint: "Run `git init` and then `mintree init`.",
+        };
+    }
+    if (!pathExists(getMintreeDir(root))) {
+        return {
+            ok: false,
+            message: ".mintree/ not found in this repo.",
+            hint: "Run `mintree init` first.",
+        };
+    }
+    const label = worktreePath.split("/").pop() ?? worktreePath;
+    if (!pathExists(worktreePath)) {
+        try {
+            pruneWorktrees(root);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                message: `git worktree prune failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return {
+            ok: true,
+            branch: label,
+            worktreePath,
+            variant: "pruned-orphan",
+            wasDirty: false,
+        };
+    }
+    const dirty = isDirty(worktreePath);
+    if (dirty && !force) {
+        return {
+            ok: false,
+            message: `Worktree at ${worktreePath} has uncommitted changes.`,
+            hint: "Commit/stash first, or pass --force to discard them.",
+        };
+    }
+    try {
+        removeWorktree({ repoRoot: root, worktreePath, force });
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err
+            ? String(err.stderr).trim()
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { ok: false, message: `git worktree remove failed: ${stderr}` };
+    }
+    return {
+        ok: true,
+        branch: label,
+        worktreePath,
+        variant: "removed",
+        wasDirty: dirty,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",