Should `gtr ai` execute `postCd` hooks before launching the AI process?

[echarrod]

Summary

After creating a worktree with gtr new we get output like this:

[OK] Worktree created: /Users/ed/dev/core-worktrees/<branch>

Next steps:
  git gtr editor <branch>  # Open in editor
  git gtr ai <branch>      # Start AI tool
  cd "$(git gtr go <branch>)"  # Navigate to worktree

But when using the suggested command gtr ai <branch> to launch an AI coding agent in a worktree, the postCd hook defined in .gtrconfig is not executed. This means environment variables set by the hook are not available to the AI process.

Context

Our monorepo uses a postCd hook to source environment setup when navigating to a worktree:

[hooks]
    postCd = source ./vars.sh

This sets environment variables that tools and test frameworks depend on to locate resources relative to the worktree.

When using gtr cd <branch>, the hook runs and everything works. But gtr ai <branch> launches the AI process directly without running the hook, so it inherits the parent shell's environment which still points at the main checkout.

Suggestion

Have gtr ai execute the postCd hook before spawning the AI process, similar to how gtr cd does for interactive shells. This would ensure the AI agent has the same environment as a developer who gtr cd-ed into the worktree.

[traycerai]

Plan

Observations

• gtr cd (shell integration in file:lib/commands/init.sh) runs postCd hooks via eval "$_gtr_hook" directly in the user's shell after cd-ing to the worktree, so env vars persist.
• cmd_ai in file:lib/commands/ai.sh calls ai_start "$worktree_path" "${ai_args[@]}" with no hook execution at all.
• Both AI adapters (file:adapters/ai/claude.sh, file:adapters/ai/cursor.sh) launch the tool inside a subshell: (cd "$path" && <tool> "$@"). The AI process inherits env vars from that subshell.
• run_hooks in file:lib/hooks.sh deliberately isolates each hook in a subshell, so env vars set inside (e.g. source ./vars.sh) never propagate back to the caller.
• _auto_launch_ai in file:lib/launch.sh (used by cmd_create --ai) has the same gap.

Approach

Add a new run_hooks_in_env function to file:lib/hooks.sh that runs hooks in the current shell (no subshell), mirroring what the gtr cd shell integration already does. Call it in cmd_ai and _auto_launch_ai before spawning the AI process. Because ai_start runs in a child subshell, env vars exported in the current process are automatically inherited by the AI tool.

sequenceDiagram
    participant Shell as User Shell
    participant cmd_ai as cmd_ai (lib/commands/ai.sh)
    participant hooks as run_hooks_in_env (lib/hooks.sh)
    participant ai_start as ai_start (adapter)
    participant AI as AI Process (claude/cursor)

    Shell->>cmd_ai: gtr ai <branch>
    cmd_ai->>cmd_ai: resolve_worktree → worktree_path, branch
    cmd_ai->>hooks: run_hooks_in_env "postCd" worktree_path REPO_ROOT=... BRANCH=...
    hooks->>hooks: cd worktree_path
    hooks->>hooks: export REPO_ROOT, WORKTREE_PATH, BRANCH
    hooks->>hooks: eval "source ./vars.sh" (in current shell)
    hooks->>hooks: cd back to original dir
    hooks-->>cmd_ai: env vars now set in current process
    cmd_ai->>ai_start: ai_start worktree_path [args...]
    ai_start->>AI: (cd worktree_path && claude ...) — inherits env vars

Loading

---

Implementation Steps

1. Add run_hooks_in_env to file:lib/hooks.sh

Add a new function after run_hooks_in. It mirrors run_hooks_in but runs each hook with eval directly in the current shell (no subshell wrapper), so exported variables survive back to the caller. The function should:

• Accept the same signature as run_hooks_in: phase, directory, and optional KEY=VALUE env var pairs.
• Save the current directory, cd to directory, and restore it afterward.
• Export each KEY=VALUE pair with export "$kv" (same as run_hooks does inside its subshell).
• Iterate over hooks from cfg_get_all "gtr.hook.$phase" "hooks.$phase" and eval "$hook" directly — no subshell.
• Log hook execution the same way run_hooks does (log_step, log_info, log_error).
• On hook failure, emit log_warn but return 0 (non-blocking), consistent with how _auto_launch_ai and cmd_ai treat non-critical failures.

2. Update cmd_ai in file:lib/commands/ai.sh

After the worktree_path and branch locals are populated (lines 36–37) and before the ai_start call (line 42), add a call to run_hooks_in_env:

run_hooks_in_env "postCd" "$worktree_path" \
  REPO_ROOT="$repo_root" \
  WORKTREE_PATH="$worktree_path" \
  BRANCH="$branch"

Hook failures must be non-fatal — the AI launch should proceed regardless.

3. Update _auto_launch_ai in file:lib/launch.sh

The current signature is _auto_launch_ai worktree_path. Extend it to accept two optional positional parameters: repo_root and branch. When provided, call run_hooks_in_env "postCd" "$worktree_path" REPO_ROOT="$repo_root" WORKTREE_PATH="$worktree_path" BRANCH="$branch" before ai_start. When omitted (e.g. future callers), skip the hook call gracefully.

Update the call site in file:lib/commands/create.sh (line 195) to pass repo_root and branch_name:

[ "$start_ai" -eq 1 ] && { _auto_launch_ai "$worktree_path" "$repo_root" "$branch_name" || true; }

---

Summary of changes

