@solaqua/gji 0.1.0 → 0.2.0

package/README.md

@@ -1,277 +1,276 @@
-# gji
+# gji — Git worktrees without the hassle
 
-Context switching without the mess.
+> Jump between tasks instantly. No stash. No reinstall. No mess.
 
-`gji` is a Git worktree CLI for people who jump between tasks all day. It gives each branch or PR its own directory, so you stop doing `stash`, `pop`, reinstall cycles, and fragile branch juggling.
+`gji` wraps Git worktrees into a fast, ergonomic CLI. Each branch gets its own directory, its own `node_modules`, and its own terminal — so switching context is a single command instead of a ritual.
 
-## Why
+```sh
+gji new feature/payment-refactor   # new branch + worktree, cd in
+gji pr 1234                        # review PR in isolation, cd in
+gji go main                        # jump back, shell changes directory
+gji remove feature/payment-refactor
+```
 
-Standard branch switching gets annoying when you are:
+---
 
-- fixing one bug while reviewing another branch
-- hopping between feature work and PR checks
-- using multiple terminals, editors, or AI agents at the same time
+**If `gji` has saved you from a `git stash` spiral, a ⭐ on [GitHub](https://github.com/sjquant/gji) means a lot — it helps other developers find this tool.**
 
-`gji` keeps those contexts isolated in separate worktrees with deterministic paths.
+---
 
-## Install
+## The problem
 
-Current source install:
+You are deep in a feature branch. A colleague asks for a quick review. You:
 
-```sh
-git clone https://github.com/sjquant/gji.git
-cd gji
-pnpm install
-pnpm build
-npm install -g .
-```
+1. stash your changes
+2. checkout their branch
+3. wait for `pnpm install` to finish
+4. review
+5. checkout back
+6. pop your stash
+7. realize something is broken
 
-Confirm the CLI is available:
+**Or you use `gji` and it is just `gji pr 1234`.**
+
+## Install
 
 ```sh
-gji --version
-gji --help
+npm install -g @solaqua/gji
 ```
 
-## Quick start
-
-Inside a Git repository:
+Then add shell integration so `gji go`, `gji new`, and `gji remove` can change your directory:
 
 ```sh
-gji new feature/login-form
-gji status
-```
-
-That creates a linked worktree at a deterministic path:
+# zsh
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc && source ~/.zshrc
 
-```text
-../worktrees/<repo>/<branch>
+# bash
+echo 'eval "$(gji init bash)"' >> ~/.bashrc && source ~/.bashrc
 ```
 
-## Shell setup
-
-`gji new`, `gji go`, `gji root`, and `gji remove`/`gji rm` can only change your current directory when shell integration is installed. Without shell integration, the raw CLI prints the target path so it stays script-friendly.
-
-For zsh:
+## Quick start
 
 ```sh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc
-source ~/.zshrc
-```
+# start a new task
+gji new feature/dark-mode
 
-After that:
+# review a pull request
+gji pr 1234
 
-```sh
-gji new feature/login-form
-gji go feature/login-form
-gji root
-gji rm feature/login-form
-```
-
-changes your shell directory directly.
+# see what's open
+gji status
 
-If you reinstall or upgrade `gji`, refresh the shell function:
+# jump between worktrees
+gji go feature/dark-mode
+gji go main
 
-```sh
-eval "$(gji init zsh)"
+# clean up when done
+gji remove feature/dark-mode
 ```
 
-For scripts or explicit piping:
+Worktrees land at a deterministic path so your editor bookmarks and scripts always know where to look:
 
-```sh
-gji new feature/login-form
-gji go --print feature/login-form
-gji root --print
 ```
-
-`gji new` and `gji remove` print their destination paths in raw CLI mode, but in a shell-integrated session they change directory directly.
+../worktrees/<repo>/<branch>
+```
 
 ## Daily workflow
 
-Start a task:
-
 ```sh
-gji new feature/refactor-auth
-```
+gji new feature/auth-refactor     # new branch + worktree
+gji new --detached                # scratch space, auto-named
 
-Start a detached scratch worktree:
+gji pr 1234                       # checkout PR locally
+gji pr https://github.com/org/repo/pull/1234  # or paste the URL
 
-```sh
-gji new --detached
-```
+gji go feature/auth-refactor      # jump to a worktree
+gji root                          # jump to repo root
 
-Check what is active:
+gji status                        # health overview + ahead/behind counts
+gji ls                            # compact list
 
-```sh
-gji status
-gji ls
-```
+gji sync                          # rebase current worktree onto default branch
+gji sync --all                    # rebase every worktree
 
-Pull a PR into its own worktree:
-
-```sh
-gji pr 123
-gji pr #123
-gji pr https://github.com/owner/repo/pull/123
+gji clean                         # interactive bulk cleanup
+gji remove feature/auth-refactor  # remove one worktree and its branch
 ```
 
-Sync the current worktree with the latest default branch:
+## Shell setup
+
+Without shell integration `gji` prints paths and exits — which is fine for scripts but means it cannot `cd` you into a new worktree. Install the integration once:
 
 ```sh
-gji sync
+gji init zsh   # prints the shell function, review it if you like
 ```
 
-Sync every worktree in the repository:
+To install automatically:
 
 ```sh
-gji sync --all
+# zsh
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc
+
+# bash
+echo 'eval "$(gji init bash)"' >> ~/.bashrc
 ```
 
-Clean up stale linked worktrees interactively:
+After a reinstall or upgrade, re-source to pick up changes:
 
 ```sh
-gji clean
+eval "$(gji init zsh)"
 ```
 
-Finish a single worktree explicitly:
+For scripts that need the raw path, use `--print`:
 
 ```sh
-gji remove feature/refactor-auth
-# or
-gji rm feature/refactor-auth
+path=$(gji go --print feature/dark-mode)
+path=$(gji root --print)
 ```
 
-After removal, the shell-integrated command returns you to the repository root.
-
 ## Commands
 
-- `gji --version` prints the installed CLI version
-- `gji init [shell]` prints shell integration for `zsh`, `bash`, or `fish`
-- `gji new [branch] [--detached]` creates a branch and linked worktree; with shell integration it moves into the new worktree, and `--detached` creates a detached worktree instead
-- `gji pr <ref>` accepts `123`, `#123`, or a full PR/MR URL, extracts the numeric ID, then fetches `origin/pull/<number>/head` and creates a linked `pr/<number>` worktree
-- `gji go [branch] [--print]` jumps to an existing worktree when shell integration is installed, or prints the matching worktree path otherwise
-- `gji root [--print]` jumps to the main repository root when shell integration is installed, or prints it otherwise
-- `gji status [--json]` prints repository metadata, worktree health, and upstream divergence
-- `gji sync [--all]` fetches from the configured remote and rebases or fast-forwards worktrees onto the configured default branch
-- `gji ls [--json]` lists active worktrees in a table or JSON
-- `gji clean` interactively prunes one or more linked worktrees, including detached entries, while excluding the current worktree
-- `gji remove [branch]` and `gji rm [branch]` remove a linked worktree and delete its branch when present; with shell integration they return to the repository root
-- `gji config` reads or updates global defaults
+| Command | Description |
+|---|---|
+| `gji new [branch] [--detached] [--json]` | create branch + worktree, cd in |
+| `gji pr <ref> [--json]` | fetch PR ref, create worktree, cd in |
+| `gji go [branch] [--print]` | jump to a worktree |
+| `gji root [--print]` | jump to the main repo root |
+| `gji status [--json]` | repo overview, worktree health, ahead/behind |
+| `gji ls [--json]` | list active worktrees |
+| `gji sync [--all]` | fetch and rebase worktrees onto default branch |
+| `gji clean [--force] [--json]` | interactively prune stale worktrees |
+| `gji remove [branch] [--force] [--json]` | remove a worktree and its branch |
+| `gji config [get\|set\|unset] [key] [value]` | manage global defaults |
+| `gji init [shell]` | print or install shell integration |
 
 ## Configuration
 
-`gji` is usable without setup, but it supports defaults through:
+No setup required. Optional config lives in:
 
-- global config at `~/.config/gji/config.json`
-- repo-local config at `.gji.json`
+- `~/.config/gji/config.json` — global defaults
+- `.gji.json` — repo-local overrides (takes precedence)
 
-Repo-local values override global defaults.
+### Available keys
 
-Supported keys:
-
-- `branchPrefix`
-- `syncRemote`
-- `syncDefaultBranch`
-- `hooks`
-
-Example:
+| Key | Description |
+|---|---|
+| `branchPrefix` | prefix added to new branch names (e.g. `"feature/"`) |
+| `syncRemote` | remote for `gji sync` (default: `origin`) |
+| `syncDefaultBranch` | branch to rebase onto (default: remote `HEAD`) |
+| `syncFiles` | files to copy from main worktree into each new worktree |
+| `skipInstallPrompt` | `true` to disable the auto-install prompt permanently |
+| `hooks` | lifecycle scripts (see [Hooks](#hooks)) |
 
 ```json
 {
   "branchPrefix": "feature/",
   "syncRemote": "upstream",
-  "syncDefaultBranch": "main"
+  "syncDefaultBranch": "main",
+  "syncFiles": [".env.example", ".nvmrc"]
 }
 ```
 
-Behavior:
+### Config commands
 
-- if `syncRemote` is unset, `gji sync` defaults to `origin`
-- if `syncDefaultBranch` is unset, `gji sync` resolves the remote default branch from `HEAD`
+```sh
+gji config get
+gji config get branchPrefix
+gji config set branchPrefix feature/
+gji config unset branchPrefix
+```
 
 ## Hooks
 
-`hooks` runs shell commands at key points in the worktree lifecycle. Configure it in `.gji.json` or `~/.config/gji/config.json`:
+Run scripts automatically at key lifecycle moments:
 
 ```json
 {
   "hooks": {
     "afterCreate": "pnpm install",
-    "afterEnter": "echo switched to {{branch}}",
+    "afterEnter": "echo 'switched to {{branch}}'",
     "beforeRemove": "pnpm run cleanup"
   }
 }
 ```
 
-Hook keys:
-
-- `afterCreate` — runs after a new worktree is created, whether via `gji new` or `gji pr`
-- `afterEnter` — runs after switching to a worktree via `gji go`
-- `beforeRemove` — runs before a worktree is removed via `gji remove`
-
-Each hook receives context in two ways:
-
-**Template variables** (substituted into the command string):
-
-| Variable | Value |
+| Hook | When it runs |
 |---|---|
-| `{{branch}}` | branch name, or empty string for detached worktrees |
-| `{{path}}` | absolute path to the worktree |
-| `{{repo}}` | repository directory name |
+| `afterCreate` | after `gji new` or `gji pr` creates a worktree |
+| `afterEnter` | after `gji go` switches to a worktree |
+| `beforeRemove` | before `gji remove` deletes a worktree |
 
-**Environment variables** (available to the hook process):
+Hooks receive `{{branch}}`, `{{path}}`, `{{repo}}` as template variables and `GJI_BRANCH`, `GJI_PATH`, `GJI_REPO` as environment variables. A failing hook emits a warning but never aborts the command.
 
-| Variable | Value |
-|---|---|
-| `GJI_BRANCH` | branch name, or empty string for detached worktrees |
-| `GJI_PATH` | absolute path to the worktree |
-| `GJI_REPO` | repository directory name |
-
-Hooks run inside the worktree directory. A non-zero exit emits a warning but does not abort the command.
-
-Global and project-level hooks are merged per key — project values override global values for the same key, while keys only present in the global config still apply:
+Global and repo-local hooks deep-merge per key:
 
-```json
+```jsonc
 // ~/.config/gji/config.json
 { "hooks": { "afterCreate": "nvm use", "afterEnter": "echo hi" } }
 
 // .gji.json
 { "hooks": { "afterCreate": "pnpm install" } }
 
-// effective hooks
-{ "afterCreate": "pnpm install", "afterEnter": "echo hi" }
+// effective
+{ "hooks": { "afterCreate": "pnpm install", "afterEnter": "echo hi" } }
+```
+
+## Install prompt
+
+When `gji new` or `gji pr` creates a worktree, `gji` detects the project's package manager from its lockfile and offers to run the install command:
+
+```
+Run `pnpm install` in the new worktree?
+› Yes       run once
+  No        skip this time
+  Always    save as afterCreate hook
+  Never     disable this prompt for this repo
 ```
 
+**Always** saves `hooks.afterCreate` to `.gji.json`; **Never** writes `skipInstallPrompt: true`. Both are local-only — global config is never modified.
+
 ## JSON output
 
-`gji ls --json` returns branch/path entries:
+Every mutating command supports `--json` for scripting and AI agent use. Success goes to stdout, errors go to stderr with exit code 1.
 
 ```sh
-gji ls --json
+# create
+gji new --json feature/dark-mode
+# → { "branch": "feature/dark-mode", "path": "/…/worktrees/repo/feature/dark-mode" }
+
+# fetch PR
+gji pr --json 1234
+# → { "branch": "pr/1234", "path": "/…/worktrees/repo/pr/1234" }
+
+# remove
+gji remove --json --force feature/dark-mode
+# → { "branch": "feature/dark-mode", "path": "/…", "deleted": true }
+
+# bulk clean
+gji clean --json --force
+# → { "removed": [{ "branch": "...", "path": "..." }, …] }
+
+# error shape (any command)
+# stderr → { "error": "branch argument is required" }
 ```
 
-`gji status --json` returns a top-level object with:
+`--json` suppresses all interactive prompts. `--force` is required for `remove` and `clean` in JSON mode. `branch` is `null` for detached worktrees.
+
+`gji ls --json` and `gji status --json` also produce structured output — see `gji status --json | jq` for the full schema.
 
-- `repoRoot`
-- `currentRoot`
-- `worktrees`
+## Non-interactive / CI mode
 
-Each worktree entry contains:
+```sh
+GJI_NO_TUI=1 gji new feature/ci-branch
+GJI_NO_TUI=1 gji remove --force feature/ci-branch
+GJI_NO_TUI=1 gji clean --force
+```
 
-- `branch`: branch name or `null` for detached worktrees
-- `current`
-- `path`
-- `status`: `clean` or `dirty`
-- `upstream`: one of
-  - `{ "kind": "detached" }`
-  - `{ "kind": "no-upstream" }`
-  - `{ "kind": "tracked", "ahead": number, "behind": number }`
+`GJI_NO_TUI=1` disables all prompts. Commands that need confirmation require `--force`. `--json` implies the same behaviour.
 
 ## Notes
 
-- `gji` works from either the main repository root or any linked worktree
-- the current worktree is never offered as a `gji clean` removal candidate
-- `gji pr` accepts GitHub, GitLab, and Bitbucket-style PR/MR links, but still fetches from `origin` using GitHub-style `refs/pull/<number>/head`
+- Works from either the main repo root or inside any linked worktree
+- The current worktree is never offered as a `gji clean` candidate
+- `gji pr` parses GitHub, GitLab, and Bitbucket URLs but always fetches via `refs/pull/<number>/head` from `origin`
 
 ## License
 

package/dist/clean.d.ts

@@ -2,6 +2,7 @@ import type { WorktreeEntry } from './repo.js';
 export interface CleanCommandOptions {
     cwd: string;
     force?: boolean;
+    json?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/clean.js

@@ -1,4 +1,5 @@
 import { confirm, isCancel, multiselect } from '@clack/prompts';
+import { isHeadless } from './headless.js';
 import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
 export function createCleanCommand(dependencies = {}) {
@@ -10,10 +11,23 @@ export function createCleanCommand(dependencies = {}) {
         const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd);
         const cleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
         if (cleanupCandidates.length === 0) {
-            options.stderr('No linked worktrees to clean\n');
+            emitError(options, 'No linked worktrees to clean');
             return 1;
         }
-        const selections = await promptForWorktrees(cleanupCandidates);
+        if (!options.force && (options.json || isHeadless())) {
+            const message = '--force is required';
+            if (options.json) {
+                emitError(options, message);
+            }
+            else {
+                options.stderr(`gji clean: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+            }
+            return 1;
+        }
+        // With --force, skip selection prompt and target all candidates.
+        const selections = options.force
+            ? cleanupCandidates.map((w) => w.path)
+            : await promptForWorktrees(cleanupCandidates);
         if (!selections || selections.length === 0) {
             options.stderr('Aborted\n');
             return 1;
@@ -28,6 +42,7 @@ export function createCleanCommand(dependencies = {}) {
             return 1;
         }
         const removedPaths = [];
+        const removedWorktrees = [];
         for (const worktree of selectedWorktrees) {
             try {
                 await removeWorktree(repository.repoRoot, worktree.path);
@@ -45,12 +60,15 @@ export function createCleanCommand(dependencies = {}) {
                     await forceRemoveWorktree(repository.repoRoot, worktree.path);
                 }
                 catch (forceError) {
-                    reportRemovedPaths(removedPaths, options.stderr);
-                    options.stderr(`Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}\n`);
+                    if (!options.json) {
+                        reportRemovedPaths(removedPaths, options.stderr);
+                    }
+                    emitError(options, `Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}`);
                     return 1;
                 }
             }
             removedPaths.push(worktree.path);
+            removedWorktrees.push(worktree);
             if (worktree.branch) {
                 try {
                     await deleteBranch(repository.repoRoot, worktree.branch);
@@ -73,7 +91,13 @@ export function createCleanCommand(dependencies = {}) {
                 }
             }
         }
-        options.stdout(`${repository.repoRoot}\n`);
+        if (options.json) {
+            const removed = removedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+            options.stdout(`${JSON.stringify({ removed }, null, 2)}\n`);
+        }
+        else {
+            options.stdout(`${repository.repoRoot}\n`);
+        }
         return 0;
     };
 }
@@ -96,6 +120,14 @@ function reportRemovedPaths(paths, stderr) {
         stderr(`Already removed: ${paths.join(', ')}\n`);
     }
 }
