CommitFlow

Enterprise Git Graph Visualization, Direct Filesystem Engine, Multi-Provider Hub & Model Context Protocol (MCP) Server for Visual Studio Code

Installation • Features • Architecture • ️ Configuration • AI & MCP • Issues

Direct Filesystem Engine Reads `.git` metadata directly from disk with zero child processes. Instantaneous startup, offline readiness, and uninterrupted operation even if Git CLI is missing.	Topological Spline DAG Continuous cubic Bézier lanes with zero line crossings, integrated stashes, lightweight/annotated tags, commit signatures, and adaptive multi-dock placement.
Unified Remote Provider Hub Deep native integration for Forgejo, Gitea, GitHub, and GitLab. Read/write issues, pull request triage, and automatic `~/.ssh/config` alias parsing.	Built-in MCP Server Native JSON-RPC 2.0 Model Context Protocol stdio server empowering AI agents (Cursor, Claude, Antigravity) with structured Git tools and real-time repo resources.
⏳ Reflog Time Machine & Bisect Recover lost or orphaned commits in one click from `.git/logs/HEAD`. Interactive visual `git bisect` assistant with good/bad DAG coloring.	Cryptographic Security Dual OpenPGP/GPG and OpenSSH signature verification. Pre-flight `merge-tree` conflict forecaster to prevent merge collisions before staging.

Visual Tour & Interface Showcase

Topological Commit Graph, Advanced Filter Bar, Interactive Branch Minimap, and Split Commit Inspector Drawer in Dark+ wide view.

Light+ Theme Fidelity (`1200px`)	High Contrast Accessibility (`1200px`)

Left/Right Sidebar Mode (`360px`)	Split Panel & Commit Drawer (`750px`)

Architectural Overview
Core Features
Topological Commit Graph
Direct Filesystem Offline Engine
Unified Remote Providers: Forgejo, Gitea, GitHub, GitLab
Universal SSH and OpenSSH Parser
Fork Desktop Client Interoperability
Issue Tracker Hub and Issue-to-Code Workflow
Pull Request and Merge Request Triage
Git Worktree Management and Multi-WIP Tracking
Visual File Evolution and Line Delta Tracking
Cloud Patches (Zero-Push Collaboration)
Inline Blame and Author Contributions
GPG and OpenSSH Cryptographic Signature Verification
Visual Git Reflog Time Machine and Lost-Commit Recovery
Multi-Commit Diff Comparison Engine
Repository Health and Garbage Collection Diagnostics
Visual Git Bisect Assistant and Regression Hunter
Pre-Flight Cherry-Pick Conflict Forecaster
Adaptive Universal Responsive Layout Engine
Connect with your AI Studio & Secure API Key Management
Interactive Git Rebase Studio
Virtual Scrolling DAG Engine
Model Context Protocol (MCP) Server
Installation and Prerequisites
Getting Started
Configuration Reference
Forgejo and Gitea Integration Guide
SSH and OpenSSH Alias Resolution Guide
Model Context Protocol (MCP) Setup
Keyboard Shortcuts and Command Reference
Offline Architecture and Direct .git Inspection
Developer Workflow Operations
Troubleshooting and FAQ
Building from Source
Security, Privacy, and Telemetry
License

Architectural Overview

CommitFlow is a high-performance Visual Studio Code extension engineered for software developers, teams, and artificial intelligence agents that require instantaneous Git repository analysis, complex branch topology visualization, and deep hosting provider integration.

Unlike traditional Git graph extensions that depend exclusively on synchronous command-line subprocesses and remote network connections, CommitFlow combines a multi-tier runtime architecture:

+---------------------------------------------------------------------------------------+
| VISUAL STUDIO CODE HOST |
| |
| +--------------------+ +-----------------------+ +----------------------------+ |
| | Primary Activity | | Bottom Panel | | Secondary Sidebar | |
| | Bar Container | | Terminal Dock | | (Mirrored Drawers) | |
| +---------+----------+ +-----------+-----------+ +--------------+-------------+ |
| | | | |
| +--------------------------+------------------------------+ |
| | |
| v |
| +------------------------------------+ |
| | GraphWebviewProvider (CSP Safe) | |
| +------------------+-----------------+ |
| | |
+---------------------------------------|-----------------------------------------------+
 | IPC Messages / RPC
