GitLens for VS Code: Commit Graph, Blame, Worktrees and Agent Tracking

What GitLens solves, and who it is written for

GitLens targets a specific kind of friction: answering questions about a repository without leaving the editor. The README frames the problem as repositories that move faster than they used to, with coding agents opening branches, worktrees accumulating and pull requests stacking while a developer is still reading a diff. The extension's answer is to pull history, working changes, branches, worktrees and live agent activity into a single interactive view.

The audience is VS Code users who already know Git and want faster access to it. The package metadata lists the extension under the Other and SCM Providers categories, and the activation events include onStartupFinished, onFileSystem:gitlens and several webview panel events. That tells you GitLens is not a small annotation add-on; it activates broadly and carries its own views and webview surfaces. The README also states the extension has been installed more than 51 million times, which is a distribution fact rather than a quality claim, but it does explain why documentation and issue traffic are substantial.

There is a second audience the README addresses explicitly: teams running coding agents. Claude Code sessions appear in the Commit Graph with live state, and an experimental Agent Kanban groups sessions by what needs attention first. If you only use Git from the terminal and never open the graph, most of the extension is dead weight.

How the Commit Graph and blame annotations actually work

The Commit Graph is the centre of the extension. According to the README, each row carries live state: ahead and behind counts, unpushed and unpulled commits, change size, and collapsible lanes. Uncommitted work appears as a row per worktree, and from that row you can stage, commit, stash, or send the work to Compose Commits. Row-level actions include branch, merge, rebase, cherry-pick, revert, stash, push, pull and opening a pull request. Details for commits, branches, stashes, pull requests and comparisons open as stacked sheets, with Esc backing out one level at a time.

The side bar mirrors the repository structure: Overview, Agents, Pull Requests, Worktrees, Branches, Remotes, Stashes and Tags. Clicking an entry scopes the graph to it. Search supports Git-style qualifiers including message:, author:, file: and change:, which means the search box is a query language rather than a substring filter. Navigation shortcuts jump to HEAD, upstream or merge target, and the forward slash finds any branch.

Blame is the other long-standing surface. The package.json contributes a configuration section with the id current-line-blame, so current-line blame is a configurable feature rather than a fixed behaviour. The README's Visual History view sits alongside it: a timeline of how a file or repository evolved, showing when changes landed, how large they were and who made them. The repository also ships a .git-blame-ignore-revs file at the root, which is the standard mechanism for excluding formatting-only commits from blame output.

Installing GitLens in VS Code and opening the Commit Graph

The README gives a four-step getting-started path. Installation is through the editor's Extensions side bar, not a package manager. Search for GitLens in the Extensions view and install it from the marketplace listing published by eamodio.

# In VS Code: open the Extensions side bar (Ctrl+Shift+X / Cmd+Shift+X)
# Search for: GitLens
# Publisher: eamodio

After installation the README asks you to sign in with a free GitKraken account. That account is what opens the Commit Graph on public repositories and starts the Pro trial if you want the graph everywhere. The README states the trial runs 14 days and requires no credit card. Whether you sign in immediately or later, the extension installs and activates either way.

# Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
GitLens: Show Commit Graph

The README also describes clicking the GitLens icon in the activity bar as the primary route to the graph. Once it opens you should see history, working changes and in-flight work in one view. The next step the README lists is connecting your Git host and issue tracker for pull requests, issues and autolinks, then your coding agents for session tracking and the GitKraken MCP.

For contributors rather than users, the build requirements are visible in package.json: Node 24 or newer, pnpm 11.0.0 or newer, and a VS Code engine of ^1.101.0. The repository is a pnpm workspace with a packages/ directory, so the extension is assembled from multiple packages rather than a single source tree.

Worktrees, agent sessions and where the bookkeeping stops

The worktree features are the most concrete addition in recent releases. A worktree is a second checkout of the same repository, and GitLens creates one from a branch, a commit or a pull request, then opens it in the current window or a new one. Each worktree gets its own working-changes row in the Commit Graph, so you can see which are dirty without opening them. Work can move between worktrees: copy working changes across, or apply a stash into another worktree. You can open a terminal in one, reveal it in the file manager, or delete it.

Agent tracking is where the design gets more speculative. Claude Code sessions appear in the Commit Graph with a state of working, idle or needs input, and can be resumed from the row they are working on. Start Work with Agent takes an issue and creates the branch or worktree before handing it to an agent. Agent Kanban is marked Experimental in the README, and the README states that Experimental features are on by default but still changing. The Agent Activity Treemap is also Experimental and shows where agents are reading and editing in real time.

