aryx/HANDOVER.md

Git-aware context UX handover

This document covers the frontend/UX work that can now be built on top of the newly implemented backend/shared git-context support.

What was implemented in backend/shared

The app now persists and refreshes per-project git context on ProjectRecord.

New shared project shape

File: src/shared/domain/project.ts

ProjectRecord now has:

git?: ProjectGitContext;

ProjectGitContext shape:

type ProjectGitContextStatus = 'ready' | 'not-repository' | 'git-missing' | 'error';

interface ProjectGitContext {
  status: ProjectGitContextStatus;
  scannedAt: string;
  repoRoot?: string;
  branch?: string;
  upstream?: string;
  ahead?: number;
  behind?: number;
  isDirty?: boolean;
  changedFileCount?: number;
  changes?: {
    staged: number;
    unstaged: number;
    untracked: number;
    conflicted: number;
  };
  head?: {
    hash: string;
    shortHash: string;
    subject: string;
    committedAt: string;
  };
  errorMessage?: string;
}

New backend behavior

Files:

• src/main/git/gitService.ts
• src/main/KopayaAppService.ts

Behavior:

• when a project is added, git context is fetched immediately
• when the workspace loads, the main process schedules an initial git-context refresh for all projects
• scratchpad projects intentionally do not carry git context
• non-repo folders are represented explicitly with status: 'not-repository'
• missing system git is represented explicitly with status: 'git-missing'
• unexpected git failures are represented with status: 'error' plus errorMessage

New Electron API

Files:

• src/shared/contracts/channels.ts
• src/shared/contracts/ipc.ts
• src/main/ipc/registerIpcHandlers.ts
• src/preload/index.ts

New API:

refreshProjectGitContext(projectId?: string): Promise<WorkspaceState>;

Notes:

• call with a projectId to refresh a single project
• call with no argument to refresh all projects
• the renderer also receives refreshed data through the existing onWorkspaceUpdated(...) subscription

Important UX constraints and current backend semantics

These are important so the frontend does not guess incorrectly:

• project.git is optional overall because scratchpad has no git context and older persisted workspaces may not have been refreshed yet
• status: 'ready' is the only state where branch/dirty/commit details should be assumed to exist
• branch may still be missing even when status === 'ready' (for example detached HEAD)
• head may be missing even when status === 'ready' (for example a repo with no commits yet)
• upstream, ahead, and behind are optional and should only be shown when present
• changedFileCount is a file-entry count, while changes breaks it down into staged / unstaged / untracked / conflicted
• this phase does not inject git context into sidecar run-turn payloads yet; this is app/backend UI support, not orchestration/runtime support

Recommended UX surfaces

1. Sidebar project rows

Primary file: src/renderer/components/Sidebar.tsx

Current ProjectGroup already renders:

• project icon
• project name
• running session count
• session count

Recommended additions for non-scratchpad projects:

• branch badge next to the project name when project.git?.status === 'ready'
• subtle dirty indicator when isDirty === true
• changed file count badge when changedFileCount > 0
• small warning/error badge for:
  • not-repository
  • git-missing
  • error
• refresh action for the selected or hovered project that calls api.refreshProjectGitContext(project.id)

Suggested behavior:

• keep the row compact; do not turn it into a full card
• prefer one-line metadata in the collapsed header and more detail in an expanded/hover area if needed
• scratchpad should remain visually distinct and should not show git affordances

2. Chat header / selected session context

Primary file: src/renderer/components/ChatPane.tsx

Current header already shows:

• project name
• pattern name
• pattern mode

Recommended additions for real projects:

• branch name beside the project title
• dirty state chip when the repo has pending changes
• optional compact summary like:
  • 3 changed
  • 2 ahead
  • 1 behind
• optional recent commit summary tooltip/popover using project.git.head

This is likely the best place to make git context feel relevant to the active conversation without overcrowding the sidebar.

3. Empty/welcome state

Primary file: src/renderer/components/WelcomePane.tsx

Optional but useful:

• update copy so project-backed sessions clearly imply branch/diff awareness
• if you add a project-management callout, mention that git state appears automatically for repositories

4. App-level wiring

Primary file: src/renderer/App.tsx

The frontend agent will likely need to thread a refresh callback into whichever component gets the refresh UI, for example:

() => void api.refreshProjectGitContext(projectId)

No extra state container is required because the workspace subscription already updates the renderer.

Suggested UX implementation order

1. Add a small git metadata presentation in Sidebar.tsx
2. Add selected-project git context in ChatPane.tsx
3. Wire refresh actions from App.tsx
4. Add polish for non-ready states (not-repository, git-missing, error)

Edge cases the UX should handle

• scratchpad: no git UI at all
• project added outside a git repo: show a neutral non-repo state, not a scary error
• git missing on the machine: show a helpful message, not a broken state
• detached HEAD: do not assume branch exists; fall back to commit short hash if useful
• brand-new repo with no commits: head may be absent even though the repo is valid
• upstream not configured: do not show ahead/behind placeholders
• refresh while viewing the project: avoid layout jumps; optimistic spinners are fine

Files most likely to change in the UX pass

• src/renderer/App.tsx
• src/renderer/components/Sidebar.tsx
• src/renderer/components/ChatPane.tsx
• src/renderer/components/WelcomePane.tsx

Out of scope for this handover

These are intentionally not implemented yet in backend/runtime:

• passing git context into sidecar agent instructions
• git diff viewers or file-by-file change inspection
• branch switching or commit actions
• git-aware working sets / file pinning
• project summary generation beyond git metadata