@taranek/orche 0.0.29 → 0.0.31

package/README.md

@@ -0,0 +1,249 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/taranek/orche/master/assets/orche.svg" alt="orche" width="128" height="128" />
+</p>
+
+<h1 align="center">orche</h1>
+
+<p align="center">Orchestrate coding agents across isolated git worktrees with a built-in code review UI.</p>
+
+https://github.com/user-attachments/assets/35150d31-84ce-4f1d-8df9-4aef179dc532
+
+orche runs your coding agents in isolated git worktrees, so several can work at once without stepping on each other. When an agent finishes, you review its diff in a desktop app and send comments straight back to its terminal.
+
+Three commands do the work:
+
+- `orche start <task>` opens a tmux or cmux session with your agent, a dev server, and a spare terminal, each in its own worktree.
+- `orche review` opens the review app for a worktree. Leave line-level comments, hit submit, and the feedback lands in the agent's pane.
+- `orche prune` cleans up the worktrees you're done with.
+
+### How it works
+
+1. Run `orche start fix-auth`. A session opens with your agent (Claude, Codex, whatever you configured), a dev server, and a spare terminal.
+2. The agent works in its own worktree.
+3. When it's done, run `orche review`, or tell the agent to.
+4. Read the diff, leave comments, submit. The feedback goes to the agent's pane.
+5. On to the next task.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) v18 or newer
+- [tmux](https://github.com/tmux/tmux) or [cmux](https://cmux.dev/) for session management
+- [git](https://git-scm.com/)
+
+## Installation
+
+```bash
+npm install -g @taranek/orche
+```
+
+## Quick start
+
+From inside a git repo, run:
+
+```bash
+orche init
+```
+
+That writes a starter `.orche.json` and adds `.orche/` to your `.gitignore`. Open the config and set the panes you want, an agent and a dev server to start with:
+
+```json
+{
+  "layout": {
+    "direction": "horizontal",
+    "panes": [
+      { "name": "agent", "command": "claude" },
+      { "name": "dev", "command": "yarn dev" }
+    ]
+  }
+}
+```
+
+Then start a session:
+
+```bash
+orche start fix-auth
+```
+
+This creates a worktree under `.orche/worktrees/`, opens a tmux or cmux session with your panes, and runs each pane's command. When you want to look at the result, run `orche review`.
+
+## Commands
+
+```
+orche init [-f]                    Bootstrap .orche.json + .gitignore entry
+orche start <task> [-p <preset>]   Start a session for <task>
+orche review [path]                Open the review UI for a worktree
+orche prune [--all] [-f]           Remove orche worktrees
+```
+
+```bash
+orche init                         # write .orche.json + ignore .orche/
+orche start fix-auth               # worktree + session for "fix-auth"
+orche start fix-auth -p mobile     # use .orche.mobile.json
+orche review                       # review the current directory
+orche review ./worktree            # review a specific worktree
+orche prune                        # pick worktrees to remove
+orche prune --all                  # remove every orche worktree
+orche prune --force                # remove even with uncommitted changes
+```
+
+`orche prune` lists every worktree under `.orche/worktrees/` in a multiselect. Anything with uncommitted changes is flagged and skipped unless you pass `--force`.
+
+## Configuration
+
+### `.orche.json`
+
+This file defines your pane layout. Put it in the project root; it works with both tmux and cmux. Splits can nest as deep as you need:
+
+```json
+{
+  "layout": {
+    "direction": "horizontal",
+    "panes": [
+      { "name": "agent", "command": "claude" },
+      {
+        "direction": "vertical",
+        "panes": [
+          { "name": "dev", "command": "npm run dev" },
+          { "name": "tests", "command": "npm run test:watch" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That config produces:
+
+```
+┌─────────────────┬─────────────────┐
+│                 │      dev        │
+│     agent       ├─────────────────┤
+│                 │     tests       │
+└─────────────────┴─────────────────┘
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `direction` | `"horizontal"` \| `"vertical"` | Split direction |
+| `panes` | array | Panes or nested splits |
+| `name` | string | Pane label |
+| `command` | string | Command to run in the pane |
+| `size` | number | Split percentage (optional) |
+
+### Multiplexer
+
+orche detects whether you're in tmux or [cmux](https://cmux.dev/). To force one, set it in your config:
+
+```json
+{
+  "multiplexer": "cmux",
+  "layout": { ... }
+}
+```
+
+Use `"tmux"` (the default) or `"cmux"`.
+
+### Gitignored files in worktrees (`.worktreeinclude`)
+
+A worktree is a clean checkout, so untracked files like `.env` from your main checkout aren't there. List the ones you want carried over in a `.worktreeinclude` file at the project root. It uses `.gitignore` syntax, and only untracked files matching a pattern are placed — tracked files are never duplicated:
+
+```text
+.env
+.env.local
+config/secrets.json
+```
+
+By default the files are **copied**, so each worktree gets its own independent copy. To **symlink** them back to the main checkout instead (shared, so edits propagate both ways), set `worktree.includeMode`:
+
+```json
+{
+  "worktree": {
+    "includeMode": "symlink"
+  },
+  "layout": { ... }
+}
+```
+
+Use `"copy"` (the default) or `"symlink"`. Note that with `"symlink"`, a worktree editing a file like `.env` mutates the main checkout.
+
+### `.orche.local.json`
+
+Same format as `.orche.json`, and it wins when both exist. It's gitignored by default, so it's the place for personal overrides that shouldn't touch the team config.
+
+### Presets
+
+Name a preset file `.orche.<name>.json` and load it with `-p`:
+
+```bash
+orche start fix-auth -p mobile    # loads .orche.mobile.json
+orche start fix-auth -p debug     # loads .orche.debug.json
+```
+
+A preset overrides both `.orche.json` and `.orche.local.json`. Ask for one that doesn't exist and orche lists the presets it can find.
+
+## Review app
+
+`orche review` opens a desktop app to look over an agent's changes before they land. Run it from inside a worktree, or pass a path. If you're in a tmux or cmux session, the review links to the agent's pane automatically, so submitted feedback gets pasted straight into the terminal.
+
+The window has three columns:
+
+```
+┌──────┬────────────┬──────────────────────────────────┐
+│      │            │                                  │
+│ icon │   file     │    multi-file diff view           │
+│ rail │   tree     │    (virtualized scroll)           │
+│      │            │                                  │
+│      │            ├──────────────────────────────────┤
+│      │            │  main ← 3 files · 2 comments     │
+└──────┴────────────┴──────────────────────────────────┘
+```
+
+The icon rail switches between the file tree, comments, and theme panels. The side panel browses changed files (with `+`/`~`/`-` status) or your pending comments. The diff viewer is a virtualized split diff with syntax highlighting, collapsible unchanged regions, and sticky file headers.
+
+To review: scroll through every changed file in one view (the sidebar tracks where you are), click a line to comment, then submit with `Cmd+Enter` on macOS or `Ctrl+Enter` on Linux. Your comments are saved as markdown under `.orche/reviews/` and pasted into the agent's pane.
+
+| Key | Action |
+|-----|--------|
+| `Cmd/Ctrl+Enter` | Submit review |
+| `Enter` (in comment) | Submit comment |
+| `Shift+Enter` (in comment) | Newline |
+| `Escape` (in comment) | Cancel |
+
+Four color themes ship with the app and persist between sessions:
+
+- Obsidian: dark, with a warm amber accent
+- Porcelain: light, with a slate-blue accent
+- Sandstone: warm light, with a burnt orange accent
+- Arctic: dark, with a teal accent
+
+## Contributing
+
+```bash
+git clone https://github.com/taranek/orche.git
+cd orche
+pnpm install
+pnpm run build
+pnpm run link:cli
+```
+
+Workspace management uses [pnpm](https://pnpm.io/). Common scripts:
+
+```bash
+pnpm run dev:cli           # watch + rebuild the CLI (linked globally)
+pnpm run dev:review        # run the review app in dev mode
+pnpm run build             # build all packages
+pnpm run typecheck         # type-check all packages
+```
+
+The code lives in three packages:
+
+```
+packages/
+  cli/       @orche/cli      CLI for session and worktree management
+  review/    @orche/review   Electron code review app
+  shared/    @orche/shared   shared components, themes, and state
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -132,7 +132,9 @@ function startSession() {
     const mux = getMultiplexer(muxFlag ?? config.multiplexer);
     // 1. Create worktree
     console.log(`creating worktree for "${taskName}"...`);
-    const { worktreePath } = createWorktree(cwd, taskName);
+    const { worktreePath } = createWorktree(cwd, taskName, {
+        includeMode: config.worktree?.includeMode,
+    });
     // 2. Create session
     const sessionName = `${repoName}-${taskName}`.replace(/[^a-zA-Z0-9_-]/g, "-");
     mux.createSession(sessionName, worktreePath);

package/dist/types.d.ts

@@ -11,8 +11,19 @@ export interface SplitConfig {
     size?: number;
 }
 export type MultiplexerType = "tmux" | "cmux" | "auto";
+/** How `.worktreeinclude` files are placed into a new worktree. */
+export type WorktreeIncludeMode = "copy" | "symlink";
+export interface WorktreeConfig {
+    /**
+     * Whether gitignored files matched by `.worktreeinclude` are copied into the
+     * worktree (independent per-worktree copies, the default) or symlinked back
+     * to the main checkout (shared, so edits propagate). Defaults to "copy".
+     */
+    includeMode?: WorktreeIncludeMode;
+}
 export interface AgentsConfig {
     multiplexer?: MultiplexerType;
+    worktree?: WorktreeConfig;
     layout: PaneConfig | SplitConfig;
 }
 export declare function isSplit(node: PaneConfig | SplitConfig): node is SplitConfig;

package/dist/worktree.d.ts

@@ -1,8 +1,30 @@
+import type { WorktreeIncludeMode } from "./types.js";
 export interface WorktreeInfo {
     worktreePath: string;
     branchName: string;
 }
-export declare function createWorktree(repoPath: string, name: string): WorktreeInfo;
+export interface CreateWorktreeOptions {
+    /** How `.worktreeinclude` files are placed into the worktree. Defaults to "copy". */
+    includeMode?: WorktreeIncludeMode;
+}
+export declare function createWorktree(repoPath: string, name: string, options?: CreateWorktreeOptions): WorktreeInfo;
+/**
+ * Places gitignored files listed in a `.worktreeinclude` file (`.gitignore`
+ * syntax) from the main checkout into the freshly created worktree. A worktree
+ * is a clean checkout, so untracked files like `.env` aren't present otherwise.
+ *
+ * In "copy" mode (the default) each file is duplicated, so the worktree can
+ * diverge freely. In "symlink" mode each file links back to the main checkout,
+ * so edits are shared — handy for config you keep in lockstep, but it means a
+ * worktree editing e.g. `.env` mutates the main checkout.
+ *
+ * Only untracked files matching a `.worktreeinclude` pattern are placed —
+ * tracked files are never duplicated. The match is computed with `git ls-files
+ * --others --ignored --exclude-from`: `--others` restricts to untracked files,
+ * and omitting `--exclude-standard` means only the `.worktreeinclude` patterns
+ * (not the repo's normal `.gitignore`) decide what matches.
+ */
+export declare function applyWorktreeIncludes(repoPath: string, worktreePath: string, mode?: WorktreeIncludeMode): void;
 export interface OrcheWorktree {
     worktreePath: string;
     branch: string | null;

package/dist/worktree.js

@@ -1,5 +1,5 @@
 import { execSync, execFileSync } from "node:child_process";
-import { existsSync, readFileSync, appendFileSync, mkdirSync, symlinkSync, readdirSync, lstatSync, } from "node:fs";
+import { existsSync, readFileSync, appendFileSync, mkdirSync, symlinkSync, copyFileSync, readdirSync, lstatSync, } from "node:fs";
 import path from "node:path";
 function slugify(text) {
     return text
@@ -26,7 +26,7 @@ function ensureGitRepo(repoPath) {
         execSync('git init && git add -A && git commit -m "Initial commit" --allow-empty', { cwd: repoPath, stdio: "ignore" });
     }
 }
-export function createWorktree(repoPath, name) {
+export function createWorktree(repoPath, name, options = {}) {
     ensureGitRepo(repoPath);
     const slug = slugify(name);
     const timestamp = Date.now();
@@ -40,9 +40,65 @@ export function createWorktree(repoPath, name) {
         stdio: "ignore",
     });
     symlinkNodeModules(repoPath, worktreePath);
+    applyWorktreeIncludes(repoPath, worktreePath, options.includeMode ?? "copy");
     console.log(`  worktree: ${worktreePath} (${branchName})`);
     return { worktreePath, branchName };
 }
+/**
+ * Places gitignored files listed in a `.worktreeinclude` file (`.gitignore`
+ * syntax) from the main checkout into the freshly created worktree. A worktree
+ * is a clean checkout, so untracked files like `.env` aren't present otherwise.
+ *
+ * In "copy" mode (the default) each file is duplicated, so the worktree can
+ * diverge freely. In "symlink" mode each file links back to the main checkout,
+ * so edits are shared — handy for config you keep in lockstep, but it means a
+ * worktree editing e.g. `.env` mutates the main checkout.
+ *
+ * Only untracked files matching a `.worktreeinclude` pattern are placed —
+ * tracked files are never duplicated. The match is computed with `git ls-files
+ * --others --ignored --exclude-from`: `--others` restricts to untracked files,
+ * and omitting `--exclude-standard` means only the `.worktreeinclude` patterns
+ * (not the repo's normal `.gitignore`) decide what matches.
+ */
+export function applyWorktreeIncludes(repoPath, worktreePath, mode = "copy") {
+    const includeFile = path.join(repoPath, ".worktreeinclude");
+    if (!existsSync(includeFile))
+        return;
+    let output;
+    try {
+        output = execFileSync("git", ["ls-files", "-z", "--others", "--ignored", "--exclude-from", includeFile], { cwd: repoPath, encoding: "utf-8" });
+    }
+    catch {
+        return;
+    }
+    let placed = 0;
+    for (const rel of output.split("\0").filter(Boolean)) {
+        const src = path.join(repoPath, rel);
+        const dest = path.join(worktreePath, rel);
+        try {
+            if (!lstatSync(src).isFile())
+                continue;
+            if (existsSync(dest))
+                continue;
+            mkdirSync(path.dirname(dest), { recursive: true });
+            if (mode === "symlink") {
+                symlinkSync(src, dest);
+            }
+            else {
+                copyFileSync(src, dest);
+            }
+            placed++;
+        }
+        catch {
+            // Skip files that vanished or can't be read; placement is best-effort.
+        }
+    }
+    if (placed > 0) {
+        const noun = placed === 1 ? "file" : "files";
+        const verb = mode === "symlink" ? "symlinked" : "copied";
+        console.log(`  ${verb} ${placed} gitignored ${noun} from .worktreeinclude`);
+    }
+}
 const ORCHE_SEGMENT = `${path.sep}.orche${path.sep}worktrees${path.sep}`;
 function parseWorktreeList(output) {
     const result = [];

package/dist/worktree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worktree.test.js

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, readFileSync, lstatSync, } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createWorktree } from "./worktree.js";
+function git(cwd, ...args) {
+    execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+function initRepo() {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "orche-wt-test-"));
+    git(dir, "init");
+    git(dir, "config", "user.email", "test@example.com");
+    git(dir, "config", "user.name", "Test");
+    // A tracked file so the repo has a real HEAD to branch from.
+    writeFileSync(path.join(dir, "README.md"), "# repo\n");
+    git(dir, "add", "README.md");
+    git(dir, "commit", "-m", "init");
+    return dir;
+}
+describe("createWorktree .worktreeinclude", () => {
+    let repo;
+    beforeEach(() => {
+        repo = initRepo();
+    });
+    afterEach(() => {
+        rmSync(repo, { recursive: true, force: true });
+    });
+    it("copies gitignored files matching .worktreeinclude into the worktree", () => {
+        writeFileSync(path.join(repo, ".gitignore"), ".env\nconfig/\n");
+        writeFileSync(path.join(repo, ".worktreeinclude"), ".env\nconfig/secrets.json\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        mkdirSync(path.join(repo, "config"));
+        writeFileSync(path.join(repo, "config", "secrets.json"), '{"k":"v"}\n');
+        const { worktreePath } = createWorktree(repo, "feature");
+        const env = path.join(worktreePath, ".env");
+        const secrets = path.join(worktreePath, "config", "secrets.json");
+        expect(existsSync(env)).toBe(true);
+        expect(lstatSync(env).isSymbolicLink()).toBe(false);
+        expect(readFileSync(env, "utf-8")).toBe("SECRET=abc\n");
+        expect(existsSync(secrets)).toBe(true);
+        expect(readFileSync(secrets, "utf-8")).toBe('{"k":"v"}\n');
+    });
+    it("defaults to copy mode (independent files)", () => {
+        writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+        writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        const { worktreePath } = createWorktree(repo, "feature");
+        const env = path.join(worktreePath, ".env");
+        expect(lstatSync(env).isSymbolicLink()).toBe(false);
+        // Editing the main checkout's copy does not affect the worktree's.
+        writeFileSync(path.join(repo, ".env"), "SECRET=changed\n");
+        expect(readFileSync(env, "utf-8")).toBe("SECRET=abc\n");
+    });
+    it("symlinks files when includeMode is 'symlink' (shared with main checkout)", () => {
+        writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+        writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        const { worktreePath } = createWorktree(repo, "feature", { includeMode: "symlink" });
+        const env = path.join(worktreePath, ".env");
+        expect(lstatSync(env).isSymbolicLink()).toBe(true);
+        // Editing the main checkout propagates through the symlink.
+        writeFileSync(path.join(repo, ".env"), "SECRET=changed\n");
+        expect(readFileSync(env, "utf-8")).toBe("SECRET=changed\n");
+    });
+    it("does not copy gitignored files that aren't listed in .worktreeinclude", () => {
+        writeFileSync(path.join(repo, ".gitignore"), ".env\n.env.local\n");
+        writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        writeFileSync(path.join(repo, ".env.local"), "LOCAL=1\n");
+        const { worktreePath } = createWorktree(repo, "feature");
+        expect(existsSync(path.join(worktreePath, ".env"))).toBe(true);
+        expect(existsSync(path.join(worktreePath, ".env.local"))).toBe(false);
+    });
+    it("ignores patterns that match tracked files (never duplicated via copy)", () => {
+        // README.md is tracked; even if listed it shouldn't be copied by the include logic.
+        writeFileSync(path.join(repo, ".worktreeinclude"), "README.md\n.env\n");
+        writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        const { worktreePath } = createWorktree(repo, "feature");
+        // README.md is present because git checked it out, .env because we copied it.
+        expect(existsSync(path.join(worktreePath, "README.md"))).toBe(true);
+        expect(existsSync(path.join(worktreePath, ".env"))).toBe(true);
+    });
+    it("is a no-op when .worktreeinclude is absent", () => {
+        writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+        writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+        const { worktreePath } = createWorktree(repo, "feature");
+        expect(existsSync(path.join(worktreePath, ".env"))).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taranek/orche",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "type": "module",
   "bin": {
     "orche": "./dist/cli.js"
@@ -15,6 +15,7 @@
     "access": "public"
   },
   "scripts": {
+    "prepack": "node ../../scripts/sync-cli-readme.mjs",
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",

package/src/cli.ts

@@ -139,7 +139,9 @@ function startSession(): void {
 
   // 1. Create worktree
   console.log(`creating worktree for "${taskName}"...`);
-  const { worktreePath } = createWorktree(cwd, taskName);
+  const { worktreePath } = createWorktree(cwd, taskName, {
+    includeMode: config.worktree?.includeMode,
+  });
 
   // 2. Create session
   const sessionName = `${repoName}-${taskName}`.replace(

package/src/types.ts

@@ -14,8 +14,21 @@ export interface SplitConfig {
 
 export type MultiplexerType = "tmux" | "cmux" | "auto";
 
+/** How `.worktreeinclude` files are placed into a new worktree. */
+export type WorktreeIncludeMode = "copy" | "symlink";
+
+export interface WorktreeConfig {
+  /**
+   * Whether gitignored files matched by `.worktreeinclude` are copied into the
+   * worktree (independent per-worktree copies, the default) or symlinked back
+   * to the main checkout (shared, so edits propagate). Defaults to "copy".
+   */
+  includeMode?: WorktreeIncludeMode;
+}
+
 export interface AgentsConfig {
   multiplexer?: MultiplexerType;
+  worktree?: WorktreeConfig;
   layout: PaneConfig | SplitConfig;
 }
 

package/src/worktree.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import {
+  mkdtempSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+  lstatSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createWorktree } from "./worktree.js";
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function initRepo(): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "orche-wt-test-"));
+  git(dir, "init");
+  git(dir, "config", "user.email", "test@example.com");
+  git(dir, "config", "user.name", "Test");
+  // A tracked file so the repo has a real HEAD to branch from.
+  writeFileSync(path.join(dir, "README.md"), "# repo\n");
+  git(dir, "add", "README.md");
+  git(dir, "commit", "-m", "init");
+  return dir;
+}
+
+describe("createWorktree .worktreeinclude", () => {
+  let repo: string;
+
+  beforeEach(() => {
+    repo = initRepo();
+  });
+
+  afterEach(() => {
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  it("copies gitignored files matching .worktreeinclude into the worktree", () => {
+    writeFileSync(path.join(repo, ".gitignore"), ".env\nconfig/\n");
+    writeFileSync(path.join(repo, ".worktreeinclude"), ".env\nconfig/secrets.json\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+    mkdirSync(path.join(repo, "config"));
+    writeFileSync(path.join(repo, "config", "secrets.json"), '{"k":"v"}\n');
+
+    const { worktreePath } = createWorktree(repo, "feature");
+
+    const env = path.join(worktreePath, ".env");
+    const secrets = path.join(worktreePath, "config", "secrets.json");
+    expect(existsSync(env)).toBe(true);
+    expect(lstatSync(env).isSymbolicLink()).toBe(false);
+    expect(readFileSync(env, "utf-8")).toBe("SECRET=abc\n");
+    expect(existsSync(secrets)).toBe(true);
+    expect(readFileSync(secrets, "utf-8")).toBe('{"k":"v"}\n');
+  });
+
+  it("defaults to copy mode (independent files)", () => {
+    writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+    writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+
+    const { worktreePath } = createWorktree(repo, "feature");
+    const env = path.join(worktreePath, ".env");
+
+    expect(lstatSync(env).isSymbolicLink()).toBe(false);
+    // Editing the main checkout's copy does not affect the worktree's.
+    writeFileSync(path.join(repo, ".env"), "SECRET=changed\n");
+    expect(readFileSync(env, "utf-8")).toBe("SECRET=abc\n");
+  });
+
+  it("symlinks files when includeMode is 'symlink' (shared with main checkout)", () => {
+    writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+    writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+
+    const { worktreePath } = createWorktree(repo, "feature", { includeMode: "symlink" });
+    const env = path.join(worktreePath, ".env");
+
+    expect(lstatSync(env).isSymbolicLink()).toBe(true);
+    // Editing the main checkout propagates through the symlink.
+    writeFileSync(path.join(repo, ".env"), "SECRET=changed\n");
+    expect(readFileSync(env, "utf-8")).toBe("SECRET=changed\n");
+  });
+
+  it("does not copy gitignored files that aren't listed in .worktreeinclude", () => {
+    writeFileSync(path.join(repo, ".gitignore"), ".env\n.env.local\n");
+    writeFileSync(path.join(repo, ".worktreeinclude"), ".env\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+    writeFileSync(path.join(repo, ".env.local"), "LOCAL=1\n");
+
+    const { worktreePath } = createWorktree(repo, "feature");
+
+    expect(existsSync(path.join(worktreePath, ".env"))).toBe(true);
+    expect(existsSync(path.join(worktreePath, ".env.local"))).toBe(false);
+  });
+
+  it("ignores patterns that match tracked files (never duplicated via copy)", () => {
+    // README.md is tracked; even if listed it shouldn't be copied by the include logic.
+    writeFileSync(path.join(repo, ".worktreeinclude"), "README.md\n.env\n");
+    writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+
+    const { worktreePath } = createWorktree(repo, "feature");
+
+    // README.md is present because git checked it out, .env because we copied it.
+    expect(existsSync(path.join(worktreePath, "README.md"))).toBe(true);
+    expect(existsSync(path.join(worktreePath, ".env"))).toBe(true);
+  });
+
+  it("is a no-op when .worktreeinclude is absent", () => {
+    writeFileSync(path.join(repo, ".gitignore"), ".env\n");
+    writeFileSync(path.join(repo, ".env"), "SECRET=abc\n");
+
+    const { worktreePath } = createWorktree(repo, "feature");
+
+    expect(existsSync(path.join(worktreePath, ".env"))).toBe(false);
+  });
+});

package/src/worktree.ts

@@ -5,16 +5,23 @@ import {
   appendFileSync,
   mkdirSync,
   symlinkSync,
+  copyFileSync,
   readdirSync,
   lstatSync,
 } from "node:fs";
 import path from "node:path";
+import type { WorktreeIncludeMode } from "./types.js";
 
 export interface WorktreeInfo {
   worktreePath: string;
   branchName: string;
 }
 
+export interface CreateWorktreeOptions {
+  /** How `.worktreeinclude` files are placed into the worktree. Defaults to "copy". */
+  includeMode?: WorktreeIncludeMode;
+}
+
 function slugify(text: string): string {
   return text
     .toLowerCase()
@@ -45,7 +52,11 @@ function ensureGitRepo(repoPath: string): void {
   }
 }
 
-export function createWorktree(repoPath: string, name: string): WorktreeInfo {
+export function createWorktree(
+  repoPath: string,
+  name: string,
+  options: CreateWorktreeOptions = {}
+): WorktreeInfo {
   ensureGitRepo(repoPath);
 
   const slug = slugify(name);
@@ -64,11 +75,73 @@ export function createWorktree(repoPath: string, name: string): WorktreeInfo {
   });
 
   symlinkNodeModules(repoPath, worktreePath);
+  applyWorktreeIncludes(repoPath, worktreePath, options.includeMode ?? "copy");
 
   console.log(`  worktree: ${worktreePath} (${branchName})`);
   return { worktreePath, branchName };
 }
 
+/**
+ * Places gitignored files listed in a `.worktreeinclude` file (`.gitignore`
+ * syntax) from the main checkout into the freshly created worktree. A worktree
+ * is a clean checkout, so untracked files like `.env` aren't present otherwise.
+ *
+ * In "copy" mode (the default) each file is duplicated, so the worktree can
+ * diverge freely. In "symlink" mode each file links back to the main checkout,
+ * so edits are shared — handy for config you keep in lockstep, but it means a
+ * worktree editing e.g. `.env` mutates the main checkout.
+ *
+ * Only untracked files matching a `.worktreeinclude` pattern are placed —
+ * tracked files are never duplicated. The match is computed with `git ls-files
+ * --others --ignored --exclude-from`: `--others` restricts to untracked files,
+ * and omitting `--exclude-standard` means only the `.worktreeinclude` patterns
+ * (not the repo's normal `.gitignore`) decide what matches.
+ */
+export function applyWorktreeIncludes(
+  repoPath: string,
+  worktreePath: string,
+  mode: WorktreeIncludeMode = "copy"
+): void {
+  const includeFile = path.join(repoPath, ".worktreeinclude");
+  if (!existsSync(includeFile)) return;
+
+  let output: string;
+  try {
+    output = execFileSync(
+      "git",
+      ["ls-files", "-z", "--others", "--ignored", "--exclude-from", includeFile],
+      { cwd: repoPath, encoding: "utf-8" }
+    );
+  } catch {
+    return;
+  }
+
+  let placed = 0;
+  for (const rel of output.split("\0").filter(Boolean)) {
+    const src = path.join(repoPath, rel);
+    const dest = path.join(worktreePath, rel);
+    try {
+      if (!lstatSync(src).isFile()) continue;
+      if (existsSync(dest)) continue;
+      mkdirSync(path.dirname(dest), { recursive: true });
+      if (mode === "symlink") {
+        symlinkSync(src, dest);
+      } else {
+        copyFileSync(src, dest);
+      }
+      placed++;
+    } catch {
+      // Skip files that vanished or can't be read; placement is best-effort.
+    }
+  }
+
+  if (placed > 0) {
+    const noun = placed === 1 ? "file" : "files";
+    const verb = mode === "symlink" ? "symlinked" : "copied";
+    console.log(`  ${verb} ${placed} gitignored ${noun} from .worktreeinclude`);
+  }
+}
+
 export interface OrcheWorktree {
   worktreePath: string;
   branch: string | null;