Project SwitchingSAFE

Use sidecar next to CLI agents for diffs, file trees, conversation history, and task management with td

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: project-switching
description: >
  Project switching implementation in sidecar: project discovery, state management,
  UI flow, modal rendering, filtering, theme preview, and plugin reinitialization.
  Use when working on the project switcher feature, project management, worktree
  switching, or the project configuration system.
user-invocable: false
---

# Project Switching

Switch between git repositories without restarting sidecar. Press `@` to open the project switcher modal.

## Architecture Overview

The project switcher uses the app's declarative modal library (`internal/modal/`) for rendering and mouse handling.

### Key Files

| File | Contents |
|------|----------|
| `internal/app/model.go` | State, init, reset, filter, switch, theme preview |
| `internal/app/update.go` | Keyboard and mouse handlers |
| `internal/app/view.go` | Modal building and section rendering |
| `internal/modal/` | Modal library (builder, sections, layout) |
| `internal/config/types.go` | ProjectConfig struct |
| `internal/config/loader.go` | Config loading with path validation |

### Model State

```go
// internal/app/model.go
showProjectSwitcher         bool
projectSwitcherCursor       int
projectSwitcherScroll       int
projectSwitcherInput        textinput.Model
projectSwitcherFiltered     []config.ProjectConfig
projectSwitcherModal        *modal.Modal           // Cached modal instance
projectSwitcherModalWidth   int                    // Width for cache invalidation
projectSwitcherMouseHandler *mouse.Handler
```

## Project vs Worktree Switching

- **Project Switching** (`@`): Switch between configured projects from `config.json` (arbitrary repos)
- **Worktree Switching** (`W`): Switch between git worktrees within the current repository

## Configuration

Projects are configured in `~/.config/sidecar/config.json`:

```json
{
  "projects": {
    "list": [
      {"name": "sidecar", "path": "~/code/sidecar"},
      {"name": "td", "path": "~/code/td", "theme": "dark"}
    ]
  }
}
```

Paths support `~` expansion. Projects can have per-project themes.

## Core Flow

### Opening (`@` key)

```go
case "@":
    m.showProjectSwitcher = !m.showProjectSwitcher
    if m.showProjectSwitcher {
        m.activeContext = "project-switcher"
        m.initProjectSwitcher()
    } else {
        m.resetProjectSwitcher()
        m.updateContext()
    }
```

### Initialization (`model.go:433-454`)

`initProjectSwitcher()` clears cached modal, creates text input with "Filter projects..." placeholder, loads all projects, pre-selects current project, and previews its theme.

### Cleanup (`model.go:413-423`)

`resetProjectSwitcher()` resets all state, clears modal cache, and restores current project's theme (undoing any live preview).

## Modal Rendering

Uses `internal/modal/` with a builder pattern and lazy caching.

### Modal Structure

```
+-------------------------------------------+
| Switch Project                            |  <- Title
| [Filter projects...                    ]  |  <- Input section
| 3 of 10 projects                          |  <- Count section
|   ^ 2 more above                          |  <- Scroll indicator
| > sidecar                                 |  <- Selected item
|   ~/code/sidecar                          |
|   td (current)                            |  <- Current project (green)
|   v 5 more below                          |  <- Scroll indicator
| enter switch  up/down navigate  esc close |  <- Hints section
+-------------------------------------------+
```

### Caching (`view.go:114-137`)

`ensureProjectSwitcherModal()` builds modal only when it does not exist or width changed. Call `clearProjectSwitcherModal()` when content changes (filter input, cursor movement with scroll).

### Section Types

| Type | Factory | Purpose |
|------|---------|---------|
| Input | `modal.Input()` | Text input with focus |
| Custom | `modal.Custom()` | Complex content with focusables |
| Text | `modal.Text()` | Static text |
| Buttons | `modal.Buttons()` | Button row |

## Keyboard Handling (`update.go:600-690`)

Priority: KeyType switch (special keys) -> String switch (named keys) -> Fallthrough to textinput.

| Key | Action |
|-----|--------|
| `Esc` | Clear filter (if set) or close modal |
| `Enter` | Switch to selected project |
| `Up/Down` | Arrow navigation |
| `ctrl+n/ctrl+p` | Emacs-style navigation |
| Other keys | Forwarded to text input for filtering |

### Esc Behavior

First Esc clears filter if set. Second Esc (or first with empty filter) closes modal.

### Navigation

Cursor movement updates `projectSwitcherCursor` and calls `projectSwitcherEnsureCursorVisible()` to maintain scroll window (max 8 visible items).

## Filtering (`model.go:457-470`)

`filterProjects()` does case-insensitive substring match on both `Name` and `Path` fields. On filter change: clear modal cache, clamp cursor, reset scroll, preview theme.

## Mouse Handling (`update.go:1073-1115`)

Uses modal library's `HandleMouse()`. Each project item has a focusable ID (`project-switcher-item-N`). Click on item triggers switch. Hover state managed by modal library via `hoverID` string.

## Theme Preview (`model.go:580-586`)

`previewProjectTheme()` applies the selected project's theme live. Called on init, cursor movement, and filter changes. Theme is restored in `resetProjectSwitcher()`.

## Project Switching (`model.go:485-577`)

`switchProject()` performs:

1. Skip if same project (show toast)
2. Save active plugin state for old workdir
3. Check for saved worktree to restore
4. Update `m.ui.WorkDir` and repo name
5. Apply project-specific theme
6. Reinitialize all plugins via `m.registry.Reinit(targetPath)`
7. Send `WindowSizeMsg` for layout recalculation
8. Restore previously active plugin for new workdir
9. Return toast notification

### What Happens on Switch

1. All plugins stop (file watchers, git commands, etc.)
2. Plugin context updates to new working directory
3. All plugins reinitialize with new path
4. Previ

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

.codex/skills

GEMINI.md

Gates applied: no_behavioural_pass.