+function emitError(options, message) {
+    if (options.json) {
+        options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+    }
+    else {
+        options.stderr(`${message}\n`);
+    }
+}
 function toMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/cli.js

@@ -59,6 +59,7 @@ function registerCommands(program) {
         .command('new [branch]')
         .description('create a new branch or detached linked worktree')
         .option('--detached', 'create a detached worktree without a branch')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('new'));
     program
         .command('init [shell]')
@@ -68,6 +69,7 @@ function registerCommands(program) {
     program
         .command('pr <number>')
         .description('fetch a pull request ref and create a linked worktree')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('pr'));
     program
         .command('go [branch]')
@@ -98,12 +100,14 @@ function registerCommands(program) {
         .command('clean')
         .description('interactively prune linked worktrees')
         .option('-f, --force', 'bypass prompts, force-remove dirty worktrees, and force-delete unmerged branches')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('clean'));
     program
         .command('remove [branch]')
         .alias('rm')
         .description('remove a linked worktree and delete its branch when present')
         .option('-f, --force', 'bypass prompts, force-remove a dirty worktree, and force-delete an unmerged branch')
+        .option('--json', 'emit JSON on success or error instead of human-readable output')
         .action(notImplemented('remove'));
     const configCommand = program
         .command('config')
@@ -126,7 +130,7 @@ function attachCommandActions(program, options) {
     program.commands
         .find((command) => command.name() === 'new')
         ?.action(async (branch, commandOptions) => {
-        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached });
+        const exitCode = await runNewCommand({ ...options, branch, detached: commandOptions.detached, json: commandOptions.json });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -146,8 +150,8 @@ function attachCommandActions(program, options) {
     });
     program.commands
         .find((command) => command.name() === 'pr')
