codmate: Instructions file for Codex

CodMate – AGENTS Guidelines

Purpose

• This document tells AI/code agents how to work inside the CodMate repository (macOS desktop GUI for Codex session management).
• Scope: applies to the entire repo. Prefer macOS SwiftUI/AppKit APIs; avoid iOS‑only placements or components.

Architecture

• App type: macOS SwiftUI app (min macOS 13.5). SwiftPM-only build (no Xcode project).
• Layering (MVVM):
  • Models: pure data structures (SessionSummary, SessionEvent, DateDimension, SessionLoadScope, …)
  • Services: IO and side effects (SessionIndexer, SessionCacheStore, SessionActions, SessionTimelineLoader, LLMClient)
  • ViewModels: async orchestration, filtering, state (SessionListViewModel)
  • Views: SwiftUI views only (no business logic)

UI Rules (macOS specific)

• Use macOS SwiftUI and AppKit bridges; do NOT use iOS‑only placements such as .navigationBarTrailing.
• Settings uses macOS 15's new TabView API (Tab("…", systemImage: "…")) when available; provide a macOS 13.5/14 fallback with tabItem + tag. Container padding is unified (horizontal 16pt, top 16pt).
  • Tab content uniformly uses SettingsTabContent container (top-aligned, overall 8pt padding) to ensure consistent layout and spacing across pages.
• Notifications is a top-level Settings page between Terminal and Providers; sections are Common, Codex, Claude Code, and Gemini CLI. Common toggles commit message, title/comment, and copy New/Resume command notifications.
• Providers has been separated from the Codex tab into a top-level Settings page: Settings › Providers manages API key providers, OAuth providers, and Codex/Claude bindings; Settings › Codex only retains Runtime/Privacy/Raw Config (notifications live in Settings › Notifications).
  • OAuth providers (Codex/Claude/Gemini/Antigravity/Qwen) are added from the Providers “Add” menu and appear under an OAuth list section with login status and info actions.
  • CLI Proxy API status, reroute, and public access live under Providers as shared capabilities; deep diagnostics and installation details live under Settings › Advanced › CLI Proxy API.
  • Built-in providers are auto-loaded from an app-bundled payload/providers.json (managedByCodMate=true). This avoids hardcoding and lets users simply provide API keys; base URLs/models come pre-filled. The list merges bundled entries with ~/.codmate/providers.json (user overrides win).
  • Schema note: use a single provider-level envKey (preferred) for both Codex and Claude Code connectors. Connector-level envKey remains tolerated for backward compatibility but is considered deprecated and will be ignored at save time to avoid duplication.
• Extensions page (aligned with Providers style):
  • Settings › Extensions replaces the old MCP Server page (icon: puzzlepiece.extension).
  • Tab 1: MCP Servers (existing list/editor/Uni‑Import UI kept as-is inside the tab); add an Import button to scan Home MCP configs into CodMate.
  • Tab 2: Skills (left list + right details split; Add menu supports folder/zip/URL; auto‑sync on changes); add an Import button to scan Home skills into CodMate.
  • Commands tab includes Add and Import buttons (Import scans Home command folders into CodMate).
  • Import sheets show a vertical list; each row has a right‑aligned strategy control (Skip/Overwrite/Rename) and a context menu “Open in…” to review source files.
  • MCP Servers tab keeps: enable toggle on left, edit on right, fixed "Add" button, Uni‑Import preview and confirmation.
  • Advanced capabilities (MCPMate download and instructions) remain as a footer/section in MCP Servers tab.
• Search: prefer a toolbar SearchField in macOS, not .searchable when exact placement (far right) matters.
• Toolbars: place refresh as the last ToolbarItem to pin it at the far right. Keep destructive actions in the detail pane, not in the main toolbar. Command+R and the refresh button also invalidate and recompute global sidebar statistics (projects/path tree and calendar day counts) to reflect new sessions immediately.
• Menu Bar (status item): keep it lightweight with status + quick actions. Show provider/model/sandbox/approval, New/Resume/Search/Open, Recent Projects/Sessions (max 5), Usage summary, Provider switch, Settings/Quit; avoid destructive actions.
• Sidebar (left):
  • Top (fixed): "All Sessions" row showing total count and selection state.
  • Middle (scrollable): path tree built from cwd counts. Rows are compact: default min row height 18, small control size, reduced insets. Single-click selects/expands; double-click applies filter (enter the directory).
  • Projects mode mirrors the compact list style; Cmd-click toggles multi-selection so users can filter sessions by several projects simultaneously (descendants remain included).
  • Bottom (fixed): calendar month view (240pt height) with per-day counts (created/last-updated switch). Always pinned to the bottom with 8pt spacing above. Supports multi-select via Command-click to toggle multiple days; plain click selects a single day (click the same day to clear).
  • Only the middle path tree scrolls; top "All Sessions" and bottom calendar remain fixed.
  • Sidebar width: min 220pt, max 25% of window width, ideal 260pt.
