codebase-map

name: codebase-map description: Detailed map of the Leap codebase - the full src/ directory tree annotated with each module and script's role, plus the key-classes reference table mapping every important class or function to its file and purpose. Use this to locate a file, class, module, or helper, or to understand where functionality lives in Leap. user-invocable: false

Codebase Map

Full annotated source tree and key-classes reference for Leap. (Extracted from CLAUDE.md to keep that file lean; consult this when locating code.)

Project Structure

src/
├── scripts/                     # Entry point scripts
│   ├── leap-main.sh          # Main launcher (called by 'leap' command)
│   ├── leap-resume.py        # `leap --resume` picker (interactive + pre-pick GUI modes; cwd-choice for cwd-bound CLIs)
│   ├── leap-hook-process.py  # Hook processor (session recording, Slack last-message extraction)
│   ├── leap-cleanup.sh       # Dead session cleanup
│   ├── _leap                 # zsh completion for user-facing flags
│   ├── leap-server.py        # Thin launcher → LeapServer
│   ├── leap-client.py        # Thin launcher → LeapClient
│   ├── leap-monitor.py       # Thin launcher → MonitorWindow
│   ├── leap-slack.py         # Thin launcher → SlackBot
│   ├── leap_monitor_launcher.py  # py2app entry point
│   ├── setup-slack-app.sh       # Interactive Slack app setup wizard
│   ├── configure_jetbrains_xml.py   # JetBrains IDE auto-configuration
│   ├── configure_hooks.py           # Unified hook config (delegates to provider.configure_hooks())
│   ├── configure_claude_hooks.py    # Legacy Claude hook config
│   ├── configure_codex_hooks.py     # Legacy Codex hook config
│   ├── leap-hook.sh             # CLI hook script (writes state to signal file)
│   ├── leap-claude-statusline.py   # Claude status line: capture-only, writes <tag>.context with the authoritative 1M/200K window (chains any existing status line; silent when none)
│   ├── leap-copilot-statusline.py  # Copilot status line: writes <tag>.context for the monitor Context column (chains any existing status line)
│   └── leap-cursor-statusline.py   # cursor-agent status line: capture-only, writes <tag>.context (registered in ~/.cursor/cli-config.json; the encrypted session store has no transcript fallback)
│
└── leap/                     # Main Python package
    ├── __init__.py              # Version, exports
    ├── main.py                  # Package entry point
    │
    ├── cli_providers/           # CLI backend abstraction (Strategy pattern)
    │   ├── __init__.py          # Package exports, get_provider(), list_providers()
    │   ├── base.py              # CLIProvider ABC (patterns, timings, hooks, input)
    │   ├── claude.py            # Claude Code provider (Ink TUI, numbered menus)
    │   ├── codex.py             # OpenAI Codex provider (Ratatui TUI, y/n approval)
    │   ├── cursor_agent.py     # Cursor Agent provider (Ink TUI, menu approval)
    │   ├── gemini.py            # Gemini CLI provider (Ink TUI, radio-button approval)
    │   ├── registry.py          # Provider registry (name → class lookup)
    │   └── states.py            # CLIState enum + state groupings (WAITING/SIGNAL/PROMPT)
    │
    ├── utils/                   # Shared utilities
    │   ├── constants.py         # QUEUE_DIR, SOCKET_DIR, timing, colors, is_valid_tag()
    │   ├── terminal.py          # Terminal title, banner
    │   ├── ide_detection.py     # IDE detection, git branch
    │   ├── line_buffer.py       # Cursor-aware line editing buffer (raw-terminal prompts)
    │   ├── menu.py              # Numbered-menu parser (extract_menu_options, shared by server + monitor)
    │   ├── socket_utils.py      # Shared Unix socket send/recv helper
    │   ├── context_usage.py     # Per-CLI context-window % (monitor Context column). Claude/Codex/Gemini: transcript parsers. Claude+Copilot+cursor-agent: statusline_context_usage() reads <tag>.context written by the status-line script (authoritative window source; Claude prefers this over transcript and heals an impossible used>window record to 1M)
    │   ├── cost_usage.py        # Per-CLI cumulative token + USD estimate feeding the Context-cell tooltip's "Last message"/"Full session" lines. Claude: walk + dedup split-line entries, incremental accumulator. Codex: read the latest token_count's cumulative total_token_usage (no walk). Gemini: walk the chat file summing per-turn tokens. Generic non-blocking cached wrapper (background pool) for the GUI thread. Copilot/Cursor: no cost (no usable data)
    │   ├── pricing.py           # Data-driven model pricing (NOT hardcoded): loads vendored assets/model_prices.json (trim of LiteLLM to claude-/gpt-/o*/gemini- ids), background-refreshes it into .storage/model_prices.json, overlays cache>vendored. ModelPricing.rate() applies the data-driven long-context tier (_above_<N>k_tokens; 200k/272k). price_for() / cost_usd() (per-token, all token classes incl. reasoning) / format_usd() / trim_models() / ensure_fresh_prices()
    │   ├── resume_store.py      # Read/write/prune of cli_sessions/<cli>/<tag>.json (used by hook + picker; + latest_transcript_for)
    │   ├── relocation.py        # Shared primitives for cross-cwd session moves (signals_blocked, stage/commit, verify, snapshots)
    │   ├── claude_session_move.py  # Claude cross-cwd move (jsonl + optional sidecar dir)
    │   ├── gemini_session_move.py  # Gemini cross-cwd move (jsonl + projects.json registry)
    │   └── cursor_session_move.py  # Cursor cross-cwd move (whole chat directory tree)
    │
    ├── server/                  # PTY Server
    │   ├── server.py            # LeapServer - main orchestrator (composed with _mixins/)
    │   ├── pty_handler.py       # CLI PTY (pexpect, provider-driven)
    │   ├── socket_handler.py    # Unix socket server
    │   ├── queue_manager.py     # Message queue persistence
    │   ├── metadata.py          # Session metadata (IDE, project, branch, cli_provider)
    │   └── _mixins/             # LeapServer mixin classes
    │       ├── capture_input_mixin.py  # "^^" capture editor + terminal input-mirror (paste/image, saved msgs, csi-u)
    │       ├── io_filter_mixin.py      # PTY input/output byte-stream filters (keystroke dispatch, ↑/↓ recall, OSC title strip)
    │       └── background_loops_mixin.py  # auto-sender / title-keeper / stdin-watchdog daemon threads
    │
    ├── client/                  # Interactive Client
    │   ├── client.py            # LeapClient - main class
    │   ├── socket_client.py     # Unix socket client
    │   ├── input_handler.py     # Prompt toolkit / readline
    │   └── image_handler.py     # Clipboard image handling
    │
    ├── monitor/                 # GUI Monitor (PyQt5)
    │   ├── app.py               # MonitorWindow (core window + UI init + lifecycle)
    │   ├── columns.py           # Session-table column registry: single source for indices, labels, mono/center/toggle sets, separator groups
    │   ├── server_launcher.py   # PR server clone/checkout/start flow
    │   ├── session_manager.py   # Session discovery + read_client_pid()
    │   ├── scm_polling.py       # SCM poller + background workers (SessionRefreshWorker also scans Cursor GUI agent tabs when enabled)
    │   ├── cursor_gui_scan.py   # Read-only scan of Cursor editor Agent/Composer tabs (SQLite on disk) -> synthetic monitor rows
    │   ├── leap_sender.py       # Socket sender for /leap commands + message bundles
    │   ├── navigation.py        # IDE terminal navigation (+ focus_cursor_window / close_cursor_composer for Cursor GUI rows)
    │   ├── monitor_utils.py     # Utilities (icon finder, lock removal)
    │   ├── themes.py            # Visual theme definitions (9 built-in themes, manager API)
    │   ├── permissions.py       # macOS Accessibility + Notifications permission checks
    │   ├── sleep_guard.py       # SleepGuard (caffeinate) + LidCloseGuard (pmset disablesleep)
    │   ├── sudo_manager.py      # Saved sudo password for LidCloseGuard (.storage/sudo_pass.b64, base64 mode 0600)
    │   │
    │   ├── _mixins/             # MonitorWindow mixin classes
    │   │   ├── actions_menu_mixin.py  # Git menu (branch col) + Path menu (Open in Terminal/IDE, Move-to-IDE)
    │   │   ├── scm_config_mixin.py    # SCM provider init, setup dialogs, toggles
    │   │   ├── session_mixin.py       # Session merge, navigate, close, delete
    │   │   ├── pr_tracking_mixin.py   # PR tracking, polling, thread send, add-row
    │   │   ├── pr_display_mixin.py    # PR column styling, dock badge, banners
    │   │   ├── notifications_mixin.py # User notification handling
    │   │   └── table_builder_mixin.py # Table build, refresh, settings
    │   │
    │   ├── dialogs/             # Dialog windows
    │   │   ├── git_changes_dialog.py  # Git diff viewer (local, commit, vs main)
    │   │   ├── settings_dialog.py     # Settings (terminal, repos dir, diff tool, etc.)
    │   │   ├── notifications_dialog.py # Per-type notification config (dock/banner)
    │   │   ├── scm_setup_dialog.py    # Abstract SCM setup base dialog
    │   │   ├── gitlab_setup_dialog.py # GitLab connection dialog
    │   │   ├── github_setup_dialog.py # GitHub connection dialog
    │   │   ├── scm_template_dialog.py # Preset editor dialog (PR context + message bundles)
    │   │   ├── add_local_dialog.py    # Add session from local path dialog
    │   │   ├── resume_session_dialog.py # GUI `leap --resume` picker (returns (cli, tag, SessionRecord))
    │   │   ├── branch_picker_dialog.py # Branch picker for git difftool comparison
    │   │   ├── queue_edit_dialog.py   # Queue message editor dialog
    │   │   ├── send_comments_dialog.py # PR comments picker (filter / mode / context-preset)
    │   │   ├── whats_new_dialog.py    # "See what's new" dialog (lists HEAD..origin/main commits)
    │   │   ├── notes_dialog.py        # NotesDialog class (helpers in notes/ sub-package)
    │   │   ├── notes_undo.py          # Undo/redo command-pattern stack for Notes dialog
    │   │   └── notes/                 # Notes-dialog sub-package
    │   │       ├── __init__.py             # Package skeleton
    │   │       ├── rtl.py                  # Directional-text detection for QLineEdits
    │   │       ├── persistence.py          # FS helpers (note paths, listing, mtime, meta)
    │   │       ├── ordering.py             # Folder + per-folder child ordering
    │   │       ├── text_helpers.py         # Markdown link/bold helpers + URL highlighter
    │   │       ├── image_helpers.py        # Note-image save / refs / cleanup / preview popup
    │   │       ├── note_text_edit.py       # _NoteTextEdit rich editor (image paste, links, Cmd+B/C; RTL box/pipe-table fix: per-block LTR pin + per-cell FSI isolation, stripped on save)
    │   │       ├── checklist_io.py         # _parse_checklist / _serialize_checklist round-trip
    │   │       ├── checklist_widgets.py    # Google Keep-style checklist editor (4 inter-referencing classes)
    │   │       ├── tree_widget.py          # _NotesTreeWidget — left-panel QTreeWidget with custom DnD
    │   │       └── session_picker.py       # _SessionPickerDialog — modal picker for "Run in Session"
    │   │
    │   ├── ui/                  # UI components
    │   │   ├── ui_widgets.py    # PulsingLabel, IndicatorLabel
    │   │   ├── dock_badge.py    # Dock icon badge overlay + notification event detection
    │   │   ├── image_text_edit.py # ImageTextEdit (clipboard image paste) + SendMessageDialog + SendPresetDialog
    │   │   ├── log_history.py   # Log history (in-memory + dialog)
    │   │   └── table_helpers.py # Qt helper widgets (separators, tooltip overrides, ColorPickerPopup)
    │   │
    │   ├── pr_tracking/         # PR tracking subsystem
    │   │   ├── base.py          # Abstract SCMProvider, PRState, PRStatus, PRDetails
    │   │   ├── config.py        # GitLab/monitor prefs + pinned sessions persistence
    │   │   ├── gitlab_provider.py # GitLab API implementation
    │   │   ├── github_provider.py # GitHub API implementation
    │   │   ├── git_utils.py     # Git remote URL parsing + PR URL parsing
    │   │   └── leap_command.py    # /leap command data model + formatting
    │   └── resources/
    │       └── activate_terminal.groovy  # JetBrains script
    │
    ├── slack/                   # Slack Integration
    │   ├── __init__.py          # Package init
    │   ├── bot.py               # SlackBot main class (Socket Mode)
    │   ├── config.py            # Slack config + session persistence
    │   ├── output_capture.py    # Capture hook response, write .last_response for Slack bot
    │   ├── output_watcher.py    # Poll .last_response files → post to Slack
    │   └── message_router.py    # Route Slack messages → Leap sessions
    │
    └── vscode-extension/        # VS Code / Cursor Extension
        ├── package.json         # Extension metadata
        ├── extension.js         # Terminal selector logic
        └── README.md            # Extension documentation

tests/
├── __init__.py
└── test_state_tracker.py        # CLIStateTracker state machine tests

assets/
├── leap-icon.png             # Source icon (1024x1024)
├── leap-icon.icns            # macOS icon bundle
├── leap-simple-icon.png      # Alternate flat icon
└── leap-exclusive-icon.png   # Alternate exclusive icon

Key Classes