-        ?.action(async (number) => {
-        const exitCode = await runPrCommand({ cwd: options.cwd, number, stderr: options.stderr, stdout: options.stdout });
+        ?.action(async (number, commandOptions) => {
+        const exitCode = await runPrCommand({ cwd: options.cwd, json: commandOptions.json, number, stderr: options.stderr, stdout: options.stdout });
         if (exitCode !== 0) {
             throw commanderExit(exitCode);
         }
@@ -221,6 +225,7 @@ function attachCommandActions(program, options) {
         const exitCode = await runCleanCommand({
             cwd: options.cwd,
             force: commandOptions.force,
+            json: commandOptions.json,
             stderr: options.stderr,
             stdout: options.stdout,
         });
@@ -233,6 +238,7 @@ function attachCommandActions(program, options) {
             branch,
             cwd: options.cwd,
             force: commandOptions.force,
+            json: commandOptions.json,
             stderr: options.stderr,
             stdout: options.stdout,
         });

package/dist/config.d.ts

@@ -11,6 +11,8 @@ export declare const DEFAULT_CONFIG: GjiConfig;
 export declare function loadConfig(root: string): Promise<LoadedConfig>;
 export declare function loadEffectiveConfig(root: string, home?: string): Promise<GjiConfig>;
 export declare function loadGlobalConfig(home?: string): Promise<LoadedConfig>;
+export declare function saveLocalConfig(root: string, config: GjiConfig): Promise<string>;
+export declare function updateLocalConfigKey(root: string, key: string, value: unknown): Promise<GjiConfig>;
 export declare function saveGlobalConfig(config: GjiConfig, home?: string): Promise<string>;
 export declare function unsetGlobalConfigKey(key: string, home?: string): Promise<GjiConfig>;
 export declare function updateGlobalConfigKey(key: string, value: unknown, home?: string): Promise<GjiConfig>;

package/dist/config.js

@@ -25,6 +25,20 @@ export async function loadEffectiveConfig(root, home = homedir()) {
 export async function loadGlobalConfig(home = homedir()) {
     return loadConfigFile(GLOBAL_CONFIG_FILE_PATH(home));
 }
+export async function saveLocalConfig(root, config) {
+    const path = join(root, CONFIG_FILE_NAME);
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    return path;
+}
+export async function updateLocalConfigKey(root, key, value) {
+    const loaded = await loadConfig(root);
+    const nextConfig = {
+        ...loaded.config,
+        [key]: value,
+    };
+    await saveLocalConfig(root, nextConfig);
+    return nextConfig;
+}
 export async function saveGlobalConfig(config, home = homedir()) {
     const path = GLOBAL_CONFIG_FILE_PATH(home);
     await mkdir(dirname(path), { recursive: true });

package/dist/file-sync.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copies files matching each pattern (relative to mainRoot) into the equivalent
+ * relative path under targetPath, creating parent directories as needed.
+ *
+ * - Non-destructive: silently skips if the target file already exists.
+ * - Silently skips if the source file does not exist.
+ * - Rejects patterns that are absolute paths or contain `..` segments.
+ */
+export declare function syncFiles(mainRoot: string, targetPath: string, patterns: string[]): Promise<void>;

package/dist/file-sync.js

@@ -0,0 +1,52 @@
+import { copyFile, mkdir, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize } from 'node:path';
+/**
+ * Copies files matching each pattern (relative to mainRoot) into the equivalent
+ * relative path under targetPath, creating parent directories as needed.
+ *
+ * - Non-destructive: silently skips if the target file already exists.
+ * - Silently skips if the source file does not exist.
+ * - Rejects patterns that are absolute paths or contain `..` segments.
+ */
+export async function syncFiles(mainRoot, targetPath, patterns) {
+    for (const pattern of patterns) {
+        if (isAbsolute(pattern)) {
+            throw new Error(`syncFiles: pattern must be a relative path, got: ${pattern}`);
+        }
+        const normalized = normalize(pattern);
+        if (normalized.startsWith('..')) {
+            throw new Error(`syncFiles: pattern must not contain '..' segments, got: ${pattern}`);
+        }
+        const sourcePath = join(mainRoot, normalized);
+        const destPath = join(targetPath, normalized);
+        // Skip silently if source does not exist
+        const sourceExists = await fileExists(sourcePath);
+        if (!sourceExists) {
+            continue;
+        }
+        // Skip silently if target already exists
+        const destExists = await fileExists(destPath);
+        if (destExists) {
+            continue;
+        }
+        await mkdir(dirname(destPath), { recursive: true });
+        await copyFile(sourcePath, destPath);
+    }
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isNotFoundError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}

package/dist/go.js

@@ -1,6 +1,7 @@
 import { basename } from 'node:path';
 import { isCancel, select } from '@clack/prompts';
 import { loadEffectiveConfig } from './config.js';
+import { isHeadless } from './headless.js';
 import { extractHooks, runHook } from './hooks.js';
 import { detectRepository, listWorktrees } from './repo.js';
 import { writeShellOutput } from './shell-handoff.js';
@@ -12,6 +13,10 @@ export function createGoCommand(dependencies = {}) {
             listWorktrees(options.cwd),
             detectRepository(options.cwd),
         ]);
+        if (!options.branch && isHeadless()) {
+            options.stderr('gji go: branch argument is required in non-interactive mode (GJI_NO_TUI=1)\n');
+            return 1;
+        }
         const prompted = options.branch ? null : await prompt(worktrees);
         const resolvedPath = options.branch
             ? worktrees.find((entry) => entry.branch === options.branch)?.path

package/dist/headless.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns true when running in a non-interactive (headless) environment.
+ * Set GJI_NO_TUI=1 to disable all interactive prompts.
+ * Commands that would otherwise hang waiting for input must fail fast instead.
+ */
+export declare function isHeadless(): boolean;

package/dist/headless.js

@@ -0,0 +1,8 @@
+/**
+ * Returns true when running in a non-interactive (headless) environment.
+ * Set GJI_NO_TUI=1 to disable all interactive prompts.
+ * Commands that would otherwise hang waiting for input must fail fast instead.
+ */
+export function isHeadless() {
+    return process.env.GJI_NO_TUI === '1';
+}

package/dist/install-prompt.d.ts

@@ -0,0 +1,10 @@
+import { type GjiConfig } from './config.js';
+import { type PackageManager } from './package-manager.js';
+export type InstallChoice = 'yes' | 'no' | 'always' | 'never';
+export interface InstallPromptDependencies {
+    detectInstallPackageManager?: (root: string) => Promise<PackageManager | null>;
+    promptForInstallChoice?: (pm: PackageManager) => Promise<InstallChoice | null>;
+    runInstallCommand?: (command: string, cwd: string, stderr: (chunk: string) => void) => Promise<void>;
+    writeConfigKey?: (root: string, key: string, value: unknown) => Promise<void>;
+}
+export declare function maybeRunInstallPrompt(worktreePath: string, repoRoot: string, config: GjiConfig, stderr: (chunk: string) => void, dependencies?: InstallPromptDependencies, nonInteractive?: boolean): Promise<void>;

package/dist/install-prompt.js

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { isCancel, select } from '@clack/prompts';
+import { loadConfig, updateLocalConfigKey } from './config.js';
+import { isHeadless } from './headless.js';
+import { detectPackageManager } from './package-manager.js';
+export async function maybeRunInstallPrompt(worktreePath, repoRoot, config, stderr, dependencies = {}, nonInteractive = false) {
+    // Skip in non-interactive mode — no prompt can be shown.
+    if (isHeadless() || nonInteractive) {
+        return;
+    }
+    // Skip if afterCreate hook is already configured in effective config.
+    const hooks = isPlainObject(config.hooks) ? config.hooks : null;
+    if (typeof hooks?.afterCreate === 'string' && hooks.afterCreate.length > 0) {
+        return;
+    }
+    // Skip if user has permanently opted out of install prompts.
+    if (config.skipInstallPrompt === true) {
+        return;
+    }
+    const detect = dependencies.detectInstallPackageManager ?? detectPackageManager;
+    const pm = await detect(worktreePath);
+    if (!pm) {
+        return;
+    }
+    const prompt = dependencies.promptForInstallChoice ?? defaultPromptForInstallChoice;
+    const choice = await prompt(pm);
+    if (!choice || choice === 'no') {
+        return;
+    }
+    if (choice === 'yes' || choice === 'always') {
+        const runner = dependencies.runInstallCommand ?? defaultRunInstallCommand;
+        try {
+            await runner(pm.installCommand, worktreePath, stderr);
+        }
+        catch (error) {
+            stderr(`gji: install command failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+    const writeKey = dependencies.writeConfigKey ?? defaultWriteConfigKey;
+    if (choice === 'always') {
+        try {
+            // Read local config hooks to deep-merge so other hook keys (e.g. afterEnter) are preserved.
+            const { config: localConfig } = await loadConfig(repoRoot);
+            const existingLocalHooks = isPlainObject(localConfig.hooks) ? localConfig.hooks : {};
+            await writeKey(repoRoot, 'hooks', { ...existingLocalHooks, afterCreate: pm.installCommand });
+        }
+        catch (error) {
+            stderr(`gji: failed to save config: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+    if (choice === 'never') {
+        try {
+            await writeKey(repoRoot, 'skipInstallPrompt', true);
+        }
+        catch (error) {
+            stderr(`gji: failed to save config: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+}
+async function defaultRunInstallCommand(command, cwd, stderr) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, { cwd, shell: true, stdio: ['ignore', 'inherit', 'pipe'] });
+        child.stderr.on('data', (chunk) => {
+            stderr(chunk.toString());
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
+        });
+        child.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+async function defaultWriteConfigKey(root, key, value) {
+    await updateLocalConfigKey(root, key, value);
+}
+async function defaultPromptForInstallChoice(pm) {
+    const choice = await select({
+        message: `Run \`${pm.installCommand}\` in the new worktree?`,
+        options: [
+            { value: 'yes', label: 'Yes', hint: 'run once' },
+            { value: 'no', label: 'No', hint: 'skip this time' },
+            { value: 'always', label: 'Always', hint: 'save as afterCreate hook' },
+            { value: 'never', label: 'Never', hint: 'disable this prompt for this repo' },
+        ],
+    });
+    if (isCancel(choice)) {
+        return null;
+    }
+    return choice;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/new.d.ts

@@ -1,13 +1,15 @@
+import { type InstallPromptDependencies } from './install-prompt.js';
 import { type PathConflictChoice } from './conflict.js';
 export type { PathConflictChoice };
 export interface NewCommandOptions {
     branch?: string;
     cwd: string;
     detached?: boolean;
+    json?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }
-export interface NewCommandDependencies {
+export interface NewCommandDependencies extends InstallPromptDependencies {
     createBranchPlaceholder: () => string;
     promptForBranch: (placeholder: string) => Promise<string | null>;
     promptForPathConflict: (path: string) => Promise<PathConflictChoice>;

package/dist/new.js

@@ -4,7 +4,10 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { isCancel, text } from '@clack/prompts';
 import { loadEffectiveConfig } from './config.js';
+import { syncFiles } from './file-sync.js';
 import { extractHooks, runHook } from './hooks.js';
+import { isHeadless } from './headless.js';
+import { maybeRunInstallPrompt } from './install-prompt.js';
 import { pathExists, promptForPathConflict } from './conflict.js';
 import { detectRepository, resolveWorktreePath } from './repo.js';
 import { writeShellOutput } from './shell-handoff.js';
@@ -18,11 +21,26 @@ export function createNewCommand(dependencies = {}) {
         const repository = await detectRepository(options.cwd);
         const config = await loadEffectiveConfig(repository.repoRoot);
         const usesGeneratedDetachedName = options.detached && options.branch === undefined;
+        if (!options.detached && !options.branch && (options.json || isHeadless())) {
+            const message = 'branch argument is required';
+            if (options.json) {
+                options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+            }
+            else {
+                options.stderr(`gji new: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+            }
+            return 1;
+        }
         const rawBranch = options.detached
             ? options.branch ?? createBranchPlaceholder()
             : options.branch ?? await promptForBranch(createBranchPlaceholder());
         if (!rawBranch) {
-            options.stderr('Aborted\n');
+            if (options.json) {
+                options.stderr(`${JSON.stringify({ error: 'Aborted' }, null, 2)}\n`);
+            }
+            else {
+                options.stderr('Aborted\n');
+            }
             return 1;
         }
         const worktreeName = options.detached
@@ -32,6 +50,16 @@ export function createNewCommand(dependencies = {}) {
             ? await resolveUniqueDetachedWorktreePath(repository.repoRoot, worktreeName)
             : resolveWorktreePath(repository.repoRoot, worktreeName);
         if (!usesGeneratedDetachedName && await pathExists(worktreePath)) {
+            if (options.json || isHeadless()) {
+                const message = `target worktree path already exists: ${worktreePath}`;
+                if (options.json) {
+                    options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+                }
+                else {
+                    options.stderr(`gji new: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+                }
+                return 1;
+            }
             const choice = await prompt(worktreePath);
             if (choice === 'reuse') {
                 await writeOutput(worktreePath, options.stdout);
@@ -47,9 +75,27 @@ export function createNewCommand(dependencies = {}) {
                 ? ['worktree', 'add', worktreePath, worktreeName]
                 : ['worktree', 'add', '-b', worktreeName, worktreePath];
         await execFileAsync('git', gitArgs, { cwd: repository.repoRoot });
+        // Sync files from main worktree before afterCreate so synced files are available to install scripts.
+        const syncPatterns = Array.isArray(config.syncFiles)
+            ? config.syncFiles.filter((p) => typeof p === 'string')
+            : [];
+        for (const pattern of syncPatterns) {
+            try {
+                await syncFiles(repository.repoRoot, worktreePath, [pattern]);
+            }
+            catch (error) {
+                options.stderr(`Warning: failed to sync file "${pattern}": ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        await maybeRunInstallPrompt(worktreePath, repository.repoRoot, config, options.stderr, dependencies, !!options.json);
         const hooks = extractHooks(config);
         await runHook(hooks.afterCreate, worktreePath, { branch: worktreeName, path: worktreePath, repo: basename(repository.repoRoot) }, options.stderr);
-        await writeOutput(worktreePath, options.stdout);
+        if (options.json) {
+            options.stdout(`${JSON.stringify({ branch: worktreeName, path: worktreePath }, null, 2)}\n`);
+        }
+        else {
+            await writeOutput(worktreePath, options.stdout);
+        }
         return 0;
     };
 }

package/dist/package-manager.d.ts

@@ -0,0 +1,5 @@
+export interface PackageManager {
+    name: string;
+    installCommand: string;
+}
+export declare function detectPackageManager(repoRoot: string): Promise<PackageManager | null>;

package/dist/package-manager.js

@@ -0,0 +1,108 @@
+import { access, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const ENTRIES = [
+    // JavaScript / TypeScript
+    { name: 'pnpm', signals: ['pnpm-lock.yaml'], command: 'pnpm install' },
+    { name: 'yarn', signals: ['yarn.lock'], command: 'yarn install' },
+    { name: 'bun', signals: ['bun.lockb'], command: 'bun install' },
+    { name: 'npm', signals: ['package-lock.json'], command: 'npm install' },
+    { name: 'deno', signals: ['deno.json', 'deno.jsonc'], command: 'deno cache' },
+    // Python
+    { name: 'poetry', signals: ['poetry.lock'], command: 'poetry install' },
+    { name: 'uv', signals: ['uv.lock'], command: 'uv sync' },
+    { name: 'pipenv', signals: ['Pipfile.lock'], command: 'pipenv install' },
+    { name: 'pdm', signals: ['pdm.lock'], command: 'pdm install' },
+    { name: 'conda-lock', signals: ['conda-lock.yml'], command: 'conda-lock install' },
+    { name: 'conda', signals: ['environment.yml'], command: 'conda env update --file environment.yml' },
+    // R
+    { name: 'renv', signals: ['renv.lock'], command: "Rscript -e 'renv::restore()'" },
+    // Rust
+    { name: 'cargo', signals: ['Cargo.lock'], command: 'cargo build' },
+    // Go
+    { name: 'go', signals: ['go.sum'], command: 'go mod download' },
+    // Ruby
+    { name: 'bundler', signals: ['Gemfile.lock'], command: 'bundle install' },
+    // PHP
+    { name: 'composer', signals: ['composer.lock'], command: 'composer install' },
+    // Elixir / Erlang
+    { name: 'mix', signals: ['mix.lock'], command: 'mix deps.get' },
+    { name: 'rebar3', signals: ['rebar.lock'], command: 'rebar3 deps' },
+    // Dart / Flutter
+    { name: 'dart', signals: ['pubspec.lock'], command: 'dart pub get' },
+    // Java / Kotlin / Scala
+    { name: 'maven', signals: ['pom.xml'], command: 'mvn install' },
+    { name: 'gradle', signals: ['gradlew'], command: './gradlew build' },
+    { name: 'gradle', signals: ['build.gradle', 'build.gradle.kts'], command: 'gradle build' },
+    { name: 'sbt', signals: ['build.sbt'], command: 'sbt compile' },
+    // .NET (C# / F# / VB)
+    { name: 'dotnet', signals: ['*.sln', '*.csproj', '*.fsproj', '*.vbproj'], command: 'dotnet restore', glob: true },
+    // Swift
+    { name: 'swift', signals: ['Package.swift'], command: 'swift package resolve' },
+    // Haskell
+    { name: 'stack', signals: ['stack.yaml'], command: 'stack build' },
+    { name: 'cabal', signals: ['cabal.project'], command: 'cabal install --only-dependencies' },
+    { name: 'cabal', signals: ['*.cabal'], command: 'cabal install --only-dependencies', glob: true },
+    // Clojure
+    { name: 'clojure', signals: ['deps.edn'], command: 'clojure -P' },
+    { name: 'leiningen', signals: ['project.clj'], command: 'lein deps' },
+    // OCaml
+    { name: 'dune', signals: ['dune-project'], command: 'dune build' },
+    // Julia
+    { name: 'julia', signals: ['Manifest.toml'], command: "julia --project -e 'using Pkg; Pkg.instantiate()'" },
+    // Nim
+    { name: 'nimble', signals: ['*.nimble'], command: 'nimble install', glob: true },
+    // Crystal
+    { name: 'shards', signals: ['shard.yml'], command: 'shards install' },
+    // Perl
+    { name: 'cpanm', signals: ['cpanfile'], command: 'cpanm --installdeps .' },
+    // Zig
+    { name: 'zig', signals: ['build.zig.zon'], command: 'zig build' },
+    // C / C++
+    { name: 'vcpkg', signals: ['vcpkg.json'], command: 'vcpkg install' },
+    { name: 'conan', signals: ['conanfile.py', 'conanfile.txt'], command: 'conan install .' },
+    // Nix
+    { name: 'nix', signals: ['flake.nix'], command: 'nix develop' },
+    { name: 'nix-shell', signals: ['shell.nix'], command: 'nix-shell' },
+    // Terraform / OpenTofu
+    { name: 'terraform', signals: ['terraform.lock.hcl'], command: 'terraform init' },
+];
+export async function detectPackageManager(repoRoot) {
+    for (const entry of ENTRIES) {
+        const matched = entry.glob
+            ? await matchesGlob(repoRoot, entry.signals)
+            : await matchesExact(repoRoot, entry.signals);
+        if (matched) {
+            return { name: entry.name, installCommand: entry.command };
+        }
+    }
+    return null;
+}
+async function matchesExact(repoRoot, signals) {
+    for (const signal of signals) {
+        try {
+            await access(join(repoRoot, signal));
+            return true;
+        }
+        catch {
+            // file not found, try next signal
+        }
+    }
+    return false;
+}
+async function matchesGlob(repoRoot, patterns) {
+    let files;
+    try {
+        files = await readdir(repoRoot);
+    }
+    catch {
+        return false;
+    }
+    const regexes = patterns.map(patternToRegex);
+    return files.some((file) => regexes.some((re) => re.test(file)));
+}
+function patternToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '[^/]*');
+    return new RegExp(`^${escaped}$`);
+}

package/dist/pr.d.ts

@@ -1,12 +1,14 @@
 import { type PathConflictChoice } from './conflict.js';
+import { type InstallPromptDependencies } from './install-prompt.js';
 export type { PathConflictChoice };
 export interface PrCommandOptions {
     cwd: string;
+    json?: boolean;
     number: string;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }
-export interface PrCommandDependencies {
+export interface PrCommandDependencies extends InstallPromptDependencies {
     promptForPathConflict: (path: string) => Promise<PathConflictChoice>;
 }
 export declare function parsePrInput(input: string): string | null;

package/dist/pr.js

@@ -3,8 +3,11 @@ import { basename, dirname } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { loadEffectiveConfig } from './config.js';
+import { syncFiles } from './file-sync.js';
 import { pathExists, promptForPathConflict } from './conflict.js';
 import { extractHooks, runHook } from './hooks.js';
+import { isHeadless } from './headless.js';
+import { maybeRunInstallPrompt } from './install-prompt.js';
 import { detectRepository, resolveWorktreePath } from './repo.js';
 import { writeShellOutput } from './shell-handoff.js';
 const execFileAsync = promisify(execFile);
@@ -25,14 +28,31 @@ export function createPrCommand(dependencies = {}) {
     return async function runPrCommand(options) {
         const prNumber = parsePrInput(options.number);
         if (!prNumber) {
-            options.stderr(`Invalid PR reference: ${options.number}\n`);
+            const message = `Invalid PR reference: ${options.number}`;
+            if (options.json) {
+                options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+            }
+            else {
+                options.stderr(`${message}\n`);
+            }
             return 1;
         }
         const repository = await detectRepository(options.cwd);
+        const config = await loadEffectiveConfig(repository.repoRoot);
         const branchName = `pr/${prNumber}`;
         const remoteRef = `refs/remotes/origin/pull/${prNumber}/head`;
         const worktreePath = resolveWorktreePath(repository.repoRoot, branchName);
         if (await pathExists(worktreePath)) {
+            if (options.json || isHeadless()) {
+                const message = `target worktree path already exists: ${worktreePath}`;
+                if (options.json) {
+                    options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+                }
+                else {
+                    options.stderr(`gji pr: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+                }
+                return 1;
+            }
             const choice = await prompt(worktreePath);
             if (choice === 'reuse') {
                 await writeOutput(worktreePath, options.stdout);
@@ -45,7 +65,13 @@ export function createPrCommand(dependencies = {}) {
             await execFileAsync('git', ['fetch', 'origin', `refs/pull/${prNumber}/head:${remoteRef}`], { cwd: repository.repoRoot });
         }
         catch {
-            options.stderr(`Failed to fetch PR #${prNumber} from origin\n`);
+            const message = `Failed to fetch PR #${prNumber} from origin`;
+            if (options.json) {
+                options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+            }
+            else {
+                options.stderr(`${message}\n`);
+            }
             return 1;
         }
         await mkdir(dirname(worktreePath), { recursive: true });
@@ -54,10 +80,27 @@ export function createPrCommand(dependencies = {}) {
             ? ['worktree', 'add', worktreePath, branchName]
             : ['worktree', 'add', '-b', branchName, worktreePath, remoteRef];
         await execFileAsync('git', worktreeArgs, { cwd: repository.repoRoot });
-        const config = await loadEffectiveConfig(repository.repoRoot);
+        // Sync files from main worktree before afterCreate so synced files are available to install scripts.
+        const syncPatterns = Array.isArray(config.syncFiles)
+            ? config.syncFiles.filter((p) => typeof p === 'string')
+            : [];
+        for (const pattern of syncPatterns) {
+            try {
+                await syncFiles(repository.repoRoot, worktreePath, [pattern]);
+            }
+            catch (error) {
+                options.stderr(`Warning: failed to sync file "${pattern}": ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        await maybeRunInstallPrompt(worktreePath, repository.repoRoot, config, options.stderr, dependencies, !!options.json);
         const hooks = extractHooks(config);
         await runHook(hooks.afterCreate, worktreePath, { branch: branchName, path: worktreePath, repo: basename(repository.repoRoot) }, options.stderr);
-        await writeOutput(worktreePath, options.stdout);
+        if (options.json) {
+            options.stdout(`${JSON.stringify({ branch: branchName, path: worktreePath }, null, 2)}\n`);
+        }
+        else {
+            await writeOutput(worktreePath, options.stdout);
+        }
         return 0;
     };
 }

package/dist/remove.d.ts

@@ -3,6 +3,7 @@ export interface RemoveCommandOptions {
     branch?: string;
     cwd: string;
     force?: boolean;
+    json?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/remove.js

@@ -2,6 +2,7 @@ import { basename } from 'node:path';
 import { confirm, isCancel, select } from '@clack/prompts';
 import { loadEffectiveConfig } from './config.js';
 import { extractHooks, runHook } from './hooks.js';
+import { isHeadless } from './headless.js';
 import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
 import { writeShellOutput } from './shell-handoff.js';
@@ -14,7 +15,17 @@ export function createRemoveCommand(dependencies = {}) {
     return async function runRemoveCommand(options) {
         const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd);
         if (linkedWorktrees.length === 0) {
-            options.stderr('No linked worktrees to finish\n');
+            emitError(options, 'No linked worktrees to finish');
+            return 1;
+        }
+        if (!options.branch && (options.json || isHeadless())) {
+            const message = 'branch argument is required';
+            if (options.json) {
+                emitError(options, message);
+            }
+            else {
+                options.stderr(`gji remove: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+            }
             return 1;
         }
         const selection = options.branch ?? (await promptForWorktree(linkedWorktrees));
@@ -24,7 +35,17 @@ export function createRemoveCommand(dependencies = {}) {
         }
         const worktree = linkedWorktrees.find((entry) => entry.branch === selection || entry.path === selection);
         if (!worktree) {
-            options.stderr(`No linked worktree found for branch: ${selection}\n`);
+            emitError(options, `No linked worktree found for branch: ${selection}`);
+            return 1;
+        }
+        if (!options.force && (options.json || isHeadless())) {
+            const message = '--force is required';
+            if (options.json) {
+                emitError(options, message);
+            }
+            else {
+                options.stderr(`gji remove: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+            }
             return 1;
         }
         if (!options.force && !(await confirmRemoval(worktree))) {
@@ -49,7 +70,7 @@ export function createRemoveCommand(dependencies = {}) {
                 await forceRemoveWorktree(repository.repoRoot, worktree.path);
             }
             catch (forceError) {
-                options.stderr(`Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}\n`);
+                emitError(options, `Failed to remove worktree at ${worktree.path}: ${toMessage(forceError)}`);
                 return 1;
             }
         }
@@ -74,7 +95,12 @@ export function createRemoveCommand(dependencies = {}) {
                 }
             }
         }
-        await writeOutput(repository.repoRoot, options.stdout);
+        if (options.json) {
+            options.stdout(`${JSON.stringify({ branch: worktree.branch, path: worktree.path, deleted: true }, null, 2)}\n`);
+        }
+        else {
+            await writeOutput(repository.repoRoot, options.stdout);
+        }
         return 0;
     };
 }
@@ -104,6 +130,14 @@ async function defaultConfirmRemoval(worktree) {
 async function writeOutput(repoRoot, stdout) {
     await writeShellOutput(REMOVE_OUTPUT_FILE_ENV, repoRoot, stdout);
 }
+function emitError(options, message) {
+    if (options.json) {
+        options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
+    }
+    else {
+        options.stderr(`${message}\n`);
+    }
+}
 function toMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/gji",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git worktree CLI for fast context switching.",
   "license": "MIT",
   "author": "sjquant",