The limitation is tiering. The README states that Preview features require a free GitKraken account and may become Pro features later, and that several Pro features, the Commit Graph among them, are free on public repositories. Read that carefully: the Commit Graph is not unconditionally free. On private repositories the README's path to the graph runs through sign-in and, past the trial, Pro. Teams with private-only code should price that before standardising on GitLens as their only Git UI.

When GitLens is the wrong tool

GitLens is a VS Code extension. The package.json engine field pins vscode to ^1.101.0, and the README's installation instructions are written for the VS Code Extensions side bar. If your team works in Visual Studio, JetBrains IDEs or a terminal-only workflow, GitLens does not follow you there. Search traffic around GitLens for Visual Studio reflects a demand the repository does not satisfy.

The account requirement is the second boundary. The README ties the Commit Graph on private repositories and Preview features to a GitKraken account, and the extension contributes an MCP server definition provider and connects to coding agents. If your environment forbids outbound account sign-in or third-party service connections, the parts of GitLens that depend on them are unavailable, and what remains is the local annotation and history surface.

Performance is the third consideration, and the README does not address it. GitLens activates on startup, on terminal events and on several webview panels, and it renders a graph over full repository history. The README does not document resource usage, memory ceilings or behaviour on very large monorepos, so that is a question to answer in your own repository rather than from documentation. The extension declares virtualWorkspaces: true and untrustedWorkspaces supported as limited, which means some capability is reduced in restricted workspaces, but the README does not enumerate which features degrade.

GitLens against Git Graph and plain Git history

The nearest comparison is the Git Graph extension, which also draws a commit graph inside VS Code. The difference is scope rather than rendering. Git Graph is a graph viewer: you look at history and act on commits. GitLens wraps the graph in a larger surface that includes blame annotations, Visual History timelines, experimental treemaps, worktree creation and management, pull request and issue integration through your Git host, and coding-agent session state. If you want a graph and nothing else, Git Graph is the smaller dependency. If you want blame, worktrees and agent tracking next to the graph, GitLens is the one that ships them together.

The second alternative is VS Code's built-in Source Control view plus the command line. That combination is free, offline and account-free, and it covers staging, committing, branching and pushing. What it does not give you is a rendered graph, per-line blame in the editor, or any awareness of worktrees and agent sessions. The trade is capability against weight and sign-in: the built-in view asks nothing of you and shows less.

A third path worth naming is the GitKraken Git client, which is the same vendor's standalone application. GitLens is the in-editor version of that product line, and the README's homepage points at gitkraken.com/gitlens. If you want the graph outside the editor, the extension is not the answer.

Licence, upgrade cost and what the repository actually ships

The licence field in the repository metadata is NOASSERTION, which means the licence could not be automatically classified. The repository root contains both a LICENSE file and a LICENSE.plus file, alongside a ThirdPartyNotices.txt. The presence of a separate LICENSE.plus strongly suggests a split between the open-source Community tier and the commercial Pro tier, which matches the README's statement that GitLens Community is free and open-source forever while Pro features exist alongside it. Anyone evaluating GitLens for a company should read LICENSE and LICENSE.plus directly rather than relying on the extension marketplace label, and should route the question to their own legal review; the metadata alone does not answer it.

Upgrade cost is mostly a matter of cadence. The repository shows releases v19.2.0 on 2026-09-16, v19.1.0 on 2026-09-01 and v19.0.1 on 2026-08-13, and the last push to the default branch was on 2026-09-21. That is a fast release rhythm, which is good for fixes and less good if you pin versions. The README offers a Switch to Pre-Release Version option on the extension page, so there is a deliberate channel for early adopters separate from the stable release. The extension declares activation on startup and on terminal events, so each upgrade touches a component that runs continuously rather than on demand. Budget for reading the CHANGELOG.md at the repository root between versions.

Editorial conclusion

Adopt GitLens if you live in VS Code and want blame annotations, a Commit Graph, worktree bookkeeping and agent session state in one place, and you accept a GitKraken account for the Commit Graph on private repositories. Do not adopt it if you need a fully offline, account-free Git UI, or if you work in Visual Studio rather than VS Code, since GitLens is a VS Code extension and the repository documents no other host. Before rolling it out, check the LICENSE and LICENSE.plus files in the repository root, confirm your VS Code build is at least 1.101.0, and decide whether the Commit Graph on public repositories alone is enough or whether you need the Pro tier.

Frequently asked questions

Official sources

1. gitkraken/vscode-gitlens on GitHub
2. Issues
3. Project website
4. README
5. Releases