repository-canvas

name	repository-canvas
description	Open the Gocus Git session launcher and repository canvas inside Codex. Use when the user wants a side-panel entry point for starting conflict resolution, commit creation, or worktree cleanup sessions, or asks to visualize and explore repository history, branches, changes, commits, or worktrees.

Repository Canvas

Open the native Gocus MCP widget as a Git session launcher. Repository visualization is supporting context.

Workflow

1. Resolve the target repository, folder, or a path inside it to an absolute path. If multiple locations are plausible, state which one you are opening.
2. Call open_repository_canvas with repoPath.
3. Select the initial history scope only when the user asks for it:
   • Use { "mode": "current" } for the checked-out branch.
   • Use { "mode": "branch", "ref": "<branch>" } for a named branch.
   • Otherwise omit view to show all refs and linked-worktree heads.
4. Omit displayMode to use the default fullscreen host surface, which Codex presents as the native side panel. Use displayMode: "inline" only when the user explicitly asks to keep the launcher in the conversation.
5. Let the user use the function panel directly: Sync, Publish, Push, Pull, and Fetch call app-only Git tools; Remote resolves and opens the configured repository URL. None of these actions sends a message to the current task.
6. Do not duplicate the full repository report in prose after the widget opens. Briefly name the selected scope and any important truncation, then let the launcher and canvas carry the workflow.

Interaction Notes

• Changed-file commit requests and merge-failure recovery may send an explicit user message through the MCP App host bridge. Function-panel actions never send messages.
• When the selected folder does not have Git initialized, the launcher opens normally in the same Folder without Git state as Gocus Desktop. The Initialize Git button creates the repository and adds a starter .gitignore only when the folder does not already contain one.
• The top-left Tools menu mirrors the Desktop Git and GitHub sections; the canvas has no embedded chat control, chat page, or Codex-specific lifecycle action.
• Sync and Fetch reuse the Desktop Git implementation. Sync may fetch, fast-forward, publish, pull, or push as indicated by the visible button; diverged and externally checked-out branches are skipped instead of forced.
• The footer Settings panel exposes the shared Disable fast-forward merges preference. Update, quit, and editor-switching controls remain outside the canvas because Codex owns that lifecycle and configuration.
• The Changed now window sends its commit prompt directly to the current Codex task instead of copying it to the clipboard.
• Commit Merge opens the same target-branch confirmation flow as Gocus Desktop and follows its Disable fast-forward merges setting, defaulting to an explicit no-fast-forward merge commit when no saved setting exists. A dirty workspace offers a Commit & merge in Codex prompt that commits the current source-branch changes, then merges that branch into the target. If Git reports another merge failure, the recovery prompt is sent directly to the current Codex task instead of being copied.
• Branch switching and safe worktree cleanup use the same explicit confirmation and safety checks as Gocus Desktop.
• Conflict sessions may resolve existing conflicts but must not commit or discard unrelated changes automatically.
• Commit sessions may stage and commit the scoped change but must not amend or push.
• Worktree sessions may remove only audit results with cleanup.safeToRemove=true and must never force removal.
• The fullscreen canvas filters commits locally by message, author, hash, and ref.
• Commit rows follow the desktop panel layout, with the Git rail, ref, hash, relative time, and diff statistics together.
• Refresh calls the same read-only tool with the current repository and view.
• The launcher requests fullscreen immediately after the MCP App host connects. Codex presents that host mode as the native side panel; other MCP App hosts may map it to their own fullscreen surface.

Safety

Opening, filtering, selecting, refreshing, resolving a remote URL, or resizing the widget is read-only. Fetch updates remote-tracking refs; Sync may update local branches or their configured remotes according to the visible action label. Initializing Git, switching branches, cleaning an audited worktree, and merging are app-only mutations that run only after the user explicitly confirms the corresponding canvas action. Initialization preserves an existing .gitignore; cleanup remains limited to audited safeToRemove worktrees; merge checks for a clean workspace and never pushes.