|
| 1 | +# Quick Launch New Claude Session — Design Doc |
| 2 | + |
| 3 | +## Problem |
| 4 | + |
| 5 | +Launching a new Claude Code session from CodeV currently has friction: |
| 6 | +- **Terminal tab**: `cd path && claude` works but is confined to CodeV's embedded terminal — cannot use external terminals (iTerm2, Ghostty, etc.) which are preferred for long sessions |
| 7 | +- **Manual**: opening an external terminal, cd-ing, running `claude` manually defeats CodeV's purpose as a quick switcher |
| 8 | +- **`claude` CLI has no `--cwd` flag**: must `cd` to the target directory first |
| 9 | + |
| 10 | +Two scenarios exist: |
| 11 | +1. **Multi-step** (already covered by Terminal tab) — complex operations needing full shell |
| 12 | +2. **One-shot launch** — quickly start a new Claude session in a specific directory, optionally in an external terminal |
| 13 | + |
| 14 | +## Design: Three Phases |
| 15 | + |
| 16 | +### Phase 1: `Cmd+Enter` on Projects Tab (Highest ROI) |
| 17 | + |
| 18 | +**Key insight**: The Projects tab already IS a path picker — no new UI needed. |
| 19 | + |
| 20 | +#### Shortcuts |
| 21 | + |
| 22 | +| Action | Effect | |
| 23 | +|--------|--------| |
| 24 | +| `Enter` (existing) | Open project in VS Code/Cursor | |
| 25 | +| `Cmd+Enter` (new) | Launch new Claude session in **default Launch Terminal** (from Settings) | |
| 26 | +| `Shift+Enter` (new) | Launch new Claude session in **CodeV terminal** (switches to Term tab) | |
| 27 | + |
| 28 | +Note: Exact shortcut assignment may be swapped after hands-on testing. Both shortcuts should be user-customizable (like existing ⌃+⌘+R etc.). |
| 29 | + |
| 30 | +#### User Flow |
| 31 | + |
| 32 | +1. `⌃+⌘+R` → open CodeV |
| 33 | +2. (optional) type to filter projects |
| 34 | +3. Select project with arrow keys |
| 35 | +4. `Cmd+Enter` → done. CodeV hides, external terminal opens with `cd <path> && claude` |
| 36 | + |
| 37 | +#### Why This Works |
| 38 | + |
| 39 | +- Zero new UI — reuses existing project list as path picker |
| 40 | +- Zero learning curve — same muscle memory as `Enter` to open project |
| 41 | +- Path already resolved from project data |
| 42 | +- Terminal choice from existing "Launch Terminal" setting |
| 43 | +- `Shift+Enter` gives "quick task in CodeV terminal" escape hatch |
| 44 | +- Fire-and-forget: `cd && claude`, no need to see output |
| 45 | + |
| 46 | +#### Implementation |
| 47 | + |
| 48 | +- Add key handler in `switcher-ui.tsx` project selection for `Cmd+Enter` / `Shift+Enter` |
| 49 | +- Reuse launch logic from `claude-session-utility.ts` — same as `openSession()` but with `claude` instead of `claude --resume <id>` |
| 50 | +- New IPC handler: `launch-new-claude-session(projectPath, terminalApp?, terminalMode?)` |
| 51 | +- For CodeV terminal: send `cd <path> && claude\n` to PTY via existing `terminalInput` IPC |
| 52 | +- No `--name` flag by default — launching from CodeV doesn't imply a specific session purpose |
| 53 | + |
| 54 | +#### Key Files |
| 55 | + |
| 56 | +| File | Changes | |
| 57 | +|------|---------| |
| 58 | +| `src/switcher-ui.tsx` | Key handler for Cmd+Enter / Shift+Enter on project items | |
| 59 | +| `src/claude-session-utility.ts` | New `launchNewClaudeSession()` function (reuses existing terminal launch logic) | |
| 60 | +| `src/main.ts` | New IPC handler `launch-new-claude-session` | |
| 61 | +| `src/preload.ts` | Expose new IPC to renderer | |
| 62 | +| `src/electron-api.d.ts` | Type definition for new API | |
| 63 | + |
| 64 | +#### Mouse Support |
| 65 | + |
| 66 | +`Cmd+Click` on a project item also launches a new Claude session (same as `Cmd+Enter`). |
| 67 | + |
| 68 | +#### UI Button Consideration (Deferred) |
| 69 | + |
| 70 | +A permanent Claude icon button on each project item was considered but deferred: |
| 71 | +- **Pro**: Discoverable, mouse-friendly |
| 72 | +- **Con**: Visual noise on items where it's unused; Projects row already has name + branch + path + X button |
| 73 | +- **Con**: Sessions tab items are even more crowded — inconsistent if only Projects has it |
| 74 | +- **Decision**: Start with keyboard (`Cmd+Enter`) + mouse (`Cmd+Click`) only. Revisit if discoverability is a problem. |
| 75 | + |
| 76 | +An alternative is the **expanded item view** (see Phase 1.5 below). |
| 77 | + |
| 78 | +#### Custom Shortcut Support |
| 79 | + |
| 80 | +Both shortcuts should be user-customizable (like existing ⌃+⌘+R etc.). |
| 81 | + |
| 82 | +### Phase 1.5: Expanded Project Item View (Deferred) |
| 83 | + |
| 84 | +An expandable detail view for project items, similar to the planned Space-key Quick Look for sessions (#66 item 3). |
| 85 | + |
| 86 | +#### Concept |
| 87 | + |
| 88 | +``` |
| 89 | + fred-ff [main] /Users/grimmer/git |
| 90 | + ┌─────────────────────────────────────────────────────────┐ |
| 91 | + │ [Open in IDE] [New Claude ▾] [Open in Terminal] │ |
| 92 | + │ Active sessions: 2 (1 CLI, 1 VS Code) │ |
| 93 | + └─────────────────────────────────────────────────────────┘ |
| 94 | + codev [docs/quick-launch-claude-session] /Users/grimmer/git |
| 95 | +``` |
| 96 | + |
| 97 | +- `Space` or `→` to expand selected project item |
| 98 | +- Shows action buttons + extra info (active sessions, git status) |
| 99 | +- `[New Claude ▾]` dropdown for terminal selection |
| 100 | +- `Esc` or `←` to collapse |
| 101 | + |
| 102 | +#### Relationship with Cmd+Enter |
| 103 | + |
| 104 | +These can coexist — expanded view is for "browse then decide" users, `Cmd+Enter` is for power users who want instant action. Like Finder: `Space` = Quick Look, `Cmd+O` = open. |
| 105 | + |
| 106 | +If expanded view becomes the primary interaction model, `Cmd+Enter` shortcut becomes less critical but still valuable as a fast path. |
| 107 | + |
| 108 | +### Phase 2: Search Bar `>` Command Mode (Power User Flexibility) |
| 109 | + |
| 110 | +When user types `>` as the first character in **either** Projects or Sessions search bar, it enters command mode. |
| 111 | + |
| 112 | +#### Syntax |
| 113 | + |
| 114 | +``` |
| 115 | +> claude → show project list for selection |
| 116 | +> claude codev → fuzzy-filter projects, select to launch |
| 117 | +> claude @ghostty codev → override terminal for this launch |
| 118 | +> claude @codev fred-ff → explicitly use CodeV terminal |
| 119 | +``` |
| 120 | + |
| 121 | +#### Visual Changes on `>` Entry |
| 122 | + |
| 123 | +- Search bar border changes color (e.g., cyan accent) |
| 124 | +- Placeholder text changes to: `claude [project], @terminal to override` |
| 125 | +- List below replaces sessions/projects with matching project items + terminal badge |
| 126 | + |
| 127 | +#### `@` Terminal Picker |
| 128 | + |
| 129 | +- Typing `@` after `> claude ` shows a dropdown of terminal options: `@iterm2`, `@ghostty`, `@terminal`, `@cmux`, `@codev` |
| 130 | +- Selecting one inserts a styled badge (like Slack @mentions) |
| 131 | +- Omitting `@` uses the default from Settings → Launch Terminal |
| 132 | + |
| 133 | +#### Why `>` Prefix |
| 134 | + |
| 135 | +- Familiar from VS Code command palette |
| 136 | +- Doesn't conflict with any session/project search term |
| 137 | +- Clean entry/exit: backspace past `>` returns to normal search |
| 138 | + |
| 139 | +#### Supported in Both Tabs |
| 140 | + |
| 141 | +Yes — same `>` behavior in Projects and Sessions search bars. In Sessions tab, `>` provides "launch new session" alongside existing "search existing sessions" flow. This addresses the need to quickly launch a new session even while browsing existing sessions. |
| 142 | + |
| 143 | +#### Future Extensibility |
| 144 | + |
| 145 | +The `>` command mode can later support additional commands beyond `claude`: |
| 146 | +- `> git status codev` — run git command for a project |
| 147 | +- `> code codev` — open project in VS Code (alternative to Enter) |
| 148 | +- etc. |
| 149 | + |
| 150 | +#### Implementation Complexity: Medium |
| 151 | + |
| 152 | +- Prefix detection in search input handler |
| 153 | +- Command parsing logic (split command, project name, @terminal) |
| 154 | +- Autocomplete UI reusing project list data |
| 155 | +- Visual mode switching (border color, placeholder) |
| 156 | +- Optional: `@` badge rendering (can defer, use plain text first) |
| 157 | + |
| 158 | +### Phase 3: Terminal Tab Enhancements (Nice-to-Have) |
| 159 | + |
| 160 | +#### A. "Open in External Terminal" Button |
| 161 | + |
| 162 | +Small icon in terminal tab header area. Detects current PTY working directory, opens it in configured Launch Terminal. |
| 163 | + |
| 164 | +Use case: user has been navigating in CodeV terminal and wants to "promote" to a proper terminal. |
| 165 | + |
| 166 | +#### B. "Launch Claude Here in External Terminal" Shortcut |
| 167 | + |
| 168 | +While in Terminal tab, a shortcut or button that takes the current directory and opens `cd <cwd> && claude` in external terminal. |
| 169 | + |
| 170 | +Use case: user cd'd to the right place in CodeV terminal but wants the Claude session in a real terminal. |
| 171 | + |
| 172 | +## Worktree Scenarios |
| 173 | + |
| 174 | +Launching new sessions often involves git worktrees. Three cases: |
| 175 | + |
| 176 | +| Case | Path | How created | Phase 1 coverage | |
| 177 | +|------|------|-------------|------------------| |
| 178 | +| **A. Sibling worktree** | `~/git/codev-xxx` | Manual `git worktree add` | ✅ Appears in Projects (if under Working Directory) | |
| 179 | +| **B. Claude-managed** | Inside project (`.claude/worktrees/...`) | `claude --worktree [name]` | Partial — path may not be in Projects list | |
| 180 | +| **C. Existing path** | Any existing directory | Already created elsewhere | ✅ If in Projects list | |
| 181 | + |
| 182 | +**Notes:** |
| 183 | +- `claude --worktree [name]` only accepts a name, not a custom path. It creates worktrees in a Claude-managed location inside the project. |
| 184 | +- Preferred workflow: sibling worktrees at `~/git/<project>-<name>` (Case A). These appear automatically in Projects tab when Working Directory is set to `~/git/`. |
| 185 | +- One-shot worktree creation (create + launch in one action) requires multiple steps (`git worktree add` + `cd` + `claude`), better suited for Terminal tab or Phase 2 `>` command mode. |
| 186 | +- Phase 1 covers Cases A and C fully. Case B is uncommon when users prefer sibling worktrees. |
| 187 | + |
| 188 | +## Technical Notes |
| 189 | + |
| 190 | +### Command Construction |
| 191 | + |
| 192 | +For terminal-based launch, the command is: |
| 193 | +```bash |
| 194 | +cd "<project-path>" && claude |
| 195 | +``` |
| 196 | + |
| 197 | +This reuses the same pattern as existing session resume (`cd "<path>" && claude --resume <id>`), just without the `--resume` flag. |
| 198 | + |
| 199 | +For **VS Code** launch, use the URI handler instead (no `cd` needed): |
| 200 | +```bash |
| 201 | +# Open project folder first (if not already open), then launch Claude Code tab |
| 202 | +# Use `open -b` with bundle ID to avoid extra Dock icon (vs `code` CLI) |
| 203 | +open -b com.microsoft.VSCode "<project-path>" |
| 204 | +open "vscode://anthropic.claude-code/open" |
| 205 | + |
| 206 | +# Or with a pre-filled prompt: |
| 207 | +open "vscode://anthropic.claude-code/open?prompt=<encoded-text>" |
| 208 | +``` |
| 209 | +See `docs/vscode-session-support-design.md` Layer 9 for details. Requires Claude Code VS Code extension v2.1.72+. |
| 210 | + |
| 211 | +### Terminal-Specific Launch |
| 212 | + |
| 213 | +Each terminal already has launch logic in `claude-session-utility.ts`: |
| 214 | +- **iTerm2**: AppleScript `create tab` + `write text` |
| 215 | +- **Ghostty**: AppleScript `new surface configuration` with `initial input` |
| 216 | +- **cmux**: CLI `new-workspace --command` |
| 217 | +- **Terminal.app**: AppleScript `do script` |
| 218 | +- **VS Code**: `open -b <bundleId> <path>` + URI handler `vscode://anthropic.claude-code/open` |
| 219 | +- **CodeV**: `terminalInput()` IPC to embedded PTY |
| 220 | + |
| 221 | +The new `launchNewClaudeSession()` function can delegate to these same implementations. |
| 222 | + |
| 223 | +### Settings Integration |
| 224 | + |
| 225 | +Uses existing settings: |
| 226 | +- `session-terminal-app`: which terminal to use (iterm2/ghostty/cmux/terminal/vscode) |
| 227 | +- `session-terminal-mode`: tab or window (not applicable to VS Code) |
| 228 | + |
| 229 | +No new settings needed for Phase 1. Phase 2's `@terminal` override is per-invocation, not persisted. |
| 230 | + |
| 231 | +## Priority & Effort |
| 232 | + |
| 233 | +| Phase | Effort | Impact | Description | |
| 234 | +|-------|--------|--------|-------------| |
| 235 | +| Phase 1 | Small | High | `Cmd+Enter` on project → new claude session | |
| 236 | +| Phase 2 | Medium | Medium | `>` command mode in search bar | |
| 237 | +| Phase 3 | Small | Low | Terminal tab → external terminal button | |
| 238 | + |
| 239 | +Recommendation: Start with Phase 1. It covers 80%+ of the "quick launch" use case with minimal code. Phase 2 is worth doing if search bar command mode is desired as a platform for future commands. Phase 3 is independent. |
| 240 | + |
| 241 | +## Open Questions |
| 242 | + |
| 243 | +1. **Shortcut assignment**: `Cmd+Enter` vs `Shift+Enter` — which maps to external vs CodeV terminal? To be decided during implementation testing. |
| 244 | +2. **Sessions tab new-session shortcut**: Should there be a way to launch a new session from Sessions tab without switching to Projects tab first? Phase 2's `>` command mode addresses this. |
| 245 | +3. **Phase 2 scope**: Is `>` command mode needed now, or is Phase 1 sufficient? Depends on whether the command platform is valuable beyond just `claude` launch. |
0 commit comments