+---------------------------------------v-----------------------------------------------+
| COMMITFLOW CORE ENGINE |
| |
| +----------------------+ +---------------------+ +------------------------------+ |
| | RemoteManager | | IssueService & | | GitFsReader | |
| | (Forgejo/Gitea/GH/GL)| | BranchLinker Engine| | (Direct Disk .git Parser) | |
| +----------+-----------+ +----------+----------+ +--------------+---------------+ |
| | | | |
| +----------v-----------+ +----------v----------+ +--------------v---------------+ |
| | SshConfigParser | | Fork Client Bridge | | GitClient | |
| | (~/.ssh/config) | | (State Sync/CLI) | | (Non-blocking Batch Exec) | |
| +----------+-----------+ +----------+----------+ +--------------+---------------+ |
| | | | |
| +----------v-------------------------v----------------------------v---------------+ |
| | PersistenceManager (SecretStorage / VS Code Settings) | |
| +------------------------------------+--------------------------------------------+ |
| | |
| +------------------------------------v--------------------------------------------+ |
| | Model Context Protocol Server (JSON-RPC 2.0 via Stdio) | |
| | Exposes Tools, Resources, and Prompts to External AI Agents | |
| +---------------------------------------------------------------------------------+ |
+---------------------------------------------------------------------------------------+

Core Features

Topological Commit Graph

Topological Multi-Lane Layout: Uses a continuous Directed Acyclic Graph (DAG) sorting algorithm to allocate lane indices without line crossings.
Retina Bézier Spline Renderer: Computes cubic Bézier paths for incoming forks, merges, and continuous branch trajectories.
Adaptive Layout Modes:
Bottom Panel (Wide Split): Dual-column layout optimized for wide desktop screens and dock placement below the code editor.
Left Sidebar: Classical single-column view with slide-out details.
Right Sidebar: Mirrored drawer architecture that slides inwards to the left, preventing display cut-offs on narrow monitors.
Auto Responsive: Automatically determines the layout mode based on the current container dimensions via ResizeObserver.
Integrated Tags and Stashes: Renders release tags, lightweight tags, and stash revisions inline within the DAG.
Instant Search and Filtering: Filter commits in real time by author name, email, commit message, branch name, or SHA-1 hash.

Direct Filesystem Offline Engine

CommitFlow contains a built-in filesystem parser (GitFsReader) that reads the contents of the .git directory directly from disk without spawning child processes and without requiring an internet connection.