File	Change
file:lib/hooks.sh	Add run_hooks_in_env — current-shell hook runner for env var propagation
file:lib/commands/ai.sh	Call run_hooks_in_env "postCd" before ai_start
file:lib/launch.sh	Extend _auto_launch_ai to accept repo_root/branch; call run_hooks_in_env
file:lib/commands/create.sh	Pass repo_root and branch_name to _auto_launch_ai

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `gtr cd` (shell integration in `file:lib/commands/init.sh`) runs `postCd` hooks via `eval "$_gtr_hook"` **directly in the user's shell** after `cd`-ing to the worktree, so env vars persist.
- `cmd_ai` in `file:lib/commands/ai.sh` calls `ai_start "$worktree_path" "${ai_args[@]}"` with no hook execution at all.
- Both AI adapters (`file:adapters/ai/claude.sh`, `file:adapters/ai/cursor.sh`) launch the tool inside a subshell: `(cd "$path" && <tool> "$@")`. The AI process inherits env vars from that subshell.
- `run_hooks` in `file:lib/hooks.sh` deliberately isolates each hook in a subshell, so env vars set inside (e.g. `source ./vars.sh`) never propagate back to the caller.
- `_auto_launch_ai` in `file:lib/launch.sh` (used by `cmd_create --ai`) has the same gap.

## Approach

Add a new `run_hooks_in_env` function to `file:lib/hooks.sh` that runs hooks in the **current shell** (no subshell), mirroring what the `gtr cd` shell integration already does. Call it in `cmd_ai` and `_auto_launch_ai` before spawning the AI process. Because `ai_start` runs in a child subshell, env vars exported in the current process are automatically inherited by the AI tool.

```mermaid
sequenceDiagram
    participant Shell as User Shell
    participant cmd_ai as cmd_ai (lib/commands/ai.sh)
    participant hooks as run_hooks_in_env (lib/hooks.sh)
    participant ai_start as ai_start (adapter)
    participant AI as AI Process (claude/cursor)

    Shell->>cmd_ai: gtr ai <branch>
    cmd_ai->>cmd_ai: resolve_worktree → worktree_path, branch
    cmd_ai->>hooks: run_hooks_in_env "postCd" worktree_path REPO_ROOT=... BRANCH=...
    hooks->>hooks: cd worktree_path
    hooks->>hooks: export REPO_ROOT, WORKTREE_PATH, BRANCH
    hooks->>hooks: eval "source ./vars.sh" (in current shell)
    hooks->>hooks: cd back to original dir
    hooks-->>cmd_ai: env vars now set in current process
    cmd_ai->>ai_start: ai_start worktree_path [args...]
    ai_start->>AI: (cd worktree_path && claude ...) — inherits env vars
```

---

## Implementation Steps

### 1. Add `run_hooks_in_env` to `file:lib/hooks.sh`

Add a new function after `run_hooks_in`. It mirrors `run_hooks_in` but runs each hook with `eval` directly in the current shell (no subshell wrapper), so exported variables survive back to the caller. The function should:

- Accept the same signature as `run_hooks_in`: `phase`, `directory`, and optional `KEY=VALUE` env var pairs.
- Save the current directory, `cd` to `directory`, and restore it afterward.
- Export each `KEY=VALUE` pair with `export "$kv"` (same as `run_hooks` does inside its subshell).
- Iterate over hooks from `cfg_get_all "gtr.hook.$phase" "hooks.$phase"` and `eval "$hook"` directly — **no subshell**.
- Log hook execution the same way `run_hooks` does (`log_step`, `log_info`, `log_error`).
- On hook failure, emit `log_warn` but **return 0** (non-blocking), consistent with how `_auto_launch_ai` and `cmd_ai` treat non-critical failures.

### 2. Update `cmd_ai` in `file:lib/commands/ai.sh`

After the `worktree_path` and `branch` locals are populated (lines 36–37) and before the `ai_start` call (line 42), add a call to `run_hooks_in_env`:

```
run_hooks_in_env "postCd" "$worktree_path" \
  REPO_ROOT="$repo_root" \
  WORKTREE_PATH="$worktree_path" \
  BRANCH="$branch"
```

Hook failures must be non-fatal — the AI launch should proceed regardless.

### 3. Update `_auto_launch_ai` in `file:lib/launch.sh`

The current signature is `_auto_launch_ai worktree_path`. Extend it to accept two optional positional parameters: `repo_root` and `branch`. When provided, call `run_hooks_in_env "postCd" "$worktree_path" REPO_ROOT="$repo_root" WORKTREE_PATH="$worktree_path" BRANCH="$branch"` before `ai_start`. When omitted (e.g. future callers), skip the hook call gracefully.

Update the call site in `file:lib/commands/create.sh` (line 195) to pass `repo_root` and `branch_name`:

```
[ "$start_ai" -eq 1 ] && { _auto_launch_ai "$worktree_path" "$repo_root" "$branch_name" || true; }
```

---

### Summary of changes

| File | Change |
|---|---|
| `file:lib/hooks.sh` | Add `run_hooks_in_env` — current-shell hook runner for env var propagation |
| `file:lib/commands/ai.sh` | Call `run_hooks_in_env "postCd"` before `ai_start` |
| `file:lib/launch.sh` | Extend `_auto_launch_ai` to accept `repo_root`/`branch`; call `run_hooks_in_env` |
| `file:lib/commands/create.sh` | Pass `repo_root` and `branch_name` to `_auto_launch_ai` |

---

Execution Information

Branch: main
Commit: d6fd5da

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[helizaga]

Fixed in #145.

gtr ai and gtr new --ai now run postCd hooks before launching the AI process. Env vars set by hooks (e.g., source ./vars.sh) propagate to the AI tool.

If no postCd hooks are configured, behavior is unchanged — no extra output.