• Content (middle):
  • Default scope loads “today” only for speed.
  • Sorting picker is left‑aligned with list content.
  • Each row shows: title, timestamps/duration, snippet, and compact metrics (user/assistant/tool/reasoning).
• Status bar (bottom console):
  • Docked console bar spans the right-side area (list + detail); sidebar stays full height.
  • Resizable via a drag handle; single-line header collapses/expands to multi-line log history.
  • Auto mode collapses when idle (no interaction); View menu supports Always Show/Hide.
• Detail (right):
  • Sticky action bar at top: Resume, Reveal in Finder, Delete, Export Markdown.
  • Add “New” button next to Resume to start a fresh Codex session using the current session’s working directory and model.
  • When an embedded terminal is running, show a “Prompts” button beside the folder (Reveal in Finder) icon. Clicking opens a searchable popover of preset command texts; selecting one inserts it into the embedded terminal input (does not auto-execute). User presses Return to run.
  • Project-level Extensions are configured in Edit Project: tabs are General, Profile, MCP Servers, Skills (auto‑sync; Gemini project-level toggles disabled). MCP Servers/Skills tabs include Import buttons that scan the project directory. Edit Project window should be resizable.
  • Review mode: the list.bullet.rectangle button toggles a full-area Review view (third mode, alongside Conversation and Internal Terminal). In Review mode the detail area is fully occupied by a Git Changes surface. It:
    • Auto-detects the Git repo at the session’s working directory (uses /usr/bin/env git and a robust PATH).
    • Lists changed files with stage/unstage toggles and shows a unified diff or a raw file preview (updates on save). Preview is text-only in phase 1.
    • Provides a commit box. In full-area mode it uses a multi-line editor with more space.
    • Repository authorization is on-demand: when opening Review, the app resolves the repository root (the folder containing .git) and, if needed, prompts the user with an NSOpenPanel to authorize that folder via a security-scoped bookmark. The Settings page no longer lists authorized repositories; authorization and revoke are managed inline in the Review header.
  • “Task Instructions” uses a DisclosureGroup; load lazily when expanded.
  • Conversation timeline uses LazyVStack; differentiate user/assistant/tool/info bubbles.
• Timeline & Markdown visibility: Settings › General provides per-surface checkboxes to choose which message types are shown in the conversation timeline and included when exporting Markdown. Defaults: Timeline shows User, Assistant, Reasoning, and Code Edit; Tool Invocation, Token Usage, and Other Info are off by default. Markdown includes only User and Assistant. Environment Context and Turn Context are surfaced in dedicated sections and not configurable; Task Instructions remain in the detail DisclosureGroup; Ghost Snapshot is ignored. Code edits are surfaced as their own message type (extracted from tool calls) and have a separate toggle.
  • Turn Context is surfaced in the Environment Context card and is not exposed as a separate toggle or timeline item.
  • Context menu in list rows adds: “Generate Title & 100-char Summary” to run LLM on-demand for the selected session.
• Embedded Terminal: One live shell per session when resumed in-app; switching sessions in the middle list switches the attached terminal. The shell keeps running when you navigate away. “Return to history” closes the running shell for the focused session.
  • Prompt picker: When embedded terminal is running, a Prompts button opens a searchable list. Prompts are merged from per-project .codmate/prompts.json (if present) and ~/.codmate/prompts.json (user), de-duplicated by command, then layered with a few built‑ins. Items accept either { "label": "…", "command": "…" } or a plain string (used for both). Selection inserts into the terminal input without executing. The header wrench button opens the preferred file (project if exists, else user). Typing a new command shows “Add …” to create a prompt in the preferred file. Deleting a built‑in prompt records it in a hidden list (prompts-hidden.json at project if project prompts exist, else at user), which suppresses that built‑in in the UI.
  • Terminal shortcuts: (none for now). Clearing via shortcut is not implemented.