Zero-Process Execution: Reads repository state in sandboxed, restricted, or remote container environments where the git binary is missing or constrained.
Data Extracted Offline:
Reference resolution via .git/HEAD, .git/refs/heads/*, .git/refs/tags/*, and .git/refs/remotes/*.
Packed references resolution via .git/packed-refs including peeled annotated tag objects (^{}).
Configuration inspection via .git/config (parsing remotes, push URLs, branch upstreams, and user credentials).
Reflog commit extraction from .git/logs/HEAD providing chronological commit history without executing git log.
In-flight operation detection: .git/MERGE_HEAD (merge in progress), .git/CHERRY_PICK_HEAD (cherry-pick), .git/REVERT_HEAD (revert), and .git/rebase-merge/ or .git/rebase-apply/ (interactive or standard rebase state, steps, and head names).
Local stash log parsing via .git/logs/refs/stash.
Linked worktrees discovery via .git/worktrees/*.

Unified Remote Providers: Forgejo, Gitea, GitHub, GitLab

CommitFlow features a polymorphic provider architecture (RemoteProvider) capable of interfacing with public platforms, self-hosted instances, and air-gapped enterprise servers.

Deep Forgejo and Gitea Support:
Fully compatible with the Forgejo / Gitea API v1 specification (/api/v1).
Automatic instance detection via hostname heuristics and silent /api/v1/version validation.
Secure credential storage in VS Code SecretStorage keyed by host name (commitflow.token.forgejo.<host>).
Read and write support for issues, comments, issue state toggles (open/closed), milestones, labels, and pull requests.
Commit CI status inspection via /api/v1/repos/{owner}/{repo}/statuses/{sha}.
Local LRU caching layer ensuring issues and pull requests remain accessible even when the network is interrupted.
GitHub and GitLab Integration:
Native VS Code authentication session integration (repo scope).
Private repository detection with dedicated status badges (GitHub Private, GitLab Private, Forgejo Private).

Universal SSH and OpenSSH Parser

Resolves Git remote configurations across standard, customized, and complex SSH network topologies:

Supported URL Schemes:
Standard SCP syntax: git@forgejo.example.com:organization/repository.git
Explicit SSH with custom port: ssh://git@forgejo.example.com:2222/organization/repository.git
HTTPS / HTTP: https://forgejo.example.com/organization/repository.git
Local filesystem paths: /var/git/repository.git
OpenSSH Configuration Resolver:
Parses ~/.ssh/config (or a custom path configured in settings).
Resolves host aliases (for example, Host forgejo-box mapped to HostName 192.168.1.100, Port 2222, User git, IdentityFile ~/.ssh/id_ed25519).
Non-Blocking SSH Execution:
Injects GIT_SSH_COMMAND="ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new" into child processes.
Prevents background fetchers (autoFetch) from hanging when an SSH prompt or unknown host fingerprint is encountered.
Automatically preserves and forwards system SSH agent sockets (SSH_AUTH_SOCK).

Fork Desktop Client Interoperability

CommitFlow integrates directly with the Fork Git desktop client (Fork.exe on Windows, /Applications/Fork.app on macOS, and Linux):

Shared State Synchronization: Reads conflict states, active rebases, and merge heads initiated within Fork.
One-Click Bridge: Launches the active repository or worktree directly in Fork via local binary discovery or the fork://open custom URI protocol.

Issue Tracker Hub and Issue-to-Code Workflow

A dedicated navigation hub (Issues) integrated directly into the extension view:

Assigned to Me: Fetches open issues assigned to the authenticated developer from Forgejo, GitHub, or GitLab.
Branch and Commit Association:
Automatically identifies issues associated with the active branch by analyzing branch patterns (such as feat/issue-42-login or fix/#108-auth).
Scans unpushed local commit messages for references like Closes #42 or Refs #108.
Displays the linked issue in a prominent banner above the issue list.
Issue-to-Code Actions:
Create Branch / Worktree: One-click branch creation using customizable templates (default: feat/{id}-{slug}) or provisioning of a parallel Git worktree.
Insert Reference: Injects Closes #<id> into the commit preparation buffer or clipboard.
Lateral Inspector Drawer: View markdown-rendered descriptions, comment feeds, label chips, and milestone deadlines. Post comments or change status directly from VS Code.
Interactive Hover Cards: Hovering over #<id> in commit messages or file blame annotations displays a hover card with title, author, labels, and state.

Pull Request and Merge Request Triage

Triage Columns: Classifies active pull requests into four distinct status groups:
Blocked: Failing continuous integration pipelines or changes requested by reviewers.
Ready: Approved by reviewers with green CI/CD status.
Pending: Awaiting initial or peer reviews.
Mine: Authored by the current authenticated user.
Quick Actions: One-click checkout of remote head branches, direct browser links, and clipboard URL copying.

Git Worktree Management and Multi-WIP Tracking

Concurrent Branch Work: Work on multiple branches simultaneously in isolated directories without stashing or switching branches.
Dirty Working Tree Detection: Identifies whether each linked worktree has uncommitted modifications or is clean.
Worktree Lifecycle Operations: Add new worktrees, open worktrees in new VS Code windows, and prune stale worktree references.

Visual File Evolution and Line Delta Tracking

File History View: Trace the historical revisions of any file in the workspace or the currently active editor tab.
Line Delta Badges: Displays added (+N) and deleted (-N) line metrics per revision.
Native Diff Integration: Launch side-by-side comparative diffs against parent commits or the working tree with a single click.

Cloud Patches (Zero-Push Collaboration)

Share Uncommitted Changes: Generate self-contained patch bundles from staged or working tree diffs.
Dry-Run Validation: Verifies patch integrity using git apply --check before applying changes.
Reverse Patch Application: Safely roll back applied patch bundles.

Inline Blame and Author Contributions

Inline Ghost Text: Displays discreet inline blame annotations at the end of the active cursor line.
Status Bar Integration: Shows the commit author, relative timestamp, and commit SHA in the VS Code status bar.
Personal Contribution Analytics: Calculates total commits, participation percentages across repository branches, and active contributor rankings.

GPG and OpenSSH Cryptographic Signature Verification

Dual Cryptographic Parsing: Evaluates commit signatures generated via GNU Privacy Guard (OpenPGP/GPG) and OpenSSH signature keys (ssh-keygen -Y sign).
Signature Status Classification: Categorizes commits as valid, invalid, untrusted, or none by extracting %G?, %GS, and %GK tokens.
Visual Verification Badges: Displays verified shields in wide and compact views with detailed popover banners indicating key IDs, signer names, and validity statuses.

Visual Git Reflog Time Machine and Lost-Commit Recovery

Chronological Reference Log: Renders full movements of HEAD recorded in .git/logs/HEAD (or via git reflog), tracing checkouts, merges, soft/hard resets, rebases, and orphaned commits.
One-Click Branch Recovery: Allows immediate creation of a new branch from any orphaned or historically discarded commit hash, preventing accidental data loss.
Zero-Process Direct Disk Fallback: Operates directly over raw filesystem logs when external processes are unavailable.

Multi-Commit Diff Comparison Engine

Arbitrary Revision Range Inspection: Select any historical commit and compare it against HEAD or any secondary revision.
Unified Change Metrics: Summarizes total additions (+N), deletions (-M), and files altered across the range, including a list of intermediate commits.
Integrated File Level Diffs: Click on any modified file in the comparison modal to open side-by-side diff editors in Visual Studio Code.

Repository Health and Garbage Collection Diagnostics

Storage Metrics Inspection: Analyzes total repository size on disk, loose object counts, packfile counts, and dangling commit objects.
Proactive Maintenance Advisories: Alerts developers when loose objects or unreferenced commits exceed performance thresholds.
One-Click Git Garbage Collection: Triggers git gc --prune=now --quiet directly from the user interface to optimize repository packfiles and reclaim disk storage.

Visual Git Bisect Assistant and Regression Hunter

Interactive Binary Search Navigation: Initiates, steps through, and resolves Git Bisect sessions directly within the graph view.
Head-Up Status Banner: Displays the current revision under evaluation, active bad and good boundaries, and an approximate estimation of remaining diagnostic steps.
One-Click State Transitions: Developers can mark commits as Good, Bad, Skip (for unbuildable intermediate revisions), or Abort directly via top-level buttons.
Topological DAG Highlighting: The active probe commit pulses with a distinctive cyan highlight, while confirmed good commits receive emerald tags and confirmed bad commits receive crimson markers.
Offline Direct Filesystem State Inspection: In air-gapped or process-restricted workspaces, GitFsReader inspects .git/BISECT_START, .git/BISECT_EXPECTED_REV, and .git/refs/bisect/* markers to restore state without terminal calls.

Pre-Flight Cherry-Pick Conflict Forecaster

In-Memory Three-Way Merge Tree Simulation: Executes non-destructive git merge-tree analysis prior to altering the working directory or staging index.
Collision Risk Warning Modal: If conflicts are anticipated, CommitFlow interrupts execution and displays the exact conflicting file paths in an advisory dialog.
3-Way Visual Conflict Resolution & Conventional Commits Builder: Resolve conflicted hunks (Accept Ours, Accept Theirs, Accept Both), stage resolution, and craft SemVer-ready Conventional Commits with live #issue autocomplete.

Adaptive Universal Responsive Layout Engine

Full Multi-Dock Placement Support: Architected to adapt to any Visual Studio Code window configuration, including the Primary Left Activity Bar, Secondary Right Sidebar, Bottom Terminal Dock, Editor Tabs, and detached Popout auxiliary windows.
Multi-Tier Viewport Breakpoints: Automatically optimizes layout metrics across standard (>600px), compact (440px - 600px), sidebar compact (260px - 440px), and ultra-narrow nano viewports (<= 260px).
Collapsing Navigation Tab Bar: On narrow sidebars, tab titles collapse smoothly into icon-only pills with native hover tooltips, allowing all primary navigation views to fit without horizontal wrapping.
Dual-Pane Bottom Dock Split: In bottom panel placement, graph visualization and inspector drawers run side-by-side in dual-column split mode, avoiding intrusive overlay obstructions.
Clamped Floating Overlays: Popovers, tooltips, and inspector drawers dynamically calculate boundary clamping against window edges, preventing off-screen clipping on compact sidebars.
High-DPI Retina Canvas Rendering: Symmetrical cubic Bézier splines with dynamic lane color palettes for passing and merge lanes.

Connect with your AI Studio & Secure API Key Management

Universal AI Studio Connection: Effortlessly bridge CommitFlow with Google Antigravity, Claude Code, Cursor IDE, Open-WebUI, or custom autonomous AI agents.
Secure Cryptographic Key Vault: Generate scoped API keys (read-only or read/write) stored using SHA-256 salted hashes inside VS Code's SecretStorage. Keys can be restricted to specific workspaces/repositories and set with auto-expiration.
Dual-Transport Model Context Protocol (MCP):
- Stdio Transport: Embedded executable (bin/commitflow-mcp.js) running frictionless for desktop AI agents.
- Authenticated HTTP/SSE Daemon: Streamable real-time events over local loopback (127.0.0.1) protected with bearer tokens and origin verification.

Interactive Git Rebase Studio

Visual Commit Reordering: Drag-and-drop or use quick action menus to reorganize commits before rebasing onto base branches.
Action Selection Matrix: Seamlessly switch actions per commit: pick, reword, edit, squash, fixup, drop.
Pre-Flight Conflict Simulation: In-memory simulation calculates potential patch collisions before touching the git working copy.
Resolution Assistant: Step-by-step guidance to Continue, Skip, or Abort during conflict resolution.

Virtual Scrolling DAG Engine

Constant DOM Footprint: Maintains fewer than 150 active DOM nodes regardless of whether a repository has 500 or 100,000+ commits.
Buttery 60fps Experience: High-speed virtual windowing and hardware-accelerated canvas tracks ensure zero lag or frame drops while navigating massive monorepositories.
WCAG 2.1 AA Keyboard Accessibility: Roving tabindex keyboard navigation (Arrow keys, PageUp/PageDown, Home/End, Enter) and full ARIA treegrid semantics.

Model Context Protocol (MCP) Server

CommitFlow includes a built-in Model Context Protocol server (CommitFlowMcpServer) compliant with the JSON-RPC 2.0 specification. Any MCP client (such as Claude Desktop, Cursor IDE, or custom agent systems) can query repository state, execute operations, and read structured resources over stdio.

Installation and Prerequisites

Prerequisites

Visual Studio Code: Version 1.85.0 or higher.
Git: Version 2.23.0 or higher recommended (with support for git merge-tree --write-tree and git worktree).
OpenSSH Client: Standard on Linux, macOS, and modern Windows 10/11 installations.

Installation via Marketplace

Open Visual Studio Code.
Press Ctrl+P (or Cmd+P on macOS) and run:

ext install Ignaciobrenas.commitflow

Alternatively, search for CommitFlow in the Extensions view (Ctrl+Shift+X).

Manual Installation from VSIX Package

To install a pre-built .vsix release:

code --install-extension commitflow-1.0.0.vsix

Getting Started

Open any directory or workspace containing a Git repository in Visual Studio Code.
Click on the CommitFlow icon in the Activity Bar or press Ctrl+Shift+P and execute:

CommitFlow: Open Graph View

To open CommitFlow in the Bottom Panel (terminal dock), run:

CommitFlow: Open CommitFlow Hub in Bottom Panel

Click on any commit in the graph to inspect parent links, file changes, author metadata, and unified diffs.

Configuration Reference

CommitFlow can be configured through the VS Code Settings editor (Ctrl+,) or directly within your .vscode/settings.json file.

Setting Key	Type	Default	Description
`commitflow.layout.placement`	`string`	`"auto"`	Layout display mode. Options: `"auto"`, `"bottom"`, `"left"`, `"right"`.
`commitflow.graph.rowHeight`	`number`	`28`	Row height in pixels for the commit graph canvas.
`commitflow.graph.defaultTheme`	`string`	`"auto"`	Graph color palette. Options: `"auto"`, `"cyberpunk"`, `"dracula"`, `"github-dark"`, `"neon-pink"`, `"neon-green"`, `"neon-blue"`, `"clean-light"`.
`commitflow.blame.enabled`	`boolean`	`true`	Enables inline blame annotations on the active editor line.
`commitflow.blame.showAuthor`	`boolean`	`true`	Displays author name in the inline blame annotation.
`commitflow.blame.showDate`	`boolean`	`true`	Displays relative or formatted date in inline blame.
`commitflow.blame.dateFormat`	`string`	`"relative"`	Date formatting style: `"relative"`, `"iso"`, or `"locale"`.
`commitflow.sync.autoFetch`	`boolean`	`true`	Enables non-blocking background fetching for active remotes.
`commitflow.sync.fetchIntervalMinutes`	`number`	`5`	Interval in minutes between background fetch cycles.
`commitflow.issues.defaultFilter`	`string`	`"assignedToMe"`	Default filter in the Issue Tracker: `"assignedToMe"`, `"allOpen"`, `"closed"`.
`commitflow.issues.branchNamingPattern`	`string`	`"feat/{id}-{slug}"`	Template used when generating branch names from issues.
`commitflow.remotes.sshConfigPath`	`string`	`"~/.ssh/config"`	Filesystem path to the OpenSSH configuration file.
`commitflow.remotes.forgejoInstances`	`array`	`[]`	List of self-hosted Forgejo or Gitea base URLs or hostnames.
`commitflow.remotes.enableForkIntegration`	`boolean`	`true`	Enables detection and integration with the Fork desktop client.
`commitflow.mcp.port`	`number`	`0`	Port for optional TCP MCP connections (0 defaults to stdio).

Forgejo and Gitea Integration Guide

CommitFlow provides native, deep integration with self-hosted Forgejo and Gitea instances.

1. Generating a Personal Access Token

Log into your Forgejo/Gitea instance in a web browser.
Navigate to Settings -> Applications -> Manage Access Tokens.
Generate a new token with the following scopes:

issue (Read and Write)
repository (Read and Write)

Copy the generated token string.

2. Storing the Token in CommitFlow

In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
Run:

CommitFlow: Configure Remote Access Token

Enter the hostname of your Forgejo instance (for example, forgejo.internal.corp or git.domain.com:2222).
Paste your Personal Access Token.
The token is encrypted and securely stored in VS Code's SecretStorage under the key:

commitflow.token.forgejo.<hostname>

3. Configuring Custom Hostnames in Settings

If your Forgejo instance runs on a private domain, IP address, or custom port, add it to your VS Code settings.json:

{
 "commitflow.remotes.forgejoInstances": [
 "forgejo.internal.corp",
 "git.domain.com:2222",
 "http://192.168.1.50:3000"
 ]
}

CommitFlow will automatically associate repositories from these domains with the ForgejoProvider, fetch assigned issues, resolve user mentions, and display the Forgejo Private security badge.

SSH and OpenSSH Alias Resolution Guide

CommitFlow automatically resolves custom SSH configurations defined in your OpenSSH configuration file (~/.ssh/config).

Sample OpenSSH Configuration

# ~/.ssh/config

# Standard Forgejo server with custom SSH port
Host my-forgejo
 HostName git.company.internal
 Port 2222
 User git
 IdentityFile ~/.ssh/id_ed25519_forgejo
 IdentitiesOnly yes

# Air-gapped development server
Host lab-git
 HostName 10.0.4.15
 Port 22
 User git
 IdentityFile ~/.ssh/id_rsa_lab

Git Remote Configurations

When your repository's .git/config references an alias:

[remote "origin"]
 url = git@my-forgejo:organization/microservice.git
 fetch = +refs/heads/*:refs/remotes/origin/*

CommitFlow performs the following resolution steps:

Detects that my-forgejo matches a Host definition in ~/.ssh/config.
Resolves the real network endpoint to git.company.internal on port 2222.
Constructs web URLs targeting https://git.company.internal/organization/microservice.
Executes background commands using GIT_SSH_COMMAND in batch mode without blocking the editor.

Model Context Protocol (MCP) Setup

CommitFlow embeds a complete Model Context Protocol (MCP) server that provides AI agents with tools, real-time repository resources, and structured prompts.

Server Executable Configuration

To connect external tools such as Claude Desktop, add CommitFlow to your client configuration file.

Claude Desktop Configuration (`claude_desktop_config.json`)

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
 "mcpServers": {
 "commitflow": {
 "command": "node",
 "args": [
 "C:/Users/<Username>/.vscode/extensions/ignaciobrenas.commitflow-1.0.0/dist/mcp.js",
 "--repo",
 "C:/Path/To/Your/Repository"
 ]
 }
 }
}

MCP Tools Reference

Tool Name	Parameters	Description
`get_my_assigned_issues`	`state?: 'open' \| 'closed'`, `labels?: string[]`	Returns all issues assigned to the developer from Forgejo, GitHub, or GitLab.
`get_issue_context`	`issueNumber: number`	Retrieves issue conversation, comments, referencing commits, and pull requests.
`start_work_on_issue`	`issueNumber: number`, `useWorktree?: boolean`	Provisions a standardized branch or parallel Git worktree linked to the issue.
`analyze_staged_changes`	`includeIssueRef?: number`	Inspects staged diffs and formulates a Conventional Commit message referencing the issue.
`search_commit_history`	`query: string`, `author?: string`, `file?: string`	Searches commit graph and historical diffs for specific changes or keywords.
`get_pr_triage_status`	`filter?: 'blocked' \| 'ready' \| 'mine' \| 'all'`	Returns pull request triage metrics, CI/CD statuses, and reviewer blocks.
`predict_merge_conflicts`	`sourceBranch: string`, `targetBranch: string`	Simulates `git merge-tree` in memory to report exact conflicting files and lines.
`compare_revisions`	`baseHash: string`, `targetHash: string`	Compares two arbitrary commits, reporting file diffs, additions, deletions, and commits between.
`restore_lost_commit`	`commitHash: string`, `branchName: string`	Restores an orphaned reflog commit onto a newly created branch.
`analyze_repo_health`	None	Performs storage diagnostics, calculating loose objects, packfiles, disk size, and dangling commits.
`git_bisect_operation`	`action: 'start' \| 'step' \| 'reset' \| 'status'`, `badCommit?: string`, `goodCommit?: string`, `step?: 'good' \| 'bad' \| 'skip'`	Controls Git Bisect binary search sessions, advances probes, and detects regression culprits.
`preview_cherry_pick`	`commitHash: string`	Simulates an in-memory three-way merge to forecast cherry-pick conflicts before application.
`read_offline_repo_state`	None	Direct filesystem snapshot of the `.git` directory without executing external processes.
`commitflow_get_user_impact`	None	Analyzes author impact, total commits, and branch participation metrics.
`commitflow_get_line_blame`	`filePath: string`, `line: number`	Returns precise authorship, date, and commit SHA for a specific file line.
`commitflow_get_repo_summary`	None	Returns aggregate statistics (commits, branches, contributors, stash count).

MCP Dynamic Resources

Resource URI	MIME Type	Description
`commitflow://repo/status`	`application/json`	Current branch, remote configuration, active worktrees, and provider type.
`commitflow://repo/offline-status`	`application/json`	Raw `.git` filesystem snapshot (HEAD, packed-refs, reflog, active operations).
`commitflow://reflog/recent`	`application/json`	Recent chronological reflog entries parsed from disk or git client.
`commitflow://repo/health`	`application/json`	Repository health diagnostics (disk size, loose objects, packfiles, dangling commits).
`commitflow://bisect/status`	`application/json`	Current Git Bisect state, current probe revision, bad commit, and good boundaries.
`commitflow://issues/assigned`	`application/json`	Live feed of issues currently assigned to the active user.
`commitflow://branch/current/diff`	`text/x-diff`	Full diff between the current branch and its base tracking branch.
`commitflow://repo/user-context`	`text/markdown`	Formatted summary of author contributions and repository impact.
`commitflow://repo/graph-summary`	`text/markdown`	High-level summary of recent commit activity and active branches.

MCP Structured Prompts

triage-issue: Guides an agent to read an issue description, comments, and referencing code to formulate an implementation plan.
review-staged-changes: Directs an agent to inspect the current index diff and draft a compliant commit message.

Keyboard Shortcuts and Command Reference

All CommitFlow actions can be executed via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) or mapped to custom keybindings in keybindings.json.

Command Identifier	Title	Default Shortcut
`commitflow.openGraph`	CommitFlow: Open Graph View	`Ctrl+Alt+G` (`Cmd+Option+G`)
`commitflow.openInBottomPanel`	CommitFlow: Open CommitFlow Hub in Bottom Panel	--
`commitflow.openIssues`	CommitFlow: Open Issues Tracker Hub	--
`commitflow.openInFork`	CommitFlow: Open Repository in Fork Client	--
`commitflow.refresh`	CommitFlow: Refresh Repository Data	`Alt+R`
`commitflow.undoLastCommit`	CommitFlow: Undo Last Commit (Soft Reset)	--
`commitflow.copyChangelog`	CommitFlow: Export Markdown Changelog to Clipboard	--
`commitflow.toggleBlame`	CommitFlow: Toggle Inline Blame Annotations	`Ctrl+Alt+B` (`Cmd+Option+B`)
`commitflow.switchTheme`	CommitFlow: Select Color Theme	--
`commitflow.switchLayout`	CommitFlow: Select Layout Placement	--

Offline Architecture and Direct .git Inspection

CommitFlow is designed to operate seamlessly in air-gapped environments, on airplanes, during network outages, or inside constrained containers where external network access is unavailable.

Filesystem Traversal Structure

.git/
├── HEAD -> Resolved to determine symbolic branch or detached commit
├── config -> Parsed for remotes, branch upstreams, and user identity
├── packed-refs -> Parsed for packed branches, remote tracking refs, and tags
├── refs/
│ ├── heads/ -> Recursive filesystem traversal for local branch heads
│ ├── tags/ -> Recursive traversal for loose tag pointers
│ └── remotes/ -> Recursive traversal for remote tracking branches
├── logs/
│ ├── HEAD -> Parsed for chronological reflog history (SHAs, authors, dates)
│ └── refs/stash -> Parsed for complete stash stack history
├── MERGE_HEAD -> Detected to signal active merge conflict state
├── CHERRY_PICK_HEAD -> Detected to signal active cherry-pick operation
├── REVERT_HEAD -> Detected to signal active commit reversal
├── rebase-merge/ -> Parsed for rebase head-name, onto SHA, step, and total steps
├── worktrees/ -> Traversed to discover linked worktree paths and HEAD pointers
└── COMMIT_EDITMSG -> Read to retrieve the last or draft commit message

When offline:

All commit graph rendering, branch tracking, and blame operations run entirely against local disk data.
The Issue Tracker Hub serves cached issues and comments from the local LruCache and persistence store.
The Webview header displays a neutral Direct .git (Offline) badge indicating that local data is being utilized.

Developer Workflow Operations

1. Reverting Commits

Right-click any commit in the graph and select Revert Commit. CommitFlow validates the working directory state, executes a clean reversal commit, and updates the DAG view.

2. Cherry-Picking

Hover over any commit row or open the inspector drawer, then click Cherry-Pick. The commit is applied directly onto your currently checked-out branch.

3. Release Tagging

Click the tag icon on any commit row to open the tagging dialog. Choose between a lightweight tag or an annotated tag with custom release notes.

4. Soft Undoing Commits

Accidentally committed with the wrong message or forgotten files? Click Undo Last Commit in the toolbar. CommitFlow executes git reset --soft HEAD~1, returning your changes to the staged index without modifying your working tree files.

5. Markdown Changelog Export

Select a range of commits or open the toolbar menu and click Export Changelog. A formatted Markdown document grouped by Conventional Commit types (feat, fix, docs, refactor) is copied directly to your clipboard.

Troubleshooting and FAQ

1. SSH Prompts Hang During Background Fetching

Ensure your remote URL is properly configured. CommitFlow automatically passes -o BatchMode=yes to prevent background processes from blocking on terminal passphrase prompts. If your private key requires a passphrase, ensure your operating system's SSH agent is running and has your key loaded (ssh-add -l).

2. Forgejo Instance Returns HTTP 401 Unauthorized

Verify that your Personal Access Token was configured using CommitFlow: Configure Remote Access Token with the exact hostname matching your Git remote (including custom port numbers if applicable, for example git.myhost.com:2222).

3. Fork Client Does Not Open

Ensure that Fork is installed in the default location:

Windows: %LOCALAPPDATA%\Fork\Fork.exe
macOS: /Applications/Fork.app
Linux: fork executable available in $PATH

If Fork is installed in a non-standard path, verify that the fork://open URI handler is registered with your operating system.

Building from Source

Prerequisites

Node.js version 18.0.0 or higher.
npm version 9.0.0 or higher.
Git version 2.23.0 or higher.

Build Instructions

Clone the repository:

git clone https://github.com/Ignaciobrenas/CommitFlow.git
cd CommitFlow

Install project dependencies:

npm install

Run TypeScript strict compilation:

npm run compile

Run the automated test suite (42 test suites covering all core subsystems):

npm test

Build production bundles:

npm run build

Package the extension into a .vsix file:

npx vsce package

Security, Privacy, and Telemetry

Zero External Telemetry: CommitFlow does not collect, record, or transmit usage metrics, telemetry, or user analytics to any external third-party servers.
Local Execution: All Git operations, diff computations, and filesystem inspections execute entirely on the local machine.
Secure Credential Storage: Authentication tokens for GitHub, GitLab, and Forgejo/Gitea are stored exclusively within Visual Studio Code's secure SecretStorage system, backed by operating system credential managers (Windows Credential Manager, macOS Keychain, or Linux Secret Service).

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude/skills		.claude/skills
.github		.github
bin		bin
docs		docs
resources		resources
scripts		scripts
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.vscodeignore		.vscodeignore
CHANGELOG.md		CHANGELOG.md
DESIGN.md		DESIGN.md
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
README.md		README.md
esbuild.js		esbuild.js
package-lock.json		package-lock.json
package.json		package.json
package.nls.es.json		package.nls.es.json
package.nls.json		package.nls.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

CommitFlow

Direct Filesystem Engine

Topological Spline DAG

Unified Remote Provider Hub

Built-in MCP Server

⏳ Reflog Time Machine & Bisect

Cryptographic Security

Visual Tour & Interface Showcase

Table of Contents

Architectural Overview

Core Features

Topological Commit Graph

Direct Filesystem Offline Engine

Unified Remote Providers: Forgejo, Gitea, GitHub, GitLab

Universal SSH and OpenSSH Parser

Fork Desktop Client Interoperability

Issue Tracker Hub and Issue-to-Code Workflow

Pull Request and Merge Request Triage

Git Worktree Management and Multi-WIP Tracking

Visual File Evolution and Line Delta Tracking

Cloud Patches (Zero-Push Collaboration)

Inline Blame and Author Contributions

GPG and OpenSSH Cryptographic Signature Verification

Visual Git Reflog Time Machine and Lost-Commit Recovery

Multi-Commit Diff Comparison Engine

Repository Health and Garbage Collection Diagnostics

Visual Git Bisect Assistant and Regression Hunter

Pre-Flight Cherry-Pick Conflict Forecaster

Adaptive Universal Responsive Layout Engine

Connect with your AI Studio & Secure API Key Management

Interactive Git Rebase Studio

Virtual Scrolling DAG Engine

Model Context Protocol (MCP) Server

Installation and Prerequisites

Prerequisites

Installation via Marketplace

Manual Installation from VSIX Package

Getting Started

Configuration Reference

Forgejo and Gitea Integration Guide

1. Generating a Personal Access Token

2. Storing the Token in CommitFlow

3. Configuring Custom Hostnames in Settings

SSH and OpenSSH Alias Resolution Guide

Sample OpenSSH Configuration

Git Remote Configurations

Model Context Protocol (MCP) Setup

Server Executable Configuration

Claude Desktop Configuration (claude_desktop_config.json)

MCP Tools Reference

MCP Dynamic Resources

MCP Structured Prompts

Keyboard Shortcuts and Command Reference

Offline Architecture and Direct .git Inspection

Filesystem Traversal Structure

Developer Workflow Operations

1. Reverting Commits

2. Cherry-Picking

3. Release Tagging

4. Soft Undoing Commits

5. Markdown Changelog Export

Troubleshooting and FAQ

1. SSH Prompts Hang During Background Fetching

2. Forgejo Instance Returns HTTP 401 Unauthorized

3. Fork Client Does Not Open

Building from Source

Prerequisites

Build Instructions

Security, Privacy, and Telemetry

License

About

Topics

Resources

Stars

Watchers

Forks

Claude Desktop Configuration (`claude_desktop_config.json`)