DEV Community: Mir Mursalin Ankur

Build Your Own IDE Extension: A Real-World Guide From Idea to Publish (VS Code and Others)

Mir Mursalin Ankur — Mon, 14 Sep 2026 15:29:12 +0000

The most useful software you'll ever write might be the kind only you needed.

Every developer has one. That small thing your editor almost does — the command you retype ten times a day, the info you keep switching to a browser to check, the tool you love that lives in a terminal while your actual work lives three windows away. You've tolerated it for months. Maybe years.

You can fix that yourself — in a weekend, without being an expert. An IDE extension is not a mystical artifact maintained by people smarter than you. It's a small program plus a form that tells the editor where to plug it in. If you can write a script, you can write an extension.

I recently went through this end to end. I maintain a CLI tool called branchdiff — it runs a local web UI for reviewing pull requests. The UI was fine, but using it meant a terminal, a command, a browser tab, a context switch. So I built a VS Code extension that starts the server, shows the numbers in the sidebar, and embeds the whole UI in an editor tab. Along the way I hit everything the tutorials don't warn you about: a status bar icon that silently refuses to render, links that open nothing with no error, a marketplace account that needs an Azure subscription before it needs an extension.

This guide is the general version of that journey — it works for whatever your use case is, and it doesn't stop at VS Code. There's a full field guide to the rest of the editor world (Zed, JetBrains, Neovim) near the end, because the most important decision you'll make is which editor to target first.

If you're not a developer, read the next section anyway — it explains what extensions actually are, in plain language, and honestly, that's the part most developers would benefit from too.

What an Extension Actually Is

Strip away the branding and every IDE extension system on earth answers the same three questions:

Where does it plug in? — a manifest, a small config file where you declare: I add a command, a keyboard shortcut, a sidebar panel, a setting.
When does it wake up? — editors don't run your code constantly. They load it when something you declared happens: the user runs your command, opens a certain file type, or the editor finishes starting up.
What can it touch? — an API the editor hands your code, and a sandbox deciding how far your code can reach.

For the non-developers: think browser extensions, but for the program people write code in. The editor is like a phone, extensions are apps, and the marketplace is the app store. Same shape, different device. And just like phone apps, most extensions are tiny — one command, one panel, one quality-of-life fix.

That diagram is the whole mental model for VS Code. Two files do almost everything:

package.json — the manifest. It's a form your extension fills out: "here's my command, here's its keyboard shortcut, here's a setting users can tweak."
src/extension.ts — your code. One function runs when the editor activates you (activate), one runs on shutdown (deactivate). Everything else is you calling editor APIs.

One detail worth knowing because it makes extensions safe to experiment with: your code runs in a separate process the editor babysits, called the extension host. If your extension crashes, the editor doesn't. You cannot brick your setup by writing a bad extension. Worst case, you disable it. This is why the barrier to trying is much lower than it looks.

The shapes extensions come in

One more thing before the code: extensions come in a handful of well-known shapes, and knowing them makes your own idea easier to place. Almost everything on a marketplace is one of these:

Shape	What it does	You've met it as
Command or tool	Adds a button that does a thing	The shape this post builds
Syntax highlighter	Teaches the editor to colorize a language it doesn't know yet	Grammar extensions for niche languages
Theme	Restyles the whole editor — colors, file icons	One Dark Pro and ten thousand cousins
Snippet pack	Three letters expand into thirty lines of boilerplate	`rafce` → a full React component
Formatter	Rewrites your code to one agreed style on save	Prettier, Black
Linter	Draws the squiggles and warnings while you type	ESLint
Language server	Real language intelligence — autocomplete, go-to-definition, hover docs	rust-analyzer, Pyright
Debugger	Breakpoints and stepping for a runtime, inside the editor	Debug adapters
Bridge	A doorway to a tool that lives outside the editor	Docker, Remote SSH, GitLens

The good news in that table: themes and snippet packs are just JSON. No code, no API, no extension host — a color palette or a pile of templates in a manifest. Plenty of people earn "published extension author" without writing a line of TypeScript, and that's a perfectly honest way in.

At the serious end, highlighters and language servers teach an editor an entire language. A highlighter is a grammar — VS Code uses TextMate grammars, while newer editors like Zed use tree-sitter, which understands the actual structure of your code instead of pattern-matching it. A language server speaks the Language Server Protocol: write it once, and every LSP-capable editor on earth can hire it, not just VS Code.

This post builds the first shape and the last one — the command and the bridge — because that's where "fix my own annoyance" ideas live. But if your itch is colors or boilerplate, congratulations: your weekend just got shorter.

Before You Write Code: Audit Your Idea

Most failed extensions die here, not in the code. Two minutes of honesty saves a weekend.

Your idea is probably good if it's one of these:

A repeated action — you do the same 3–4 steps daily (copy file path, transform it, paste it somewhere, open a tool). A command plus a keyboard shortcut turns that into one keypress.
Glanceable information — build status, server health, ticket numbers, whatever you'd otherwise open a browser tab to check. A status bar item or sidebar row makes it ambient.
A bridge — a tool you love (a CLI, a local server, an internal dashboard) that lives outside the editor. The extension doesn't replace the tool; it hands you a doorway to it.

Your idea is probably bad if:

Settings or keybindings already do it. Embarrassing numbers of "extensions" are re-implementations of built-in configuration. Search the editor's settings first.
An existing extension already does it. Search the marketplace twice — once for what it's called, once for what it does.
It's a whole app. If your extension needs its own navigation, accounts, and a database, ask whether it should be a web app with an extension as a thin doorway instead.

The thin-client principle

When I planned the branchdiff extension, the obvious-looking path was to rebuild the review UI natively inside VS Code — native diffs, native comment threads, the works. The APIs exist. I said no, and it's the decision I'd repeat every time.

The extension doesn't re-implement anything. It embeds the existing web UI inside an editor tab, and every sidebar row deep-links to the exact section of it. One UI, two viewports. If the editor can host a web view, the same app appears inside it; everywhere else, one click opens the right page in a browser.

Why this matters for you: if your tool has any real interface, an extension should be a bridge to it, not a second copy of it. Otherwise you're maintaining two frontends forever — and if you ever target a second editor, four. The extension's actual jobs are the cheap ones: start the thing, show the numbers, open the right place. That's a weekend. A native re-implementation is a quarter.

The VS Code Path

VS Code first, for three reasons: the API is genuinely pleasant, TypeScript does half the work for you, and one VS Code extension covers way more editors than VS Code. Cursor, Windsurf, VSCodium, and friends are all built on VS Code's open-source core, and they install extensions from the same second store. Build once, reach nearly everyone. (Details in the shipping section.)

The fifteen-minute skeleton

You need Node.js installed. Then, in an empty folder:

npx --package yo --package generator-code -- yo code

That's the official scaffolder. It asks a handful of questions — name, identifier, TypeScript (say yes) — and hands you a working extension with a sample command.

To see it alive: open the folder in VS Code and press F5. A second VS Code window appears — the Extension Development Host — with your extension loaded in it. Press Ctrl+Shift+P (that menu is the Command Palette), type your command's name, run it. A notification pops up. Congratulations, that's the whole loop.

You'll live in this loop: edit, F5, test in the host window, Developer: Reload Window to pick up changes. It's fast and it's the same for every extension you'll ever write. No emulator downloads, no signing certs, no device registration. Compare that to any other platform you've developed for.

The manifest: where half the work happens

Here's the part that surprises people: a lot of "extension development" is filling in package.json. You don't code a command palette entry or a keyboard shortcut — you declare them, and the editor builds them for you:

{
  "name": "deploy-buddy",
  "publisher": "yourname",
  "engines": { "vscode": "^1.85.0" },
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      { "command": "deploybuddy.deploy", "title": "Deploy current branch" }
    ],
    "keybindings": [
      {
        "command": "deploybuddy.deploy",
        "key": "ctrl+alt+d",
        "when": "editorTextFocus"
      }
    ],
    "configuration": {
      "title": "Deploy Buddy",
      "properties": {
        "deploybuddy.environmentUrl": {
          "type": "string",
          "default": "https://staging.example.com",
          "description": "Where deployments go"
        }
      }
    }
  }
}

That JSON gives you: a Command Palette entry, a keyboard shortcut that only fires when you're focused in the editor, and a settings screen — the settings UI is generated from that configuration block, free.

Two manifest notes that save real pain:

engines.vscode must match the editor you test in. A mismatch is the number-one reason a fresh extension's command simply doesn't appear. If your command is missing, check this before anything else.
Modern VS Code infers most activation events from what you contribute — declare a command and the editor knows to load you when it runs. You rarely hand-write activationEvents anymore; an empty array is normal for command-driven extensions.

Your first command

The code side, complete:

import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand(
    "deploybuddy.deploy",
    async () => {
      const editor = vscode.window.activeTextEditor;
      if (!editor) {
        vscode.window.showErrorMessage("Open a file first");
        return;
      }
      const branch = await vscode.commands.executeCommand("git.currentBranch");
      vscode.window.showInformationMessage(`Deploying ${branch}…`);
      // your actual work here
    },
  );
  context.subscriptions.push(disposable);
}

export function deactivate() {}

Read it and notice what it isn't: there's no framework, no build orchestration you must understand, no lifecycle diagram to memorize. The editor calls activate, you register things, done. subscriptions.push is just "clean this up when I'm unloaded" — copy the pattern and move on.

The five surfaces you'll actually use

The VS Code API is huge, but almost every useful extension is built from five surfaces. Know these and you can read anyone's extension:

Surface	What it is	Use it for
Command Palette	`Ctrl+Shift+P` entries	Anything the user does occasionally
Quick Pick	`showQuickPick()` — the fuzzy-search dropdown	Picking one thing from a list: environments, branches, tickets
Status bar	`createStatusBarItem()` — text in the bottom bar	One number or word, always visible: build status, server health
Sidebar panel	`createTreeView()` — a tree in the activity bar	Structured info: multiple items, live counts, expandable rows
Webview	`createWebviewPanel()` — a real browser tab inside the editor	Anything visual: dashboards, forms, embedding an existing web UI

A status bar item is three lines:

const bar = vscode.window.createStatusBarItem(
  vscode.StatusBarAlignment.Left,
  100,
);
bar.text = "$(rocket) staging";
bar.tooltip = "Current deploy target — click to switch";
bar.command = "deploybuddy.deploy";
bar.show();

That $(rocket) is a codicon — a built-in icon from VS Code's icon font. Remember that phrase; it stars in the gotchas section.

If your extension wraps an existing local web tool, the webview is the finish line: point an iframe in a webview panel at http://localhost:PORT and your entire UI now lives in an editor tab. Chromium treats localhost as trustworthy, so the http iframe doesn't trip security rules.

One refinement worth stealing: reuse a single "main" panel and repoint its src on navigation instead of spawning a tab per click — it behaves like a browser tab, not a pile of them. Embed, don't rebuild — that's the thin-client principle in code.

Lessons that cost me an afternoon each

These are the things the docs mention in one buried line and reality teaches loudly. Consider this section the fee I already paid on your behalf.

Status bar icons are codicons only. StatusBarItem cannot render a custom SVG — the API simply has no iconPath on it. You use the built-in codicon font ($(rocket), $(git-compare), $(sync)) or you use text. Custom icons go in the sidebar and editor tabs, which do accept SVGs — but the rules differ per surface: the activity bar alpha-masks your SVG and repaints it in the theme color (draw with currentColor and punched holes), while editor-tab icons want a {light, dark} pair because the tab background flips with the theme. I verified this the hard way, against the latest type definitions, after wondering why nothing rendered.

Manifest changes sometimes need a full restart, not a reload. Some contributes entries — icons, view containers, menus — are only read when the extension host starts. Developer: Reload Window picks up your code; if a new icon or view stubbornly refuses to appear, fully quit the host window and relaunch. This one had me convinced my icon path was wrong for far too long.

Webviews are sandboxed, and they fail silently. A webview is a locked-down browser. window.open() and target="_blank" links do nothing — no error, no console spam, just silence. If your embedded UI needs to open things, your webview code must postMessage the URL to the extension, which decides: same-server link → open a new webview tab; external link → vscode.env.openExternal(). Also set retainContextWhenHidden: true when you create the panel, or the webview's state resets every time the user switches tabs. There's a memory cost; for a dashboard it's worth it.

Two more traps live inside that same iframe. Keystrokes land in it, where the editor's keybindings can't see them — your embedded app has to forward the workbench escapes (Ctrl+Shift+P, Ctrl+P, the sidebar toggles) to the extension over postMessage, and the extension replays a short whitelist of commands, nothing more.

And the editor's theme only reaches the iframe after a message round trip, so a fresh load briefly falls back to the OS theme — pass it in the iframe's URL (?theme=dark) and apply it with an inline script before your stylesheets load, or dark-theme editors on light-OS machines flash the wrong theme on first paint.

Windows spawns need a shell. If your extension launches a local tool and it works on your Mac but dies for Windows users: npm-installed CLIs are .cmd shim files on Windows, and those can't be spawned directly. Pass shell: true in your spawn options. This is the classic "works on my machine" bug of extension development, and Windows users will find it for you.

Adopt, don't duplicate, long-running processes. If your extension starts a server, check whether one is already running for this workspace first, and attach to it. Otherwise every window reload spawns another copy, ports fight, and users end up with zombie processes. My extension reads a small registry file the CLI maintains; a healthy match means adopt, otherwise spawn. Ten lines of code, entire class of bugs gone.

One source of truth for repeated lists. I had the same menu in two places — a sidebar panel and a quick pick — hand-maintained separately. They drifted: the quick pick was missing rows and had a copy-pasted wrong icon on one entry. The fix was boring and permanent: both surfaces now render from one array in one file. Any list that appears twice in your UI will drift; make it appear once in code.

Testing like it matters

The F5 loop is for your eyes. For real coverage, VS Code ships a test runner that downloads an actual VS Code binary and runs your tests inside the real extension host — not a mock, the actual editor, headless:

npm install --save-dev @vscode/test-electron
# package.json: "test": "node out/test/runTest.js" (the scaffold has this)

Because it's "a real editor, headless," it also runs in CI on all three operating systems. If you ship to strangers, do this: a test that asserts your commands are registered and your endpoints answer catches the entire class of "the extension loaded but nothing works" bug reports.

One quirk to know before it bites: the test host rejects a module that merely runs itself — it must export a run() function. Then keep a small manual checklist for what automation can't see — icons rendering, panels looking right, keyboard shortcuts firing. Two lists, both short.

Shipping It

Start with just a file: the `.vsix`

Everything in VS Code extension land packages into one file format: .vsix. It's a zip with your code and manifest inside, installable directly.

npm install -g @vscode/vsce
vsce package

Now there's a your-extension-1.0.0.vsix file. Anyone — including future you — installs it via the Extensions panel's ⋯ menu → Install from VSIX…, or:

code --install-extension your-extension-1.0.0.vsix

Do not skip past this. A .vsix file is a completely legitimate end state. Your team's shared tooling, an internal extension that will never be public, a personal scratch extension for your own workflow — package it, drop it in a shared drive or a GitHub release, done. Two things to know at this stage: a .vscodeignore file keeps junk out of the package (only ship your dist/ bundle, manifest, README, license), and manually installed .vsix files never auto-update — installing the next version's file over it just works.

The Marketplace — and the Azure detour nobody warns you about

The main app store is the Visual Studio Marketplace. Publishing is one command (vsce publish) behind two accounts, and the accounts are the hard part:

Create a publisher on the Marketplace — an ID that permanently identifies you and your extensions.
Create a Personal Access Token on Azure DevOps. Yes, Azure. The Marketplace's auth lives there, not on the Marketplace site. The token must be scoped to All accessible organizations with the Marketplace → Manage scope — pick anything else and you get a bare 403 that doesn't tell you why.
And the genuinely absurd part: creating an Azure DevOps organization can require linking an Azure subscription, and even a free-tier Azure account wants a card for identity verification. To publish a free extension. Plan for this detour; it's the single most common place extension publishing stalls out.

One more thing to calendar: Microsoft is retiring global PATs on December 1, 2026, and the going-forward path is Entra ID-based auth (workload identity federation in CI, vsce publish --azure-credential). If you're setting up publishing fresh, set it up the new way from day one and skip the token-renewal treadmill entirely.

Marketplace rules that bite people, from the official docs and from experience:

Versions must strictly increase. Published a broken version? You can't overwrite it — you fix it by shipping the next version.
The listing is a snapshot. Your README, icon, and description on the store update only when you publish. There is no "refresh listing" button.
No SVGs in listings — icon, badges, and README images must be PNG/other raster with https URLs.
Removal is forever. Unpublishing removes the extension from every user, and extension names stay reserved after removal. Prefer leaving an old version up.

Open VSX: one extra step, five more editors

Microsoft's Marketplace terms only allow Microsoft builds of VS Code to use it. Cursor, Windsurf, VSCodium, Gitpod, Theia — all built on VS Code's open-source core, all banned from the main store. They share a second store instead: Open VSX.

And it takes the same .vsix you already built. One package, two stores, every major editor covered:

Open VSX setup is its own small saga, so you don't hit it blind: you sign in with GitHub, then discover that's not enough — you need an Eclipse Foundation account (separate registration), sign the publisher agreement, and link your GitHub account inside your Eclipse profile. Skip that last link and login fails with a bare redirect that looks like an OAuth bug. The actual reason lives in a background request (eclipse-missing-github-id) that the page never shows you.

Once in: create a namespace matching your publisher ID exactly, generate a token, npx ovsx publish.

That's the entire distribution strategy for a solo developer: build one .vsix, publish it twice, and every editor from stock VS Code to Cursor can install your work.

Beyond VS Code: A Field Guide

VS Code has the gentlest on-ramp, but it's not the only editor people love. Here's the honest state of each — what you can build, what you can't, and what it costs.

Zed: small, sharp, sandboxed

Zed takes the opposite bet from VS Code on extension power. Extensions are written in Rust, compiled to WebAssembly, and run in a sandbox. The manifest is an extension.toml file; you test locally by installing your folder as a "dev extension," and publishing means opening a pull request against Zed's central extensions repository — with a license file at the root of your repo (open source is required) and CI checking your submission.

What Zed extensions can be: language support (tree-sitter grammars, language servers you can download on demand), themes and icon themes, snippets, debug adapters, and MCP context servers — the integration path for connecting Zed's assistant to your own tools.

What they still can't be: anything with its own UI. No sidebars, no panels, no status bar items of your own, and no general "draw a window" API. Extensions can reach outside the sandbox a little, through narrowly-scoped capability grants — running specific commands (process:exec), downloading files from specific hosts, installing named npm packages — but with nowhere to render a result, that power changes little. The Visual Extension API is an open proposal; until it lands, Zed extensions are ingredients, not apps.

So what do you do if you love Zed and want your tool closer? Two honest answers:

tasks.json. Zed's task runner can execute your CLI with a keystroke, and its terminal renders printed http://localhost:… URLs as clickable links. A config file, not code — and suddenly your tool is one keypress away, opening in the browser at exactly the right page.
An MCP context server. If the integration should be smart — tools and prompts the assistant can call — that's the sanctioned path, and it's genuinely useful even without any custom UI.

This is exactly the route I mapped for branchdiff-in-Zed: no extension at all, just task definitions and clickable URLs. Sometimes the right extension is a config file.

Cursor, Windsurf, VSCodium: already done

Nothing new to build. They're VS Code-family editors pulling from Open VSX — your published extension reaches them the moment it's on that second store. One .vsix installs into any of them directly too (cursor --install-extension … works exactly like code --install-extension …). If your extension talks to local servers or CLIs, do test in each — forks have their own quirks — but it's QA work, not development work.

JetBrains: a different planet, respectfully

IntelliJ, PyCharm, WebStorm and the family run on the JVM, and so do their plugins — Kotlin or Java, built with Gradle via the IntelliJ Platform Gradle Plugin (2.x is the current line; the old DevKit workflow is deprecated), usually starting from JetBrains' official plugin template. Publishing goes to the JetBrains Marketplace.

The trade is the inverse of Zed's: you get full power — plugins there are first-class citizens that can rebuild any part of the IDE's UI — in exchange for a much heavier platform. You're learning a desktop-application framework, with the debugger, the IDE setup, and the build times to match. If your day job lives in a JetBrains IDE and your idea needs real UI inside the editor, it's worth the climb. For everyone else, it's the last stop on the tour, not the first.

Neovim: no ceremony, by design

Neovim's answer to "what's the extension system?" is "your config is the extension system." Plugins are Lua modules; there's no manifest, no store, no review — plugins are git repositories, installed by a plugin manager like lazy.nvim, loaded by users who opt in. Total freedom, zero hand-holding: you can do anything, including break everything, and packaging/distribution is entirely your problem. If you live in Neovim, a plugin for your own workflow can be an evening; just know you're building for the smallest (but most devoted) audience of this list.

The comparison, at a glance

	VS Code family	Zed	JetBrains	Neovim
Language	TypeScript/JavaScript	Rust → WASM	Kotlin/Java	Lua
Custom UI	Webviews, panels, status bar	None yet (open RFC)	Full IDE-grade UI	Full TUI
Distribution	Marketplace + Open VSX	PR to central repo	JetBrains Marketplace	Git repos
Effort to first result	An evening	An evening (non-UI)	A weekend or two	An evening
Reach	Every VS Code-based editor	Zed users	All JetBrains IDEs	Neovim users

So Which One First?

The decision is less about favorite editor and more about reach-per-effort:

Default answer: VS Code, then Open VSX. One TypeScript codebase, two publish commands, and you've covered stock VS Code plus Cursor, Windsurf, and VSCodium — the largest developer audience on earth for extension work. Nothing else comes close.
If your team lives in JetBrains IDEs and the idea needs to live inside the editor, go Kotlin and budget the learning curve — it's the only sanctioned way in.
If your tool's real home is a web UI, build the thinnest VS Code bridge (embed + deep links), and for Zed don't build at all — tasks plus clickable URLs cover it today.
If it's just for you, the calculus collapses: build for whatever you actually use, ship it as a .vsix or a config file, skip the stores entirely. Software that serves one user well is not a failure.

And whatever you pick — start absurdly small. One command that does one thing you actually do daily. Ship that, use it for a week, and let the extension tell you what it wants to become next. The branchdiff extension started as "start the server without typing a command." The sidebar counts, the embedded tab, the quick picks — those were all pull, added because daily use kept asking for them. I've never seen an extension ruined by starting too small. The big-bang ones, I've seen plenty.

Wrapping Up

The gap between "my editor should do that" and "my editor does that" is shorter than it's ever looked. A manifest and one function gets you running; five surfaces cover almost every idea; a .vsix file is a real distribution channel even if you never touch a store; and two stores get you nearly every editor people use in 2026.

The concrete path from here:

Today: run npx --package yo --package generator-code -- yo code, press F5, change the sample command's message to something that makes you smile. You're now an extension developer.
This week: pick the one repetitive thing you actually do daily, and make a command for it. Add a keybinding in the manifest.
When it's useful: vsce package and install the .vsix properly — you'll feel the difference the first time it's just there after a restart.
If the world needs it: publish — Marketplace for VS Code, Open VSX for everything VS Code-shaped, and remember the Azure detour is a rite of passage, not a sign you're doing it wrong.

The most useful software you'll ever write might be the kind only you needed. There's exactly one way to find out.

Sources and Further Reading

Your First Visual Studio Extension — official scaffolding-to-F5 walkthrough
Extension Capabilities Overview — the official map of extension kinds: themes, formatters, linters, debuggers, snippets, and the rest
Publishing Extensions — vsce, publishers, tokens, and the PAT-to-Entra transition
Open VSX — the marketplace for VS Code-family editors
Zed Extension Capabilities and the Zed Publishing Guide — what sandboxed extensions may do and how submissions work
Visual Extension API RFC (Zed discussion #53403) — the still-open proposal for custom UI in Zed
IntelliJ Platform Plugin SDK and the IntelliJ Platform Gradle Plugin 2.x — the JetBrains path
branchdiff's extension R&D notes — the full engineering log behind the case study in this post

End:

That's all!

I hope you've found the article useful. You should try building your own extension if you haven't already — start with the one command you actually need. Feel free to share your thoughts and what you built in the comments below.

Check more on

Your Desk in Your Pocket — Free Remote Control for Mac & Ubuntu, Same Room or Anywhere on Earth

Mir Mursalin Ankur — Thu, 27 Aug 2026 01:56:31 +0000

The gap between having a thought worth acting on and acting on it shouldn't cost a walk to the desk — or a flight home.

A build's running upstairs. You're on the couch, and something needs doing — reply to that message, nudge the agent, check whether the tests passed. Later that week you're in a coffee shop, same thought, except now the machine is kilometers away.

This post builds a phone-to-desktop remote control in three parts:

Part 1 — Same network. macOS Screen Sharing, Ubuntu x11vnc, one phone app. Set this up first.
Part 2 — Over the internet. The same rig from a coffee shop or hotel, via a mesh VPN. Re-addressing, not a rebuild.
Part 3 — Deep dive. The protocol, the 8-character password cap, why VNC triggers hotkeys when SSH can't.

Everything is free, and once wired, needs nothing further from you. Set it up on a Saturday, and the couch becomes a valid place to get something done — and so does another city.

The phone keyboard's own voice typing works straight through this rig (Part 1), so dictation comes along for free.

The one table worth internalizing — the same phone app drives both machines, one saved entry per box:

The job	Ubuntu machine	macOS machine
Share + control the screen	x11vnc	built-in Screen Sharing
Phone VNC client	RealVNC Viewer (Android/iOS)	RealVNC Viewer — same app, second entry
Address (Part 1)	`<ubuntu-lan-ip>:5900`	`<mac-lan-ip>:5900`
Address (Part 2)	tailnet IP, permanent	tailnet IP, permanent
Password	the `x11vnc -storepasswd` one	the 8-character VNC password
OS-specific extras	none needed	none needed

Security and license notes for every tool close the post.

Part 1 — Same network: the phone drives the desktop

Why VNC, and not just SSH

If you've remoted into a machine before, it was probably SSH — and SSH can't do this job. An SSH session drops you into a new text shell: it can't show you the desktop you left running, can't click anything, can't type into the apps already open, and can't fire global hotkeys. It's a parallel door into the basement.

VNC is a mirror plus a hand: the phone sees the actual desktop — your apps, your windows, exactly as you left them — and every tap and keystroke is injected as a real input event, indistinguishable to every app and every hotkey listener from sitting at the keyboard. That property is what makes the whole rig work: switch apps, run shortcuts, check a build, drag a slider — all with the same mechanism you'd use in person.

Both halves are standard: macOS and Ubuntu can each serve VNC with built-in or one-command-free tooling, and any standards-compliant client can connect. That's why one phone app is enough for both machines.

The macOS machine: Screen Sharing, already installed

The Mac ships with the VNC server — this is mostly a matter of turning it on. This route was shaken down live on a Sequoia Mac with an Android phone in hand: Screen Sharing answering on port 5900, a phone client driving the screen, everything below marked "tested live" came off that machine.

The macOS control path — the server is already installed; one toggle and a VNC password turn it on.

System Settings → General → Sharing → Screen Sharing — flip it on. Keep it plain Screen Sharing: if Remote Management is the enabled one instead, legacy-VNC clients get served the login window even while you're logged in, and typing into that over VNC drops focus (tested live — Remote Management off, Screen Sharing on, and the phone landed straight on the desktop; logging in over VNC works too, for the after-reboot case).
For a third-party client (RealVNC Viewer — anything not Apple's own Screen Sharing app), click the ⓘ next to Screen Sharing and enable "VNC viewers may control screen with password", then set that password. Without it, macOS expects Apple's own authentication handshake and most phone clients fail to connect at all.
Connect from the phone to <mac-lan-ip>:5900, password = the VNC password from step 2. Same separate-from-WiFi-password logic as below on Ubuntu — it controls who can drive the Mac, not who can join the network.

Or skip the GUI for step 1: sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.screensharing.plist — but step 2 has no equally clean CLI path, so most of this toggle lives in System Settings either way. There's also a CLI for the whole thing (.../ARDAgent.app/Contents/Resources/kickstart -activate -configure -access -on -clientopts -setvnclegacy -vnclegacy yes -setvncpw <pw> -restart -agent -privs -all), but on Sequoia it sets privileges and the password while refusing to actually open the service — it prints "Screen Sharing or Remote Management must be enabled from System Settings or via MDM" and the port stays closed until you flip the GUI toggle once. Count on ending in System Settings regardless.

Three auth behaviors worth knowing before a phone client rejects a correct-looking password:

The VNC password is effectively 8 characters. System Settings happily accepts a longer one, but legacy VNC auth is a DES challenge-response capped at 8 — if the client keeps rejecting the password you set, the first 8 characters are the password. (Part 3 opens up the mechanism, for the curious.)
macOS serves two auth types side by side: Mac account auth (a username + your Mac login password, Apple's ARD-style handshake) and the legacy VNC password. A client looping on "enter VNC credentials" is often answering the wrong one — the server offers both, and which one you get depends on the client's negotiation. Note Screen Sharing and Remote Management each have their own VNC-password setting; only the one for the service you actually enabled is consulted.
RealVNC Viewer connects with the plain VNC password, username blank — tested live. That's the configuration this post standardizes on, and it's why the same app works against the Ubuntu box too.

What you don't need, relative to Ubuntu below: no display-number hunting, no Xauthority chase, no autostart file, no reconnect/key-repeat flag tuning — Apple's server handles those correctly by default. And one genuine upgrade: Screen Sharing is a system daemon that serves the login window too, so after a reboot you can VNC in and log in remotely — the Ubuntu route can't do that (x11vnc only starts after a graphical login).

The Ubuntu machine: x11vnc

x11vnc shares and drives the existing desktop session — the one you're actually logged into, with your apps already open — rather than spawning a fresh virtual one. It's in the standard repos:

The Ubuntu control path — x11vnc turns the desktop session you're already logged into into a VNC server.

sudo apt install -y x11vnc

Run it

x11vnc -display :<real-display-number> -auth guess -usepw -shared -repeat -forever

Find <real-display-number> with who (look for <user> :N <date>) from a terminal that's actually part of the graphical session.

First run is interactive: no password file exists yet, so -usepw prompts you to set one. Always do this — never run x11vnc without auth.
-forever keeps listening after the first client disconnects.
-shared matters. Without it, x11vnc allows exactly one client at a time — a stale half-open connection from a WiFi blip or app switch makes every reconnect fail with refusing new client ... Not shared & existing client until you restart the server. With it, reconnects just work.
-repeat matters too. x11vnc turns off the X server's key autorepeat by default while a client keyboard is active — its log even says so (active keyboard: turning X autorepeat off). Without this flag, holding an arrow key (or any key) from the phone does nothing beyond the first tap — no repeat, one character per touch, forever. -repeat keeps autorepeat on so a held key behaves like a physical one. Only drop it if your specific client does its own repeat and you start seeing doubled characters.
-auth guess (x11vnc ≥0.9.9) finds the right Xauthority cookie itself. Modern GNOME/gdm sessions often keep it at /run/user/<uid>/gdm/Xauthority, not the default ~/.Xauthority — hardcoding the default path is a common source of a silent auth failure.
There's no -localhost=no flag — that's not real; -localhost (no value) restricts to loopback, and passing =no gets rejected as unrecognized. Allowing LAN connections is the default when you omit the flag entirely.
Scope the port to your LAN: sudo ufw allow from <your-subnet> to any port 5900 — never expose it to the internet. If you've never touched ufw before and only use SSH outbound to other machines (not inbound into this one), you don't need sudo ufw allow OpenSSH — that rule only matters for a device that accepts incoming SSH connections; ufw's default policy already allows all outbound traffic regardless of any inbound rule you add.

What the VNC password actually is — easy to conflate with the WiFi password, but it's a separate thing: it's set by you via x11vnc -storepasswd (not your router), it controls who can drive this desktop once already on the network (not who can join the network), and it doesn't change when you switch WiFi networks — phone and desktop just need to be on the same network at connection time, whichever one that is. Like the Mac's, it's capped at 8 effective characters by the classic VNC auth protocol.

Persist across reboots — the autostart file

There's no separate script to write here — GNOME (and most desktops) autostarts anything dropped as a .desktop file in ~/.config/autostart/, once per graphical login, which is the earliest point a display actually exists to serve. Set the password once first (x11vnc -storepasswd), then create this file:

# ~/.config/autostart/x11vnc.desktop
[Desktop Entry]
Type=Application
Name=x11vnc
Exec=x11vnc -display :<N> -auth guess -rfbauth /home/<you>/.vnc/passwd -shared -repeat -forever
X-GNOME-Autostart-enabled=true

<N> is your real display number from who (see above); <you> is your Linux username — Exec= needs the absolute path, ~ isn't expanded there. X-GNOME-Autostart-enabled=true is what actually flips it on; a .desktop file without that line sits inert. Verify it's live any time with pgrep -af x11vnc after a fresh login — no separate "did it start" step needed beyond that.

One consequence of the after-login design: if the machine reboots (or loses power) and sits at a lock screen, nothing's listening yet — someone has to log in locally once before the phone can reach it. The Mac's Screen Sharing doesn't have that limitation; this is the one thing it does better.

The phone client: RealVNC Viewer (one app, both machines)

RealVNC Viewer (free on Android and iOS) is the client this post standardizes on, for one reason that matters more than any feature list: it speaks the classic VNC authentication that both servers above serve, so the same app — the same UI, the same gestures, the same saved-entries list — drives the Mac and the Ubuntu box. Two entries, one muscle memory. On the Mac side that's live-tested end to end; against x11vnc it's the same standard handshake (the one x11vnc -storepasswd sets), so it connects the same way.

Worth knowing where the line sits: RealVNC the company sells a cloud-connected ecosystem (account, device list, "connect from anywhere"). None of that is needed here — the Viewer app connects directly, machine-to-machine over your LAN, with no account and nothing routed through anyone's cloud. Don't sign in; just add an address and connect. The same company's download page markets a comparison table implying classic direct connections to third-party servers are unsupported — the Mac test above (direct LAN, Apple's server, plain VNC password) says otherwise, and that's the configuration this post uses. (On iOS, RealVNC's VNC Viewer app is the equivalent client for either machine.)

Try it now — first win. Server on (either machine), Viewer installed: add an entry with the machine's LAN IP and port 5900, connect, enter the VNC password with the username blank. Your desktop should fill the phone's screen, and a tap anywhere should move the real cursor. If it does, the rig works — everything left in this part is technique. If it doesn't, the Reference section's troubleshooting tables are ordered by likelihood; start at the top.

One session, multiple monitors

If the desktop has more than one display, nothing changes on the phone side: the VNC session mirrors the whole desktop, both monitors side by side, as one wide screen. Swipe/pan across to move between them, pinch out to see both at once, pinch in to work one monitor at full zoom — the monitors are just regions of one mirrored framebuffer. Verified live from the phone (a browser on one monitor, a terminal on the other, both driven in the same session):

Works identically against both machines — the Mac's Screen Sharing serves all attached displays, and x11vnc serves the entire X session (:0 spans whatever monitors it spans). One practical note: at phone scale a two-monitor desktop is wide, so the pan-and-pinch rhythm from the gestures section below is the everyday motion, not a workaround.

Driving the desktop from the phone

Everything here is VNC-client behavior, not OS behavior — it works the same against the Ubuntu machine and the Mac. The connection details, in one place:

	Ubuntu machine	macOS machine
Client	RealVNC Viewer	RealVNC Viewer — same app
Address	`<ubuntu-lan-ip>:5900`	`<mac-lan-ip>:5900`
Password	the `x11vnc -storepasswd` one	the 8-character VNC password

Both passwords are separate from your WiFi password and unaffected by switching networks — phone and desktop just need to be on the same network at connection time, whichever one that is.

VNC just mirrors real mouse and keyboard input — there's no VNC-specific "select an app" step, it behaves exactly like sitting at the desktop:

Focus a window: tap it directly in the mirrored screen — a real click.
Type: tap the field to focus it, tap the keyboard icon to bring up the phone's soft keyboard. Everything typed sends as real keystrokes — no special "VNC mode."
Modifier combos (Ctrl+key, Alt+key, Cmd+key): use the client's extra-keys toolbar, the row of dedicated Ctrl/Alt/Shift/Esc/Tab buttons you tap to hold, then tap the other key.

Switching between applications

Three ways, in the order actually worth trying on a phone:

The desktop's hot corner (no keys needed at all): on GNOME, tap the very top-left pixel of the mirrored screen, just under where "Activities" would show — the overview opens with every open window as a thumbnail; tap the one you want. macOS has the same feature: System Settings → Desktop & Dock → Hot Corner (e.g. top-left → Mission Control). This is the one to reach for first: it needs no modifier key, works even if your VNC client's extra-keys toolbar doesn't expose Tab (some builds don't), and is one tap instead of a hold-plus-tap combo.
Alt+Tab / Cmd+Tab, if your client has both keys: hold Alt (or Cmd on the Mac) and tap Tab from the extra-keys toolbar to cycle, same as at a physical keyboard — same toggle-then-tap mechanism as the multi-key shortcuts below. Falls back to the hot corner if Tab isn't in your toolbar's default row.
Between terminals/shells specifically: don't alt-tab or hot-corner between separate GUI terminal windows at all if you can help it — hunting for the right thumbnail among several is more taps than it's worth. Use the desktop's window overview (hot corner or Alt+Tab) instead.

All three are the same underlying trick: VNC sends real input events, so every desktop-level shortcut or gesture you'd use at the keyboard works identically from the phone.

Multi-key shortcuts, e.g. `Super+A`

A touchscreen can't physically hold two keys down at once, so the extra-keys toolbar buttons don't work like a normal press-and-release key — they're toggles. Tapping a modifier arms it (it stays visually pressed/highlighted); tapping the next key sends both together as one combo, and the modifier releases automatically right after.

To fire Super+A (or any modifier combo — Ctrl+Shift+T, Alt+F4, Cmd+Q on the Mac):

Open the extra-keys toolbar (the keyboard/gear icon in the client's in-session toolbar).
Tap the Super/Win/Cmd key icon (labeled Super, Win, Cmd, or shown as a ⊞-style icon depending on client) — it stays highlighted, armed.
Tap A on the soft keyboard — the combo fires as Super+A, and the modifier releases on its own.

Same mechanism for stacking more than one modifier — tap Ctrl, tap Shift, then tap the letter key, and all three go through together. If the client's default extra-keys row doesn't show a Super/Win button, check its settings for a toolbar/keys customization option before assuming the key isn't supported — most VNC clients that expose Ctrl/Alt as toggles expose Super the same way.

Right-click, and where Enter/Backspace live

Right-click in RealVNC Viewer: tap with two fingers at once. One finger tap = left click, two fingers = right, three = middle — and the click lands where the mouse cursor sits, not where your fingers touch (default mode drags the cursor with one finger, offset so you can see it). Two other gestures from the same official table worth knowing: two fingers dragged up/down = scroll, and double-tap + hold + drag = select text or drag-and-drop. (RealVNC's gesture reference.) If you're doing anything right-click-heavy, a Bluetooth mouse pairs to the phone and its actual right button just works.

Enter and Backspace — not special VNC buttons, just the ordinary keys on Android's own soft keyboard, same as any other key you tap. The extra-keys toolbar exists specifically for keys a normal mobile keyboard doesn't have — Ctrl, Alt, Esc, Tab, arrows.

Scrolling — the most common gesture of all

You'll scroll more than you'll click. Two fingers swiped up/down sends real mouse-wheel events — so anything that scrolls at the desk scrolls from the phone, identically on the Mac and Ubuntu: web pages, chat logs, file lists, code editors. There's no VNC-specific scroll mode to enable; the two-finger swipe is the wheel.

The one place it needs help is the terminal, and only because terminals handle wheels oddly at the desk too:

Plain GUI terminal, Ubuntu: the wheel scrolls the terminal's own scrollback in GNOME Terminal as usual — two-finger swipe works out of the box.
Plain Terminal on the Mac: same — the wheel drives the window's scrollback natively.

If a two-finger swipe ever pans the view instead of scrolling the app, you're zoomed out or in touch-drag mode — pinch back to 100% (or tap once to re-center the cursor) and the wheel behavior returns. And on a multi-monitor desktop, remember the two-finger swipe doubles as the pan across monitors when zoomed out.

The everyday actions: new tab, Ctrl+C, close

The four things you'll do a hundred times, in one place. Modifier mechanics are the toggles from the multi-key section above — tap the modifier, it arms, tap the key, the combo fires:

Everyday action	How, from the phone
Open a new terminal tab on the desktop	Same combo as at the desk: `Ctrl+Shift+T` (Ubuntu's GNOME Terminal) — tap Ctrl, tap Shift, tap T. Mac Terminal: `Cmd+T` (Super toggle, then T)
Right-click	Tap with two fingers at once (section above)
Stop a running command (`Ctrl+C`)	Tap Ctrl in the extra-keys row (it arms, stays highlighted), tap `c` → sends `Ctrl+C`, which interrupts the foreground process. It closes nothing — not the tab, not the session
Close the tab / end the shell	`exit`, or `Ctrl+D` (Ctrl toggle + `d`) — the thing people wrongly reach for `Ctrl+C` to do. Different key, different job
Done — end the phone session	Just disconnect from the toolbar; everything keeps running on the desktop

The pair worth memorizing: Ctrl+C stops a program, Ctrl+D ends the shell. C is "interrupt what's running," D is "I'm leaving" — and neither ever touches the VNC session itself. (Running bVNC against the Ubuntu box instead of RealVNC Viewer? Same plays — its Ctrl toggle arms the same way, and its right-click is a hold-then-second-finger-tap gesture.)

More of the everyday, grouped by who's holding the phone — every row uses the same three mechanics already covered (modifier toggles, the extra-keys row, touch gestures), just combined:

If you're developing:

Action	From the phone
Copy / paste in a terminal	Double-tap, hold the second tap, drag to select, then `Ctrl+Shift+C` / `Ctrl+Shift+V` — the terminal is the one app that needs the Shift; everywhere else plain `Ctrl+C`/`Ctrl+V`
Reopen a browser tab you closed by accident	`Ctrl+Shift+T` — the same three-tap combo as "new terminal tab," but in the browser it resurrects the dead tab
New / close browser tab	`Ctrl+T` / `Ctrl+W`
Jump to the address bar (or type a file path)	`Ctrl+L` — browser address bar, and GNOME Terminal's "type a path" prompt
Run the last command again	`↑` from the extra-keys row, then Enter — no modifier needed
Search shell history by fragment	`Ctrl+R`, type a fragment of the command, Enter
Close the focused app window	`Alt+F4` (Linux) / `Cmd+Q` (Mac)
Lock the screen when you walk away	`Super+L` (GNOME) / `Ctrl+Cmd+Q` (Mac) — client stays connected

If you're exploring the machine:

Action	From the phone
Middle-click paste (Linux's best-kept secret)	Tap with three fingers at once — RealVNC's native middle click (or a Bluetooth mouse's middle button)
Zoom the remote screen	Pinch — client-side zoom, sharp on a phone's high-DPI panel, touches nothing on the desktop
Scroll a terminal	Two-finger swipe (works in most terminals; check scrollback settings if not)
Move a window	Touch mode: drag its title bar like a real finger would
Dismiss a dialog / cancel a popup	`Esc` from the extra-keys row — one tap, no modifiers

If you're just using the computer:

Action	From the phone
Passwords	The phone keyboard's autofill — your password manager fills straight into the desktop login field, nothing to type
Emoji into a desktop chat	The phone keyboard's own emoji panel — arrives as real keystrokes, no desktop setup
Play / pause video	`Space` — a key the phone keyboard already has
Long text (URLs, messages)	Copy on the phone, paste with the keyboard's paste button — or dictate it (mic button, section below)

That's the quiet payoff: if the phone's keyboard can produce it, the desktop receives it — and everything else is one armed modifier away.

Editing text in a terminal

Faster than arrow-key nudging on touch, works on both machines: standard readline bindings work over VNC exactly like they do locally — Ctrl+A/Ctrl+E jump to line start/end, Ctrl+W deletes the last word, Ctrl+U clears back to cursor.

Typing on the desktop with your phone keyboard — including voice typing

The soft keyboard that appears when you tap the keyboard icon is your phone's normal keyboard app — whatever you already use, nothing new installed. Everything the keyboard app is good at carries over, because VNC just receives whatever the keyboard commits and sends it as real keystrokes:

Glide typing / swipe input — drag through the letters, same as texting.
Autocorrect and next-word prediction — actively helpful in chat and email apps on the desktop.
Long-press for numbers and symbols — long-press the top-row letters, same as anywhere.
Clipboard — copy on the phone (from anywhere), paste into the desktop app with the keyboard's paste button. Copy on the desktop, read it on the phone.
Multilingual typing — your keyboard's per-language or multi-language modes work as usual; typing Bangla or any other language into a desktop app needs no desktop-side setup beyond the app accepting text.
One-handed / floating mode — shrink the keyboard to a thumb-zone corner for couch use.
Voice typing — the built-in speech-to-text (tested live): any keyboard with a mic button (Gboard, SwiftKey, Samsung Keyboard) works over VNC. Tap the mic, speak, and the transcribed text arrives as committed keystrokes in whatever desktop app is focused — a commit message, a Slack reply, a doc — no extra rig, no second app, no setup. The catch: nearly every phone keyboard dictates through its maker's cloud speech service (Google/Microsoft/Samsung servers do the transcribing), so it's "free and zero-setup," not "offline." For most dictation, that's the right trade — just know which way it cuts before dictating anything sensitive.

Two cautions from the terminal-shaped parts of this rig:

Autocorrect + terminals don't mix. Suggestions will happily "fix" flags, paths, and git subcommands. Your keyboard app's settings (its own toolbar, or Settings → System → Languages & input) usually offer a suggestions/autocorrect toggle — disable it when a terminal is focused, or type flags carefully and proofread before Enter. There's no desktop-side guard; the keystrokes arrive already "corrected."
Voice typing lands wherever the cursor is. Same rule as autocorrect, stronger stakes: check the focused window before you speak, because the words land as keystrokes the instant the keyboard commits them.

A note on global hotkeys

Any app that listens for a global hotkey (a launcher, a window manager action, a screenshot tool, an app-specific shortcut utility) can be triggered from the phone — VNC delivers the key to the desktop's real input stack, and the listener fires. The practical rule for which hotkey to pick for phone use: a single key with no modifier (End, Insert, Home, Page Up/Down) beats any combo, because a combo means arming a toggle button and then tapping a second key — two taps instead of one, every single time.

Part 1 — Troubleshooting & security

Everything above gets the phone driving either machine. What follows is what to check when a step doesn't behave, plus the security notes for Part 1 — read now, or bookmark for later.

If the phone client won't connect (macOS)

Every failure below was either hit live on this rig or traced to a documented server behavior — check symptoms in order:

Symptom	Cause	Fix
Client loops on "enter VNC credentials" with a password you know is right	One of the two auth types being served (Mac-account vs VNC-password) is being answered with the wrong credential — or the password is longer than 8 characters and got silently truncated (DES cap)	Enter the VNC password, username blank; if longer than 8 chars, the first 8 are the real password
Nothing can connect at all	"VNC viewers may control screen with password" never enabled — macOS is waiting for Apple's own auth	Enable it via the ⓘ next to Screen Sharing (step 2 in the macOS setup above), set the password, retry
Connects but lands on the login window instead of your desktop; typing into it drops focus	Remote Management is the enabled service, not plain Screen Sharing — legacy-VNC clients get served the login window under Remote Management (tested live)	System Settings → General → Sharing → disable Remote Management, enable Screen Sharing; reconnect and you land on the desktop
Worked yesterday, won't connect today (after a reboot)	The Mac's LAN IP re-leased to a different address	Recheck with `ipconfig getifaddr en0`, update the saved entry — or set a DHCP reservation in the router
Times out — "but I'm on the same WiFi"	Traffic never arrived: phone silently off the LAN, router guest/AP isolation, or a VPN on the phone — not a Mac-side failure	Check the phone's WiFi details page (SSID + gateway match the router); watch `log stream --predicate 'process == "screensharingd"' --info` while tapping Connect — nothing logged = it never arrived. "Refused" = arrived, nothing listening → the server rows above
VNC view freezes/blank after the Mac sits idle	The Mac auto-locked; the lock screen's password field fights phone-client keystrokes for focus	Unlock once at the Mac's keyboard; for couch sessions set Lock Screen → "Require password…" to a long interval
Client rejects the correct password, non-RealVNC app	Not every Android/iOS client can complete classic VNC auth against a Mac — some negotiate Apple's DH handshake and fail it with no override	Standardize on RealVNC Viewer (tested live against a Mac); verify the two auth-type behaviors above before blaming the password

Two closing notes on the macOS side. First, much of the "Sequoia is rough on third-party VNC clients" chatter traces back to the Remote Management behavior in the table above, not the OS itself — with plain Screen Sharing and the VNC password, RealVNC Viewer connected cleanly here through reboots and IP changes. Reports of screen-recording/share permissions demanding roughly-monthly reauthorization do exist; if a client won't connect, first try Apple's own Screen Sharing app from another Mac to isolate server-toggle vs client. Second, firewall: macOS's application firewall allows the signed system Screen Sharing service through by default — no ufw-style rule to add. The LAN-only hygiene advice still applies: don't port-forward 5900 out of your router, ever. Third: the timeout-vs-refused split from the Ubuntu section below applies to the Mac unchanged — "refused" is the server rows in this table, "timed out" is the phone's network path — and the Mac's ten-second instrument is log stream --predicate 'process == "screensharingd"' --info, watched live while you tap Connect (it's the unified-log equivalent of Ubuntu's journalctl watch: silence = the traffic never arrived).

Session realities (tested across a reboot): everything server-side comes back after a restart, but the Mac's LAN IP can re-lease (ours changed on one reboot — if the saved phone entry stops connecting, recheck with ipconfig getifaddr en0, or give the Mac a DHCP reservation in the router). And multiple displays arrive as one wide canvas — pinch out in the client and pan; VNC has no per-monitor concept.

If the phone won't connect (Ubuntu)

"Connection refused" — port 5900 has nothing listening, x11vnc either never started or died on launch:

pgrep -af x11vnc     # nothing = not running
ss -tln | grep 5900  # nothing = nothing listening

If it's not running, re-run it and actually read what it prints. x11vnc fails fast on a bad flag or auth error and drops straight back to a clean-looking shell prompt — nothing visually distinguishes "crashed instantly" from "idle and fine" unless you read the output. The two causes that hit here:

Wrong display number. -display :0 failed with an Xauthority error on a session that was actually :1. Check with who (<user> :1 <date> — the number after the colon) from a terminal that's part of the actual graphical session, not an unrelated SSH shell.
Xauthority not at the default path. Modern GNOME/gdm often keeps it at /run/user/<uid>/gdm/Xauthority instead of ~/.Xauthority. -auth guess finds it automatically; the explicit fallback is -auth /run/user/<uid>/gdm/Xauthority.

If it's still refused after that: check ufw status verbose actually shows the port-5900 rule as active, and re-check the desktop's LAN IP hasn't drifted from a DHCP re-lease. The one-glance version of that check is hostname -I — every IPv4 on one line; ignore the 172.x.x.x ones (Docker and virtual-machine bridges) and read the 192.168.x.x or 10.x.x.x one.

A timeout is a different animal than "refused" — and the phone's exact error text tells you which you have. "Refused" means the phone's packets reached the desk and nothing was listening — the server-side territory above. "Timed out" means the packets never arrived at all, which is almost always phone-side or network-side:

The phone isn't actually on the same network. Check the phone's WiFi details page, not just the icon: the SSID must match, and the gateway should be your router's LAN address (ours is 192.168.68.1). A mismatched gateway — or a silent fallback to mobile data — puts the phone on a different path entirely.
Guest network or AP/client isolation. Many routers isolate guests (and sometimes a separate 2.4 GHz network) from main-network devices: both phones connect to "the WiFi," neither can see the other. If the router admin panel calls it AP isolation, client isolation, or guest access, that's the switch to check.
A VPN running on the phone can intercept or route away LAN traffic — turn it off for the LAN path (you only need it for the Part 2 path).

The instrument that settles all of it in ten seconds — watch the server log live while you tap Connect on the phone:

journalctl --user -f | grep -i x11vnc

Nothing appears while the phone churns = traffic isn't arriving — work the list above. Got connection from client <ip> followed by an auth failure = the network is fine, it's the password. A connection that appears and instantly drops = server-side — read what it prints (the -shared lockout in the flags section above looks exactly like this).

Part 1 security recap

Keep port 5900 LAN-scoped. ufw allow from <your-subnet> to any port 5900 on Ubuntu; on macOS the firewall already permits Screen Sharing — and on both, the rule that matters is at the router: never port-forward 5900 to the internet. If you ever need in from outside your LAN, that's a VPN job (Part 2 builds exactly that), not a port-forward job.
VNC passwords are weak by protocol. Classic VNC auth is a DES challenge-response capped at 8 characters — both servers in this post use it. On a firewalled home LAN that's an acceptable trade; anywhere shared, tunnel VNC through SSH or use x11vnc's TLS/VeNCrypt options.
No cloud in the control path. RealVNC Viewer connects direct, machine-to-machine; nothing in Part 1 routes through or requires anyone's servers.

That's the whole control rig: the phone can see and drive either machine, from anywhere in the house. One constraint remains — phone and desktop must share a network. Part 2 removes it.

Part 2 — Over the internet: the same rig, anywhere

"Wait — this only works on my WiFi. What if I'm at a coffee shop? What if the desktop is at home and I'm not?"

That's the question Part 1 leaves hanging. This part answers it: same phone, same desktop, same free tools — working from a coffee shop, a hotel room, or the back seat of a cab on mobile data, with nothing exposed to the open internet and nothing added to the bill.

First, the check most people skip: can you even port-forward?

The traditional answer to "reach my home machine from outside" is: open the router's admin panel, forward port 5900 to the desktop, point the phone at your public IP. Before considering that path, run a five-minute check — because on a large share of modern connections it's dead on arrival:

Open the router admin panel (usually 192.168.1.1 or 192.168.0.1 — your gateway address) and note its WAN IP.
From the desktop, ask the internet what IP it sees: curl ifconfig.me.
Compare. Same address → your connection has a real public IP; port-forwarding is at least possible. Different address, or the router's WAN IP somewhere in 100.64.0.0–100.127.255.255 → you're behind CGNAT (Carrier-Grade NAT): your router's "public" side is itself a private address inside your ISP's shared NAT layer. Inbound port-forwards simply won't route to you — no router configuration changes that, because the NAT layer that drops the traffic belongs to the ISP, not you.

CGNAT is now standard on many fiber and 5G home connections, which is exactly why "just forward the port" advice from 2010 blog posts fails silently today: everything on your side is configured correctly, and the packets still never arrive.

Even if you can port-forward, don't — not raw VNC

Suppose the check comes back clean and you do have a real public IP. Port 5900 open to the whole internet is still the wrong move:

Classic VNC auth is a single shared password — no usernames, no rate limiting, no second factor, no lockout. A 1990s-era protocol assumption wearing modern exposure.
5900 is a top-tier scanning target. Internet-wide scanners map the whole IPv4 space continuously; an open VNC port gets probed within hours. Every probe is a password-guess against an 8-character-effective secret (Part 3 explains the cap).
One password = one blast radius. The VNC password doesn't just "view the screen" — it drives the desktop. A correct guess is a full remote session, as if the attacker sat down at your keyboard.

So the real goal was never "forward port 5900." It's this:

Put the phone and the desktop on the same private network no matter where either of them physically is — and let VNC keep believing it's on a LAN, exactly like Part 1.

The options

Approach	Setup effort	Ongoing cost	Survives CGNAT	Exposes anything raw to the internet
Tailscale (mesh VPN)	Low — install, log in, done	Free (personal plan)	Yes — NAT traversal built in, falls back to encrypted relay	No — nothing public-facing, no opened router ports
WireGuard, self-hosted rendezvous	Medium-high — you run a reachable relay yourself	Free if you own a suitable always-on box; else a cheap VPS	Only if the relay has a real public IP	The relay host does
SSH reverse tunnel to a VPS	Medium	~$4–6/mo VPS or a free-tier instance	Yes — desktop initiates outbound	The VPS's SSH port (harden it)
Cloudflare Tunnel	Low-medium	Free tier	Yes — `cloudflared` runs outbound	No inbound port, but traffic transits Cloudflare's edge
Port forward + DDNS	Low if CGNAT check passes	Free	No — the one CGNAT kills outright	Yes, directly — the whole point of the approach

The rest of this part builds the first row. The alternatives get a short treatment in the Reference section below ("Escape hatches").

Tailscale: what it is and why it fits

Tailscale is a mesh VPN built on WireGuard. You install it on each device, log them into the same account (a "tailnet"), and every device gets a stable private address in the 100.x.y.z range. That address doesn't change when the device moves networks — laptop on café WiFi, phone on mobile data, desktop at home: same tailnet IPs, as if they were all plugged into one switch in your living room.

The properties that matter for this rig:

NAT traversal is handled for you. Tailscale tries to establish a direct peer-to-peer WireGuard tunnel first (even through NAT layers); when no direct path can be punched — double-NAT on both ends, strict firewalls — it transparently relays through DERP servers, Tailscale's encrypted relays. Relayed traffic is still end-to-end encrypted; the relay carries ciphertext it cannot read.
Nothing is publicly exposed. No router ports open, no public IP needed, inbound scanning finds nothing. The desktop's VNC port stays reachable only from inside the tailnet.
The protocols don't change. VNC on 5900, same password, same client app — the rig's software never learns a VPN exists. This is a networking-layer swap; Part 1's setup survives untouched.

The trade-off: the LAN-only rig was "no cloud dependency" in the strictest sense. Tailscale adds a third-party coordination service — its control plane handles identity and connection setup. In the common direct-connection case, no VNC pixels ever touch Tailscale's servers; in the relay-fallback case their servers carry them, encrypted, unreadable in transit. If that trade-off ever stops being acceptable, Headscale — the self-hosted control-plane replacement — keeps everything else identical.

Part 2 in one picture: the tailnet replaces "same WiFi" — VNC keeps believing it's on a LAN.

Is Tailscale safe to trust?

The VNC password is one tailnet membership away from your desktop, so this matters. The short version:

WireGuard crypto, not home-rolled. Curve25519 key exchange, ChaCha20-Poly1305. Traffic is end-to-end encrypted between your two devices only. Private keys never leave the device — Tailscale's servers can't decrypt what flows between your phone and desktop.
Clients are open source. Linux, macOS, Android, iOS, Windows, even the DERP relay server — all on GitHub. The closed piece is the coordination/control plane, which sees metadata (who connects to whom), never payloads.
Audited and scaled. Recurring third-party reviews by Latacora, SOC 2 Type II certified. Millions of daily users; named customers include Duolingo, Instacart, Retool, Mercury.
Account-side is solid. SSO/MFA, per-device approval, ACLs, tailnet lock. The tailnet is your outer wall now, not the 8-character VNC password.

The remaining caveat: coordination is a third-party closed service. If that ever bothers you, Headscale — the self-hosted control-plane replacement — keeps everything else identical.

On the desktop

Ubuntu and macOS both get the same one-liner or installer:

# Ubuntu
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# prints a login URL → open it → authenticate with your account
tailscale ip -4   # note this: the desktop's permanent 100.x.y.z address

macOS: install from the Mac App Store or brew install --cask tailscale (or brew install tailscale for the CLI variant), log in from the menu-bar app, read the address from the menu bar or tailscale ip -4.

Then one firewall change on Ubuntu. The Part 1 rule was LAN-scoped:

sudo ufw allow from 192.168.68.0/24 to any port 5900 proto tcp   # LAN-only (Part 1)

The tailnet version keeps the same shape — port 5900 reachable only from a network the phone is on — just against Tailscale's address space:

sudo ufw allow from 100.64.0.0/10 to any port 5900 proto tcp     # any tailnet device
# or tighter, once the phone's tailnet IP is stable:
sudo ufw allow from 100.<phone-tailnet-ip> to any port 5900 proto tcp

(That 100.64.0.0/10 range is CGNAT address space by spec, which is exactly why Tailscale picked it — those addresses are never routable on the public internet, so tailnet traffic can't collide with anything real.)

x11vnc itself: no change. Same command, same flags, same ~/.vnc/passwd. macOS Screen Sharing: no change. Same toggle, same VNC password. macOS's firewall needs no rule either — it permits Screen Sharing by default no matter which interface the traffic arrives on.

On the phone

Install Tailscale from the Play Store, log into the same account, toggle it on. Read the phone's tailnet IP from the app (or the admin console).
RealVNC Viewer: edit the saved connection, point it at the desktop's tailnet IP instead of the LAN IP. Port still 5900. Same VNC password.
That's it — no other app on the phone changes.

What changes, what doesn't

Piece	Part 1 (LAN)	Part 2 (internet)
x11vnc / Screen Sharing	running	unchanged
VNC port	5900	unchanged
VNC password	`~/.vnc/passwd` / Screen Sharing setting	unchanged
Phone client	RealVNC Viewer	unchanged app — new target IP
Desktop address phone dials	LAN IP, re-check after router re-leases	tailnet IP — permanent
ufw rule (Ubuntu)	`allow from 192.168.x.0/24`	`allow from 100.64.0.0/10` (or the phone's tailnet IP)
hotkeys, everything else	working	unchanged

In short: Part 2 is a re-addressing, not a rebuild. Two new apps (Tailscale on each end), one firewall rule, one edited IP.

Verified from cellular

The off-LAN path was tested end to end: phone on mobile data (WiFi off) driving the desktop over VNC through the tailnet, on a direct WireGuard path. tailscale ping answered in ~66 ms — not even the relay was needed. The Mac's internet route has since been tested too, over the DERP relay at ~125 ms, fully usable.

When you verify it on your own networks: Connect, tap the hot corner, open a terminal, type a line, fire a Ctrl+key combo. Every one of those exercising the real-input path is the proof the rig works.

Part 2 — Security and alternatives

That's everything needed to run off the LAN. What follows is the trust boundary to keep in mind, and where to look if Tailscale ever isn't the right fit.

Security recap

The VNC port is now reachable from wherever your phone is — the tailnet replaces "same WiFi" as the trust boundary. Keep the tailnet small: personal Tailscale plans allow a limited number of users and devices; use them for your devices only, not as a shared VPN for acquaintances.
Tailscale's ACLs can pin it further: phone may talk to desktop on 5900, nothing else, nobody else. Locking a two-device tailnet down to exactly one rule is an afternoon's reading, not a project.
Still true from Part 1: VNC auth is one shared password. Over the tailnet that's acceptable to many people — an attacker needs tailnet membership first, which means your Tailscale account, which has MFA and device approval. Layered, the 8-character cap stops being the outer wall.
And the classic still applies: never port-forward 5900 on the router to "make Tailscale unnecessary." You'd be re-opening exactly what Part 2 closed.

If Tailscale isn't the right fit

SSH reverse tunnel to a VPS — the fallback that removes the VPN vendor entirely: ssh -R 5900:localhost:5900 user@your-vps (or a persistent autossh/systemd unit). Outbound-only, so CGNAT is irrelevant; the phone dials the VPS. Costs a VPS (~$4–6/mo or free tier), needs key-only SSH and careful GatewayPorts, and adds a box you must keep alive.
Headscale — self-hosted Tailscale control plane, same clients, your server, your rules. The "nothing outside my control" property, at the price of running the coordination layer yourself.
Cloudflare Tunnel — cloudflared outbound from the desktop; supports raw TCP (VNC included). Viable, but it's HTTP-shaped infrastructure repurposed for TCP, needs a domain and Access policies, and its trust model is "transits Cloudflare's edge." For two personal devices, Tailscale is the better-fitting tool.

Part 3 — Deep dive: how the rig actually works

Part 1 said "trust me, taps become real keystrokes." Part 2 said "trust me, two devices behind two different NATs find each other, encrypted." This part cashes those checks. Nothing here is new setup — it's the working rig, opened up. Read it when something breaks and you want to know why, or because you just like knowing how things work.

The wire protocol: RFB, and the 8-character password

VNC speaks RFB (Remote Framebuffer). A session is a short fixed conversation, and knowing its shape explains several behaviors you met in Part 1 without explanation:

The whole VNC session is this conversation — and step 3 is where the 8-character cap lives.

Version handshake — client and server exchange RFB 003.008-style strings and agree on a version.
Security negotiation — the server lists the auth types it will accept; the client picks one. This is where macOS offers two at once — Mac-account (Apple's ARD-style handshake) and the legacy VNC password — and where a client that can only speak one of them dies with a rejected-correct-password loop. It negotiated the wrong door, not the wrong key.
Auth, then framebuffer negotiation — pixel format, encodings, and from there a stream of framebuffer updates (server → client) and pointer/key events (client → server).

The 8-character cap: classic VNC authentication is a DES challenge-response. The server sends a 16-byte challenge; the client encrypts it with DES using the password itself as the key — and DES keys are 8 bytes. Whatever you type beyond 8 characters never enters the computation. Every VNC implementation that speaks classic auth inherits the cap: the Mac's Screen Sharing password (Part 1's "first 8 are the real password" gotcha) and x11vnc's -rfbauth file alike. It's a protocol limitation, not a bug in either server.

Why VNC triggers hotkeys when SSH can't

Part 1's rule was: "global hotkeys fire from the phone." Here's the mechanism underneath.

Same keystroke, two doors: VNC injects at the X server level (XTEST); SSH hands bytes to one process's stdin.

When the phone's keyboard commits text, RealVNC Viewer sends RFB key events. On the desktop, x11vnc turns those into calls to XTEST — the X11 extension written for automated testing that injects input at the server level, upstream of any application. XTEST-synthesized events enter the X server's input stream and are dispatched exactly like events from the physical keyboard driver: same keycodes, same grabs, same global hotkey listeners.

That's the whole trick the rig rests on:

A terminal sees keystrokes → typing works.
The window manager sees key combos → Super-shaped shortcuts work.
Any global hotkey hook sees a real key event → launchers, screenshot tools, window-manager actions all fire from the phone.
SSH, by contrast, delivers bytes to one process's stdin. Nothing about an SSH keystroke is a keyboard event as far as the OS is concerned — no window manager, no listeners, no GUI. That's "the real reason this rig is VNC-based, not SSH-based," now with its gears visible.

macOS runs the same play with different plumbing: Screen Sharing injects events through the window server's event path — equivalent to a physical event to every listener, which is why the same hotkey rule held on the Mac (verified live: shortcuts fired from the phone exactly as from the keyboard).

Part 2's layer: WireGuard, NAT traversal, and DERP

The internet build adds one more layer to trace, and its mental model is small:

WireGuard is the encryption: each pair of tailnet devices shares cryptographic keys; traffic between them is a sealed UDP envelope no relay can open.
NAT traversal is the connection problem: both endpoints are (usually) behind NATs that reject unsolicited inbound packets. Tailscale's coordination plane tells each side what the other's observable address:port is, and the two sides simultaneously send packets at each other — each side's outbound packet opens the pinhole in its own NAT that the other's inbound packets then slip through. That's "direct connection," and it's the common case.
DERP is the fallback for when no pinhole works (symmetric NAT on both ends, hostile firewalls): encrypted packets relayed through Tailscale's servers. Slower — an extra hop, and hop distance matters — but the payload stays end-to-end encrypted, so the relay is a post office, not a listener.

The generic version of the same trick Tailscale's coordination plane runs before falling back to DERP.

You can see which path you're on: tailscale status on the desktop prints, per peer, direct or relay "..." — worth checking once when you set up, because it explains the latency you feel.

Part 3 — Troubleshooting

The table below is for when something breaks — symptom to layer, so you debug in the right order instead of by guesswork:

Symptom	Suspect layer	Check
Phone can't connect to desktop at all (off-LAN)	Tailnet	`tailscale status` on both devices — is each online and showing the other? Then `tailscale ping <desktop-tailnet-ip>`
Same WiFi, correct IP, still times out (on-LAN)	Phone network path	Watch live while tapping Connect: `journalctl --user -f \
Tailnet up, VNC refuses	Firewall / server	Is x11vnc running? Does the ufw rule cover {% raw %}`100.64.0.0/10`? (Mac: `sudo lsof -iTCP:5900 -sTCP:LISTEN` — empty = Screen Sharing off.) `tailscale ping` works but 5900 times out = firewall
VNC connects, password rejected	Auth	8-character DES cap (first 8 are real); Mac: VNC password, username blank
Screen connects but input feels laggy (off-LAN)	Transport	`tailscale status` — relayed instead of direct? Relayed + packet loss = transport, not the rig
Everything connects, nothing types	Client keyboard plumbing	Does the client send key events for text (IME commits)? RealVNC Viewer does (tested live); a client that injects nothing won't — try its key panel
Works on LAN, never off-LAN	Tailnet membership	Both devices logged into the same tailnet? Phone's Tailscale toggle actually on? (Android kills VPNs quietly — check the key icon)
Ubuntu unreachable after a power cut	x11vnc autostart	x11vnc starts only after graphical login — someone must log in locally once (the Mac serves its login window over VNC; Ubuntu can't)

Quick start after first setup

The setup above happens once. This is the 30-second checklist for every session after — or for any "suddenly won't connect" moment. Run these on the desk.

1. Find the desk's addresses

hostname -I
# All IPv4s on one line. Ignore 172.x.x.x (Docker/VM bridges). You want:
#   LAN:       192.168.x.x or 10.x.x.x   <- changes sometimes (DHCP)
#   Tailscale: 100.x.x.x                 <- never changes

Explicit variant, showing which interface carries which (interface names vary per machine — don't memorize them):

ip -4 -o addr show scope global

On a Mac, the one-glance version is even shorter:

ipconfig getifaddr en0    # Wi-Fi IP, nothing else; empty = not on Wi-Fi (desktop Macs: try en1)

2. Tailscale side

tailscale ip -4      # the desk's permanent address — what the phone should dial
tailscale status     # every tailnet device + its IP; the phone's line must NOT say "offline"

A phone showing offline, last seen … = its Tailscale VPN is off (Android's battery optimization kills it quietly) — nothing off-LAN will connect until it's back on.

3. Is the server up?

pgrep -af x11vnc     # expect: x11vnc -display :N -auth guess ... -shared -repeat -forever
ss -tln | grep 5900  # expect: LISTEN 0.0.0.0:5900

On a Mac, the server is screensharingd — one command answers both questions:

sudo lsof -iTCP:5900 -sTCP:LISTEN   # expect: screensharingd LISTEN

Empty on either = the server side is down — Ubuntu: re-login graphically (autostart fires on login); Mac: System Settings → General → Sharing → Screen Sharing got flipped off — flip it back on (and re-check the "VNC viewers may control screen with password" setting).

4. What the phone should dial

Situation	Address in RealVNC Viewer
Phone on the same WiFi as the desk	`<lan-ip>:5900` (e.g. `192.168.1.42:5900` — example only)
Anywhere else (cellular, other WiFi)	`<tailscale-ip>:5900`

Rule of thumb: just use the Tailscale address always — it works on the same WiFi too, and it never changes.

5. Watch it live while the phone retries

journalctl --user -f | grep -i x11vnc        # Ubuntu
log stream --predicate 'process == "screensharingd"' --info   # Mac — same read

Run it, hit Connect on the phone, read the outcome: nothing appears → traffic isn't arriving (Tailscale off, wrong address, wrong WiFi, firewall — steps 1, 2, 4) · "Got connection" then auth failure → connection is fine, wrong password · phone says "refused" → right network, wrong IP — the LAN IP changed.

Even faster, from any machine that can already reach the desktop (tailnet or LAN) — the ten-second port check, no logs and no phone needed:

nc -vz <desktop-ip> 5900

An instant "refused" means the packets arrived and nothing is listening — server off, start it (on the Mac, check the Screen Sharing toggle; on Ubuntu, pgrep -af x11vnc). Silence, then timeout means a path problem — VPN down, firewall, wrong network. "succeeded" means go: the phone will connect. nc is the built-in on macOS (there's no telnet there anymore); on Ubuntu it ships with the default netcat-openbsd package. Verified live on the Mac's internet route — it's the command worth remembering from this section.

6. Why the LAN IP drifts, and the fix

The router hands out LAN IPs by DHCP — after a router reboot or lease expiry the desk can get a new one, and the phone's saved entry keeps dialing the old address. Two permanent fixes:

DHCP reservation in the router settings ("always give this MAC this IP") — pins the LAN IP.
Use the Tailscale IP — it never changes, and works from anywhere, not just home WiFi.

Option 2 is the better default: save <tailscale-ip>:5900 as the primary entry and this whole class of breakage disappears.

7. Phone error text → cause

Phone shows	Meaning	Fix
The connection timed out	Packets never arrived: Tailscale off on the phone, wrong network, AP isolation, or firewall	Check the phone's Tailscale/WiFi details (SSID + gateway), verify the address
Connection refused	Network reachable, but no server at that address — almost always a stale LAN IP	Re-check current IPs (step 1); prefer the Tailscale IP
Authentication failed / wrong password	Connection fine, VNC password mismatch	Re-enter it, or reset on the desk: `x11vnc -storepasswd` then restart (Ubuntu); System Settings → General → Sharing → Screen Sharing ⓘ (Mac)

Tools & licenses

Tool	Role	License / cost
x11vnc	VNC server, Ubuntu	GPL-2.0; actively maintained; past CVEs addressed by 0.9.17
macOS Screen Sharing	VNC server, macOS	Built-in
RealVNC Viewer	Phone client, both OSes	Free for personal use; direct-connection mode, no account
Tailscale	Mesh VPN (Part 2)	Free personal plan; WireGuard end-to-end, SOC 2 Type II
Headscale	Self-hosted control plane (escape hatch)	Open source, BSD-3

Never port-forward 5900, on either OS, for any reason. Classic VNC auth is a DES challenge-response capped at 8 characters — fine behind a LAN rule or a tailnet, never fine exposed to the internet.

Let's Connect

If you try any of this, I'd rather hear what broke than what worked:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs
Support: SupportKori

Self-Review With AI Before You Open the PR — A Practical Workflow with branchdiff

Mir Mursalin Ankur — Mon, 01 Jun 2026 15:40:37 +0000

You know the moment. You push the branch, open the PR, and immediately see it — the undefined return on the refund path, the token logged to the console, the TODO that was supposed to be temporary six weeks ago. The reviewer catches it four hours later and you reply "good catch, fixing now" as if someone else wrote that line.

The first reviewer on most pull requests should have been the author. Half the comments you will receive — the missing null check, the untested error branch, the duplicate logic that could be extracted, the import that now goes nowhere — are things you would have caught with one more careful read-through. You skip that read because you have been in the code for two days and your brain completes the sentences for you. You see what you meant to write, not what is on the page.

This post is about closing that gap with a structured AI-assisted self-review before the PR opens. Not to skip the human reviewer — to walk into the review with the obvious problems already gone, the test gaps already filled, and the PR description already written. So the reviewer's attention can land on what actually needs a second pair of eyes.

The tool is branchdiff: a local browser app that runs your diff on localhost, stores everything in ~/.branchdiff/, and keeps the AI surface controlled through an explicit branchdiff agent command API. Nothing leaves your machine until you decide to push it.

Why "before the PR" is the right moment

If you review after opening the PR, every AI fix becomes noise: a force-push, a re-read for your reviewer, another commit in the audit trail. If a teammate is already mid-review when you discover the bug, you look careless. The patch that should have been in the original push becomes a distraction for everyone downstream.

If you review before opening the PR, the AI's output is a private workspace. You act on what matters, commit the fixes into your own history (often as fixup! commits you squash before pushing), and the PR that goes up is cleaner from the first push. Reviewers see your real work, not your stream-of-consciousness corrections.

There is a subtler benefit too: you learn from the dismissals. Every time you push back on an AI comment with a real reason — "the wrapper handles null upstream", "this is intentionally synchronous because of write contention" — you are writing down the rationale you would otherwise leave implicit. That reason is exactly what the next reviewer needs in the PR description. The self-review session generates your PR description as a side effect.

The workflow in 4 steps

Assume you have a feature/payments branch off main — twelve files changed, about three hundred lines added. You want to clean it up before requesting review.

Step 1 — open your own diff locally

branchdiff main feature/payments

A browser tab opens at http://localhost:5391. Because you are comparing two named refs, this is a persistent session — comments you (or the AI) post here survive new commits to either branch. You can iterate across multiple rounds of fixes without losing the review trail. If you want a fresh start, --new archives the current session and creates a clean one; archived sessions stay queryable via branchdiff review threads --session <id>.

The diff renders with split or unified view, syntax highlighting for 150+ languages, a sidebar of changed files, and keyboard shortcuts (j/k for next/previous file, n/p for next/previous hunk).

Step 2 — run an AI review pass

If you use Claude Code, install the skills once:

branchdiff skill add        # adds .claude/skills/branchdiff-{review,resolve}

Then in your Claude Code session:

/branchdiff-review main feature/payments

The skill calls branchdiff agent diff to read the full diff, then posts inline comments via branchdiff agent comment --file <path> --line <n> --body "[tag] ...". Each comment carries a severity tag:

Tag	Meaning	Typical action
`[must-fix]`	Bug, security issue, broken contract	Fix before pushing
`[suggestion]`	Better pattern, missing test, refactor opportunity	Fix or dismiss with reason
`[nit]`	Style, naming, minor inconsistency	Dismiss if low priority
`[question]`	AI is uncertain, needs context	Reply with explanation

If you use a different AI, the README ships a copy-paste prompt that drives the same branchdiff agent command surface. Or pipe the context directly:

branchdiff review context | claude -p "review for security and breaking changes"
branchdiff review run --exec "claude" --mode review

Two improvements in v1.5.0 make this pass noticeably better:

Constructive tone. The skill leads with the problem, not a judgment — "This returns undefined when amount === 0" rather than "This is wrong." Collaborative language. When AI comments read as observations rather than accusations, engineers actually fix the bug.
Nth-time review awareness. Before commenting, the skill reads resolved and dismissed threads. Resolved threads are not re-raised; dismissed ones are only re-flagged if there is new evidence. You can run /branchdiff-review after every meaningful commit without re-litigating the same feedback.

Step 3 — read, triage, decide

Open the browser. Each AI comment is anchored to a line in the diff, tag visible in the gutter, body inline. Four options per thread:

Fix it — make the change in your editor, then resolve the thread (branchdiff agent resolve <id> --summary "added null guard" or click Resolve in the UI). The summary is optional but worth writing — future review passes and future reviewers can see what was done and why.

Auto-fix it — if you are using Claude Code, /branchdiff-resolve reads open comments, applies mechanical fixes (rename, extract function, null check, missing test stub), and resolves threads with a summary. Read the diff before committing — the AI occasionally takes a suggestion more literally than you intended.

Dismiss it — the comment was wrong, out of scope, or already handled upstream. branchdiff agent dismiss <id> --reason "..." records why. That reason is what nth-time awareness uses so the same point is not re-raised next pass.

Reply to it — for [question] tags, branchdiff agent reply <id> --body "..." lets you answer in-thread. Useful when the AI flagged unclear behaviour and you want the rationale on record for the next reviewer.

The dismissal reason is the single most important habit to build. It keeps the AI honest across passes, and it leaves a paper trail you can point to when a reviewer asks "why is this line like that?"

Step 3.5 — use the review tools that make long diffs tractable

The features that make a teammate's 40-file PR manageable pay equal dividends on your own branch:

Viewed counter + stale detection. Mark files viewed (eye icon or right-click) as you walk through. The sidebar shows 12 / 24 viewed. Any file you marked viewed but later changed gets flipped to stale with an amber dot — staleness is detected via an FNV-1a hash on the diff signature, so a rebase that does not change the content does not invalidate your markers.

Sidebar filters. Nine filter chips — Commented, Uncommented, Viewed, Unviewed, Stale, Collapsed, Expanded, Staged, Unstaged — stack with the search box. On the second pass after a set of fixes: Filter → Stale shows exactly which files need re-reading.

Collapse all / Expand all. A quick high-level pass before diving in. Files with open comments are force-expanded so threads are never hidden behind a collapsed diff.

Staged / unstaged toggle. When reviewing your working tree before the first commit, flip between git diff --staged and git diff from the toolbar. File rows show inline status badges: S (staged) and U (unstaged).

Full-file view + minimap. The toolbar's Full-file view opens a VS Code-style rendering of the entire file with all hunks in place. A minimap on the right marks added, removed, and modified regions — scan a 1,000-line file at a glance and click straight to the change. Inline comments stay anchored when you switch from hunk view to full-file view. Markdown files get a Preview toggle (v1.5.0) that renders both sides as formatted markdown.

Commit detail page. Click any commit in the history sidebar to open /commit/:hash with the full SHA, parent links, file list with +N / -N counts, and the same diff view. The back button preserves your position.

Step 4 — focused passes for the risky parts

The generalist review catches a wide range. These four pre-built workflows catch a narrower, deeper class of issue:

Security audit — looks only for injection (SQL, command, XSS, template, NoSQL, prompt), secret leaks, weak crypto, broken authorisation, deserialisation traps, path traversal, SSRF, and dependency risk. Skips style entirely. A 200-line auth diff produces five precise comments instead of fifty.

Test coverage gaps — for every new function, branch, or error path, checks the test directory and flags uncovered paths with a stub it(...) suggestion. Priority: error branches → new public API → edge cases → happy path.

Breaking-change review — classifies every change as breaking or non-breaking, drafts an UPGRADE.md snippet for breaking ones, flags schema migrations without a rollback path as [must-fix].

Dependency review — flags added or major-bumped packages with maintenance status, license compatibility, bundle-size delta, first-party alternatives, and known CVEs.

A realistic session on a 12-file payments branch

Here is what branchdiff agent list --status open might look like after the general review pass:

[must-fix]   src/billing/charge.ts:84      Refund path returns undefined when amount === 0
[must-fix]   src/api/webhooks.ts:42        Missing signature verification before parsing body
[suggestion] src/utils/format.ts:12        Replace toFixed(2) with Intl.NumberFormat for i18n
[suggestion] src/billing/charge.ts:140     No test covers partial-refund branch
[suggestion] src/billing/charge.ts:156     Extract retry logic — duplicated three times
[nit]        src/types.ts:7                Inconsistent enum casing
[question]   src/api/webhooks.ts:55        Should we 200 on duplicate webhook IDs or 409?

Two [must-fix] items, three improvements, one nit to dismiss, one question to answer. Twenty minutes of cleanup. The PR you push is materially better than the one you would have pushed before lunch.

The AI's general comment often summarises the change set in two or three sentences ready to paste into the PR description — that alone saves five minutes of staring at the PR form wondering how to explain what you did.

And the dismissal trail matters beyond this session. When you dismiss the [nit] with reason "team style is mixed casing for legacy enums — see ADR-014", that reason is on record. The next engineer who reads src/types.ts and wonders about the inconsistency has an answer one branchdiff session away.

Where to stay skeptical

AI is fallible. It will flag non-issues and miss real bugs. The most common failure mode is confident-sounding wrong advice on async code — read those comments twice.

Local context only. The AI sees the diff and the files in your repo. It does not see runtime behaviour, production logs, or upstream service contracts. Those still need a human reviewer or an integration test.

Token budget. For a 200-file refactor, point the AI at the riskiest ten files first — you can always run a second pass with a different focus.

Do not auto-resolve everything. /branchdiff-resolve is convenient, but read the patches before committing. The AI will occasionally "fix" something by deleting code instead of correcting it.

The AI does not replace understanding your own change. If you do not understand a chunk of code well enough to review it, no AI pass magically fills that gap.

Ship the PR

When the session is clean — open count at zero, threads resolved or dismissed with reasons attached — commit your fixes, squash any fixup! commits, and push. Either open the PR on the platform or use the Open a Pull Request button in the branchdiff toolbar (it appears automatically when no PR exists for the branch). The local session stays in ~/.branchdiff/ for your own reference; nothing from the AI pass needs to land on the PR unless you explicitly push it.

The reviewer who picks it up sees a tighter diff, fewer obvious bugs, a clearer description. Their attention can land on the parts that need real judgement: the architectural decision, the unclear contract, the edge case that matters in production but not in tests.

Quick start

Full install guide, changelog, and uninstall steps on the branchdiff releases page.

npm install -g @encryptioner/branchdiff
# or: pip install branchdiff
# or: brew tap encryptioner/branchdiff https://github.com/encryptioner/branchdiff-releases \
#          && brew install branchdiff

branchdiff skill add                         # one-time, for Claude Code
branchdiff main feature/your-branch          # opens local UI
# in Claude Code:  /branchdiff-review
# triage threads → fix → resolve → dismiss with reasons
# squash fixup! commits → push branch → open PR

Self-review is the part of the workflow you can improve without changing your team's process. Try it on the next branch you were about to push without looking at it again.

Let's Connect

I am always excited to hear what you are building. If this guide helped, or if you have questions about building self-review habits into your workflow:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs
Support: SupportKori

branchdiff releases, install guide, and changelog: encryptioner.github.io/branchdiff-releases

Graphify + code-review-graph: Build a Self-Updating Knowledge Graph for Claude Code and other AI Coding Agent

Mir Mursalin Ankur — Sun, 17 May 2026 15:31:39 +0000

Every developer working with LLMs on a large codebase eventually hits the same wall: context windows are finite, but codebases are not.

You start a new AI coding session, ask about the payment flow — and your agent starts re-reading dozens of files just to get oriented. Twenty thousand tokens evaporated before a single line of code is written. Multiply that by every session, every team member, every day.

Two open-source tools solve this in different but complementary ways:

Graphify — converts your folder into a queryable knowledge graph with community detection, Obsidian-compatible reports, and cross-file traversal
code-review-graph (CRG) — builds a SQLite-backed AST graph with blast-radius analysis, embedding-based semantic search, ~25 MCP tools (allow-listable to a working set of 8), and sub-second incremental updates

This guide walks through installing both tools, connecting them to any AI coding agent — Claude Code, Cursor, Gemini CLI, Windsurf, GitHub Copilot, and more — wiring auto-updates for code edited by humans, git commits, or the agent itself, and pairing everything with an Obsidian vault as a persistent memory layer.

Pick one, both, or none — every section degrades gracefully. Each tool works standalone; the smart-grep-hook, session-start cheatsheet, and CLAUDE.md routing rules all detect what is present and adapt. Use just graphify if you want a pure CLI / zero-MCP setup. Use just CRG if you want embedding-aware semantic search and PR-grade impact tools. Use both for the full stack (CRG primary, graphify on miss). If neither is installed, the agent silently falls back to grep — no broken hooks, no errors.

All commands in this guide were tested on Ubuntu and macOS across multiple real pnpm monorepos of varying sizes.

Real Numbers from Two Test Projects

Before diving in, here's what both tools produced across two real codebases — one a full-stack TypeScript monorepo with 5 packages, the other a lighter frontend-only repo:

Metric	Graphify (AST-only)	code-review-graph
Files indexed (large)	1,020	1,052
Nodes (large)	3,815	5,780
Edges (large)	4,830	30,611
Files indexed (small)	702	711
Nodes (small)	2,035	2,773
Edges (small)	2,357	15,037
Communities	750 / 499	28 wiki pages each
Incremental update	~10s (8 workers)	0.425s
LLM tokens used	0	0
Storage	`graphify-out/` (JSON)	`.code-review-graph/` (SQLite)

How Each Tool Works

Graphify — Two-Pass Graph with Communities

Your Code
    │
    ▼
Pass 1: Tree-sitter AST   ← 0 tokens, 25 languages
(classes, functions, imports, call graphs)
    │
    ▼
Pass 2: AI Extraction     ← only for PDFs, images, markdown (optional)
(semantic relationships via Claude subagents)
    │
    ▼
NetworkX Graph + Leiden Clustering
    │
    ├── graphify-out/graph.json       (queryable)
    ├── graphify-out/GRAPH_REPORT.md  (750 communities, Obsidian links)
    ├── graphify-out/graph.html       (interactive visual)
    └── graphify-out/cache/           (SHA256 per file)

Each edge has a confidence tag:

Tag	Source	Confidence
`EXTRACTED`	Directly in AST	1.0
`INFERRED`	Reasonable deduction	0.7–0.9
`AMBIGUOUS`	Needs review	<0.7

On the large monorepo: 87% EXTRACTED · 13% INFERRED · 0% AMBIGUOUS

code-review-graph — Blast-Radius Graph with MCP

Your Code (git-tracked files)
    │
    ▼
Tree-sitter AST (23 languages, 0 tokens)
    │
    ▼
SQLite (.code-review-graph/graph.db)
    │
    ├── Nodes: functions, classes, files
    ├── Edges: imports, calls, inheritance
    └── Full-text search index (FTS5)
    │
    ▼
~25 MCP tools available (allow-list to ~8 via CRG_TOOLS env — see "Strip Unused CRG Tools")
(semantic_search_nodes, query_graph, get_impact_radius, list_communities, ...)

Installation

Install one or both — the rest of the guide shows where each section applies.

Ubuntu

# Pick what you need:
pip install graphifyy         # graphify CLI (note: two y's on PyPI)
pip install code-review-graph # CRG (CLI + MCP server, includes embeddings extra)

# Verify (only the lines for installed tools):
graphify --help | head -5
code-review-graph --version

macOS

# Via uv (fastest):
uv tool install graphifyy           # graphify only
uv tool install code-review-graph   # CRG only — or run both lines for both

# Or via pipx:
brew install pipx
pipx install graphifyy
pipx install code-review-graph

PyPI quirk: The package is graphifyy (two y's). The CLI command after install is graphify (one y).

Step 1: Create Ignore Files

Before building any graph, exclude noise from indexing. Place these at your project root.

.graphifyignore

node_modules/
dist/
build/
.pnpm-store/
coverage/
*.min.js
*.min.css
*.map
pnpm-lock.yaml
yarn.lock
*.lock
*.log
.env*
graphify-out/
.code-review-graph/
*.example.*

.code-review-graphignore (same content)

node_modules/
dist/
build/
.pnpm-store/
coverage/
*.min.js
*.min.css
*.map
pnpm-lock.yaml
yarn.lock
*.lock
*.log
.env*
graphify-out/
.code-review-graph/
*.example.*

Step 2: Build the Graphs Manually

code-review-graph

cd /path/to/your-project

# Full build (first time) — parses all files
code-review-graph build

# Output (large monorepo):
# Full build: 1052 files, 5780 nodes, 30611 edges (postprocess=full)

# Output (smaller frontend repo):
# Full build: 711 files, 2773 nodes, 15037 edges (postprocess=full)

Graphify (AST-only, no LLM cost)

cd /path/to/your-project

# AST-only update (no API key required)
graphify update .

# Output (large monorepo):
# Rebuilt: 3815 nodes, 4830 edges, 750 communities
# graph.json, graph.html and GRAPH_REPORT.md updated in graphify-out

# Output (smaller repo):
# Rebuilt: 2035 nodes, 2357 edges, 499 communities

For the richer semantic graph (PDFs, images, markdown — uses LLM):

# Full extraction with Claude subagents (requires ANTHROPIC_API_KEY)
graphify extract .

Step 3: Register with Your AI Agent

code-review-graph (auto-configures 5 platforms)

code-review-graph install

This single command:

Writes .mcp.json (Claude Code MCP server config)
Writes .cursor/mcp.json, .opencode.json, Zed settings, .cursorrules, GEMINI.md, AGENTS.md
Creates .claude/skills/ for Claude Code tool integration
Installs hooks in .claude/settings.json (move these out — see below)
Installs a git pre-commit hook
Updates .gitignore to exclude .code-review-graph/

Post-install housekeeping: code-review-graph install is aggressive — it writes configs for every AI IDE it knows about. Most teams only use one. Add the noise to .gitignore:

# .gitignore additions
AGENTS.md
GEMINI.md
.mcp.json          # keep only .mcp.example.json
.cursorrules
.windsurfrules
.opencode.json
.kiro/

Three-file hook pattern: settings.json stays clean — permissions only, no hooks. Hooks go into example/local:

.claude/settings.example.json (committed) — documents the full hook structure for teammates. Contains all graph hooks (Stop, SessionStart, PreToolUse). Copy from here to activate.
.claude/settings.local.json (gitignored) — your actual personal hooks that fire at runtime. Copy from settings.example.json on first setup, then customize with env vars or secrets. You can also copy individual hooks into your global ~/.claude/settings.json if you want them active across all projects.

// .claude/settings.example.json — committed reference, shows hook structure
// Copy this file to .claude/settings.local.json and customize
{
  "hooks": {
    "PostToolUse": [],
    "Stop": [
      {
        "_comment": "CRG auto-update after AI finishes turn — once per turn, PID-guarded.",
        "hooks": [{
          "type": "command",
          "command": "command -v code-review-graph >/dev/null 2>&1 && [ -d .code-review-graph ] && { PF=/tmp/crg-claude.pid; if [ -f \"$PF\" ] && kill -0 \"$(cat \"$PF\")\" 2>/dev/null; then true; else { code-review-graph update --skip-flows 2>/dev/null && nohup code-review-graph embed >/dev/null 2>&1 & } & echo $! > \"$PF\"; fi; } || true",
          "timeout": 5
        }]
      }
    ],
    "SessionStart": [
      {
        "_comment": "CRG graph status on session open",
        "hooks": [{
          "type": "command",
          "command": "command -v code-review-graph >/dev/null 2>&1 && code-review-graph status 2>/dev/null || true",
          "timeout": 10
        }]
      },
      {
        "_comment": "Setup nudge — prompt to initialize if CLI installed but no graph built yet",
        "hooks": [{
          "type": "command",
          "command": "if command -v code-review-graph >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1 && [ ! -d .code-review-graph ]; then printf '{\"systemMessage\":\"Graph tool installed but not yet initialized. Ask me to set up: code-review-graph (code-review-graph install)\"}'; fi || true",
          "timeout": 10
        }]
      },
      {
        "_comment": "Graph query cheatsheet — injected once per session (~150 tokens)",
        "hooks": [{
          "type": "command",
          "command": "if [ -f .code-review-graph/graph.db ] || [ -f graphify-out/graph.json ]; then STATS=\"\"; TOOL_LINES=\"\"; if [ -f .code-review-graph/graph.db ]; then STATS=$(python3 -c \"import sqlite3; c=sqlite3.connect('.code-review-graph/graph.db'); n=c.execute('SELECT COUNT(*) FROM nodes').fetchone()[0]; e=c.execute('SELECT COUNT(*) FROM edges').fetchone()[0]; print(f'{n} nodes, {e} edges'); c.close()\" 2>/dev/null || echo \"\"); TOOL_LINES=\"  where is X defined    → semantic_search_nodes_tool(query=X)\\n  who calls X           → query_graph_tool(pattern=callers_of, target=X)\\n  pre-refactor blast    → get_impact_radius_tool(changed_files=[...])\\n  community/cluster     → list_communities_tool()\\n  code review context   → get_review_context_tool(changed_files=[...])\"; fi; if [ -f graphify-out/graph.json ]; then GFY_STATS=$(python3 -c \"import json; g=json.load(open('graphify-out/graph.json')); nodes=g.get('nodes',[]); comms=len(set(n.get('community','') for n in nodes if n.get('community',''))); print(f'{len(nodes)} nodes, {comms} communities')\" 2>/dev/null || echo \"\"); [ -n \"$GFY_STATS\" ] && STATS=\"${STATS:+$STATS | }graphify: $GFY_STATS\"; TOOL_LINES=\"${TOOL_LINES:+$TOOL_LINES\\n}  CRG miss / explore    → graphify query '<term>' --graph graphify-out/graph.json\\n  path A→B              → graphify path '<from>' '<to>' --graph graphify-out/graph.json\"; fi; printf '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"GRAPH QUERY CHEATSHEET (%s) — use BEFORE Read/Grep/Bash-find on code:\\n%s\\nSkip graph for: .md .json .yml .log .jsonl configs cross-repo paths.\\nOverride grep gate: append --graph-tried to any Bash command.\"}}' \"$STATS\" \"$TOOL_LINES\"; fi",
          "timeout": 5
        }]
      }
    ]
  }
}

# .claude/settings.local.json — gitignored, actual runtime hooks
# Copy from settings.example.json on first setup:
cp .claude/settings.example.json .claude/settings.local.json
# Then add any personal env vars or secrets

Why Stop, not PostToolUse? PostToolUse fires after every individual file edit — if Claude makes 10 edits in one response, it fires 10 times. The pgrep guard that prevents double-spawning has a race window of a few milliseconds, which is not enough to block concurrent spawns reliably. The result: multiple CRG Python processes pile up, load average hits 12+, RAM saturates, and the machine slows to a crawl. Stop fires once when the AI finishes its entire turn — all edits batched, single update triggered. The PID-file guard then prevents overlap across turns (skip if the previous turn's update is still running). Zero pile-up by design.

Why graphify update is NOT in any Claude hook: graphify update takes ~10s+ on a real monorepo (even with SHA256 caching). Running it in Stop or PostToolUse would block the session or cause the process to hang in the background, accumulating across turns. It belongs only in git hooks (post-commit, post-checkout) where it runs as a fully detached nohup process after the commit returns — the developer has already moved on, so the latency is invisible.

# .claude/settings.local.json — gitignored, actual runtime hooks (copy from example)

The .mcp.json it creates (keep as .mcp.example.json only):

{
  "mcpServers": {
    "code-review-graph": {
      "command": "uvx",
      "args": ["code-review-graph", "serve"],
      "type": "stdio"
    }
  }
}

Graphify (AI Agent Integration)

# Adds graphify section to CLAUDE.md + PreToolUse hook (Claude Code)
graphify claude install

Graphify's claude install adds a PreToolUse hook that intercepts grep, rg, find commands and redirects the agent to graphify query instead — turning search interception into graph navigation. For other agents: code-review-graph install already writes equivalent config to GEMINI.md, AGENTS.md, .cursorrules, and Zed settings.

Note: graphify claude install writes the PreToolUse hook into .claude/settings.json. Move it to .claude/settings.example.json (committed as a reference) and copy to .claude/settings.local.json to activate it locally — not every teammate will have graphify installed, so it shouldn't fire automatically for everyone.

Auto-Update on Commit (the full picture)

Three independent triggers keep the graph fresh — install all of them so no edit path leaves it stale:

Trigger	Hook location	Tool	Notes
Claude finishes a turn	`settings.example.json` → `settings.local.json` Stop hook	CRG only	~0.425s — fast enough to run after every AI turn; PID-guarded
Any commit	`.git/hooks/post-commit` (or `.husky/post-commit`)	graphify + CRG	terminal commits, IDE commits, other AI tools; graphify runs as background `nohup`
Branch switch	`.git/hooks/post-checkout` (or `.husky/post-checkout`)	graphify + CRG	smart: ≤5 files diff → incremental update; >5 files or new branch → full rebuild; background `nohup`

graphify is NOT in the Claude Stop hook. graphify update takes ~10s+ on large monorepos — too slow for an AI turn hook. It would pile up, hang in the background, and saturate CPU/RAM (observed: 3 stuck processes at 65–73% CPU each). Use git hooks instead — the developer has already moved on by the time graphify finishes.

Graphify ships its own installer for the git side:

graphify hook install   # writes post-commit + post-checkout

Code-review-graph does not. Its install command writes a pre-commit hook that runs detect-changes --brief (a status warning before the commit lands) but no post-commit hook to update the SQLite graph after. Without one, .code-review-graph/graph.db only refreshes when Claude touches a file — every terminal/IDE/other-tool commit drifts.

Add the post-commit update yourself. Both forms are detached so git commit returns immediately.

Resource guard required. Graph rebuilds are CPU-intensive. Without guards, multiple rebuilds can pile up (observed: 3 concurrent graphify processes at 65–73% CPU each, load average 12+, RAM saturated). Every hook below includes a _resources_ok check (CPU ≤ 50% of cores, memory ≥ 2 GB free) and a pgrep process deduplication guard. If either check fails, the rebuild silently skips — the next commit retriggers a fresh attempt.

Plain git project — append to .git/hooks/post-commit:

#!/bin/sh
# Knowledge graph tools are optional — each section silently skips if tools are absent.

# Returns 0 (ok) when CPU load and free memory are within acceptable limits.
# CPU: 1-min load average must be <= 50% of logical core count (Linux/macOS)
#      or aggregate load percentage <= 50% (Windows).
# Memory: effectively available memory must be >= 2048 MB on all platforms.
_resources_ok() {
  _os=$(uname -s 2>/dev/null)
  case "$_os" in
    Linux)
      _nproc=$(nproc 2>/dev/null || grep -c '^processor' /proc/cpuinfo 2>/dev/null || echo 1)
      _cpu_ok=$(awk -v n="$_nproc" 'NR==1 { print ($1 / n <= 0.50) ? "1" : "0" }' /proc/loadavg 2>/dev/null)
      if [ "${_cpu_ok:-1}" != "1" ]; then
        echo "[graph hook] Skipping rebuild — CPU load above 50% threshold"
        return 1
      fi
      _mem_ok=$(awk '/^MemAvailable:/ { print ($2 / 1024 >= 2048) ? "1" : "0" }' /proc/meminfo 2>/dev/null)
      if [ "${_mem_ok:-1}" != "1" ]; then
        echo "[graph hook] Skipping rebuild — available memory below 2 GB threshold"
        return 1
      fi
      ;;
    Darwin)
      _nproc=$(sysctl -n hw.logicalcpu 2>/dev/null || echo 1)
      _cpu_ok=$(sysctl -n vm.loadavg 2>/dev/null | awk -v n="$_nproc" \
        '{ gsub(/[{}]/, ""); print ($1 / n <= 0.50) ? "1" : "0" }')
      if [ "${_cpu_ok:-1}" != "1" ]; then
        echo "[graph hook] Skipping rebuild — CPU load above 50% threshold"
        return 1
      fi
      _page_size=$(sysctl -n hw.pagesize 2>/dev/null || echo 4096)
      _mem_ok=$(vm_stat 2>/dev/null | awk -v ps="$_page_size" '
        /Pages free:/        { gsub(/\./, "", $3); free = $3 + 0 }
        /Pages inactive:/    { gsub(/\./, "", $3); inactive = $3 + 0 }
        /Pages speculative:/ { gsub(/\./, "", $3); spec = $3 + 0 }
        END { print ((free + inactive + spec) * ps / 1048576 >= 2048) ? "1" : "0" }
      ')
      if [ "${_mem_ok:-1}" != "1" ]; then
        echo "[graph hook] Skipping rebuild — available memory below 2 GB threshold"
        return 1
      fi
      ;;
    MINGW*|MSYS*|CYGWIN*)
      if command -v powershell.exe > /dev/null 2>&1; then
        _cpu_pct=$(powershell.exe -NoProfile -Command \
          "(Get-CimInstance Win32_Processor | Measure-Object -Property LoadPercentage -Average).Average" \
          2>/dev/null | tr -d '\r\n ')
        _cpu_over=$(echo "${_cpu_pct:-0}" | awk '{ print ($1 > 50) ? "1" : "0" }')
        if [ "$_cpu_over" = "1" ]; then
          echo "[graph hook] Skipping rebuild — CPU load above 50% threshold"
          return 1
        fi
        _mem_mb=$(powershell.exe -NoProfile -Command \
          "[math]::Round((Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory / 1024)" \
          2>/dev/null | tr -d '\r\n ')
        _mem_low=$(echo "${_mem_mb:-9999}" | awk '{ print ($1 < 2048) ? "1" : "0" }')
        if [ "$_mem_low" = "1" ]; then
          echo "[graph hook] Skipping rebuild — available memory below 2 GB threshold"
          return 1
        fi
      fi
      ;;
  esac
  return 0
}

# Skip during rebase/merge/cherry-pick
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
[ -d "$GIT_DIR/rebase-merge" ] && exit 0
[ -d "$GIT_DIR/rebase-apply" ] && exit 0
[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0

# ── graphify: rebuild graph after commit ─────────────────────────────────────
# Entire block skips if graphify is not installed.
if command -v graphify > /dev/null 2>&1; then
  CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null)
  if [ -n "$CHANGED" ]; then
    GRAPHIFY_BIN=$(command -v graphify)
    case "$GRAPHIFY_BIN" in
      *.exe) _SHEBANG="" ;;
      *)     _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | sed 's/^#![[:space:]]*//') ;;
    esac
    case "$_SHEBANG" in
      */env\ *) GRAPHIFY_PYTHON="${_SHEBANG#*/env }" ;;
      *)        GRAPHIFY_PYTHON="$_SHEBANG" ;;
    esac
    case "$GRAPHIFY_PYTHON" in
      *[!a-zA-Z0-9/_.@-]*) GRAPHIFY_PYTHON="" ;;
    esac
    if [ -z "$GRAPHIFY_PYTHON" ] || ! "$GRAPHIFY_PYTHON" -c "import graphify" 2>/dev/null; then
      GRAPHIFY_PYTHON=""
      command -v python3 >/dev/null 2>&1 && python3 -c "import graphify" 2>/dev/null \
        && GRAPHIFY_PYTHON="python3"
      [ -z "$GRAPHIFY_PYTHON" ] && command -v python >/dev/null 2>&1 \
        && python -c "import graphify" 2>/dev/null && GRAPHIFY_PYTHON="python"
    fi
    if [ -n "$GRAPHIFY_PYTHON" ] && ! pgrep -qf 'graphify' 2>/dev/null && _resources_ok; then
      export GRAPHIFY_CHANGED="$CHANGED"
      _LOG="${HOME}/.cache/graphify-rebuild.log"
      mkdir -p "$(dirname "$_LOG")"
      echo "[graphify hook] launching background rebuild (log: $_LOG)"
      nohup timeout 300 $GRAPHIFY_PYTHON -c "
import os, sys
from pathlib import Path
changed_raw = os.environ.get('GRAPHIFY_CHANGED', '')
changed = [Path(f.strip()) for f in changed_raw.strip().splitlines() if f.strip()]
if not changed:
    sys.exit(0)
print(f'[graphify hook] {len(changed)} file(s) changed - rebuilding graph...')
try:
    from graphify.watch import _rebuild_code
    _force = os.environ.get('GRAPHIFY_FORCE', '').lower() in ('1', 'true', 'yes')
    _rebuild_code(Path('.'), force=_force)
except Exception as exc:
    print(f'[graphify hook] Rebuild failed: {exc}')
    sys.exit(1)
" > "$_LOG" 2>&1 < /dev/null &
      disown 2>/dev/null || true
    fi
  fi
fi

# ── code-review-graph: incrementally update MCP graph index after commit ────
# Uses `update --skip-flows` (incremental, sub-second) rather than `build`
# (full rebuild — minutes on large repos).
if command -v code-review-graph > /dev/null 2>&1 && [ -d .code-review-graph ] && ! pgrep -qf 'code-review-graph update' 2>/dev/null && _resources_ok; then
  _LOG="${HOME}/.cache/code-review-graph-update.log"
  mkdir -p "$(dirname "$_LOG")"
  echo "[code-review-graph] Commit detected - launching background update (log: $_LOG)"
  nohup sh -c 'code-review-graph update --skip-flows && code-review-graph embed' > "$_LOG" 2>&1 < /dev/null &
  disown 2>/dev/null || true
fi

Husky project — create .husky/post-commit (Husky v9+ runs .husky/<hookname> directly; no .husky/_/ shim editing needed). The content is identical to the plain git version above — copy the entire script. Always prefer update --skip-flows (incremental, sub-second) over build (full rebuild — minutes on large repos):

# .husky/post-commit — same content as .git/hooks/post-commit above
# (copy the full script from the plain git example)

Verify both graphs caught up to the latest commit:

git log -1 --format=%ci                          # last commit timestamp
stat -f %Sm graphify-out/graph.json              # macOS
stat -f %Sm .code-review-graph/graph.db          # macOS
# stat -c %y graphify-out/graph.json             # Linux equivalent

Both file mtimes should be at or after the commit timestamp. If graph.db lags, the post-commit hook isn't firing — check chmod +x on the hook file and that pnpm install ran (so Husky's prepare script wired up .husky/).

Agent Config: trigger-list pattern (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`)

Rather than pasting the full tool docs into your agent config file (which bloats every session's context), create a dedicated docs/agent/knowledge-graph.md and add a trigger-list pointer. This works the same way across agents — Claude Code reads CLAUDE.md, Gemini CLI reads GEMINI.md, Codex and OpenAI agents read AGENTS.md:

## Knowledge Graph

**Read `docs/agent/knowledge-graph.md` whenever you:**
- Answer any architecture, cross-module, or "how does X work" question
- Plan to grep, find, or glob through the codebase
- Need to understand an unfamiliar module or trace a call chain
- Are about to refactor or change something with unclear blast radius

The doc covers graphify (community detection, path tracing, GRAPH_REPORT.md), code-review-graph (MCP tools, impact analysis), when to use each, and the full auto-update pipeline.

Place this block in CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, or AGENTS.md for Codex/OpenAI-compatible agents — the trigger-list pattern works the same across all of them. A vague "read before exploring unfamiliar code" pointer is easy for any agent to skip. Explicit trigger conditions — especially "plan to grep" — activate the graph habit reliably. The full reference lives in docs/agent/knowledge-graph.md and is only loaded when actually needed.

Enforcing Graph-First: The Smart Grep Hook

The trigger-list in CLAUDE.md is a soft nudge — in practice, agents still reach for grep by default even with both knowledge graphs initialized and the pointer in place. Soft warnings alone do not reliably change behaviour.

The fix is a smarter PreToolUse hook that doesn't just warn — it answers the question inside the rejection, and handles every scenario gracefully: no graph, cross-repo grep, multi-repo registries.

Decision ladder (first match wins, zero false positives):

Situation	Hook behaviour
No graph in this repo, no registered siblings	Silent pass — zero noise
Non-code target (`.md`, `.json`, `.log`, `.jsonl`)	Silent pass
`--graph-tried` flag in command	Silent pass — explicit override
Grep targets abs path outside CWD + that dir has graph	Query that graph, show result as context, allow grep
Grep targets abs path outside CWD + no graph found	Silent pass — grep is the right tool here
No local graph + registered sibling repo matches pattern	Show sibling result as context, allow grep
First grep this session + local graph hit	Show answer and allow grep (one-shot lesson)
First grep this session + no graph hit	Allow grep, suggest MCP tool for next time
Subsequent grep + local graph hit	Deny with answer inline — zero retry loop
Subsequent grep + no graph hit	Silent pass

The key insight: the deny message IS the answer. The costly retry loop (deny → model reads error → model tries graph → gets answer = 2 API calls) collapses to 1.

Three graph sources, consulted in priority order:

Local graph — .code-review-graph/graph.db in current working directory
Cross-repo graph — walk up from any absolute path in the command to find the nearest .code-review-graph/ directory
Multi-repo registry — code-review-graph repos for globally registered repos

All lookups use the nodes_fts FTS5 full-text index — sub-millisecond, no external process, no network. Falls back to a LIKE scan if FTS returns empty.

Save ~/.claude/scripts/smart-grep-hook.sh:

#!/usr/bin/env bash
# ~/.claude/scripts/smart-grep-hook.sh
# Adaptive graph-first grep interceptor — CRG (SQLite FTS5) + graphify (JSON)
# Decision ladder (first match wins):
#   1. Not a search command              → pass silently
#   2. --graph-tried override            → pass silently
#   3. Non-code target (.md/.json/…)    → pass silently
#   4. Cross-repo abs path:
#      a. Target has CRG or graphify     → query both, show context, allow grep
#      b. No graph in target             → pass silently
#   5. No local graph of either type:
#      a. CRG registered repo match     → show context, allow grep
#      b. Global merged graphify match  → show context, allow grep
#      c. No match                      → pass silently
#   6. Local graph(s) present — session-aware gating:
#      a. First grep + hit              → show result, allow (one-shot lesson)
#      b. First grep + miss             → allow, suggest tool for next time
#      c. Subsequent + hit              → answering deny (result inline, no retry)
#      d. Subsequent + miss             → pass silently
set -uo pipefail

INPUT=$(cat)
CMD=$(printf '%s' "$INPUT" | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))" \
  2>/dev/null || echo "")

# ── Tier 1-3: fast exits ──────────────────────────────────────────────────────
case "$CMD" in *grep*|*" rg "*|*"   rg "*|*ripgrep*|*" fd "*|*" ack "*|*" ag "*) ;;
  *find\ *) ;; *) exit 0 ;; esac
case "$CMD" in *--graph-tried*|*"# graph-checked"*|*"GRAPH_TRIED=1"*) exit 0 ;; esac
case "$CMD" in
  *.md*|*.json*|*.yml*|*.yaml*|*.log*|*.jsonl*|*.txt*|*.csv*|\
  *node_modules*|*"/.git/"*|*/dist/*|*/build/*|*/.next/*|*/__pycache__/*) exit 0 ;; esac

json_esc() { python3 -c "import json,sys; print(json.dumps(sys.stdin.read())[1:-1])"; }

# ── CRG: SQLite FTS5 query (sub-ms) ──────────────────────────────────────────
query_crg() {
  local db="$1" pat="$2"
  python3 - "$pat" "$db" <<'PYEOF' 2>/dev/null
import sqlite3, sys, os
pat, db = sys.argv[1], sys.argv[2]
if not os.path.exists(db): sys.exit(0)
try:
    c = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=3)
    rows = c.execute(
        "SELECT n.kind, n.name, n.file_path, n.line_start "
        "FROM nodes_fts f JOIN nodes n ON n.id=f.rowid WHERE nodes_fts MATCH ? LIMIT 5",
        (pat,)).fetchall()
    if not rows:
        rows = c.execute(
            "SELECT kind, name, file_path, line_start FROM nodes WHERE name LIKE ? LIMIT 5",
            (f'%{pat}%',)).fetchall()
    c.close()
    for kind, name, path, line in rows:
        print(f'[crg] {kind}  {name}  →  {path}:{line}')
except: pass
PYEOF
}

# ── graphify: JSON in-memory search (~5ms for 4k nodes) ──────────────────────
query_graphify() {
  local json="$1" pat="$2"
  python3 - "$pat" "$json" <<'PYEOF' 2>/dev/null
import json, sys, os
pat_low, gfile = sys.argv[1].lower(), sys.argv[2]
if not os.path.exists(gfile): sys.exit(0)
try:
    g = json.load(open(gfile))
    results = []
    for n in g.get('nodes', []):
        label = n.get('label', '')
        if pat_low in label.lower() or pat_low in n.get('id', '').lower():
            src = n.get('source_file', '')
            loc = n.get('source_location', '') or n.get('line', '')
            kind = n.get('file_type', 'node')
            community = n.get('community', '')
            results.append(f'[graphify] {kind}  {label}  →  {src}:{loc}  (community {community})')
    for r in results[:5]: print(r)
except: pass
PYEOF
}

# ── Query both graphs at a given root ─────────────────────────────────────────
query_at_root() {
  local root="$1" pat="$2"
  local out=""
  local crg_db="${root}/.code-review-graph/graph.db"
  local gfy_json="${root}/graphify-out/graph.json"
  [ -f "$crg_db" ]   && out+=$(query_crg "$crg_db" "$pat")$'\n'
  [ -f "$gfy_json" ] && out+=$(query_graphify "$gfy_json" "$pat")$'\n'
  printf '%s' "$out" | sed '/^[[:space:]]*$/d'
}

# ── Walk up to nearest repo with any graph ────────────────────────────────────
find_graph_root() {
  local d="$1"; [ ! -d "$d" ] && d=$(dirname "$d")
  while [ "$d" != "/" ] && [ "$d" != "$HOME" ]; do
    { [ -f "$d/.code-review-graph/graph.db" ] || [ -f "$d/graphify-out/graph.json" ]; } \
      && echo "$d" && return
    d=$(dirname "$d")
  done
}

# ── Extract search pattern ────────────────────────────────────────────────────
PATTERN=$(printf '%s' "$CMD" | python3 -c "
import sys, shlex
cmd = sys.stdin.read().strip()
try: parts = shlex.split(cmd)
except: parts = cmd.split()
bases = {'grep','rg','ripgrep','egrep','fgrep','ag','ack','fd'}
idx = next((i for i,p in enumerate(parts) if p.rsplit('/',1)[-1] in bases), -1)
if idx < 0: sys.exit(0)
for p in parts[idx+1:]:
    if not p.startswith('-') and '/' not in p and len(p) > 2: print(p[:60]); break
" 2>/dev/null || echo "")

# ── Tier 4: cross-repo detection ──────────────────────────────────────────────
TARGET=$(printf '%s' "$CMD" | python3 -c "
import sys, shlex, os
try: parts = shlex.split(sys.stdin.read())
except: parts = sys.stdin.read().split()
cwd = os.getcwd()
for p in parts:
    if p.startswith('/') and not p.startswith('-') and not p.startswith(cwd): print(p); break
" 2>/dev/null || echo "")

if [ -n "$TARGET" ]; then
  ROOT=$(find_graph_root "$TARGET")
  if [ -n "$ROOT" ] && [ -n "$PATTERN" ]; then
    RESULT=$(query_at_root "$ROOT" "$PATTERN")
    if [ -n "$RESULT" ]; then
      MSG="Cross-repo graph hit (${ROOT##*/}) for '${PATTERN}':\n${RESULT}\n\nGrep proceeding — result shown as context. Open a session in that repo for deeper analysis."
      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}' \
        "$(printf '%s' "$MSG" | json_esc)"
    fi
  fi
  exit 0  # always allow cross-repo grep
fi

# ── Local graph detection ─────────────────────────────────────────────────────
HAVE_CRG=0; HAVE_GFY=0
[ -f .code-review-graph/graph.db ]   && HAVE_CRG=1
[ -f graphify-out/graph.json ]       && HAVE_GFY=1

# ── Tier 5: no local graph → registry + global merged graph ───────────────────
if [ "$HAVE_CRG" = "0" ] && [ "$HAVE_GFY" = "0" ]; then
  EXTRA_RESULT=""

  # 5a: CRG multi-repo registry
  if command -v code-review-graph >/dev/null 2>&1 && [ -n "$PATTERN" ] && [ "${#PATTERN}" -gt 2 ]; then
    REG=$(code-review-graph repos 2>/dev/null | python3 - "$PATTERN" <<'PYEOF' 2>/dev/null
import sys, os, sqlite3
pat = sys.argv[1]; results = []
for line in sys.stdin.read().strip().splitlines():
    for token in line.split():
        if not token.startswith('/'): continue
        db = f"{token}/.code-review-graph/graph.db"
        if not os.path.exists(db): continue
        try:
            c = sqlite3.connect(f'file:{db}?mode=ro', uri=True, timeout=2)
            rows = c.execute(
                'SELECT n.kind, n.name, n.file_path, n.line_start '
                'FROM nodes_fts f JOIN nodes n ON n.id=f.rowid WHERE nodes_fts MATCH ? LIMIT 3',
                (pat,)).fetchall()
            c.close()
            for kind, name, fp, ln in rows:
                results.append(f'[crg:{token}] {kind}  {name}  →  {fp}:{ln}')
        except: pass
for r in results[:5]: print(r)
PYEOF
    )
    [ -n "$REG" ] && EXTRA_RESULT+="$REG"$'\n'
  fi

  # 5b: global merged graphify (~/obsidian-vault/merged-graph.json)
  GLOBAL_GFY="${HOME}/obsidian-vault/merged-graph.json"
  if [ -f "$GLOBAL_GFY" ] && [ -n "$PATTERN" ] && [ "${#PATTERN}" -gt 2 ]; then
    GRESULT=$(query_graphify "$GLOBAL_GFY" "$PATTERN")
    [ -n "$GRESULT" ] && EXTRA_RESULT+="$GRESULT"$'\n'
  fi

  if [ -n "$EXTRA_RESULT" ]; then
    CLEAN=$(printf '%s' "$EXTRA_RESULT" | sed '/^[[:space:]]*$/d')
    MSG="No local graph. Sibling/global graph hit for '${PATTERN}':\n${CLEAN}\n\nGrep proceeding. Open a session in the repo shown above for deeper analysis."
    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}' \
      "$(printf '%s' "$MSG" | json_esc)"
  fi
  exit 0
fi

# ── Tier 6: local graph(s) — session-aware gating ────────────────────────────
KEY=$(printf '%s' "${PWD}" | md5 2>/dev/null || printf '%s' "${PWD}" | md5sum 2>/dev/null | cut -c1-8)
DIR="${HOME}/.cache/claude-graph-hook"; mkdir -p "$DIR"
SLOT="${DIR}/first-grep-${KEY}-$(date +%Y%m%d_%H)"

RESULT=""
[ -n "$PATTERN" ] && [ "${#PATTERN}" -gt 2 ] && \
  RESULT=$(query_at_root "." "$PATTERN")

# Adaptive tool hint — shows MCP tool (CRG) or graphify CLI or both
TOOL_HINT=""
[ "$HAVE_CRG" = "1" ] && TOOL_HINT="semantic_search_nodes_tool(query='${PATTERN}')"
[ "$HAVE_GFY" = "1" ] && {
  GFY_HINT="graphify query '${PATTERN}' --graph graphify-out/graph.json"
  TOOL_HINT="${TOOL_HINT:+${TOOL_HINT} or }${GFY_HINT}"
}

if [ ! -f "$SLOT" ]; then
  touch "$SLOT"
  if [ -n "$RESULT" ]; then
    MSG="Graph pre-answer for '${PATTERN}':\n${RESULT}\n\nIf enough — skip the grep. Running this time (one-shot). Future code-path greps denied when graph answers. Override: --graph-tried."
  else
    MSG="No graph hit for '${PATTERN}' — grep proceeding (one-shot). Next time try: ${TOOL_HINT}. Append --graph-tried to bypass permanently."
  fi
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}' \
    "$(printf '%s' "$MSG" | json_esc)"
  exit 0
fi

# Subsequent greps: answering deny if graph hits, else pass
if [ -n "$RESULT" ]; then
  MSG="Graph has this — no retry needed:\n\n${RESULT}\n\nUse: ${TOOL_HINT}. Append --graph-tried to override."
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"block","permissionDecisionReason":"%s"}}' \
    "$(printf '%s' "$MSG" | json_esc)"
  exit 0
fi

printf '[graph-hook] no result for "%s"\n' "$PATTERN" >> "${DIR}/bypass.log"
exit 0

Wire it in settings.example.json (then copy to settings.local.json or ~/.claude/settings.json):

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/scripts/smart-grep-hook.sh",
        "timeout": 6
      }
    ]
  }
]

Pair with a concrete SessionStart cheatsheet — injects a query→tool map once per session (~150 tokens, prevents most reflexive greps before they happen). Fires only when a graph exists in the current project, silent otherwise:

"SessionStart": [
  {
    "hooks": [{
      "type": "command",
      "command": "if [ -f .code-review-graph/graph.db ] || [ -f graphify-out/graph.json ]; then STATS=''; TOOL_LINES=''; if [ -f .code-review-graph/graph.db ]; then STATS=$(python3 -c \"import sqlite3; c=sqlite3.connect('.code-review-graph/graph.db'); n=c.execute('SELECT COUNT(*) FROM nodes').fetchone()[0]; e=c.execute('SELECT COUNT(*) FROM edges').fetchone()[0]; print(f'{n} nodes, {e} edges'); c.close()\" 2>/dev/null || echo ''); TOOL_LINES=\"  where is X defined    → semantic_search_nodes_tool(query=X)\\n  who calls X           → query_graph_tool(pattern=callers_of, target=X)\\n  pre-refactor blast    → get_impact_radius_tool(changed_files=[...])\\n  community/cluster     → list_communities_tool()\\n  code review context   → get_review_context_tool(changed_files=[...])\"; fi; if [ -f graphify-out/graph.json ]; then GFY_STATS=$(python3 -c \"import json; g=json.load(open('graphify-out/graph.json')); nodes=g.get('nodes',[]); comms=len(set(n.get('community','') for n in nodes if n.get('community',''))); print(f'{len(nodes)} nodes, {comms} communities')\" 2>/dev/null || echo ''); [ -n \"$GFY_STATS\" ] && STATS=\"${STATS:+$STATS | }graphify: $GFY_STATS\"; TOOL_LINES=\"${TOOL_LINES:+$TOOL_LINES\\n}  CRG miss / explore    → graphify query '<term>' --graph graphify-out/graph.json\\n  path A→B              → graphify path '<from>' '<to>' --graph graphify-out/graph.json\"; fi; printf '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"GRAPH QUERY CHEATSHEET (%s) — use BEFORE Read/Grep/Bash-find on code:\\n%s\\nSkip graph for: .md .json .yml .log .jsonl configs cross-repo paths.\\nOverride grep gate: append --graph-tried to any Bash command.\"}}' \"$STATS\" \"$TOOL_LINES\"; fi",
      "timeout": 5
    }]
  }
]

Why --graph-tried beats a hard block:

13 characters. The agent adds it when it has already consulted the graph or when the query targets content the AST graph cannot index (string literals, config values, log text, content in another language not indexed). The hook detects the flag and passes silently — legitimate grep is never more than one retry away.

Cross-repo and no-graph: always allow, never penalise:

The hook is non-blocking in every case where the graph can't definitively help. Cross-repo greps get graph context shown as additional info, not a gate. Repos without any graph see zero hook overhead. The only hard deny is when the local graph has the exact answer — and even then, --graph-tried is the immediate escape.

Session state (hourly bucket per repo):

~/.cache/claude-graph-hook/
├── first-grep-<repo-hash>-<YYYYMMDDHH>   ← one-shot allowance marker
└── bypass.log                             ← audit: greps that passed with no graph answer

The allowance resets hourly. The bypass.log is an audit trail — recurring patterns signal queries worth adding to a custom graph index or documentation.

Real Token Cost Comparison

All numbers measured live on a 1336-node TypeScript monorepo, embeddings enabled (code-review-graph embed run once, then incremental after each edit).

Symbol and concept lookups

Query	grep	graphify query	CRG keyword	CRG semantic
"Where is `createThread`?"	594 tokens (2374 chars, 24 lines)	1532 tokens (165 nodes, BFS depth=2)	115 tokens	115 tokens
"uiState persistence layer"	1069 tokens (4274 chars, 43 lines)	1552 tokens (87 nodes)	miss	100 tokens
"comment submit handler"	114 tokens (narrow query)	1538 tokens	miss	100 tokens
"what imports api.ts?"	437 tokens (filenames only)	1563 tokens (378 nodes)	125 tokens (41 results)	125 tokens
"who calls `createThread`?"	~1109 tokens + manual filter	1532 tokens	80 tokens	80 tokens
"error handling in server"	2220 chars (noise: auto-generated .react-router types)	1538 tokens	477 chars (source only)	477 chars

Hidden grep cost: after a grep hit the model usually reads the matched file. comment-form.tsx = 909 tokens. comment-thread.tsx = 1397 tokens. A typical grep + follow-up read costs 1300–2500 tokens per question. CRG returns file:line — no follow-up read needed.

Signal quality gap: grep returns every file containing the pattern — including dist/, generated .react-router/types/, auto-compiled .d.ts, and node_modules leakage. CRG indexes only what Tree-sitter parses as source. For the "error handling" query: grep returned 20 lines from auto-generated type files before any real source. CRG returned 5 precise hits: sendError and withJsonBody in http-utils.ts, ErrorBoundary in root.tsx and diff.tsx. Zero noise.

graphify query — right tool, wrong use case: BFS depth=2 returns 87–378 nodes (~1500 tokens) regardless of query specificity. For symbol lookup ("where is createThread?"), this is 15× more expensive than CRG semantic. For neighborhood exploration ("what connects to this module when I don't know the codebase?"), the BFS output is exactly what you want — a visual map of relationships. The smart-grep hook intercepts it for symbol queries and routes through CRG; if CRG misses, graphify query proceeds. Use graphify query deliberately for exploration, not as a default lookup tool.

Why graphify appears less in session logs than you'd expect: In a measured multi-hour session on a 1336-node monorepo, graphify had 2 actual code lookups vs CRG's 36 graph tool calls. This is correct behaviour, not underuse. CRG with embeddings covers 90%+ of targeted symbol and concept queries at 100–350 tokens — graphify BFS for the same query returns 1,500 tokens. The session was targeted feature work on a known codebase; both tools appropriately routed to CRG. Graphify's value surface is: unfamiliar codebase onboarding, cross-community architecture tracing, and path exploration between distant modules — none of which were needed. If the session had started with "I've never seen this codebase, orient me", graphify would have dominated.

The CRG-miss → grep fallback gap: When semantic_search_nodes_tool returns 0 results (happened 3× for exact symbol names like validateRef, parseUnifiedDiff), the current cheatsheet doesn't tell the agent to try graphify query next. The agent falls back to grep, which returned 6–29 chars of near-nothing. The correct fallback chain is: CRG semantic (miss) → graphify query '<term>' → grep. Add this line to your CLAUDE.md trigger list or SessionStart cheatsheet to close the gap:

CRG 0 results → graphify query '<term>' --graph graphify-out/graph.json

What grep cannot do at all

Some questions require multi-hop graph traversal. Grep answers the text search question; it cannot answer the dependency question.

Scenario: "What breaks if I change server.ts?"

With grep you would need to:

Read server.ts header to find what it exports (~828 chars)
grep -rn "startServer" packages/ to find 1-hop callers (~715 chars)
For each caller found, grep again for their importers (~309+ chars)
Aggregate manually — still missing transitive re-exports and inferred dependencies

Total: 3 separate operations, 1852+ chars, still incomplete.

With get_impact_radius_tool:

{"summary": "Blast radius for server.ts:
  - 21 nodes directly changed
  - 500 nodes impacted (within 2 hops)
  - 135 additional files affected",
 "risk": "high",
 "key_entities": ["completer","promptBranch","fetchDefaultReviewers"]}

1 call, 274 chars, complete 2-hop picture, risk rating included.

Grep reaches one level of importers in one pass. To get two levels, you need to loop. To get re-exports of re-exports, you need to understand the module graph. get_impact_radius_tool does all of this from the pre-built AST graph — sub-second.

This matters most before refactoring: touching a widely-imported file without an impact check risks breaking 135 files silently.

`get_review_context_tool` — best single call for code review

Before any code review, this one call returns: risk level, impacted node count, impacted file count, and test gaps — all in ~111 tokens (session-measured average; range 80–270 depending on depth). No follow-up reads needed.

get_review_context_tool(changed_files=["packages/git/src/threads.ts"], depth="minimal", include_source=false)

→ Risk: high
→ 359 impacted nodes in 126 files
→ test_gaps: 15

Compare with manually: read file (828 tokens) + grep importers (715 tokens) + read callers to assess risk (1400+ tokens) = 2943 tokens, incomplete.

Add it to your review workflow via the SessionStart cheatsheet — it fires once per session at ~150 tokens total, pointing the agent at this tool first for any PR or diff review.

The winner by query type

┌────────────────────────────────┬────────────────────────────────┬──────────────────────────────┐
│ Query type                     │ Best tool                      │ Est. tokens                  │
├────────────────────────────────┼────────────────────────────────┼──────────────────────────────┤
│ Find function/class X          │ semantic_search_nodes_tool     │ ~100                         │
│ Who calls X?                   │ query_graph_tool(callers_of)   │ ~80                          │
│ What imports file X?           │ query_graph_tool(importers)    │ ~125 (41 results)            │
│ Concept graph traversal        │ traverse_graph_tool(query=X)   │ ~1000 (measured avg, depth=3) │
│ Pre-refactor impact check      │ get_impact_radius_tool         │ ~70, complete 2-hop          │
│ Code review / PR impact        │ get_review_context_tool        │ ~111 (measured avg), risk + test gaps │
│ Module/behavioral clusters     │ list_communities_tool          │ ~170 (12 communities)        │
│ CRG miss / neighborhood explore│ graphify query '<term>'        │ ~1500 (BFS — use sparingly)  │
│ Exact path A→B hop-by-hop      │ graphify path '<A>' '<B>'      │ ~200                         │
│ String/regex in code body      │ grep (# --graph-tried)         │ varies                       │
│ Config/JSON/log values         │ grep — graph can't index these │ varies                       │
└────────────────────────────────┴────────────────────────────────┴──────────────────────────────┘

Real session measurement: complete token accounting

The per-query numbers above cover tool result sizes. A complete picture must also include the hidden context costs each approach carries: MCP schema overhead, required setup reads, and cache dynamics. These numbers were measured from a live multi-hour coding session on the same 1336-node monorepo (578 total API calls).

Hidden context overhead per approach:

Approach	Schema/setup overhead	Per-call result	How it's paid
grep	0 tokens (none)	~550 tok/call	per call, direct
graphify CLI	0 tokens (it's a Bash call)	~292 tok/call	per call, direct
+ GRAPH_REPORT.md	+458 tok (partial read, measured)	one-time	Read into context once
CRG MCP tools	~6,000 tok always (~25 tool schemas, default) — drops to ~1,800 tok with `CRG_TOOLS` allow-list (8 tools)	~69–1,359/call	written to cache on cold start, then served from cache at 10× lower cost

Honest full-session accounting (37 graph tool calls):

What	With CRG	With grep+Read
Schema/setup overhead	~6,000 tok (cached)	0
Tool result tokens	14,167 tok (measured)	110,335 tok (estimated)
Total	~20,167 tok	~110,335 tok
Net saving	~90,168 tokens — 5.5× cheaper after schema overhead	—

CRG schema tokens are written to the prompt cache on the first API call of a session (cold start: 59,310 tokens including system prompt + all tool schemas). After that they're served from cache_read at $0.30/MTok — one-tenth the cost of new input ($3.00/MTok). The get_architecture_overview_tool block saved 33,000 tokens from a single denied call; that alone exceeds the CRG schema overhead.

Cache economics for the full session:

Metric	Value
Cold-start cache_write (call 1)	59,310 tokens — full context incl. all schemas
Total cache_write across session	3,056,502 tokens
Cold-start share of writes	1.9%
Total cache_read	50,942,267 tokens
New input tokens	7,694 tokens
Est. session cost (Sonnet 4.x)	~$36 (cache_write $11.46 + cache_read $15.28 + output $9.49)

Estimated cost without CRG (same session, grep+Read instead): the additional 90K tool result tokens would each need to be cache-written then read — adding roughly $0.34 in cache_write + $2.70 in cache_read per 100K tokens. More importantly, a larger context window means cache blocks expire and must be re-created more often, compounding costs across 578 calls.

Three-way comparison including all hidden costs (37 lookup calls, measured session):

                      grep          graphify CLI      CRG MCP
─────────────────────────────────────────────────────────────
Schema overhead       0 tok         0 tok             ~6,000 tok
                      (none)        (Bash call,       (~25 tool schemas,
                                     no MCP schema)    always in context)
Setup read            0 tok         +458 tok          0 tok
                                    (GRAPH_REPORT.md,
                                     one partial read,
                                     measured)
Per-call result       ~550 tok      ~292 tok          ~69–1,359 tok
Follow-up Read?       +~1,842 tok   not needed        not needed
                      (usually yes)

37 calls — total cost:
  Tool results        ~20,350 tok   ~10,804 tok       14,167 tok (measured)
  + overhead          0             +458 tok          +6,000 tok
  ─────────────────────────────────────────────────────────────
  TOTAL               ~20,350 tok   ~11,262 tok       ~20,167 tok

vs grep+Read equiv:   110,335 tok   110,335 tok       110,335 tok
Net saving            ~5.4×         ~9.8×             ~5.5×

graphify CLI is the most token-efficient per lookup when full overhead is counted — zero MCP schema tax, no follow-up Read needed, compact output. Its limitation is output size at BFS scale (87–378 nodes, ~1,500 tokens) and needing GRAPH_REPORT.md for orientation. For targeted symbol lookup CRG wins; for schema-free cost-conscious exploration graphify wins.

CRG's 6K schema overhead pays back fast: the blocked get_architecture_overview_tool call alone saved 33,000 tokens — 5× the entire schema overhead — from a single hook denial in this session. After cold-start, schemas cost $0.30/MTok (cache_read) not $3.00/MTok (new input).

Graphify vs CRG split: graphify had 2 actual code lookups; CRG had 36 tool calls. This is the right ratio for targeted feature work on a known codebase — CRG semantic search (100–350 tok) dominated because the work was precise. Graphify BFS (~1,500 tok) is for orientation on unfamiliar ground. Same session on an unknown codebase would flip the ratio.

Strip Unused CRG Tools (Cuts Schema Overhead 70%)

CRG registers 25 MCP tools by default but a typical session uses ~8. Every unused tool still costs always-loaded schema tokens. CRG ships with a built-in allow-list filter — _apply_tool_filter removes tools at server boot via mcp.local_provider.remove_tool(name). Filtered tools cannot be invoked at all, so the explicit PreToolUse block on get_architecture_overview_tool becomes redundant.

Set CRG_TOOLS in ~/.claude.json mcpServers env (or pass serve --tools ...):

"mcpServers": {
  "code-review-graph": {
    "type": "stdio",
    "command": "uvx",
    "args": ["--with", "code-review-graph[embeddings]", "code-review-graph", "serve"],
    "env": {
      "CRG_TOOLS": "semantic_search_nodes_tool,query_graph_tool,get_impact_radius_tool,traverse_graph_tool,list_communities_tool,get_community_tool,get_review_context_tool,list_graph_stats_tool"
    }
  }
}

The 8-tool working set covers 95% of session usage:

Tool	When
`semantic_search_nodes_tool`	"where is X defined" — embedding match, ~100–350 tok
`query_graph_tool`	callers/callees/relations — `pattern=callers_of`, ~80 tok
`get_impact_radius_tool`	pre-refactor blast radius
`traverse_graph_tool`	dependency walk (keep depth ≤ 3)
`list_communities_tool`	architecture overview, ~170 tok for 12 clusters
`get_community_tool`	cluster drill-down
`get_review_context_tool`	code review with risk + test gaps, ~111 tok avg
`list_graph_stats_tool`	sanity check / status

Dropped (17 tools): get_architecture_overview_tool (33k tok output — never useful), refactor_tool / apply_refactor_tool (use git), get_minimal_context_tool, get_docs_section_tool, get_wiki_page_tool, find_large_functions_tool, list_flows_tool / get_flow_tool / get_affected_flows_tool (flow analysis is rare), get_hub_nodes_tool / get_bridge_nodes_tool (covered by communities), get_knowledge_gaps_tool, get_surprising_connections_tool, get_suggested_questions_tool, list_repos_tool / cross_repo_search_tool (single-repo work).

Token math:

Before: ~6,000 tok schema overhead (25 tools, full descriptions + params, always loaded after cold-start)
After: ~1,800 tok (8 tools)
Savings: ~4,200 tok per session, ~70% schema reduction
Bonus: Claude Code's deferred-tool layer further lazy-loads param schemas via ToolSearch — only the description metadata stays always-loaded, so real overhead is even lower

Lazy loading reality check: MCP protocol itself does not support lazy-loading tool schemas — all are listed at startup. Claude Code adds a deferred-tool layer on top: tool descriptions are exposed for matching, but full param schemas only load when ToolSearch resolves a tool by name. So stripping at the CRG layer cuts the always-loaded description set; the Claude Code layer cuts the params. They compound.

By case:

Workflow	Strategy
Targeted symbol lookup on known codebase	`semantic_search_nodes_tool` → fallback to `query_graph_tool` → fallback to `graphify query` → grep
Pre-refactor blast	`get_impact_radius_tool` + `traverse_graph_tool(depth=2)`
Architecture orientation	`list_communities_tool` → `get_community_tool` (NEVER `get_architecture_overview_tool`)
Code review on a PR	`get_review_context_tool(changed_files=[...])` only
Cross-repo work	re-add `cross_repo_search_tool`, `list_repos_tool` to allow-list
Flow / DAG analysis	re-add `list_flows_tool`, `get_flow_tool`, `get_affected_flows_tool`

The concurrent session had zero graph tools: a parallel session on the same codebase used only grep+Read (15 grep calls, 22 reads). Cold start: 60,610 tokens (same MCP schemas loaded — schemas are always present regardless of whether graph tools are used). Tool result tokens were proportionally higher per lookup, with no structured relationship data returned.

Bypassing the smart-grep hook: append # --graph-tried as a shell comment (not a flag) to pass silently: grep -rn "TODO" src/ # --graph-tried. On macOS, ugrep rejects --graph-tried as an unknown flag — always use it as a comment.

Expensive Calls to Avoid

Some graph tool calls look useful but are token-budget traps.

get_architecture_overview_tool — returns 131,000 chars (~33,000 tokens), exceeds any usable context budget. Best fix: strip it via CRG_TOOLS allow-list (see "Strip Unused CRG Tools" above) so it cannot be called at all. If you can't strip it, block via PreToolUse hook. Alternative: list_communities_tool first (~170 tokens for 12 clusters), then get_community_tool for any cluster you want to drill into.

graphify query '<term>' — BFS depth=2 returns 87–378 nodes (~1500 tokens) regardless of specificity. The smart-grep hook intercepts it: if CRG has a matching symbol it blocks with the CRG result inline (~100 tokens); if CRG misses it allows graphify to proceed but warns about cost. This is the right split — CRG for symbol lookup, graphify for neighborhood exploration when you genuinely want to see what's connected.

traverse_graph_tool on hub nodes without budget — takes a query string (not source/target nodes), does concept-based traversal, and at depth=5+ on hub nodes (server.ts, api.ts) returns thousands of nodes. Keep depth ≤ 3 and token_budget ≤ 1500. For a specific A→B path, use graphify path '<A>' '<B>' instead — it returns the shortest hop chain in ~200 tokens. For "who calls X", use query_graph_tool(pattern=callers_of, target=X) (~80 tokens).

Tool stripping > hook blocking. The cleanest enforcement is the CRG_TOOLS allow-list shown earlier — stripped tools are removed from the MCP server entirely, so they cannot be invoked and their schemas never enter context. The PreToolUse hook block is only useful if you cannot edit the MCP server env (e.g., shared config).

The graphify query interception lives inside smart-grep-hook.sh and requires no extra config — it fires via the existing Bash PreToolUse hook.

Making This Work for Any Project

The hooks in settings.example.json are designed to be portable — they silently no-op when the relevant tool or graph data isn't present. This means you can copy them to settings.local.json per-project, or into ~/.claude/settings.json to activate across all projects.

What the hooks do (each row is a no-op when the relevant tool/file is missing):

Hook	What fires	When	Resource-safe?
Stop	CRG `update + embed` (background, PID-guarded — silent if not installed/initialized)	Once after AI finishes each turn (all edits batched)	PID file prevents overlap
PreToolUse	`smart-grep-hook.sh` (graph-first routing — adaptive: CRG only, graphify only, both, or silent fallback)	Before every grep/find/graphify query	Read-only, no resource concern
PreToolUse	Linter config guard	Before writing ESLint/Prettier/Biome	N/A
SessionStart	Graph cheatsheet (adaptive: shows CRG tools, graphify CLI, both, or nothing)	Session open, only if graph exists	Read-only
SessionStart	Setup nudge (only when CLI installed but graph not initialized)	Session open	Read-only

What the git hooks do (resource-guarded, all platforms):

Hook	What fires	When	Guards
post-commit	graphify rebuild + CRG update + embed (both background nohup)	Every commit	`_resources_ok` + `pgrep` + `timeout 300`
post-checkout	graphify rebuild + CRG update/build (smart: ≤5 files incremental, >5 full)	Branch switch only	`_resources_ok` + `pgrep` + `timeout 300`
pre-commit	Branch protection (blocks direct commits to master/development/release branches)	Every commit attempt	—

graphify is not in the Stop hook. Running graphify update after every AI turn causes long-running background processes that accumulate, spike CPU, and exhaust swap. graphify update fires only via git hooks (post-commit, post-checkout) where it runs detached after the developer's action — invisible latency.

Why no get_architecture_overview_tool block hook? The recommended setup uses the CRG_TOOLS allow-list to strip that tool entirely (see "Strip Unused CRG Tools"). A stripped tool cannot be invoked, so the explicit block hook becomes redundant. If you cannot or do not want to strip, add the PreToolUse block as a fallback.

Project .claude/settings.json is only for project-specific permissions — which package-manager commands to allow, which config files to protect. Graph hooks go in settings.example.json (committed reference) and settings.local.json (live copy) — or your global ~/.claude/settings.json if you want them everywhere.

One-time setup per project — pick what you have installed:

# CRG only (embedding-aware, MCP integration)
code-review-graph install
code-review-graph embed

# Graphify only (pure CLI, zero MCP overhead)
graphify init .
graphify update .

# Both — run all four; the smart-grep-hook routes CRG-first, graphify on miss

# Git hooks — graphify ONLY updates via git hooks (too slow for Claude hooks)
code-review-graph hook install   # post-commit: CRG update + embed (also runs in Stop hook)
graphify hook install            # post-commit + post-checkout: graphify update (background nohup)

After setup: every time the AI finishes a turn, the Stop hook fires once — CRG only updates in background (PID-guarded, ~0.425s, no pile-up). Every commit triggers both git hooks. graphify never runs from a Claude hook — only from git hooks. If only one tool is installed, only that one updates. If neither is installed, hooks are silent no-ops.

Step 4: Verify Your Setup

Run the checks for whichever tools you installed. Skip the rows for tools you did not install — there is no requirement to have both.

Check CLI installation

# Either or both:
graphify --help | head -3            # graphify only
code-review-graph --version          # CRG only
# code-review-graph 2.3.2

Check graph outputs exist

# Graphify (skip if not installed):
ls graphify-out/
# cache  graph.html  graph.json  GRAPH_REPORT.md  manifest.json

# CRG (skip if not installed):
code-review-graph status
# Nodes: 5780  Edges: 30611  Files: 1052
# Languages: bash, javascript, vue, typescript
# Last updated: 2026-05-05T18:29:51

Check GRAPH_REPORT.md freshness

head -15 graphify-out/GRAPH_REPORT.md
# ## Corpus Check
# - 1020 files · ~1,587,186 words
# - Verdict: corpus is large enough that graph structure adds value.
#
# ## Summary
# - 3815 nodes · 4830 edges · 750 communities (533 shown, 217 thin omitted)
# - Extraction: 87% EXTRACTED · 13% INFERRED · 0% AMBIGUOUS
#
# ## Graph Freshness
# - Built from commit: `4968d67a`
# - Run `git rev-parse HEAD` and compare to check if the graph is stale.

Check Stop hook is in settings.json (or settings.local.json)

python3 -m json.tool .claude/settings.json | grep -A5 '"Stop"'
# Should show the CRG PID-guard command
# PostToolUse should be empty ([]) — graph updates moved to Stop hook

# Verify PostToolUse is cleared (no graph update commands there):
python3 -m json.tool .claude/settings.local.json | grep -A3 '"PostToolUse"'
# Should show: "PostToolUse": []

Check MCP server config

cat .mcp.example.json
# Should show: code-review-graph serve entry
# Copy to .mcp.json locally if it doesn't exist yet:
cp .mcp.example.json .mcp.json

Check git hooks

# Husky projects (hooks live in .husky/, not .husky/_/)
grep -c "graphify" .husky/post-commit
# 1 (or more)

# Plain git projects
head -5 .git/hooks/pre-commit

Test incremental update speed

time code-review-graph update --skip-flows
# real  0m0.425s  ← CRG incremental speed (runs in Stop hook after each AI turn)

time graphify update .
# SHA256 cache skips unchanged files — subsequent runs are near-instant
# Note: graphify is slower (~10s on large repos) — this is why it moved to Stop
# hook (once per turn) rather than PostToolUse (once per file edit)

Test vault sync (if vault is configured)

cp graphify-out/GRAPH_REPORT.md ai-vault/graphify/GRAPH_REPORT.md
ls ai-vault/graphify/
# GRAPH_REPORT.md

Step 5: Query the Graphs

Graphify CLI

# BFS traversal — find connections between concepts
graphify query "what connects payment to enrollment" \
  --graph graphify-out/graph.json --budget 1500

# Depth-first traversal for flow tracing
graphify query "auth flow" --dfs --graph graphify-out/graph.json

# Shortest path between two nodes
graphify path "UserDashboard.vue" "PaymentService" \
  --graph graphify-out/graph.json

# Plain-language explanation of a node
graphify explain "UserDashboard.vue" --graph graphify-out/graph.json

Example output from graphify explain:

Node: UserDashboard.vue
  Source:    packages/client/src/views/Dashboard
  Community: 239
  Degree:    3

Connections (3):
  --> UserDashboard()  [imports_from] [EXTRACTED]
  --> handleApiError() [contains]     [EXTRACTED]
  --> AuthService      [calls]        [INFERRED]

Inside Your AI Agent

After graphify install and code-review-graph install, your AI agent gets graph tools automatically. For Claude Code, a SessionStart hook shows the graph status on every session open. Cursor, Gemini CLI, and Windsurf pick up the MCP server from .mcp.json instead.

# code-review-graph status on session open:
Nodes: 5780  Edges: 30611  Files: 1052
Languages: bash, javascript, vue, typescript
Last updated: 2026-05-05T18:29:51

Step 6: Auto-Update Strategies

The graph is only valuable if it reflects current code. Here are the four strategies, from manual to fully automatic.

Strategy A: Manual Update (Always Available)

# Incremental (only changed files — fast)
code-review-graph update        # 0.425s on ~1000-file project
graphify update .               # SHA256 cache, AST-only

# Full rebuild (when switching branches or major refactors)
code-review-graph build
graphify update . --force

Strategy B: Auto-Update via Git Hooks (Recommended for graphify)

graphify update belongs in git hooks, not in Claude Code hooks. The incremental rebuild takes ~10s+ on a real monorepo — too slow for a per-turn trigger. Git hooks fire at the right moment: after a commit or branch switch, when the developer has already moved on.

graphify hook install   # installs post-commit + post-checkout

The post-commit hook runs the rebuild in the background (detached nohup process) so git commit returns immediately. Rebuild logs go to ~/.cache/graphify-rebuild.log. The post-checkout hook fires on every git checkout <branch> and rebuilds for the new branch state.

This is the only recommended automatic trigger for graphify update — do not add it to Stop, PostToolUse, or SessionStart hooks.

The hooks installed by graphify hook install — both run as detached nohup so the git operation returns immediately. Add the _resources_ok function (shown in the post-commit hook above) to the top of each hook file to prevent resource exhaustion.

.git/hooks/post-commit — see the full resource-guarded version in the "Auto-Update on Commit" section above.

.git/hooks/post-checkout (or .husky/post-checkout for Husky projects):

#!/bin/sh
# Knowledge graph tools are optional — each section silently skips if tools are absent.

# _resources_ok function — copy from the post-commit hook above
# (CPU ≤ 50% of logical cores, memory ≥ 2 GB free — same implementation)

PREV_HEAD=$1
NEW_HEAD=$2
BRANCH_SWITCH=$3

# Only run on branch switches, not file checkouts
[ "$BRANCH_SWITCH" != "1" ] && exit 0

# Skip during rebase/merge/cherry-pick
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
[ -d "$GIT_DIR/rebase-merge" ] && exit 0
[ -d "$GIT_DIR/rebase-apply" ] && exit 0
[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0

# Smart rebuild threshold — shared by graphify and CRG sections below
_ZERO="0000000000000000000000000000000000000000"
_CHANGED_COUNT=$(git diff --name-only "$PREV_HEAD" "$NEW_HEAD" 2>/dev/null | wc -l | tr -d ' ')
_FULL_REBUILD=false
{ [ "$PREV_HEAD" = "$_ZERO" ] || [ "${_CHANGED_COUNT:-0}" -gt 5 ]; } && _FULL_REBUILD=true

# ── graphify: force-rebuild graph after branch switch ────────────────────────
# Entire block skips if graphify is not installed or graph has never been built.
if command -v graphify > /dev/null 2>&1 && [ -d "graphify-out" ]; then
  # (Python interpreter detection — same as post-commit hook)
  GRAPHIFY_BIN=$(command -v graphify)
  # ... shebang detection omitted for brevity — copy from post-commit hook ...
  GRAPHIFY_PYTHON="python3"  # fallback

  if [ -n "$GRAPHIFY_PYTHON" ] && ! pgrep -qf 'graphify' 2>/dev/null && _resources_ok; then
    _LOG="${HOME}/.cache/graphify-rebuild.log"
    mkdir -p "$(dirname "$_LOG")"
    [ "$_FULL_REBUILD" = "true" ] && export GRAPHIFY_FORCE=true
    echo "[graphify] Branch switched (${_CHANGED_COUNT:-?} files diff, full=$_FULL_REBUILD) - launching background rebuild (log: $_LOG)"
    nohup timeout 300 $GRAPHIFY_PYTHON -c "
from graphify.watch import _rebuild_code
from pathlib import Path
import os, sys
try:
    _force = os.environ.get('GRAPHIFY_FORCE', '').lower() in ('1', 'true', 'yes')
    _rebuild_code(Path('.'), force=_force)
except Exception as exc:
    print(f'[graphify] Rebuild failed: {exc}')
    sys.exit(1)
" > "$_LOG" 2>&1 < /dev/null &
    disown 2>/dev/null || true
  fi
fi

# ── code-review-graph: update MCP graph index after branch switch ────────────
if command -v code-review-graph > /dev/null 2>&1 && [ -d .code-review-graph ] && ! pgrep -qf 'code-review-graph update\|code-review-graph build' 2>/dev/null && _resources_ok; then
  _LOG="${HOME}/.cache/code-review-graph-update.log"
  mkdir -p "$(dirname "$_LOG")"
  if [ "$_FULL_REBUILD" = "true" ]; then
    echo "[code-review-graph] Branch switched (full rebuild: ${_CHANGED_COUNT:-?} files diff) - launching background build (log: $_LOG)"
    nohup sh -c 'code-review-graph build' > "$_LOG" 2>&1 < /dev/null &
  else
    echo "[code-review-graph] Branch switched (incremental: ${_CHANGED_COUNT:-?} files diff) - launching background update (log: $_LOG)"
    nohup sh -c 'code-review-graph update --skip-flows && code-review-graph embed' > "$_LOG" 2>&1 < /dev/null &
  fi
  disown 2>/dev/null || true
fi

Key differences from post-commit:

Only runs on actual branch switches (BRANCH_SWITCH=1 check)
Smart rebuild: ≤5 files diff → incremental update; >5 files or new branch → full rebuild
CRG uses build (full SQLite rebuild) for large diffs, update --skip-flows for small ones
graphify sets GRAPHIFY_FORCE=true for large diffs to force full AST reparse

Strategy C: Git Hooks (On Commit + Branch Switch)

Both tools install git hooks automatically:

# code-review-graph: pre-commit hook in .git/hooks/pre-commit
code-review-graph install

# graphify: installs hooks in .git/hooks/ — for Husky projects, copy the hook logic to .husky/post-commit
graphify hook install

The graphify post-commit hook runs the rebuild in the background (detached process) so git commit returns immediately. Rebuild logs go to ~/.cache/graphify-rebuild.log.

Strategy D: Claude Code Hooks (AI-Driven Updates)

Only CRG belongs in Claude hooks. graphify does not.

Tool	Claude hook?	Why
code-review-graph	✅ Stop hook	~0.425s incremental — safe after every AI turn
graphify	❌ No Claude hook	~10s+ on large monorepos — causes hanging background processes, CPU spike, swap exhaustion

When an AI agent edits files, the Stop hook triggers a CRG incremental update. code-review-graph install writes hooks into .claude/settings.json initially — move them out. The right home is .claude/settings.example.json (committed reference for teammates) and .claude/settings.local.json (your live runtime copy, gitignored).

Use the fallback-safe version that silently no-ops if the CLI isn't installed:

At 0.425s per update, CRG runs after every AI turn without blocking the agent's workflow.

The settings.example.json hooks (copy to settings.local.json for this project, or to ~/.claude/settings.json for all projects):

{
  "hooks": {
    "PostToolUse": [],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "command -v code-review-graph >/dev/null 2>&1 && [ -d .code-review-graph ] && { PF=/tmp/crg-claude.pid; if [ -f \"$PF\" ] && kill -0 \"$(cat \"$PF\")\" 2>/dev/null; then true; else { code-review-graph update --skip-flows 2>/dev/null && nohup code-review-graph embed >/dev/null 2>&1 & } & echo $! > \"$PF\"; fi; } || true",
          "timeout": 5
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "bash ~/.claude/scripts/smart-grep-hook.sh",
          "timeout": 6
        }]
      }
    ],
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "command -v code-review-graph >/dev/null 2>&1 && code-review-graph status 2>/dev/null || true",
          "timeout": 10
        }]
      },
      {
        "hooks": [{
          "type": "command",
          "command": "if command -v code-review-graph >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1 && [ ! -d .code-review-graph ]; then printf '{\"systemMessage\":\"Graph tool installed but not yet initialized. Ask me to set up: code-review-graph (code-review-graph install)\"}'; fi || true",
          "timeout": 10
        }]
      },
      {
        "hooks": [{
          "type": "command",
          "command": "if [ -f .code-review-graph/graph.db ] || [ -f graphify-out/graph.json ]; then STATS=\"\"; TOOL_LINES=\"\"; if [ -f .code-review-graph/graph.db ]; then STATS=$(python3 -c \"import sqlite3; c=sqlite3.connect('.code-review-graph/graph.db'); n=c.execute('SELECT COUNT(*) FROM nodes').fetchone()[0]; e=c.execute('SELECT COUNT(*) FROM edges').fetchone()[0]; print(f'{n} nodes, {e} edges'); c.close()\" 2>/dev/null || echo \"\"); TOOL_LINES=\"  where is X defined    → semantic_search_nodes_tool(query=X)\\n  who calls X           → query_graph_tool(pattern=callers_of, target=X)\\n  pre-refactor blast    → get_impact_radius_tool(changed_files=[...])\\n  community/cluster     → list_communities_tool()\\n  code review context   → get_review_context_tool(changed_files=[...])\"; fi; if [ -f graphify-out/graph.json ]; then GFY_STATS=$(python3 -c \"import json; g=json.load(open('graphify-out/graph.json')); nodes=g.get('nodes',[]); comms=len(set(n.get('community','') for n in nodes if n.get('community',''))); print(f'{len(nodes)} nodes, {comms} communities')\" 2>/dev/null || echo \"\"); [ -n \"$GFY_STATS\" ] && STATS=\"${STATS:+$STATS | }graphify: $GFY_STATS\"; TOOL_LINES=\"${TOOL_LINES:+$TOOL_LINES\\n}  CRG miss / explore    → graphify query '<term>' --graph graphify-out/graph.json\\n  path A→B              → graphify path '<from>' '<to>' --graph graphify-out/graph.json\"; fi; printf '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"GRAPH QUERY CHEATSHEET (%s) — use BEFORE Read/Grep/Bash-find on code:\\n%s\\nSkip graph for: .md .json .yml .log .jsonl configs cross-repo paths.\\nOverride grep gate: append --graph-tried to any Bash command.\"}}' \"$STATS\" \"$TOOL_LINES\"; fi",
          "timeout": 5
        }]
      }
    ]
  }
}

Why Stop, not PostToolUse? PostToolUse fires after every individual file edit — if Claude makes 10 edits in one response, it fires 10 times. The PID-file guard has a race window, so concurrent CRG Python processes pile up. Stop fires once when the AI finishes its entire turn — all edits batched, single update, PID-guarded. Zero pile-up by design.

Why PostToolUse: []? Explicitly empty. Previous setups used PostToolUse for CRG updates. Clearing it prevents stale hook configs from double-triggering with the Stop hook.

Step 7: Generate Additional Outputs

Resource exhaustion prevention — all git hooks above include a _resources_ok() guard that checks CPU load (≤ 50% of logical cores) and available memory (≥ 2 GB) before spawning any background rebuild. If either threshold is exceeded, the rebuild silently skips and logs why. This prevents a real problem: rapid-fire commits (amend chains, interactive rebase) spawning multiple concurrent graphify/CRG processes — observed at 3 stuck processes at 65–73% CPU each, load average 12+, RAM saturated, machine unresponsive. The pgrep guard adds process-level deduplication (if a previous rebuild is still running, skip). The timeout 300 ensures no background process lives longer than 5 minutes. Together these three guards ensure graph rebuilds are always non-blocking and device-safe.

Wiki (Markdown pages per community)

code-review-graph wiki
# Wiki: 28 new pages → .code-review-graph/wiki/

graphify tree --graph graphify-out/graph.json
# D3 collapsible-tree HTML

Interactive Visualization

code-review-graph visualize
# → .code-review-graph/graph.html

# graphify-out/graph.html is generated automatically during build

Blast-Radius Analysis

# What does this commit affect?
code-review-graph detect-changes --base HEAD~1 --brief

# Risk-scored output:
# Analyzed 3 changed file(s)
# - 2 changed function(s)/class(es)
# - 1 affected flow(s)
# - Overall risk score: 0.42

Step 8: Obsidian Vault (Visual Graph + Persistent Memory)

The Obsidian layer adds a human-readable, visual knowledge graph on top of your codebase. You've probably seen screenshots shared in the Claude Code / graphify community — a force-directed graph of hundreds of connected nodes. That's Obsidian's Graph View rendering one .md file per symbol, linked by imports.

Install Obsidian:

# Ubuntu
snap install obsidian

# macOS
brew install --cask obsidian

Three Vault Modes

Mode	Where	Best for
Browser only	`graphify-out/graph.html`	One-off exploration, no Obsidian needed
Project vault	`<project>/ai-vault/`	Single project, clean wikilinks
Global vault	`~/obsidian-vault/`	Multiple projects + cross-repo merged view

Mode 1: Browser Only (Zero Setup)

The graph.html file graphify generates is a self-contained interactive D3 force graph — drag nodes, zoom, click to inspect. No Obsidian required.

xdg-open graphify-out/graph.html   # Linux
open graphify-out/graph.html        # macOS

Mode 2: Project Vault

The project vault lives at ./ai-vault/ inside the project (gitignored). It has two layers:

Layer 1 — Basic (GRAPH_REPORT.md only):

mkdir -p ai-vault/{graphify,permanent,logs,chats}
cp graphify-out/GRAPH_REPORT.md ai-vault/graphify/

This gives you the community report with wikilinks — useful for navigating clusters.

Layer 2 — Rich vault (one .md per symbol):

The GRAPH_REPORT.md uses wikilinks like [[_COMMUNITY_Community 0]], but those target files don't exist yet. To make Obsidian's Graph View actually light up with a full network, generate individual note files for every node and community:

Save this script to ~/.graphify/gen-obsidian-vault.py:

#!/usr/bin/env python3
"""
gen-obsidian-vault.py — Generate Obsidian notes from graphify graph.json.

Usage:
  # Project vault
  python3 ~/.graphify/gen-obsidian-vault.py --project-root /path/to/project

  # Global vault (multiple projects)
  python3 ~/.graphify/gen-obsidian-vault.py \
    --project-root /path/to/project \
    --vault ~/obsidian-vault \
    --project-name my-project

  # Merged cross-repo graph
  python3 ~/.graphify/gen-obsidian-vault.py \
    --merged-graph ~/obsidian-vault/merged-graph.json \
    --vault ~/obsidian-vault \
    --project-name merged
"""

import argparse, json, os, re, sys
from collections import defaultdict
from pathlib import Path

MAX_LINKS = 30

def _build_adjacency(nodes, links):
    out, inc = defaultdict(list), defaultdict(list)
    for link in links:
        src, tgt, rel = link["source"], link["target"], link["relation"]
        if src in nodes and tgt in nodes:
            out[src].append((tgt, rel))
            inc[tgt].append((src, rel))
    return out, inc

def _node_files(nodes, out, inc, nodes_dir, node_pfx, comm_pfx):
    nodes_dir.mkdir(parents=True, exist_ok=True)
    for nid, node in nodes.items():
        lines = [f"# {node['label']}", ""]
        if node.get("source_file"): lines.append(f"**File:** `{node['source_file']}`  ")
        if node.get("source_location"): lines.append(f"**Location:** {node['source_location']}  ")
        if node.get("file_type"): lines.append(f"**Type:** {node['file_type']}  ")
        lines.append(f"**Community:** [[{comm_pfx}/Community {node.get('community','?')}|Community {node.get('community','?')}]]")
        lines.append("")
        if out[nid]:
            lines.append("## Imports / Depends On")
            for tgt_id, rel in out[nid][:MAX_LINKS]:
                if nodes.get(tgt_id): lines.append(f"- [[{node_pfx}/{tgt_id}|{nodes[tgt_id]['label']}]] `{rel}`")
            lines.append("")
        if inc[nid]:
            lines.append("## Used By")
            for src_id, rel in inc[nid][:MAX_LINKS]:
                if nodes.get(src_id): lines.append(f"- [[{node_pfx}/{src_id}|{nodes[src_id]['label']}]] `{rel}`")
            lines.append("")
        (nodes_dir / f"{nid}.md").write_text("\n".join(lines))

def _community_files(nodes, out, inc, comm_dir, node_pfx, comm_pfx):
    comm_dir.mkdir(parents=True, exist_ok=True)
    groups = defaultdict(list)
    for nid, node in nodes.items(): groups[node.get("community", "?")].append(nid)
    for cid, mids in sorted(groups.items()):
        lines = [f"# Community {cid}", "", f"**Members:** {len(mids)}", "", "## Members"]
        for mid in mids:
            if nodes.get(mid): lines.append(f"- [[{node_pfx}/{mid}|{nodes[mid]['label']}]]")
        cross = {nodes[t].get("community") for m in mids for t, _ in out[m] if nodes.get(t) and nodes[t].get("community") != cid}
        cross |= {nodes[s].get("community") for m in mids for s, _ in inc[m] if nodes.get(s) and nodes[s].get("community") != cid}
        if cross:
            lines += ["", "## Connected Communities"] + [f"- [[{comm_pfx}/Community {c}|Community {c}]]" for c in sorted(cross) if c]
        lines.append("")
        (comm_dir / f"Community {cid}.md").write_text("\n".join(lines))
    return len(groups)

def generate(project_root=None, vault_root=None, project_name=None, graph_json_path=None):
    graph_json = Path(graph_json_path) if graph_json_path else Path(project_root) / "graphify-out" / "graph.json"
    if not graph_json.exists():
        print(f"ERROR: {graph_json} not found. Run 'graphify update .' first."); sys.exit(1)
    g = json.loads(graph_json.read_text())
    nodes = {n["id"]: n for n in g["nodes"]}
    links = g.get("links", [])
    out, inc = _build_adjacency(nodes, links)
    vault = Path(vault_root).expanduser() if vault_root else Path(project_root) / "ai-vault"
    base = vault / project_name if project_name else vault
    pfx = f"{project_name}/" if project_name else ""
    _node_files(nodes, out, inc, base / "nodes", f"{pfx}nodes", f"{pfx}communities")
    n_comm = _community_files(nodes, out, inc, base / "communities", f"{pfx}nodes", f"{pfx}communities")
    if project_root:
        report = Path(project_root) / "graphify-out" / "GRAPH_REPORT.md"
        if report.exists():
            gdir = base / "graphify"; gdir.mkdir(parents=True, exist_ok=True)
            content = re.sub(r"\[\[_COMMUNITY_Community (\d+)\|Community \1\]\]",
                lambda m: f"[[{pfx}communities/Community {m.group(1)}|Community {m.group(1)}]]",
                report.read_text())
            (gdir / "GRAPH_REPORT.md").write_text(content)
    print(f"  ✓ {len(nodes)} nodes · {len(links)} links · {n_comm} communities → {base}")

def main():
    p = argparse.ArgumentParser()
    p.add_argument("--project-root"); p.add_argument("--vault"); p.add_argument("--project-name")
    p.add_argument("--merged-graph")
    a = p.parse_args()
    generate(a.project_root, a.vault, a.project_name, a.merged_graph)

if __name__ == "__main__": main()

Run it:

mkdir -p ~/.graphify
# save the script above to ~/.graphify/gen-obsidian-vault.py, then:

python3 ~/.graphify/gen-obsidian-vault.py --project-root .
# ✓ 3815 nodes · 4830 links · 749 communities → ./ai-vault

This generates ai-vault/nodes/ (one .md per symbol) and ai-vault/communities/ (one .md per cluster). Each file contains wikilinks to its neighbors — Obsidian's Graph View draws the edges automatically.

ai-vault/
├── .obsidian/               ← Obsidian config (auto-created)
├── nodes/                   ← one .md per function / class / file  ← NEW
├── communities/             ← one .md per module cluster           ← NEW
├── graphify/
│   └── GRAPH_REPORT.md      ← synced from graphify-out/
├── permanent/               ← Architecture decisions (human notes)
├── logs/                    ← Session records
└── CLAUDE.md                ← vault-level agent instructions

Open in Obsidian → press Ctrl+G → you get the full network.

Mode 3: Global Vault (Multiple Projects)

One Obsidian window, all projects. Each project goes into its own subfolder with namespaced wikilinks — necessary because two projects often share node IDs (shared packages like dto, types, utilities).

# Add each project to the global vault
python3 ~/.graphify/gen-obsidian-vault.py \
  --project-root /path/to/project-a \
  --vault ~/obsidian-vault \
  --project-name project-a

python3 ~/.graphify/gen-obsidian-vault.py \
  --project-root /path/to/project-b \
  --vault ~/obsidian-vault \
  --project-name project-b

~/obsidian-vault/
├── 00-Welcome.md           ← optional index note
├── project-a/
│   ├── nodes/
│   ├── communities/
│   └── graphify/GRAPH_REPORT.md
├── project-b/
│   ├── nodes/
│   ├── communities/
│   └── graphify/GRAPH_REPORT.md
└── merged/                 ← optional cross-repo combined view

Filter by project in Graph View: Graph View sidebar → Filters → path:project-a/nodes

Cross-Repo Merged View

When projects share types or utilities, merging their graphs reveals bridge nodes — code that affects both sides.

graphify merge-graphs \
  /path/to/project-a/graphify-out/graph.json \
  /path/to/project-b/graphify-out/graph.json \
  --out ~/obsidian-vault/merged-graph.json

python3 ~/.graphify/gen-obsidian-vault.py \
  --merged-graph ~/obsidian-vault/merged-graph.json \
  --vault ~/obsidian-vault \
  --project-name merged

Nodes in merged/communities/ that link to both projects are your highest-impact change points — changing them ripples across repos.

Switching Between Vaults

This is a common pain point: clicking X quits Obsidian entirely and the next launch reopens the same vault.

Switch inside Obsidian (always works):
Click the vault icon at the very bottom-left of the sidebar (looks like a small building/safe). A panel lists all known vaults — click to switch.

Open two vaults simultaneously (Obsidian v1.x+):
Open the vault switcher → hold Ctrl while clicking a vault → opens in a new window. Both are live at once.

From the terminal — Linux snap install:

The obsidian:// URI scheme and xdg-open do not work with snap-installed Obsidian because snap doesn't register the protocol with the system. Use a small helper script instead.

Save ~/.graphify/obs.py:

#!/usr/bin/env python3
"""Open a specific Obsidian vault from the terminal (snap-compatible)."""

import hashlib, json, subprocess, sys, time
from pathlib import Path

OBSIDIAN_CONFIG = Path("~/snap/obsidian/current/.config/obsidian/obsidian.json").expanduser()

def _load():
    return json.loads(OBSIDIAN_CONFIG.read_text()) if OBSIDIAN_CONFIG.exists() else {"vaults": {}}

def _save(c):
    OBSIDIAN_CONFIG.parent.mkdir(parents=True, exist_ok=True)
    OBSIDIAN_CONFIG.write_text(json.dumps(c, indent=2))

def open_vault(vault_path):
    path = str(Path(vault_path).expanduser().resolve())
    config = _load()
    vaults = config.setdefault("vaults", {})
    vid = next((k for k, v in vaults.items() if v.get("path") == path), None)
    if vid is None:
        vid = hashlib.md5(path.encode()).hexdigest()[:16]
        vaults[vid] = {"path": path, "ts": int(time.time() * 1000)}
        print(f"Registered: {path}")
    for k in vaults: vaults[k].pop("open", None)
    vaults[vid]["open"] = True
    _save(config)
    print(f"Opening: {path}")
    subprocess.Popen(["/snap/bin/obsidian"], start_new_session=True,
                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)

if __name__ == "__main__":
    if len(sys.argv) < 2: print("Usage: obs.py <vault-path>"); sys.exit(1)
    open_vault(sys.argv[1])

This registers the vault in Obsidian's JSON config and launches Obsidian pointing to it.

Shell aliases (add to ~/.zshrc on macOS, ~/.bashrc on Linux):

alias obs='python3 ~/.graphify/obs.py ~/obsidian-vault'
alias obs-project='python3 ~/.graphify/obs.py /path/to/your-project/ai-vault'

Then: source ~/.zshrc (or source ~/.bashrc on Linux) and use obs / obs-project from any terminal.

macOS (non-snap):

open "obsidian://open?vault=obsidian-vault"
# or
alias obs='open "obsidian://open?vault=obsidian-vault"'

Practical tip — avoid switching entirely:
Keep the global vault as your default. Inside Graph View, use the path filter to scope to one project:

Graph View sidebar → Filters → path:my-project/nodes

This shows only that project's symbols without switching vaults.

Graph View Filters

Filter	Shows
`path:nodes`	All code symbols
`path:my-project/nodes`	One project's symbols (global vault)
`path:communities`	Module clusters only
`path:permanent`	Architecture decisions (human notes)
`path:logs`	Session records
`-path:nodes`	Human notes only, no code graph

`ai-vault/CLAUDE.md` (vault-level agent instructions — Claude Code example; use `AGENTS.md` or `GEMINI.md` for other agents)

## Session Commands
- `/resume` — Read the latest log in `logs/` to restore context
- `/save` — Write a timestamped session summary to `logs/YYYY-MM-DD-HH-MM.md`

## Navigation
- `graphify/GRAPH_REPORT.md` — Codebase graph report
- `permanent/` — Architecture decisions and atomic notes
- `logs/` — Session records

## Graph Usage
Before answering architecture questions, read `graphify/GRAPH_REPORT.md`.
Use `graphify query`, `graphify path`, and `graphify explain` from the project root.

Keeping the Vault Fresh

Git hooks keep graph.json current automatically. Refresh the Obsidian notes after significant changes:

# Project vault
python3 ~/.graphify/gen-obsidian-vault.py --project-root .

# Global vault entry
python3 ~/.graphify/gen-obsidian-vault.py \
  --project-root /path/to/project \
  --vault ~/obsidian-vault \
  --project-name my-project

# Rebuild merged view
graphify merge-graphs \
  /path/to/a/graphify-out/graph.json \
  /path/to/b/graphify-out/graph.json \
  --out ~/obsidian-vault/merged-graph.json && \
python3 ~/.graphify/gen-obsidian-vault.py \
  --merged-graph ~/obsidian-vault/merged-graph.json \
  --vault ~/obsidian-vault \
  --project-name merged

Add vault regen to git hooks

Husky projects: create .husky/post-commit (git-tracked; note .husky/_/ is gitignored and dead code — the h wrapper always exits before any appended code there runs).

Plain git projects: use .git/hooks/post-commit instead.

The hook is structured in two independent sections so teammates without these tools see zero overhead — each section guards itself and silently no-ops if the tool isn't present:

#!/bin/sh
# Knowledge graph tools are optional — each section silently skips if tools are absent.

# _resources_ok function — copy from the post-commit hook above
# (CPU ≤ 50% of logical cores, memory ≥ 2 GB free, all platforms)

GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
[ -d "$GIT_DIR/rebase-merge" ] && exit 0
[ -d "$GIT_DIR/rebase-apply" ] && exit 0
[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0

# ── graphify: rebuild graph after commit ─────────────────────────────────────
# Entire block skips if graphify is not installed.
if command -v graphify > /dev/null 2>&1; then
  CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null)
  if [ -n "$CHANGED" ]; then
    # (Python interpreter detection omitted for brevity — see full hook above)
    if [ -n "$GRAPHIFY_PYTHON" ] && ! pgrep -qf 'graphify' 2>/dev/null && _resources_ok; then
      export GRAPHIFY_CHANGED="$CHANGED"
      _LOG="${HOME}/.cache/graphify-rebuild.log"
      mkdir -p "$(dirname "$_LOG")"
      echo "[graphify hook] launching background rebuild (log: $_LOG)"
      nohup timeout 300 $GRAPHIFY_PYTHON -c "
import os, sys
from pathlib import Path
changed_raw = os.environ.get('GRAPHIFY_CHANGED', '')
changed = [Path(f.strip()) for f in changed_raw.strip().splitlines() if f.strip()]
if not changed:
    sys.exit(0)
from graphify.watch import _rebuild_code
_rebuild_code(Path('.'))
" > "$_LOG" 2>&1 < /dev/null &
      disown 2>/dev/null || true
    fi
  fi
fi

# ── code-review-graph: incrementally update MCP graph index after commit ────
if command -v code-review-graph > /dev/null 2>&1 && [ -d .code-review-graph ] && ! pgrep -qf 'code-review-graph update' 2>/dev/null && _resources_ok; then
  _LOG="${HOME}/.cache/code-review-graph-update.log"
  mkdir -p "$(dirname "$_LOG")"
  echo "[code-review-graph] Commit detected - launching background update (log: $_LOG)"
  nohup sh -c 'code-review-graph update --skip-flows && code-review-graph embed' > "$_LOG" 2>&1 < /dev/null &
  disown 2>/dev/null || true
fi

Why timeout 300? graphify _rebuild_code has no internal deadline. On large repos it can hang indefinitely if it hits a file lock, encoding error, or memory pressure. timeout 300 auto-kills the background process after 5 minutes — the git commit returns immediately either way, and the next commit retriggers a fresh attempt.

Why _resources_ok? Without it, rapid-fire commits (amend chains, rebase, interactive rebase) spawn multiple concurrent graphify processes. Observed: 3 stuck processes at 65–73% CPU each, load average 12+, RAM exhausted. The resource check ensures a rebuild only starts when the machine can handle it.

Create the same file at .husky/post-checkout with one change: wrap the graphify block with if command -v graphify > /dev/null 2>&1 && [ -d "graphify-out" ] (force-rebuild only when the graph has been built before). Mark both executable: chmod +x .husky/post-commit .husky/post-checkout.

What "safe to commit" means here: a developer with none of these tools runs exactly the 4 rebase guards and exits 0 — no Python spawned, no directories created, no errors.

Complete Auto-Update Flow

After full setup, the pipeline looks like this:

AI agent session opens (Claude Code shown — other agents use equivalent plugin hooks)
    → SessionStart: code-review-graph status
    → SessionStart: setup nudge (only if CLI installed but no graph built yet)
    → SessionStart: graph cheatsheet injected (query→tool map, ~150 tokens, once per session)

AI agent searches the codebase (grep / rg / find)
    → PreToolUse: smart-grep-hook.sh intercepts
        ├── no graph / non-code target / --graph-tried flag → pass silently
        ├── first grep this session
        │     ├── graph has answer → show answer in context, allow grep (one-shot lesson)
        │     └── graph has no answer → allow grep, suggest MCP tool
        └── subsequent grep
              ├── graph has answer → deny with answer inline (zero retry, saves 2000+ tokens)
              └── graph has no answer → pass silently

AI agent edits a file
    → Stop hook (once per full AI turn): code-review-graph update --skip-flows (0.425s)
    [graphify does NOT update here — too slow for per-turn trigger]

Code committed
    → post-commit: _resources_ok() check
        ├── CPU > 50% or memory < 2 GB → skip rebuild, log why
        ├── pgrep: graphify already running → skip
        └── resources OK → graphify update . (background nohup, timeout 300)
    → post-commit: _resources_ok() check
        ├── pgrep: CRG already running → skip
        └── resources OK → code-review-graph update + embed (background nohup)

Branch switched
    → post-checkout: diff count = git diff --name-only PREV NEW | wc -l
        ├── ≤5 files OR same-base branch switch
        │     ├── graphify: incremental update (SHA256 cached, fast) [resource-guarded]
        │     └── CRG: update --skip-flows + embed [resource-guarded]
        └── >5 files OR brand-new branch
              ├── graphify: force full rebuild (GRAPHIFY_FORCE=true) [resource-guarded]
              └── CRG: build (full SQLite rebuild) [resource-guarded]

Result: developer commits or switches branches → both graphs update in background (if device has resources).
        Agent edits files → CRG updates after each AI turn.
        Agent searches → graph answers before grep fires.
        Device overloaded → rebuilds silently skip, next commit retries.

Quick Reference

Each block below is independent — install only the tools you want. Pure CLI setup → graphify only. Embedding + MCP setup → CRG only. Full stack → both.

Installation

# Either, both, or pick one:
pip install graphify              # graphify (CLI only)
pip install code-review-graph     # CRG (CLI + MCP server)
# Or via uvx / pipx — see the Installation section earlier in this guide

Project Setup (run once per project, for each tool you installed)

# Create ignore files (only the ones you need)
touch .graphifyignore                 # graphify only
touch .code-review-graphignore        # CRG only

# Build graphs manually
graphify update .           # graphify: JSON graph, AST-only (no tokens)
code-review-graph build     # CRG: SQLite graph (fast, no tokens)

# Register with your AI agent (run only the lines for installed tools)
graphify claude install     # graphify hooks + CLAUDE.md trigger
graphify hook install       # graphify post-commit hook
code-review-graph install   # CRG MCP server + skills + hooks

Verify (run only the rows for tools you installed)

code-review-graph status            # CRG: node/edge counts
head -15 graphify-out/GRAPH_REPORT.md  # graphify: corpus + freshness
time code-review-graph update --skip-flows   # CRG: should be <1s
python3 -m json.tool .claude/settings.local.json | grep -A3 PostToolUse

Daily Commands (each line targets one tool — use what is relevant)

# Manual incremental update
graphify update .           # graphify: SHA256 incremental
code-review-graph update    # CRG: 0.4s

# Query (graphify CLI)
graphify query "auth flow" --graph graphify-out/graph.json
graphify path "ComponentA" "ServiceB" --graph graphify-out/graph.json
graphify explain "MyService" --graph graphify-out/graph.json

# Blast-radius review (CRG)
code-review-graph detect-changes --base HEAD~1 --brief

# Status (CRG)
code-review-graph status

# Wiki / visualization (CRG)
code-review-graph wiki
code-review-graph visualize

Watch Mode

graphify watch .                  # continuous auto-rebuild (graphify)
code-review-graph watch           # continuous auto-rebuild (crg)

Why Not a Vector Database?

Code navigation is fundamentally relational — UserController calls AuthService which imports TokenRepository. This is a directed graph, not a bag of vectors.

	Knowledge Graph	Vector DB
Code structure	Topology-exact	Approximate
Setup	No embedding pipeline	Embedding + chunking + sync
Hallucination	None (AST is deterministic)	Can return similar-but-wrong
Cost (indexing)	0 tokens (AST mode)	Embedding cost per file
Incremental update	0.4s (SQLite diff)	Re-embed changed chunks
Exact symbol lookup	Use grep/LSP (still best)	Often worse

Knowledge graphs excel at "how does X relate to Y" questions. For exact symbol lookup, grep and LSP still win — and both tools' PreToolUse hooks (or equivalent agent config) redirect the agent toward the graph for structural questions while leaving grep for exact matches.

Files Created / Modified

After completing this setup, here's what changes in each project:

Committed to repo:

your-project/
├── .graphifyignore                    ← new
├── .code-review-graphignore           ← new
├── .mcp.example.json                  ← new (reference config for teammates)
├── CLAUDE.md                          ← 2-line pointer to docs/agent/knowledge-graph.md
├── .claude/
│   ├── settings.json                  ← permissions only, no hooks
│   ├── settings.example.json          ← new (hook reference: Stop CRG update + SessionStart cheatsheet + setup nudge)
│   └── skills/                        ← new (code-review-graph skills relevant to the repo)
├── .husky/                            ← Husky hooks (if using Husky)
│   ├── pre-commit                     ← branch protection (blocks direct commits to protected branches)
│   ├── post-commit                    ← graphify + CRG rebuild (resource-guarded, background nohup)
│   └── post-checkout                  ← graphify + CRG rebuild on branch switch (resource-guarded, smart incremental/full)
└── docs/agent/knowledge-graph.md      ← new (full tool reference)

Gitignored (local only, not committed):

your-project/
├── .mcp.json                          ← personal MCP config (copy from .mcp.example.json)
├── .claude/settings.local.json        ← live personal hooks (copy from settings.example.json)
├── graphify-out/                      ← generated (graph.json, GRAPH_REPORT.md, graph.html)
├── .code-review-graph/                ← generated (SQLite db, wiki, visualization)
├── ai-vault/                          ← Obsidian vault (personal, lives inside the project)
├── AGENTS.md / GEMINI.md              ← tool-generated, IDE-specific
├── .cursorrules / .windsurfrules      ← IDE-specific
└── .kiro/ / .opencode.json            ← IDE-specific

New teammate setup (copy example files and activate):

cp .mcp.example.json .mcp.json
cp .claude/settings.example.json .claude/settings.local.json
# Or copy hooks into ~/.claude/settings.json to activate across all projects

References

Graphify — AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs, papers, images, or videos into a queryable knowledge graph. App code + database schema + infrastructure in one graph.
code-review-graph — Local knowledge graph for Claude Code. Builds a persistent map of your codebase so Claude reads only what matters — 6.8× fewer tokens on reviews and up to 49× on daily coding tasks.
From Karpathy's LLM Wiki to Graphify: AI Memory Layers are Here — Analytics Vidhya article on the evolution and implementation of knowledge graphs for AI systems.

Let's Connect

I'm always excited to hear about what you're building! If you found this guide helpful, have questions, or just want to share your ai setup strategy:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs
Support: SupportKori

branchdiff + GitHub & Bitbucket: A Local Lens for the Pull Request Workflow You Already Have

Mir Mursalin Ankur — Sun, 10 May 2026 11:32:50 +0000

Here is a number nobody tracks but everyone feels: the number of tab switches in a single code review.

Open the PR. Switch to your editor to search for the function being changed. Switch back to the PR to find your place. Click a file in the sidebar. Scroll to the relevant hunk. The author pushes a fix commit — the diff resets to the top. Switch to Slack to tell them you were mid-read. Switch back. Find your place again. Copy a snippet into your AI assistant. Paste the AI's reply back as a comment. Tab-switch to the PR. Tab-switch back because you forgot which file you were on.

By the time you post your review, you have made twenty tab switches to do ten minutes of actual reading. That friction is not a big problem. It is a hundred small ones. And small frictions are the exact things that cause engineers to put review off until Friday afternoon when they are too tired to read carefully.

branchdiff is not a replacement for GitHub or Bitbucket. It is a local browser app that sits beside your editor and handles the reading, marking, commenting, and lifecycle actions — while every click that matters (merge gate, approval, audit trail, CI status) still happens on the platform, through the same APIs you would use anyway. The PR on the platform is still the source of truth. branchdiff is just a better cockpit for the part of review that does not benefit from being a cloud round-trip.

This post explains how those two layers fit together — what lives where, and why the seam is designed the way it is.

The mental model: source of truth vs. working surface

Think of the PR on GitHub or Bitbucket as the source of truth. The review history, approvals, merge state, CI status, branch protection, and audit trail all live there. Nothing in branchdiff changes any of that. Your team's review process, your release process, and your compliance posture keep working exactly the way they always have.

branchdiff is the working surface for the part of review that is fundamentally local — reading the diff, marking files as you go, drafting comments, navigating between files, and running an AI pass. When you are ready, you sync the comments to the PR with one click and the platform takes over again.

The split in practice:

Concern	GitHub / Bitbucket	branchdiff
Merge gating, branch protection	✓
CI / status checks	✓
Approvals & required reviewers	✓
Final review comments	✓ (after sync)	✓ (drafted here)
Reading the diff with full context		✓
Marking files reviewed / stale		✓
Running AI review or resolve		✓
PR lifecycle clicks (approve, merge)	✓ (canonical)	✓ (proxied via API)

Everything in the right column is a convenience layer. Everything in the left column is still authoritative. Uninstall branchdiff tomorrow and your team's review process keeps working — you go back to clicking on the PR page. That is the design constraint the whole tool is built around.

Opening any PR locally in seconds

Point branchdiff at a PR URL on either platform:

branchdiff https://github.com/owner/repo/pull/123
branchdiff https://bitbucket.org/workspace/repo/pull-requests/45

It resolves the base and head refs, runs git fetch if needed, and opens a browser tab at http://localhost:5391 with the diff rendered — syntax highlighting for 150+ languages, split or unified view, a sidebar of changed files, keyboard navigation (j/k next/previous file, n/p next/previous hunk). The PR on the platform is untouched.

Named-ref comparisons (main..feature) get a persistent review session backed by a local SQLite file in ~/.branchdiff/. Inline comments survive new commits — same idea as a GitHub PR thread, but stored on your machine, readable instantly, without a round-trip. If the author force-pushes mid-review, your view markers and drafts stay intact.

Multiple sessions are the default, not a workaround. Each unique ref pair opens on its own port — the second session on 5392, the third on 5393, and so on. Reviewing a teammate's PR while working on your own branch in another tab is just two browser tabs. branchdiff list shows everything running.

PR lifecycle from the toolbar — a remote control, not a parallel database

The toolbar shows a dropdown for the open PR with the actions you would otherwise click on the platform. It is not a separate database of PR state. It is a remote control. Each action calls gh for GitHub or the Bitbucket REST API for Bitbucket, and the canonical PR records the action with the same timestamp it would have had if you had clicked on the website.

The dropdown groups four kinds of action:

Review actions — Approve, Request Changes, Comment. The Comment action posts a regular PR comment via gh pr comment (fixed in v1.5.1; the previous version mistakenly created a formal review object). Request Changes allows an optional comment; if you provide nothing, a default message is posted because both APIs require a review body.

Merge action — with a strategy picker. GitHub offers Merge commit, Squash, and Rebase; Bitbucket offers Merge commit, Squash, and Fast-forward (added in v1.5.1). Branch protection rules and required status checks still apply — if the PR cannot merge, the platform refuses and branchdiff surfaces the error inline.

State actions — Close, Reopen (only when valid), Mark as Draft, Mark Ready for Review.

Metadata actions — Edit title and description, Sync comments, Open in browser.

The dropdown header carries a state dot (green for open, purple for merged, red for closed) and a row of reviewer pills showing each reviewer's latest state — approved, changes requested, commented, pending, or dismissed. Destructive actions (merge, close, request changes) show a confirmation dialog; errors stay inline in the dialog so a typed message is not lost when the network blips.

Comment sync — both directions, both opt-in

Push local comments to the PR. Draft comments in branchdiff (manually or via an AI pass), then click the PR badge in the toolbar and choose Push to PR. Each single-comment thread is posted as an inline review comment. Duplicates (same file, line, body) are skipped. Multi-reply threads stay local because the platform APIs do not map cleanly to them.

A status toast tells you what happened: Pushed 3, skipped 1 duplicate, skipped 1 multi-reply thread. Failures keep the local thread intact so you can fix the anchor and retry.

Pull PR comments into branchdiff. Same dialog, Pull from PR. Existing review comments come down as local threads anchored to the same lines, with author and timestamp preserved. This is what makes branchdiff practical for re-review — open the PR locally on day three, pull the comments, see every thread inline, mark them resolved as the author addresses them, push the resolutions back.

Sync requires your local HEAD to match the PR head and your working tree to be clean. branchdiff surfaces both constraints in the dialog with a one-line explanation (git pull --rebase, git stash).

This is the only cloud round-trip in the whole tool. No telemetry, no remote diff service. Wipe ~/.branchdiff/ and there is nothing in any backend with your data.

A concrete 90-second flow

# Teammate posts: "PR is up — https://github.com/acme/api/pull/482"
branchdiff https://github.com/acme/api/pull/482

Browser opens in about three seconds. Toolbar shows #482 with a green dot. Reviewer pills: one teammate already approved, one pending. You scroll the diff, mark a few files viewed, drop two [suggestion] comments and one [must-fix]. Click #482 → Push to PR. Toast: "Pushed 3 comments." Click Approve in the dropdown. The toolbar updates to show your green pill.

Total wall-clock time: 90 seconds from "teammate posts link" to "PR has your review on it." The work of reading the diff is unchanged. Everything around it shrunk.

Why this matters for AI-assisted review

AI is now part of almost every review, whether the team has formalised it or not. Engineers paste diffs into ChatGPT, run Copilot review, pipe git diff into claude. Done ad-hoc, that AI usage drifts — different people use different prompts, comments do not land on the right lines, and the context never makes it back to the PR.

branchdiff gives that AI usage a controlled, repeatable surface: the same diff the human is looking at, the same line numbers, the same comment threads, with explicit branchdiff agent commands so the AI cannot wander outside the review. Every AI comment lands on a real line, with a severity tag, in the same session as your manual comments. You can dismiss, resolve, or push selectively. The AI cannot post directly to the PR — it goes through the same command surface you use, and you stay the gate.

The next two posts in this series go deeper: self-review on your own branch before the PR opens, and AI-assisted review of teammates' PRs that syncs back to the canonical thread.

What it honestly saves you

Fewer tab switches. Diff, comments, AI assistant, and PR lifecycle all live on one local page that loads in milliseconds.
A consistent UX across GitHub and Bitbucket. Review keystrokes are the same on either side — engineers who straddle both platforms stop having to learn two UIs.
No re-reading after a force-push. Viewed / stale tracking remembers which files you have already looked at. You re-read only the parts that actually changed.
A predictable AI surface. Systematic, tagged, dismissable. Not an ad-hoc paste-into-ChatGPT that leaves no trace.

Where it stops

No CI. The platform's checks are still the gate.
No cloud storage. Wipe ~/.branchdiff/ and you lose local drafts that have not been pushed.
No multi-reply thread push. Back-and-forth conversations belong on the PR.
No branch protection bypass. Merge actions still respect required reviews and status checks on the platform.
No full PR page replacement. The PR description, linked issues, and CI status block still live on the platform. Open in browser in the toolbar is one click away.

The tool is intentionally small. It does the part that benefits from being local, and gets out of the way of the part that benefits from being on the platform.

Try it on a PR you already have open

Install from the branchdiff releases page — install instructions, changelogs, and uninstall steps are all there. Quickstart:

npm install -g @encryptioner/branchdiff
# or: pip install branchdiff
# or: brew tap encryptioner/branchdiff https://github.com/encryptioner/branchdiff-releases \
#          && brew install branchdiff

branchdiff https://github.com/your-org/your-repo/pull/123

Click the PR badge in the toolbar, watch the reviewer pills populate, push a comment back, check that it appears on the PR. The point is not "branchdiff vs. GitHub" — it is to see where your current review workflow keeps a tab open that does not need to be open.

Let's Connect

I am always excited to hear what you are building. If you found this guide helpful, have questions, or just want to share your code review setup:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs
Support: SupportKori

branchdiff releases, changelog, install & uninstall guide: encryptioner.github.io/branchdiff-releases

Claude Code Configuration Blueprint: The Complete Guide for Production Teams

Mir Mursalin Ankur — Sun, 15 Mar 2026 05:01:20 +0000

Configure Claude Code once — get security, reusable workflows, specialized agents,
and cross-session intelligence across every project.

Who This Is For

You've used Claude Code on a project or two. You know the basics. Now you want to:

Stop Claude from touching secrets, credentials, or system files
Share team standards via git without leaking personal preferences
Create reusable workflows (spec, plan, implement, review, ship)
Make Claude remember lessons across sessions

This guide gives you copy-paste configs and explains the why behind each decision.

The Configuration Layers

Claude Code loads configuration from multiple layers, each with a specific scope:

Personal (not in any repo):
  ~/.claude/settings.json        → Security (deny list for all projects)
  ~/.claude/CLAUDE.md            → Personal workflow preferences
  ~/.claude/skills/*/SKILL.md    → Reusable workflows
  ~/.claude/commands/*/SKILL.md  → Convenience shortcuts
  ~/.claude/rules/*.md           → File-specific patterns (glob matching)
  ~/.claude/agents/*.md          → Domain specialists

Team-shared (committed to git):
  .claude/settings.json          → Project permissions
  CLAUDE.md                      → Coding standards, architecture
  .claude/rules/*.md             → Team-specific patterns

Personal overrides (gitignored):
  .claude/settings.local.json    → Your project overrides
  CLAUDE.local.md                → Your project preferences

Key rule: Your project CLAUDE.md must be self-contained. Teammates don't have your global skills, agents, or personal CLAUDE.md — global files are your personal toolkit, project files are the team playbook.

Part 1: Security — The Permission System

Permissions follow a strict hierarchy: Deny (always blocks) → Ask (prompts you) → Allow (auto-approved). Deny always wins — this is what makes the system trustworthy.

Pattern Syntax

Bash(exact command)       → matches only that exact command
Bash(command *)           → matches command with any arguments (space before *)
Read(path/to/file)        → matches exact file
Read(path/**/*.json)      → matches glob pattern
Read(~/.ssh/**)           → ~ expands to home directory on any OS

Space matters: Bash(ls *) matches ls -la but NOT lsof. Bash(ls*) matches both.

Global Settings (`~/.claude/settings.json`)

{
  "permissions": {
    "allow": ["Read", "Edit", "Write", "Glob", "Grep", "Bash(git status:*)", "Bash(git diff:*)", "Bash(nvm use:*)", "Bash(node:*)", "Bash(ls:*)"],
    "ask": ["Bash(git push:*)", "Bash(git commit:*)", "Bash(pnpm install:*)", "Bash(docker:*)", "Bash(curl:*)"],
    "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)", "Bash(git push --force:*)", "Read(.env)", "Read(.env.*)", "Read(~/.ssh/**)", "Read(~/.aws/**)", "Read(~/Library/Keychains/**)"]
  }
}

Cross-OS coverage: The deny list covers macOS (~/Library/Keychains), Linux (~/.local/share/keyrings), and Windows WSL (/mnt/c/Users/*/AppData). One global config works on any machine.

Project Settings (`.claude/settings.example.json`)

{
  "permissions": {
    "allow": ["Read", "Edit", "Write", "Glob", "Grep", "Bash(pnpm build:*)", "Bash(pnpm test:*)"],
    "deny": ["Read(.env)", "Read(.env.*)", "Read(node_modules/**)", "Read(dist/**)"]
  }
}

Add to .gitignore: .claude/* and !.claude/*.example*

Part 2: CLAUDE.md — Teaching Claude Your Codebase

A well-written CLAUDE.md turns Claude from a generic assistant into a team member who knows your conventions, pain points, and architecture.

The Instruction Budget Problem

Frontier LLMs reliably follow roughly 150–200 instructions total. Claude Code's system prompt consumes ~50 slots before your CLAUDE.md loads. Instruction degradation is uniform — every low-value rule you add actively makes your high-value rules less likely to be followed.

Brevity isn't nice — it directly affects instruction compliance.

The Template

Write it for Claude, not humans. Don't duplicate your README.

# CLAUDE.md

## Commands
- `pnpm dev` — Start development server
- `pnpm build` — Production build
- `pnpm lint-fix` — Lint and fix all packages

## Architecture
- `packages/client` — Vue 3 frontend
- `packages/server` — Express API
- `packages/shared` — Types, DTOs, utilities

## Coding Standards
- TypeScript strict mode, no `any` types
- Absolute imports only (no `../../`)
- API payloads: declare as typed constants

## PR Review Rules
1. **Type Safety** — Never use `any`. Typed constants for API payloads
2. **Dead Code** — Remove unused imports, variables, i18n keys
3. **Error Handling** — Wrap all API calls in try/catch

## Critical Gotchas
- Always use projection in DB queries — never fetch entire documents
- Server error messages MUST come from constant files

Progressive Disclosure

For larger projects, use a progressive disclosure pattern — put detailed docs in a separate directory:

## Detailed Documentation
When working on specific areas, read the relevant doc first:
- `docs/Agent/database_schema.md` — Data model and relationships
- `docs/Agent/payment_flow.md` — Payment gateway integration

What Works vs. What Doesn't

Do	Don't
Include commands Claude needs	Include formatting rules (use linter + hooks)
Document non-obvious patterns	Document obvious language features
List real PR review pain points	Duplicate your README
Keep it under 200 lines	Include aspirational rules nobody follows

Part 3: Rules — Enforcing Patterns with Globs

For patterns that must apply across specific file types, use rules with glob matching. Place them in ~/.claude/rules/:

---
description: Common coding mistakes — enforced across all projects
globs: "*.ts,*.tsx,*.vue,*.js,*.jsx"
---

# Coding Gotchas
- Never use relative imports (`../../`) — always absolute paths
- Never introduce `any` types — find or create the proper type

When Claude edits files matching the glob, these rules apply automatically.

	CLAUDE.md	Rules (`~/.claude/rules/`)
Scope	Per-project	Global (all projects)
Content	Architecture, commands, standards	File-specific patterns
Trigger	Loads when working in directory	Loads when file matches glob
Best for	Teaching your codebase	Enforcing patterns across projects

For teams: commit project-specific rules to .claude/rules/ in your repo.

Part 4: Plugins & Agents — Instant Capabilities

Plugins

Plugins are pre-built packages from the community. One install command gives you agents, MCP servers, and skills:

claude plugins:install context7 superpowers code-review feature-dev

Recommended stack:

Plugin	Purpose
`context7`	Live, version-specific documentation lookup
`feature-dev`	Codebase exploration + architecture design agents
`superpowers`	TDD, debugging, brainstorming, parallel agents
`code-review`	Multi-agent PR review with confidence scoring
`playwright`	Browser automation and E2E testing
`commit-commands`	Streamlined git commit, push, and PR creation

MCP Servers — Many plugins include MCP (Model Context Protocol) servers that bridge Claude Code with external systems (databases, APIs, task trackers). No additional configuration needed.

Custom Marketplaces — Add team-specific or community plugins:

{
  "extraKnownMarketplaces": {
    "my-team": { "source": { "source": "github", "repo": "my-team/claude-plugins" } }
  }
}

Agents

Agents are pre-configured specialists you can call for specific tasks. Unlike plugins (which add tools), agents add expertise.

Category	Example Agents	When to Use
Engineering	`backend-architect`, `frontend-developer`, `ai-engineer`	Domain-specific architecture
Testing	`test-writer-fixer`, code-review agents	Test strategy, bug fixing
Operations	`analytics-reporter`, `finance-tracker`	Data analysis, reporting
Development	`code-explorer`, `code-architect`, `rapid-prototyper`	Codebase understanding, MVPs

Example: Instead of explaining React Server Components patterns, say "Use the frontend-developer agent to build this with Server Components." The agent already knows the patterns, has React-specific tools, and follows frontend best practices automatically.

	Plugins	Agents
What they add	Tools, MCP servers, skills	Domain expertise and focus
Best for	Adding capabilities	Complex tasks requiring depth

Part 5: Skills & Commands — Building Workflows

Skills vs. Commands

	Commands (`~/.claude/commands/`)	Skills (`~/.claude/skills/`)
Purpose	Convenience shortcuts	Workflow orchestration
Examples	`/commit`, `/loop`, `/rewind`	`/spec`, `/implement`, `/grill`
Scope	Single operations	Multi-step processes
Use Case	Quick actions	Structured workflows

Use a command for quick shortcuts. Use a skill for multi-step workflows with decision points.

The Spec-to-Ship Workflow

The real power of skills comes from chaining them into a complete development workflow:

/scope (optional) → /spec → /grill (auto) → /plan-work → /grill (auto) → /implement → /verify → /ship

The ceremony scales with the risk:

Task Type	Workflow
New product	`/scope` → full chain
Feature	Full chain
Minor enhancement	Light spec → plan → implement → verify → ship
Bug fix	Bug spec or skip → plan → implement → verify → ship
Hotfix	Inline plan → implement → verify → ship

Key Skills

Skill	Purpose
`/scope`	Rapid product scoping — forces "ONE thing" question, maps user journey, identifies cost drivers
`/spec`	Clarified technical spec with Change Log for tracking mid-implementation updates
`/grill`	Hard-critic review through 7 lenses (security, architecture, testing, etc.) with severity levels
`/plan-work`	Phase-by-phase implementation plan traced to spec requirements
`/implement`	Executes plans with mid-implementation discovery handling (minor/moderate/significant tiers)
`/verify` → `/pre-review` → `/ship`	Type check → spec requirement walkthrough → branch management + PR creation

Ticket Directory Structure

ai/TICKET-146/
├── requirements/
│   ├── original-requirement.md    # Raw requirement (verbatim)
│   ├── spec.md                    # Clarified technical spec
│   └── grill-log.md              # Review findings
├── plans/
│   ├── overview.md               # High-level plan
│   ├── phase-1-data-model.md     # Detailed phase plan
│   └── grill-log.md              # Plan review findings
└── tests/
    └── manual-test-cases.csv

This structure makes work resumable across sessions — future sessions read spec/plan files to pick up where you left off.

Building Your Own Skills

---
name: my-skill
description: Use when the user says "plan this" or presents a multi-file task
---

# Skill Title
## When to Use
- [Trigger conditions]

## Process
### Step 1: [Name]
[Instructions Claude follows]

## Rules
- [Hard constraints]

Three tips:

Write instructions TO Claude, not documentation ABOUT a process
Include trigger phrases in the description
Keep each skill focused — one workflow, one skill

Part 6: Advanced Patterns — Hooks, Subagents, Worktrees

Hooks — Automated Quality Gates

Hooks run automatically at lifecycle events. Two types:

prompt — Claude evaluates a condition and acts (block, remind, warn)
command — Runs a shell command directly (always executes)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "If this is a git commit, verify lint and type-check have been run. If not, block with: 'Run lint and type-check before committing.'"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the file is TypeScript and more than 3 TS files have been edited since the last type-check, remind: 'Consider running type-check before continuing.'"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "notify-send 'Claude Code' 'Awaiting your input'" }]
    }]
  }
}

Use hooks instead of CLAUDE.md for linting rules — LLMs are expensive compared to linters. Hooks free up instruction budget for things only CLAUDE.md can teach.

Subagents — Keeping Context Clean

For complex tasks, spawn subagents to handle research, exploration, or parallel work. Subagents run in separate contexts and return distilled findings — keeping your main conversation focused on implementation.

Scenario	Example
Research	Investigating a library before using it
Exploration	Understanding a large codebase section
Parallel work	Running independent analyses
Heavy debugging	Deep investigation
Code review	Multiple reviewers checking different aspects

Many skills use subagents automatically. /grill spawns review agents for different aspects. /implement may spawn research agents for unfamiliar libraries.

Worktrees — Isolated Development

For feature work that needs isolation, use git worktrees. Claude can create and manage worktrees, giving you a clean environment for each branch.

Scenario	Benefit
Multiple features	Work on several branches simultaneously
Parallel testing	Test approaches in isolated environments
Code review	Review PR branches while keeping main stable
Hotfixes	Fix production without interrupting feature work

Part 7: Automation — Auto-Invocation & Memory

Auto-Invocation — Skills That Trigger Themselves

Both plugins and skills support auto-invocation — Claude reads the skill's description and triggers it automatically when your request matches. You don't need to remember slash commands.

To make auto-invocation reliable:

Be specific with trigger phrases — vague descriptions lead to false activations
Include negative triggers — "Do NOT use for TDD projects — use /plan-tdd instead"
Test with natural language — try different phrasings

Example: With /grill configured to trigger on "grill this", "poke holes", or "stress test this", simply saying "poke holes in this spec" auto-triggers the workflow.

Auto Memory — Cross-Session Intelligence

Claude Code maintains a persistent memory directory per project at ~/.claude/projects/<project-path>/memory/. The MEMORY.md file (first 200 lines) loads into every conversation automatically — no manual setup needed.

Claude updates this file as it learns your project: architectural patterns, common mistakes, file paths that matter. The /ship skill captures learnings at the end of each ticket automatically, so memory grows organically across sessions.

Part 8: Putting It All Together

New Project Setup (5 Minutes)

Create CLAUDE.md — commands, architecture, coding standards, PR review rules, critical gotchas
Create .claude/settings.example.json — project-specific deny list
Optionally create .claude/rules/*.md — project-specific patterns with glob matching
Add to .gitignore: .claude/* and !.claude/*.example*
Ensure ~/.claude/settings.json has the global security deny list
Install plugins: claude plugins:install context7 superpowers code-review feature-dev

How the Layers Work in Practice

"Read .env.local"             → Project deny  → BLOCKED
"pnpm add lodash"             → Ask rule      → Prompts you
"git push --force"            → Global deny   → BLOCKED (even with --dangerously-skip-permissions)
"Read src/components/App.vue" → Allow         → AUTO-APPROVED
"This test is failing"        → Auto-invoke   → debugging skill triggers

Quick Reference

File	Shared?	Purpose
`~/.claude/settings.json`	No	Global security (deny list)
`~/.claude/CLAUDE.md`	No	Personal workflow preferences
`~/.claude/skills/*/SKILL.md`	No	Custom workflows
`~/.claude/commands/*/SKILL.md`	No	Convenience shortcuts
`~/.claude/rules/*.md`	No	File-specific patterns (glob)
`~/.claude/agents/*.md`	No	Domain specialists
Plugins	No	Pre-built agents + MCP + skills
`.claude/settings.json`	Yes	Team project permissions
`.claude/rules/*.md`	Yes	Team-specific patterns
`CLAUDE.md`	Yes	Team coding standards
`~/.claude/projects/*/memory/`	No	Cross-session memory

The Takeaway

Layer your configuration by scope and shareability:

Global settings protect your system — secrets, credentials, destructive commands
Project settings protect project resources — config files, build artifacts
CLAUDE.md encodes team standards (keep it under 200 lines — every low-value instruction degrades high-value ones)
Rules enforce file-specific patterns with glob matching — language conventions, gotchas
Agents provide domain expertise — backend, frontend, AI, testing, operations
Plugins add instant capabilities — code review, testing, documentation, MCP servers
Skills encode workflows (multi-step) — Commands handle shortcuts (single actions)
Hooks automate quality gates — free up CLAUDE.md instruction slots
Subagents keep context clean — offload research, exploration, parallel analysis
Worktrees enable isolated development — multiple branches without switching
Memory captures lessons learned — no reteaching the same thing twice
Auto-invocation makes skills trigger themselves — no slash commands needed

The spec-to-ship workflow isn't bureaucracy. It's front-loading the thinking so implementation is mechanical. A grilled spec catches the bug that would have taken a day to debug. A phased plan prevents the "I changed 47 files and nothing type-checks" disaster.

Configure once. Benefit on every session, every project, every team member.

References

Official:

Claude Code Documentation — Permissions, hooks, settings, skills
Plugins README — Plugin marketplace

Community:

Writing a Good CLAUDE.md — HumanLayer — Instruction budgets research
Claude Code Hooks: Complete Guide — aiorg.dev — 20+ hook examples
Claude Code Permissions Guide — eesel.ai — Security setup

Let's Connect

I'm always excited to hear about what you're building! If you found this guide helpful, have questions, or just want to share your Claude Code journey:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs

Navigating Bangladesh's Software Industry: A Practical Guide for Developers in 2026

Mir Mursalin Ankur — Tue, 20 Jan 2026 15:39:57 +0000

Bangladesh's software industry has grown rapidly over the past decade. From $1.3 billion in exports to 2,650+ ICT companies employing hundreds of thousands of developers, the sector has transformed from a niche outsourcing destination into a serious global technology hub. The country now boasts over 1 million active freelancers (2026), making it a global freelancing powerhouse.

But the landscape has changed dramatically. The entry-level market is saturated. Senior talent is scarce. And the post-2024 reality—marked by internet shutdowns, tax policy uncertainty, and global competition—means the easy growth is over.

This guide is about action—not analysis.

The Brutal Truth: Too Many Developers, Not Enough Jobs

Let's start with what's actually happening in Bangladesh.

We have a massive oversupply problem. Every year, hundreds of universities and colleges pump out thousands of computer science graduates. Add to that the hundreds of online training institutes, bootcamps, and YouTube tutorials creating "developers" in 3-6 months.

The result? A glut of low-skill junior developers fighting for the same entry-level positions.

Experience Level	Jobs Available	Candidates	Competition
Entry-level	~12,000	30,000+	2.5x oversubscribed
Mid-level	~8,000	20,000	2.5x oversubscribed
Senior	~3,000	5,000	1.7x oversubscribed
Specialized	~1,000	500	0.5x (talent shortage)

The lesson: If you're doing what everyone else is doing (basic web development, tutorial-heavy learning, no specialization), you're competing with 2-3 other people for every job.

Why This Is Happening: The Training Glut

The University Problem

Bangladesh has 150+ universities offering computer science and engineering programs. Many of these programs are outdated, teaching curriculums from 5-10 years ago. Students graduate knowing theory but unable to build real applications.

Common issues:

Professors who haven't worked in the industry in decades
Outdated technologies (teaching Java applets in 2026)
Zero emphasis on practical projects
No industry exposure or internships

The Online Course Explosion

YouTube, Udemy, Coursera, and local platforms have made programming education accessible to everyone. But this has created a new problem: tutorial developers.

Thousands of graduates complete 20+ tutorials but can't:

Build an original project without following instructions
Debug their own code
Write clean, maintainable code
Explain technical decisions
Work in a team environment

The Bootcamp Industry

Dozens of "become a full-stack developer in 3 months" bootcamps promise quick careers. They teach students to copy-paste code, pass interviews, and get jobs. But these developers struggle when faced with real-world complexity.

The result: Companies are flooded with resumes from graduates who look good on paper but can't deliver. They've stopped trusting fresh graduates and now require 2-3 years of experience—even for "entry-level" positions.

The New Reality: Global Competition + AI

Just when Bangladesh's oversupply problem was peaking, two global shifts made things harder:

1. Remote Work Saturation

During COVID, remote work exploded. Bangladeshi developers could finally access international jobs. But this also meant they were now competing directly with developers from India, Pakistan, Eastern Europe, and the Philippines—all of whom offer similar rates.

2. AI Coding Tools

AI tools like ChatGPT, GitHub Copilot, and Claude have changed the entry-level equation globally. A Stanford study found that employment for software developers aged 22-25 dropped nearly 20% between 2022-2025.

Why this hits Bangladesh hard:

Entry-level tech hiring globally decreased 25% in 2024
70% of hiring managers believe AI can do the work of interns
Companies asking: "Why hire a junior for $90K when GitHub Copilot costs $10?"

The tasks that junior developers used to do—writing boilerplate code, fixing bugs, writing test scripts—are now what AI tools handle well.

Three Career Paths That Actually Work

Despite the challenges, there are still paths to a successful career. You just need to be strategic.

Path 1: Specialization Premium

Pick a high-value niche (embedded systems, AI/ML, security, DevOps)
Become exceptional in it
Charge 2-3x what generalist developers charge
Competition: Low
Why it works: Specialized work is harder to automate and outsources can't easily replicate

Path 2: International Remote

Build skills for global market
Work directly for US/European companies
Earn in USD (3-5x local rates)
Competition: Medium (requires English and self-marketing)
Why it works: Local market is saturated; global market has talent shortages

Path 3: Local Premium

Join top outsourcing companies (Cefalo, Enosis, Optimizely, Cheq)
Work your way up through established career ladders
Earn local premium rates
Competition: High (everyone wants these jobs)
Why it works: These companies have established client relationships and can pay more

The AI Reality: Don't Ignore It, Don't Overrate It

85% of developers globally use AI tools, but here's what most don't realize:

The challenges:

46% distrust AI accuracy (only 3% "highly trust" it)
66% are frustrated by "AI solutions that are almost right, but not quite"
45% say debugging AI-generated code takes longer
67% spend more time debugging AI code
68% spend more time fixing security issues in AI code

The reality: AI makes you faster at routine tasks but can slow you down overall when you account for verification and debugging.

What this means for you:

Learn AI tools – GitHub Copilot, Cursor, ChatGPT, Claude, Gemini are industry standards
But don't depend on them – Understand what the code is actually doing
Focus on what AI can't do – Architecture, security, business logic, client communication

Developers resist using AI for high-responsibility tasks:

Deployment and monitoring: 76% don't use AI
Project planning: 69% don't use AI

That's where your value lives.

Action Plan: Your First 5 Years

Year 1: Foundations + Specialization Choice

Months 1-6: Pick your lane (don't try to do everything)
- Web/Mobile? Generalist path, more competition
- Embedded Systems? Fewer competitors, higher pay
- AI/ML? Growing field, severe talent shortage
- DevOps/Cloud? Critical infrastructure, hard to find
- Security/Biometrics? Trust-sensitive, premium pay
Months 7-12: Build portfolio while learning
- 3-5 substantial projects (not tutorials)
- Learn AI tools—but don't depend on them
- Start freelancing on Upwork for real experience

Year 2-3: First Job + Skill Deepening

Target companies based on your chosen path
Build real-world experience
Start specializing deeper
Salary target: 30,000-50,000 taka/month

Year 3-5: Seniority or Pivot

Option A: Grow in current company toward senior roles
Option B: Jump to higher-paying company
Option C: Go full remote international
Salary target: 80,000-150,000+ taka/month

Specialization Deep Dives

Embedded Systems & IoT

Why pays premium: Specialized knowledge, fewer engineers, global talent shortage
Market demand: ~2,921 embedded systems job openings on major job portals
Key employers: Samsung R&D Institute Bangladesh, Teton Electronics, BJIT Embedded, SIMEC, Subra Systems, Ninos IT Solution
Skills needed: C/C++, firmware development, microcontrollers, RTOS, hardware-software integration
Salary range: 60,000-180,000+ taka/month
Time to expertise: 12-18 months

AI/ML & Data Science

Why pays premium: Global talent shortage, high value work
Skills needed: Python, TensorFlow/PyTorch, SQL, statistics, MLOps
Salary range: 100,000-200,000+ taka/month
Time to expertise: 18-24 months

DevOps & Cloud

Why pays premium: Critical infrastructure, hard to find qualified people
Skills needed: Linux, AWS/Azure/GCP, Docker, Kubernetes, CI/CD, scripting
Salary range: 120,000-250,000+ taka/month
Time to expertise: 12-18 months

Security & Biometrics

Why pays premium: Trust-sensitive roles, regulatory requirements
Key employers: Tiger IT, security roles at banks/telecom
Skills needed: Cryptography, network security, ethical hacking, compliance
Salary range: 90,000-150,000+ taka/month
Time to expertise: 12-18 months

Targeting the Right Companies

Tier 1: International Outsourcing (Premium Pay)

Cefalo: Norwegian market, 65,000-220,000 taka/month
Enosis: US/Europe clients, 50,000-220,000 taka/month
Optimizely BD: US company, 70,000-300,000 taka/month
Cheq BD: US cybersecurity, 70,000-300,000 taka/month
Tero Labs: 120,000-150,000 taka/month

Tier 2: Top Local Companies

Brain Station 23: 60,000-220,000 taka/month (800+ employees)
BJIT: Japanese market, 30,000-220,000 taka/month (80% work from Japan)
Selise: Swiss-Bangladeshi operations (~$37.9M revenue)

Tier 3: High-Growth Startups

Pathao: 65,000-180,000 taka/month + equity
Chaldal: 70,000-180,000 taka/month
ShopUp, Shikho, Arogga: Competitive packages + equity upside

Salary Breakdown: The Real Numbers (2024-2025)

Level	Salary Range (BDT/month)	Salary Range (USD/month)
Trainee/Intern	0-15,000	$0-135
Junior Developer (0-2 years)	20,000-45,000	$180-405
Software Engineer (2-5 years)	50,000-80,000	$450-720
Senior Engineer (5+ years)	100,000-220,000	$900-1,980
Tech Lead/Principal	165,000-300,000	$1,485-2,700

The Remote Work Premium: Engineers working remotely for international companies earn substantially more (~345,000 taka/month average)—2-4x higher than local salaries.

Training: What Actually Works in 2026

For Foundations:

BITM (BASIS): Industry-aligned, most credible for placement
University CS programs: Top-tier only (BUET, DU, KUET, RUET, NSU, BRAC, AIUB)
Poridhi.io: Bangla-language, AI/ML tracks, 250+ hands-on labs

For Practical Skills:

Build real projects, not tutorials – This is the #1 differentiator
GitHub portfolio – Quality over quantity
Freelancing on Upwork – Real client experience
Open source contributions – Demonstrates collaboration skills

AI Tools (Learn, Don't Depend):

GitHub Copilot, Claude, Gemini, or Cursor – Industry standard tools
Practice validation – Review AI code for security and correctness
Understand first, then automate – Strong fundamentals matter more than AI skills

Red Flags:

Courses that only teach syntax without projects
"Become a full-stack developer in 3 months" claims
No portfolio/real-world application
Instructors who haven't worked in the industry
"AI will replace developers" – No, it won't. But developers who use AI will replace those who don't.

Common Mistakes to Avoid

Mistake 1: Tutorial addiction

Problem: You've completed 20 tutorials but can't build anything original
Solution: After learning basics, stop tutorials and build original projects

Mistake 2: Jack of all trades

Problem: You know a little of everything, expert in nothing
Solution: Pick one stack and go deep

Mistake 3: Ignoring the market reality

Problem: "If I learn MERN stack, I'll get a job"
Solution: Look at what companies actually need. 30,000+ people know MERN. Fewer know embedded systems or DevOps.

Mistake 4: Relying on AI too much

Problem: Copy-pasting AI code without understanding it
Solution: Always validate. Security vulnerabilities in AI code are common.

Mistake 5: Waiting for the "perfect job"

Problem: 6 months unemployed, waiting for top company
Solution: Take the good-enough job, build skills, move up later

Mistake 6: No specialization

Problem: Doing what everyone else is doing
Solution: Pick a niche. Embedded systems, security, DevOps, AI/ML—anything but generic web development.

Where the Industry Is Headed

Short-term (2026-2027):

Post-2024 stabilization (after internet shutdown, white paper, tax changes)
Entry-level jobs remain tough; senior/specialized roles in high demand
AI adoption accelerates—teams that use AI effectively will win

Medium-term (2027-2029):

Developer role transforms from "coder" to "problem solver"
Companies that don't hire juniors will eventually have no seniors
New career pathways emerge for AI-augmented developers

Long-term (2029-2031):

Either: Software becomes a top export category ($5B+)
Or: Stagnation at current levels ($1-2B)
Difference depends on: Investment + Education quality + Policy stability

Final Thoughts

Bangladesh's software industry is at an inflection point. The easy growth is over. The market is saturated with junior developers. AI has disrupted entry-level jobs globally. But this isn't the end—it's a transformation.

The developers who thrive in 2026 and beyond will be the ones who:

Specialize in areas where there's actual demand
Build genuine skills—not tutorial certificates
Use AI tools without depending on them
Think architecturally, not just syntactically
Communicate effectively (English + technical explanation)

The free ride ended in 2024. What comes next depends on the choices you make.

For those who build genuine skills and create real value: The opportunity is substantial.

For those who want shortcuts: The door is closing.

Choose wisely.

Resources

Learning Platforms:

Poridhi.io - Bangla Software Engineering Courses
BITM - BASIS Institute of Technology & Management - Industry-aligned training
Coursera - University-level courses
edX - MIT, Harvard courses

AI Coding Tools (Learn, Don't Depend):

GitHub Copilot - Industry standard
Cursor - AI-native IDE
ChatGPT - Code review and explanation
Claude - Advanced coding assistant with long context
Gemini - Google's AI assistant

Job Platforms:

Upwork - Freelance work
Toptal - Elite freelance network
Turing - Remote US jobs
CSE Job Bangladesh Facebook Group - Local jobs

Career Development:

LinkedIn - Build your professional profile
GitHub - Showcase your code
Stack Overflow - Learn and help others

Bangladesh Industry Data (2026):

Vivasoft: Top 20 Best Software Companies in Bangladesh 2026 (January 6, 2026)
Ontik Technology: Top 25 Software Companies in Bangladesh 2026 (January 7, 2026)
Nextzen: Top 10 Best Software Companies in Bangladesh 2026 (January 10, 2026)
Kaz Software: Top AI Developers in Bangladesh 2026
Vocal Media: The Rise of Freelancing in Bangladesh 2026 - Over 1 million active freelancers

AI Impact & Job Market Data:

Stanford Digital Economy Study: Canaries in the Coal Mine (2025) - 20% decline for devs aged 22-25
CIO: Demand for Junior Developers Softens as AI Takes Over - Entry-level hiring down 25% YoY
Stack Overflow Developer Survey 2025 - AI Section - 84% adoption, sentiment data
World Economic Forum: Software Developers and AI Work (January 2026) - Learning priorities and trends
DevOps.com: AI Coding Tools Survey (January 2026) - Daily usage statistics

Salary & Company Data:

This guide is based on publicly available information and industry analysis as of January 2026. Specific situations vary by individual skills, location, and market conditions.

End

That's all!

I hope you've found the article useful. I'll write more about the software engineering, career opportunities and overall ecosystem. Feel free to share your thoughts.

Check more on

Inside Bangladesh's Software Industry: Companies, Models, and Opportunities

Mir Mursalin Ankur — Thu, 15 Jan 2026 19:19:47 +0000

When you think about software outsourcing destinations, Bangladesh probably isn't the first name that comes to mind. But it should be.

Beside the Bay of Bengal, this country of 170 million people has built a diverse software ecosystem with companies doing remarkable work—from government systems that serve millions to products used by British Council and ACCA for global examinations.

Let me walk you through the companies, what they actually do, and the business models that work.

The Industry at a Glance

Current State (2024-2025):

$1.3 billion+ in annual ICT exports
$840 million in official software export revenue (FY 2023-24)
4,500+ registered IT/software companies
400,000+ professionals employed
Exports to 80+ countries worldwide

Growth:

From $26 million in 2008 to over $1 billion today—a 40x increase in 16 years

Why Bangladesh's Software Industry Exists

Bangladesh has pulled off something remarkable over the past fifteen years. The government made a deliberate bet on IT services as an export industry, offering tax breaks, building infrastructure, and pushing digitization across public services. The result? An industry that went from essentially nothing to generating over a billion dollars annually.

Here's what makes the model work: Bangladesh offers highly skilled English-speaking developers at competitive rates that deliver exceptional value. A senior software engineer in Dhaka might earn 100,000+ taka monthly (roughly $900+)—professional compensation that enables access to world-class engineering talent at reasonable investment levels.

For American or European companies, the value proposition is compelling. You're not "saving money"—you're accessing talented engineers who bring strong technical skills, problem-solving abilities, and dedication to building quality products. The time zone works perfectly too—Bangladesh is well-positioned for both European and US clients, enabling real-time collaboration when needed.

This created multiple distinct types of software businesses beyond just traditional outsourcing. Let's break them down.

The Complete Business Model Breakdown

Looking across Bangladesh's software landscape, you can categorize companies into seven main business models—not just the two or three most people talk about:

Business Model	% of Industry	Description	Top Companies
Pure Outsourcing	40%	Provide developers/teams to international clients on time-and-materials or fixed-price projects	Brain Station 23, BJIT, Cefalo, Enosis, Vivasoft
Government Contracts	15%	Specialize in public sector projects, national infrastructure, digitization initiatives	Datasoft, Tiger IT, OrangeBD, Tappware, SoftBD
Product Companies	12%	Build and sell own software (SaaS, licenses, marketplace products)	BDTask, Ollyo, REVE Systems, NerdDevs
Hybrid Models	8%	Combine client work with own products for diversification	Brain Station 23, NerdDevs, Kaz Software
Tech Startups	10%	VC-backed growth companies building consumer/enterprise platforms	bKash, Pathao, ShopUp, Chaldal, Shikho
Embedded Systems	5%	Firmware, IoT, hardware-software integration for electronics/devices	Samsung R&D, BJIT Embedded, Teton Electronics
Freelance-to-Company	6%	Companies that started as freelancers on Upwork/Fiverr and grew into agencies	Hundreds of small agencies across Dhaka/Chittagong
Digital Services	4%	Software + SEO, content marketing, social media management	Bizcope, Red Sparrow Digital, HYPE DHAKA

Let's dive into each category with the major players you need to know.

The Government Contract Giants

Datasoft Systems Bangladesh Limited

Website: https://datasoftbd.com
Founded: 1998
Employees: 300+
Certification: CMMI Level 5 (first in Bangladesh)

Datasoft was the first mover in Bangladesh's software industry, and they focused on something many others avoided—government contracts. That turned out to be prescient.

Walk into any government office in Bangladesh and there's a decent chance you'll encounter Datasoft's work. They built the national ID system, the e-passport system, biometric registration systems for multiple agencies, voter registration platforms, and border control infrastructure. These aren't small projects—they're nation-building scale, often worth tens or hundreds of millions of taka.

Their flagship commercial product, Microfin 360 (launched 2008), targets microfinance institutions and NGOs. Given Bangladesh's massive microfinance sector (pioneered by Grameen Bank), this was smart positioning. The product has since expanded across the region to Nepal, Bhutan, Canada, and India.

What Datasoft understood early was that government contracts, while bureaucratic and sometimes slow-paying, provide stable long-term revenue. Once you're embedded in a ministry's infrastructure, replacement becomes politically and technically difficult. That stickiness matters.

Salary Range: 30,000-180,000 taka/month+ for software engineers

Tiger IT Bangladesh Limited

Website: https://www.tigerit.com
Founded: 2006
Employees: 100+
Specialization: Biometric and identity management

If Datasoft is the generalist in government contracts, Tiger IT is the specialist. They focus almost exclusively on security, identity management, and biometric systems—the stuff that requires security clearances and deep technical expertise.

This is the company government agencies call when they need fingerprint identification systems, automated fingerprint identification systems (AFIS), facial recognition, or secure document management. Their client list includes defense and security agencies, which means many of their projects aren't publicly discussed.

Tiger IT has carved out a defensible niche. Biometric systems aren't something you can easily commodity outsource—they require specialized knowledge, security protocols, and trust.

Salary Range: 90,000-180,000 taka/month+ for software engineers

The Government Contract Controversy

No discussion of Bangladesh's software industry is complete without addressing the elephant in the room: government procurement controversies.

Between 2019 and 2024, the a2i (Aspire to Innovate) project—a major government digitalization initiative supported by UNDP—procured software through 46 separate contracts. An investigation found that just four companies received 23 of those 46 contracts (50%).

The companies were:

Tappware Solutions: 6 contracts
SoftBD: 6 contracts
Business Automation Limited: 6 contracts
OrangeBD (Orange IT): 5 contracts

Allegations emerged of a "syndicate" where procurement conditions were allegedly tailor-made to benefit specific companies. This isn't unique to Bangladesh—government tech procurement is notoriously prone to corruption globally. But it illustrates why some companies focus intensely on government contracts while others avoid them entirely.

The International Outsourcing Leaders

Brain Station 23

Website: https://brainstation-23.com
Founded: 2006
Employees: 800+ (700+ software engineers)
Certifications: CMMI Level 3, ISO 9001, ISO 27001 Projects Completed: 2,000+

If you had to pick one company that represents Bangladesh's software ambitions, it's probably Brain Station 23. They're the largest by headcount, the most diverse in services, and have the strongest international presence with offices in the USA, UK, Australia, Nigeria, and across Europe and the Middle East.

Brain Station 23 does everything. Banking and fintech (they built CityTouch for City Bank, which processes over $3 billion in transactions), e-commerce platforms (the Shwapno supermarket system), ERP implementations (official Odoo partner), learning management systems (Moodle partner with their own Proctoring Pro product), AI and machine learning solutions, AR/VR, mobile apps—the list goes on.

Their client roster reads like a who's who: PayPal, Nissan, British Telecom, Unilever, City Bank, AB Bank, HSBC Bangladesh, MetLife, Grameenphone, Robi, BAT Bangladesh, and multiple pharmaceutical companies.

What makes Brain Station 23 interesting is their hybrid model:

~50% international outsourcing
~30% own product development (like Intellifriend, their AI time-tracking app)
~20% local enterprise solutions

Salary Range: 60,000-220,000 taka/month+ for software engineers

BJIT Group

Website: https://bjitgroup.com
Founded: 2007
Employees: 800+
Specialization: Japanese market

BJIT took a different approach—instead of trying to serve everyone, they became the go-to partner for Japanese companies. About 80% of their work comes from Japan, with the rest split between Singapore and other markets.

This specialization makes sense. The Japanese market is huge, culturally specific, and historically underserved by South Asian outsourcing. Companies like BJIT that invest in understanding Japanese business culture, communication styles, and quality expectations can command premium rates.

Salary Range: 30,000-220,000 taka/month+ for software engineers

Cefalo Bangladesh Ltd.

Website: https://www.cefalo.com
Specialization: Norwegian market

Like BJIT with Japan, Cefalo focused almost exclusively on Norway. They provide full-time capable developers to Norwegian businesses and have built a reputation as one of the best workplaces in Bangladesh.

The salaries reflect Norwegian client budgets:

Salary Range: 65,000-220,000 taka/month+ (senior engineers can earn 185,000-220,000 taka)

That senior engineer salary is exceptional for Bangladesh—roughly $1,700-$2,000/month. Competitive value for Norwegian clients while representing top-tier local compensation.

Enosis Solutions

Website: https://enosisbd.com
Founded: 2010
Employees: 200+
Focus: US and European markets

Enosis went the American and European route, focusing on web and mobile application development, cloud solutions, and IT consulting using agile methodologies. About 70% of revenue comes from US clients, 20% from Europe, 10% elsewhere.

Salary Range: 50,000-220,000 taka/month+ (well-structured career ladder with clear levels)

Vivasoft Limited

Website: https://vivasoftltd.com
Founded: 2010
Employees: 300+ (180+ dedicated engineers)
Focus: Team augmentation and offshore office setup

Vivasoft positioned themselves uniquely—instead of just doing custom development, they focus on team augmentation (providing dedicated developers to extend existing teams) and helping companies set up full offshore offices in Bangladesh.

Salary Range: 25,000-220,000 taka/month+ for software engineers

Selise Digital Platforms

Website: https://selisegroup.com
Revenue: ~$37.9 million
Headquarters: Zürich, Switzerland (with Bangladesh operations)
Ranking: #2 Top Software Company in Bangladesh 2025

Selise is a global IT delivery organization with significant Bangladesh operations. They specialize in advanced computing, AI, data science, and digital platform creation. As a "Swiss tech partner for digital transformation," they bring European quality standards to Bangladeshi talent.

The Product Companies

NerdDevs

Website: https://nerddevs.com
Product Website: https://biddaan.com
Founded: 2015
Employees: 20+ (small but impactful)
Specialization: EdTech and messaging solutions

NerdDevs represents a different model—staying small, focusing intensely on specific problems, and building both client work and own products simultaneously.

Their flagship partnership achievement is TestReach, an online assessment platform that ACCA (Association of Chartered Certified Accountants), British Council, CIPS, and iSQI use for global examinations. If you've taken a professional certification exam in the UK, there's a decent chance NerdDevs wrote part of the software.

They also built Genius and other messaging apps, which are mostly used in the US market that handles 4-5 million messages monthly—managing that volume reliably requires serious engineering.

For the Bangladesh market, their major products include:

Biddaan (https://biddaan.com) - Their flagship Learning Management System specifically designed for Bangladeshi & International educational institutions. It handles student tracking, progress notes, institution management, and the full administrative stack educational organizations need. The interface is multilingual, which matters—most LMS solutions are English-only, creating barriers for local schools.

Salary Range: 30,000-220,000 taka/month+ for software engineers

BDTask Limited

Website: https://www.bdtask.com
Focus: Ready-made software products

While most Bangladeshi companies do client work, BDTask went the opposite direction—they build ready-made software and sell it globally through marketplaces like Envato.

Their product catalog includes accounting software, inventory management, POS systems, school management, hospital management, hotel management, restaurant management, HR and payroll systems—basically every business management need you can think of.

This is a different business model entirely. Instead of getting paid for hours worked or projects completed, they sell licenses—think $50-$500 per copy, with customers in Europe, North America, and Southeast Asia buying directly.

Ollyo (MuktoSoft)

Website: https://ollyo.com
Founded: 2010
Focus: WordPress and Joomla ecosystem

Ollyo took a similar product approach but focused narrowly on WordPress plugins, themes, Joomla extensions, and open-source tools. They're an Envato partner, meaning their products sell through Envato's massive marketplace.

Products include WordPress plugins, Joomla templates, no-code website builders, e-learning platforms, e-commerce solutions, and a free open-source icon library. Some of their work is used by thousands of websites globally.

REVE Systems Ltd.

Website: https://www.revechat.com
Focus: VoIP and communications platform software

REVE Systems built telecommunications software—VoIP platforms, communication tools, and enterprise communications solutions used globally. This is highly specialized work requiring understanding of telecommunications protocols, real-time communication, and handling large-scale voice/video traffic.

Salary Range: 50,000-150,000 taka/month+ for software engineers

The Embedded Systems & IoT Specialists

This is a specialized but critical segment of Bangladesh's software industry—companies working on firmware, embedded systems, IoT solutions, and hardware-software integration. These engineers bridge the gap between software code and physical devices.

Samsung R&D Institute Bangladesh (SRBD)

Website: https://research.samsung.com/srbd
Founded: February 2011
Focus: Embedded systems, IoT, cellular modem technology

Samsung chose Bangladesh for its first-ever R&D hub in the country—a strong endorsement of the local engineering talent. SRBD works on cutting-edge embedded systems including cellular modem systems, IoT hardware, and intelligent embedded devices.

What they work on:

Embedded software and systems engineering
Cellular modem systems development
IoT hardware and connectivity systems
Firmware for Samsung's global product line

Why it matters: When Samsung—one of the world's largest electronics companies—sets up an R&D center in your country, it's a validation of your engineering talent. SRBD employs some of Bangladesh's most skilled embedded systems engineers working on products used globally.

Teton Electronics / Teton Private Ltd.

Website: https://tetonelectronics.com
Focus: Firmware development and embedded systems services

Teton Electronics provides comprehensive firmware development services, including:

Programming and updating embedded firmware
Integration for different types of microcontrollers and processors
Hardware-software integration solutions
Custom embedded systems design

They work across various industries requiring specialized firmware solutions—from consumer electronics to industrial applications.

BJIT Embedded Systems Division

Website: https://www.bjit.co.jp
Focus: IoT & Embedded Engineering

BJIT, known for its Japanese market specialization, has a dedicated embedded systems division offering:

IoT & Embedded Engineering
Embedded Application Development
Mechanical Design
Hardware-software integration

Their Japanese clients demand precision and reliability—qualities that have driven BJIT to develop strong embedded systems capabilities.

Subra Systems Limited

Specialization: Embedded systems and industrial automation

Subra Systems focuses on embedded solutions for industrial applications, where reliability and real-time performance are critical. They work on automation systems, control systems, and industrial IoT solutions.

SIMEC System Ltd.

Specialization: Embedded systems and firmware development

SIMEC provides embedded systems services across various sectors, working on firmware design, implementation, and optimization for different hardware platforms.

Ninos IT Solution

Website: https://www.ninositsolution.com
Specialization: Cutting-edge embedded systems design

Ninos IT Solution specializes in designing and developing embedded systems with seamless integration capabilities. They work on projects requiring deep hardware and software knowledge.

The Embedded Systems Job Market:
The demand for embedded systems engineers in Bangladesh is substantial, with approximately 2,921 embedded systems job openings listed on major job portals. Skills in high demand include:

Embedded software engineering
IoT development
LoRaWAN device development
Firmware design and implementation
Hardware-software integration
Robotics and automation

Salary Ranges: 60,000-180,000 taka/month+ for embedded systems engineers (higher due to specialized skills)

Why Embedded Systems Matter:
As the world becomes more connected with smart devices, IoT sensors, and intelligent electronics, embedded systems expertise becomes increasingly valuable. Bangladeshi companies are positioning themselves to serve this growing global market with skilled engineers who understand both hardware and software.

The Tech Startup Scene (The Real Growth Engine)

bKash

Industry: Mobile Financial Services
Ranking: #3 Top Startup in Bangladesh

bKash isn't just a startup—it's practically a utility. As Bangladesh's leading mobile financial services provider, bKash has transformed how millions of Bangladeshis send, receive, and store money. With international investment and attention, bKash has attracted significant funding and become one of Bangladesh's most successful tech exports.

Pathao

Founded: 2015
Founders: Hussain Elius, Shifat Adnan, Fahad
Ranking: #6 Top Startup in Bangladesh

Pathao is Bangladesh's "super-app" offering:

Ride-sharing services (bikes, cars, cycles)
Food delivery
Logistics and parcel delivery
Created over 300,000 jobs in eight years
Serving 60,000 small businesses
Over 8 million users

Salary Range: 65,000-180,000 taka/month+ for software engineers

ShopUp

Ranking: #1 Startup in Bangladesh

ShopUp focuses on B2B commerce platform, helping small retailers and businesses source inventory. As Bangladesh's top-ranked startup, ShopUp has attracted significant investor attention and represents the maturation of Bangladesh's startup ecosystem.

Chaldal

Industry: E-commerce grocery

Chaldal has revolutionized grocery shopping in Bangladesh's major cities with its online grocery platform. They've built sophisticated logistics technology and inventory management systems that compete with international players.

Salary Range: 70,000-180,000 taka/month+ for software engineers

Other Notable Startups:

Shikho - EdTech platform
Arogga - Healthcare/medicine delivery
PriyoShop Retail - B2B retail platform
Shohoz - Transportation and logistics

Startup Ecosystem Growth:

Bangladesh's startup investment grew 1,116% year-over-year to $119.9 million in H1 2025
698+ top startups currently operating
Middle class growing at 10% per annum to reach 34 million by 2025

2024 Startup Investments That Matter:

Sombhab (tech startup): $1 million investment from Singapore's Cocoon Capital
Blue-Tech: $100,000+ foreign investment
Bangladesh Startup Summit 2024: July 27-28 at Bangladesh Computer Council, theme "Smart Bangladesh, Limitless Possibilities"
AdTech Recognition: 7 Bangladeshi EdTech startups ranked in South Asia's top 100

The Freelance-to-Company Model (Hidden Giants)

This is the category nobody talks about but it's MASSIVE. Hundreds of software companies in Bangladesh started as individual freelancers on Upwork, Fiverr, Freelancer.com, and oDesk (now Upwork).

Here's how it works:

Developer starts freelancing on Upwork/Fiverr while in university or early career
Builds reputation, gets 5-star reviews, starts earning $2,000-$5,000/month
Gets more work than they can handle alone
Hires friends/junior developers
Registers a company
Continues taking contracts through platforms + direct clients

Characteristics of these companies:

5-50 employees typically
Heavy focus on web development (WordPress, Laravel, React, Node.js)
Strong presence on Upwork, Fiverr, Freelancer.com
Often specialize in specific niches (e-commerce sites, real estate portals, booking systems)
Salaries: 20,000-150,000 taka/month+ typically
Revenue: $50,000-$500,000 annually for established agencies

Why this model works:

Low barrier to entry (no sales team needed—platforms bring clients)
International clients from day one
Payment security through platforms
Can build reputation faster than cold outreach

Notable platforms used:

Upwork (most popular for software development)
Fiverr (quick projects, WordPress fixes, small websites)
Freelancer.com (competitive bidding model)
PeoplePerHour, Guru (alternative platforms)

Digital Marketing + Software Companies

A growing category of companies combines software development with digital marketing services. These companies often build websites, then handle SEO, content creation, social media marketing, and paid advertising for clients.

Leading Digital Marketing Agencies:

Bizcope (https://www.bizcope.com/)

Global SEO and digital marketing agency
Services: SEO, web development, content production, 360-degree digital marketing

Red Sparrow Digital (https://www.redsparrowdigital.com/)

Full-stack digital marketing agency
Web design & development, SEO, comprehensive marketing solutions

HYPE DHAKA

Communications agency
Services: SEO, email marketing, social media marketing, website development
100% positive client reviews according to Clutch.co

Marketorr

One of the fastest-growing digital marketing agencies
Deep SEO expertise and full-funnel marketing strategies

Implevista (https://digital.implevista.com/)

Expert SEO, PPC, and social media marketing (SMM) solutions

Why this model matters:
Many Bangladeshi businesses don't just need software—they need the complete digital package. These companies provide that integrated solution, often at competitive rates compared to Western agencies.

Salary Comparison: The Real Numbers

Let me give you the unvarnished truth about salaries in Bangladesh's software industry. These are ranges based on current market data (2024-2025):

By Experience Level:

Level	Salary Range (BDT/month)	Salary Range (USD/month)
Trainee/Intern	0-15,000	$0-135
Junior Developer (0-2 years)	20,000-45,000	$180-405
Software Engineer (2-5 years)	50,000-80,000	$450-720
Senior Engineer (5+ years)	100,000-220,000	$900-1,980
Tech Lead/Principal	165,000-300,000	$1,485-2,700

By Company Type:

Company Type	Junior	Mid-Level	Senior
Local Outsourcing	25,000-35,000	50,000-70,000	100,000-150,000
Western Outsourcing (Cefalo, Enosis)	50,000-80,000	70,000-130,000	185,000-220,000
International Companies (Optimizely, Cheq)	70,000+	120,000+	250,000-300,000
Tech Startups (Pathao, Chaldal)	65,000+	70,000-100,000	155,000-220,000
Product Companies	30,000-50,000	60,000-90,000	100,000-220,000

Key Observations:

1. The Entry-Level Reality:
Many companies pay trainee and intern positions 0-10,000 taka monthly (effectively free or near-free labor). It's controversial but common—companies view it as paid training rather than productive work.

2. The International Company Premium:
Companies with international headquarters pay significantly more:

Optimizely: Senior Software Engineer at 250,000-300,000 taka/month+
Cheq Inc.: Senior QA Automation Engineer at 180,000-300,000 taka/month+
Tero Labs: Engineer at 120,000-150,000 taka/month+

3. The Startup Competitiveness:
Local tech companies (Pathao, Chaldal) pay competitively because they compete directly with international employers for talent.

4. Remote Work Premium:
Engineers working remotely for international companies earn substantially more:

~$41,465 (average for remote software developers in Bangladesh)
~$46,135 (median annual salary for remote software engineers)
That's 2-4x higher than local salaries

The Complete Company Directory

Government & Enterprise Solutions

Datasoft Systems Bangladesh: https://datasoftbd.com - CMMI Level 5, government contracts specialist
Tiger IT Bangladesh: https://www.tigerit.com - Biometric and security systems
Southtech Limited: https://www.southtech.com.bd - Banking and ERP solutions
LeadSoft Bangladesh: Financial and insurance platforms

International Outsourcing Leaders

Brain Station 23: https://brainstation-23.com - Largest diversified player, 800+ employees
Selise Digital Platforms: https://selisegroup.com - #2 ranked, Swiss-Bangladeshi operations, $37.9M revenue
BJIT Group: https://bjitgroup.com - Japan market specialist
Cefalo Bangladesh: https://www.cefalo.com - Norway market specialist
Enosis Solutions: https://enosisbd.com - US/Europe agile development
Vivasoft Limited: https://vivasoftltd.com - Team augmentation and offshore setup

Product Companies

NerdDevs: https://nerddevs.com - EdTech and messaging solutions
- Biddaan LMS: https://biddaan.com - Learning management system for Bangladesh
BDTask Limited: https://www.bdtask.com - Ready-made software products
Ollyo (MuktoSoft): https://ollyo.com - WordPress/Joomla ecosystem
REVE Systems: https://www.revechat.com - VoIP and communications platforms

Embedded Systems & IoT Companies

Samsung R&D Institute Bangladesh: https://research.samsung.com/srbd - Embedded systems, IoT, cellular modem (founded 2011)
Teton Electronics: https://tetonelectronics.com - Firmware development and embedded systems services
BJIT Embedded Systems: https://www.bjit.co.jp - IoT & Embedded Engineering
Subra Systems Limited: Embedded systems and industrial automation
SIMEC System Ltd.: Embedded systems and firmware development
Ninos IT Solution: https://www.ninositsolution.com - Cutting-edge embedded systems design

Tech Startups (Growth Stage)

bKash: https://www.bkash.com - Mobile financial services (#3 startup)
Pathao: https://pathao.com - Super-app: ride-sharing, food delivery, logistics (#6 startup)
ShopUp: #1 ranked startup - B2B commerce platform
Chaldal: https://chaldal.com - E-commerce grocery
Shikho: EdTech platform
Arogga: Healthcare/medicine delivery
PriyoShop Retail: B2B retail platform
Shohoz: Transportation and logistics

Digital Marketing + Software Agencies

Bizcope: https://www.bizcope.com - SEO, web development, content production
Red Sparrow Digital: https://www.redsparrowdigital.com - Full-stack digital marketing
HYPE DHAKA: SEO, email marketing, social media marketing
Marketorr: Fastest-growing digital marketing agency
Implevista: https://digital.implevista.com - SEO, PPC, SMM solutions

Smaller Specialists

Kaz Software: https://www.kaz.com.bd - Enterprise custom development
Nascenia Limited: https://www.nascenia.com - SaaS product engineering
Dynamic Solution Innovators: https://www.dsibd.com - E-commerce and ERP
Dream71 Bangladesh: Mobile games and creative apps
PipilikaSoft: Education management systems
Dcastalia Limited: Top 10 ranked software company

Government Contractors (Under Investigation)

OrangeBD (Orange IT): Infrastructure and cybersecurity
Tappware Solutions: Software development and maintenance
SoftBD: Software development services
Business Automation Limited: Process automation solutions

International Companies with Bangladesh Operations

Optimizely Bangladesh: Global optimization platform office
Samsung R&D Bangladesh: Samsung research and development
Cheq Inc.: Cybersecurity platform

IT Training Institutes

BASIS Institute of Technology & Management (BITM): bitm.org.bd
Creative IT Institute: Web development, MERN stack, digital marketing
Dewan ICT Institute: #1 ranked IT training institute
European IT Institute: Professional IT training, Dhanmondi
Softopark IT Institute: Career-boosting IT programs

Resources

BASIS (Bangladesh Association of Software & Information Services): https://basis.org.bd - Industry association
DoICT (Directorate of ICT): https://doict.gov.bd - Government ICT initiatives
Salary Data: https://tahanima.github.io/salary-ranges-offered-by-bangladeshi-software-companies-for-different-positions/

What This All Means

Bangladesh's software industry has reached an interesting inflection point. The early stage of just doing outsourcing for international clients is maturing into something more sophisticated.

Companies like Brain Station 23, NerdDevs, and Selise show it's possible to move up the value chain—not just writing code someone else specifies, but building products, solving complex problems, and working with prestigious international clients. TestReach (NerdDevs' platform) being used by British Council and ACCA isn't just outsourcing—it's being the technical partner for critical global infrastructure.

The government digitalization push, despite procurement controversies, created a domestic market for software. Companies like Datasoft and Tiger IT built genuinely hard technology (national ID systems, biometric platforms) that required serious engineering.

The product companies (BDTask, Ollyo, Biddaan) demonstrate that Bangladeshi developers can compete globally in marketplaces and create solutions used by thousands of businesses and schools.

The startup ecosystem (bKash, Pathao, ShopUp, Chaldal) shows that world-class consumer platforms can be built from Bangladesh for Bangladesh—and eventually for emerging markets globally.

But challenges remain real. Salaries lag far behind international standards. A "senior" engineer in Bangladesh earning $2,000/month would be entry-level pay in the US or Europe. This creates brain drain—talented developers leave for opportunities abroad. Companies struggle to retain their best engineers once they get two-three years experience and realize their market value elsewhere.

Infrastructure issues persist. Power grid losses, internet reliability in secondary cities, and reliance on Dhaka for most operations limit growth. The skills gap in advanced technologies (AI, machine learning, blockchain) means many companies can't compete for cutting-edge work.

The procurement corruption allegations around government contracts raise questions about whether that sector is sustainable long-term without serious reform.

Still, the trajectory is impressive. From essentially nothing twenty years ago to a billion-dollar industry employing hundreds of thousands, with serious companies working on real problems for real international clients—that's meaningful progress.

The Future: Where Bangladesh's Software Industry Is Headed

The software industry Bangladesh built over fifteen years is real, substantial, and growing. It's not Silicon Valley, and it's not trying to be. It's something different—a developing country using its advantages (cost, talent, English proficiency) to build an export industry while simultaneously digitizing its own economy.

What to watch in 2026-2030:

AI and ML Adoption: As global demand for AI talent explodes, Bangladesh's value proposition could drive growth—if the skills gap can be addressed
Startup Exits: Bangladesh has yet to see a major IPO or acquisition. When bKash, Pathao, or ShopUp exit, it will unlock capital and validate the ecosystem
Government Reform: If procurement becomes transparent and merit-based, government contracts could drive sustainable growth rather than creating dependencies
Regional Expansion: Bangladeshi companies are well-positioned to serve other emerging markets in South Asia, Southeast Asia, and Africa
Remote Work: As remote work becomes normalized, Bangladeshi developers can work directly for international companies at international rates—reducing brain drain
Product Success: BDTask, Ollyo, and NerdDevs are showing that products can scale. More success stories here could shift the industry from services to products
Freelance Professionalization: The freelance-to-company pipeline will likely formalize, creating more sustainable agencies rather than individual freelancer outfits

The story of Bangladesh's software industry isn't just about affordable services. It's about a country leveraging its human capital to participate in the global digital economy. It's about companies like Datasoft building national infrastructure, NerdDevs powering global examinations, and Pathao transforming transportation.

It's about 400,000 professionals building their futures one line of code at a time.

That's a story worth paying attention to.

References

Industry Statistics & Market Data

Salary & Compensation Data

Company Rankings & Lists

Startup Ecosystem

Digital Marketing Agencies

Outsourcing Comparisons

Freelance & Marketplace Resources

Embedded Systems & IoT

Government & Policy

Company Reviews & Salary Data (Bangla Sources)

Academic & Research

This blog is based on publicly available information as of January 2026. Company details, salaries, and situations may change. All salary figures are approximate based on employee reports and job postings.

End

That's all!

I hope you've found the article useful. I'll write more about the software engineering and it's business ecosystem. Feel free to share your thoughts.

Check more on

The Complete Guide to Software Business Models: How Tech Companies Actually Make Money

Mir Mursalin Ankur — Sat, 10 Jan 2026 15:03:06 +0000

If you've ever wondered how your favorite apps stay free, why some software charges monthly while others are one-time purchases, or how tech giants like Google and Apple structure their businesses, you're in the right place.

The software industry has evolved far beyond simple "buy once, use forever" models. Today's tech landscape features dozens of sophisticated business models, each designed to solve specific problems and create value in unique ways. Understanding these models isn't just for entrepreneurs—it helps you make smarter decisions as a consumer, investor, or anyone navigating the digital economy.

Let's break down the most important business models shaping the software world today.

The Foundation: Core Business Model Families

Think of these as the main categories that most tech businesses fall into. While companies often mix and match elements, understanding these fundamentals helps you see the bigger picture.

Subscription: The Predictable Revenue Machine

Remember when you bought Microsoft Office once and used it for years? Those days are largely gone. The subscription model has become the dominant force in software, and for good reason—it works incredibly well for both companies and customers.

Here's how it works: instead of paying a large upfront fee, you pay a smaller amount regularly—usually monthly or annually. Netflix pioneered this for entertainment, but it's everywhere now. Adobe Creative Cloud, Spotify, Microsoft 365, and thousands of business software tools all use subscriptions.

Why did this model take over? For companies, it creates predictable, recurring revenue. Instead of hunting for new customers every month, they can focus on keeping existing ones happy. A company with 10,000 subscribers paying $10 monthly knows it has roughly $100,000 coming in next month, making planning and investment much easier.

For customers, the benefits are real too. Lower upfront costs mean less risk when trying new software. You're not committing $500 upfront—maybe just $10 for the first month. Plus, subscriptions typically include automatic updates, cloud storage, and customer support. The software company stays invested in keeping you happy because if you cancel, their revenue drops.

The numbers tell the story. A well-run subscription business might see 90-95% of customers renew each year. That compounds powerfully over time. After three years, a company might still have 75% of its original customers, all while adding new ones. This creates what investors call an "annuity stream"—revenue that keeps flowing with less effort over time.

Freemium: The Generous Hook

Freemium is everywhere, even if you don't realize it. The name combines "free" and "premium"—give away the basic product for free, then charge for advanced features.

Think about Spotify, Canva, or Slack. All offer genuinely useful free tiers that millions of people use daily without ever paying. But eventually, enough users hit limitations that matter to them—whether it's offline listening, premium templates, or message history—and convert to paid plans.

The economics seem counterintuitive at first. How can you make money giving away your product? The key is that digital products have near-zero marginal cost. Serving one more free user costs almost nothing—no manufacturing, shipping, or materials. So if you can convert even 2-5% of free users to paying customers, the math works beautifully.

Dropbox famously grew this way. They gave everyone 2GB of free storage—enough to be useful, but eventually, most people needed more. Some users upgraded immediately, others took years, but the free tier kept them engaged the whole time. Today, Dropbox has millions of paying customers who started with that free 2GB.

The challenge is finding the right balance. Make the free tier too generous, and no one upgrades. Make it too restrictive, and people never experience the value. The best freemium products hook users with the free tier, then create natural "aha moments" that drive upgrades.

Transaction and Commission: Taking a Cut

Some of the world's largest tech companies don't sell software at all—they connect buyers and sellers and take a percentage of each transaction.

Airbnb doesn't own hotels. Uber doesn't own cars. Etsy doesn't make crafts. But they've built billion-dollar businesses by creating marketplaces where transactions happen, then taking a slice of each one.

The magic of this model is that it scales with customer success. When an Airbnb host makes more money, Airbnb makes more money. When Stripe processes more payments for businesses, Stripe earns more. The incentives align perfectly.

Transaction rates vary widely. Stripe and PayPal charge around 2.9% plus 30 cents per transaction. Airbnb takes about 3% from hosts and 14% from guests. The App Store and Google Play take 15-30% of app sales. These percentages might seem small, but when you're processing billions in transactions, they add up fast.

The tricky part is reaching critical mass. A marketplace with few buyers won't attract sellers, and vice versa. This "chicken and egg problem" means transaction-based businesses often operate at a loss initially, subsidizing one or both sides to build momentum. Once they reach critical mass, though, network effects create powerful moats—the more users join, the more valuable the platform becomes, attracting even more users.

Advertising: Free for Users, Paid by Brands

If you're not paying for the product, you are the product. This saying captures the advertising model perfectly.

Google Search, Facebook, Instagram, YouTube, and most of the internet you use daily are free because advertisers pay for your attention. These companies have gotten incredibly sophisticated at targeting ads based on your behavior, demographics, and interests, making those ads more valuable to advertisers.

The numbers are staggering. Google made over $200 billion from ads in 2023. Meta (Facebook/Instagram) made another $130 billion. These aren't small businesses with ads on the side—advertising IS their business.

For this model to work, you need massive scale. A blog with 1,000 readers might make a few dollars from ads. A platform with 100 million users makes millions. That's why ad-supported businesses focus obsessively on growth and engagement—more eyeballs and more time spent equals more ad revenue.

The model has its critics. Privacy concerns have grown as tracking becomes more sophisticated. Regulations like GDPR in Europe are forcing changes. And users increasingly turn to ad blockers or paid ad-free alternatives. Still, for many services—particularly social media—advertising remains the dominant model because users won't pay directly.

Pay-As-You-Go: Usage-Based Pricing

Some software charges based on exactly what you use, like your electricity bill. This usage-based model has exploded with cloud computing.

Amazon Web Services (AWS), the backbone of much of the internet, bills by the computing power, storage, and bandwidth you consume. Use more, pay more. Use less, pay less. The same applies to Twilio (charged per text message or phone call), Stripe (per transaction), and many developer tools.

This model aligns costs with value better than almost anything else. A startup spending $100 monthly on AWS can scale to $100,000 when they grow, without renegotiating contracts or switching providers. The pricing grows naturally with their business.

For customers, it removes the fear of overpaying. You're never paying for capacity you don't need. For companies, it means revenue automatically scales with customer success—a win-win.

The downside is unpredictability. Companies can't forecast usage-based revenue as easily as subscriptions. A customer might spend $1,000 one month and $5,000 the next. This variability makes planning harder. Many companies now combine fixed subscriptions with usage-based pricing to balance predictability and flexibility.

Marketplaces: Connecting Supply and Demand

Marketplaces are fascinating because they create value without creating products. eBay doesn't manufacture goods. Upwork doesn't do the freelance work. Airbnb doesn't provide the accommodations.

Instead, they build platforms that reduce friction between buyers and sellers. They handle payments, build trust through reviews, provide insurance, and create discovery mechanisms. This infrastructure is valuable enough that both sides willingly pay fees.

The best marketplaces solve real pain points. Before Airbnb, renting your apartment to strangers was risky and complicated. Before Uber, hailing a cab in many cities was frustrating. The marketplace didn't just connect supply and demand—it made transactions trustworthy and convenient.

Two-sided marketplaces face unique challenges. You need enough supply to attract demand and enough demand to attract supply. Successful marketplaces often subsidize one side initially. Uber spent billions on driver incentives to ensure riders could always find a car. Once established, network effects made the platform nearly impossible to displace.

Open Source and Open Core: The Generosity Paradox

Some of the most valuable software companies give away their core product for free—completely free, not freemium. How does that work?

The open-core model releases the basic software as open source (anyone can use, modify, and see the code for free) but charges for enterprise features, support, or managed services.

GitLab is a perfect example. Their core product is free and open source. Millions of developers use it daily without paying a cent. But large companies pay substantial fees for advanced features like enterprise security, compliance tools, and dedicated support.

This model builds massive adoption and community goodwill while still generating revenue from those who need enterprise capabilities. It's particularly effective for developer tools because developers love open source and will advocate for tools they already use when their companies need to make purchasing decisions.

Red Hat pioneered this model with Linux, eventually selling to IBM for $34 billion. MongoDB, Elastic, and many others have followed similar paths. The key is offering enough value in the free version to drive adoption while reserving genuinely valuable enterprise features for paying customers.

Quick Reference: Business Model Comparison

Here's a comprehensive comparison of the major software business models to help you quickly understand their key differences:

Model	Revenue Structure	Best For	Pros	Cons	Examples	Key Metrics
Subscription	Recurring monthly/annual fees	Products with ongoing value, sticky workflows	Predictable revenue, customer retention, compounding growth	Churn management, subscription fatigue	Netflix, Spotify, Adobe CC, Microsoft 365	MRR, ARR, Churn, LTV, NRR
Freemium	Free tier + paid upgrades	Products that scale with usage/team size	Low friction acquisition, viral growth, large user base	Low conversion (2-5%), high support costs for free users	Spotify, Canva, Slack, Dropbox	Free-to-paid conversion, activation rate, time to convert
Transaction/Commission	% of each transaction	Marketplaces, payment processing, two-sided platforms	Scales with customer success, aligned incentives	Chicken-egg problem, needs critical mass	Uber, Airbnb, Stripe, Etsy, App Store	GMV, take rate, liquidity, active buyers/sellers
Advertising	CPM/CPC from brands	Mass-market consumer products	Free for users drives scale, massive revenue potential	Privacy concerns, ad blockers, regulatory risk	Google, Facebook, YouTube, Instagram	DAU/MAU, engagement time, CPC/CPM, revenue per user
Usage-Based	Pay per unit consumed	Cloud infrastructure, APIs, developer tools	Fair pricing, scales with customer growth	Unpredictable revenue, harder forecasting	AWS, Twilio, Zapier, Stripe	Usage volume, consumption trends, expansion revenue
Marketplace	Fees from buyers/sellers or both	Supply-demand matching, peer-to-peer transactions	Network effects, strong moat at scale	Critical mass challenge, complex trust-building	eBay, Upwork, Airbnb, Uber, Etsy	GMV, take rate, buyer/seller ratio, transaction frequency
Open Core	Free OSS + paid enterprise features	Developer tools, infrastructure software	Community trust, rapid adoption, developer advocacy	Converting OSS users to paid is challenging	GitLab, MongoDB, Red Hat, Elastic	Enterprise conversion rate, community growth, support revenue
API-First	Per-call or % of transaction value	Technical infrastructure, developer platforms	Deep integration, switching costs, usage scales automatically	Technical audience, requires developer trust	Stripe, Twilio, Plaid, SendGrid	API calls, transaction volume, developer adoption
Platform Ecosystem	Multiple revenue streams (hardware + services + subscriptions)	Companies with product breadth	Lock-in, multiple monetization touchpoints, high LTV	Requires huge capital, slow to build, complex coordination	Apple, Google, Microsoft, Amazon	Cross-product adoption, ecosystem retention, ARPU
Creator Economy	% of creator earnings or subscription	Content creator monetization platforms	Aligns with creator success, viral growth	Content moderation, payment processing complexity	Patreon, Substack, YouTube, OnlyFans	Active creators, creator earnings, fan spend per creator
White-Label	Wholesale licensing fees	B2B infrastructure, platform tech	Rapid scaling through partners, reduced CAC	Lower margins, less customer control, brand dilution	WordPress, white-label SaaS	Partner count, reseller revenue, partner retention
Data as Service	Subscription for data access	Companies with unique, valuable data	High margins, recurring revenue, defensible	Privacy/ethics concerns, data quality maintenance	Bloomberg, weather services, analytics platforms	Data accuracy, subscriber count, data refresh rate

Choosing Based on Your Situation

Your Situation	Recommended Model(s)	Why
Consumer app, viral potential	Freemium + Ads	Low barrier, mass scale required
B2B software, clear ROI	Subscription (tiered)	Predictable revenue, willingness to pay
Marketplace idea	Transaction/Commission	Scales with transaction volume
Developer tool	Open Core + API/Usage	Developers prefer OSS, enterprises pay for support
Infrastructure/technical	Usage-based/API	Fair pricing, scales naturally
Content/media	Ads + Creator Economy split	Users won't pay directly, creators need monetization
Enterprise focus	Subscription + White-label	High contract values, predictable revenue
Platform vision	Ecosystem approach	Maximize LTV through multiple touchpoints

Revenue Predictability Comparison

High Predictability:  Subscription │────────────────────────────────│ 95%+
                        SaaS Tiered │─────────────────────────│ 90%+

Medium Predictability: Freemium→Sub │──────────────│ 70-80%
                        Usage-Based (large customers) │────────│ 60-70%

Low Predictability:   Usage-Based (small customers) │────│ 50-60%
                        Transaction/Commission │──│ 40-50%
                        Advertising │─│ 30-40%

Customer Acquisition Cost (CAC) Recovery Time

Model	Typical CAC Recovery	Why
Freemium	12-24+ months	Most users never pay, long conversion cycles
Advertising	Immediate (but per-user value is low)	Revenue starts immediately but margins thin
Subscription	6-18 months	Predictable monthly payments accelerate recovery
Usage-Based	3-12 months	Depends on customer adoption speed
Transaction	Varies wildly	Scales with customer transaction volume
Enterprise Subscription	12-36 months	High CAC but large contracts justify it

Specialized Software Business Models

Beyond the main categories, several specialized models have emerged for specific contexts.

Software as a Service (SaaS) Variations

SaaS deserves its own deep dive because it's become the default for business software. But not all SaaS is created equal. Let's look at the main pricing variations.

Flat-rate SaaS charges everyone the same amount—simple but limiting. Basecamp famously charges $99 monthly regardless of team size. This simplicity is refreshing in a world of complex pricing tiers, though it means large companies and small teams pay the same.

Tiered pricing offers multiple plans at different prices. Think Slack's Free, Pro, Business, and Enterprise tiers. This captures more value from customers with different needs and budgets. A startup might pay $8 per user monthly while an enterprise pays $15+.

Per-user pricing scales costs with team size. Most SaaS tools use this—Zoom, Microsoft 365, and thousands of others charge per user per month. It's straightforward and aligns costs with value, though teams sometimes share accounts to save money.

Usage-based SaaS charges for consumption, not seats. Zapier charges based on tasks automated. AWS charges for computing resources used. This works beautifully when value correlates directly with usage.

Many modern SaaS companies use hybrid models, combining elements. You might have a base platform fee, per-user charges, and usage fees for certain features. Complexity increases but so does revenue optimization.

API-First Business Models

APIs (Application Programming Interfaces) have become products themselves. Companies like Stripe, Twilio, and Plaid built billion-dollar businesses by offering APIs that developers integrate into their applications.

Stripe's API makes it incredibly easy to accept payments. Instead of building payment infrastructure from scratch—dealing with banks, fraud prevention, and compliance—developers add a few lines of code and start processing payments immediately. Stripe handles the complexity and charges per transaction.

This model works because it solves hard technical problems and packages them as simple APIs. Developers pay for convenience, reliability, and not having to become experts in payments, communications, or banking infrastructure.

The economics are compelling. Once you build the API infrastructure, serving additional customers costs very little. A company processing $1 million in payments pays the same percentage as one processing $100 million, but Stripe's costs don't increase proportionally. At scale, margins are excellent.

Data as a Service

Some companies have realized their data itself is valuable. Bloomberg built an empire selling financial data. Weather companies sell forecasts to businesses. Analytics platforms sell aggregated insights.

This model requires unique data that others don't have and customers who will pay for it. Bloomberg can charge thousands monthly because traders need real-time market data to make billion-dollar decisions. The value is clear.

The challenge is often privacy and ethics. Companies must aggregate and anonymize data carefully. Selling individual user data creates backlash, but selling anonymized trends and insights can be legitimate and valuable.

White-Label and Licensing

Some software companies don't sell to end users at all—they license their technology to other companies who rebrand and resell it.

WordPress powers 40%+ of the internet, but most users don't know or care. Web hosting companies like Bluehost and GoDaddy offer "WordPress hosting," adding their branding and support. WordPress benefits through ecosystem growth.

White-label SaaS lets companies offer software products without building them. A marketing agency might white-label email marketing software, offering it to clients under their own brand. The underlying software company charges a wholesale rate, and the agency marks it up.

This model scales quickly because each licensing partner becomes a sales channel. The tradeoff is lower margins and less direct customer relationships.

Emerging and Creative Models

Innovation in business models continues. Here are some newer patterns worth understanding.

Platform Ecosystems: Building Worlds, Not Products

The most valuable tech companies don't sell products—they create ecosystems that lock users in through interconnectivity and network effects.

Apple's ecosystem is the classic example. An iPhone works beautifully alone, but add an iPad, MacBook, Apple Watch, and AirPods, and you're deeply embedded. Messages sync across devices. AirPods switch seamlessly between them. Files move effortlessly through AirDrop. Leaving means losing all that integration.

Apple doesn't just sell hardware—they sell the App Store (30% commission), Apple Music (subscription), iCloud storage (subscription), Apple TV+ (subscription), and more. Each product makes the others more valuable. This is ecosystem thinking at its finest.

Google does the same with Android, Chrome, Search, Gmail, Drive, and YouTube. Once you're using several Google services, switching becomes increasingly difficult. Your data, preferences, and workflows are all integrated.

Building ecosystems requires patience and capital. You need multiple products that genuinely work better together. But once established, ecosystems create powerful moats. Customers stay not because they can't leave but because leaving would mean losing substantial value.

Platform Cooperatives: The Democratic Alternative

While most platforms are owned by shareholders seeking maximum profit, a small but growing movement advocates for platform cooperatives—platforms owned by users or workers.

Imagine if Uber were owned by drivers. Or if a social network were owned by its users. Instead of optimizing for investor returns, these platforms could optimize for user welfare.

Examples are emerging. Stocksy (stock photography) is owned by contributing artists. Resonate (music streaming) is owned by musicians and listeners. These cooperatives still need to generate revenue and cover costs, but profits are distributed among stakeholders rather than external shareholders.

The model addresses concerns about platform power and wealth concentration. Whether it can scale to compete with venture-backed giants remains uncertain, but it represents an interesting alternative approach to platform building.

Creator Economy Models

The rise of creators—YouTubers, podcasters, newsletter writers, course creators—has spawned new business models.

Platforms like Patreon let creators charge fans directly for access to exclusive content. Substack enables writers to run paid newsletters, keeping 90% of revenue. YouTube shares ad revenue with creators. OnlyFans takes a percentage of creator earnings.

These platforms succeeded by recognizing that creators needed infrastructure for payments, hosting, and fan management. By providing these tools, they could capture a percentage of the growing creator economy without creating content themselves.

The model works because it aligns incentives. When creators succeed, the platform succeeds. Unlike traditional media where companies employed creators, these platforms enable independent creators while taking a cut.

Bundling and Cross-Selling

Some companies win not through individual products but through packaging multiple offerings together.

Microsoft 365 bundles Word, Excel, PowerPoint, Teams, OneDrive, and more for one price. Individually, these might cost $15-30 monthly each. Bundled, they're $12.50 per user. Customers get better value, Microsoft gets stickier relationships and higher total revenue per customer.

Adobe Creative Cloud similarly bundles Photoshop, Illustrator, Premiere Pro, and 20+ other tools. Professional designers might use several daily. Buying individually would cost hundreds monthly; bundled, it's $55.

Bundling increases switching costs. A customer might consider alternatives to Photoshop, but finding replacements for their entire Adobe workflow is much harder.

The risk is that customers only value one or two bundle components. If they're paying for 10 tools but only using 2, competitors offering just those 2 tools for less might win.

How to Choose the Right Model

With so many options, how should a company choose? Several factors matter.

Audience and market: Consumer apps rarely work with direct payments—users expect free or very cheap. Business software can command higher prices because the ROI is clear.

Product nature: Some products fit certain models naturally. Developer tools work well with usage-based pricing. Creative tools suit subscriptions. Marketplaces obviously need transaction models.

Competition: In crowded markets, freemium helps acquire users despite competition. In blue ocean markets, you might charge from day one.

Growth goals: Venture-backed startups often prioritize growth over revenue, making freemium attractive. Bootstrapped companies need revenue sooner, favoring paid models.

Margins and economics: High-margin products (pure software) support freemium better than low-margin ones (with human services or heavy infrastructure costs).

Customer acquisition costs: If it costs $1,000 to acquire a customer, you need a business model that generates substantially more than $1,000 per customer over time. Subscriptions work well here; one-time purchases might not.

Most successful companies eventually use hybrid models. Slack is freemium with tiered subscriptions. AWS has subscriptions for some services, usage-based pricing for others. Apple combines hardware sales, commissions, subscriptions, and ecosystem lock-in.

The key is starting simple, learning from customers, and evolving thoughtfully rather than adopting every trendy model.

Strategic Considerations

Beyond choosing a model, several strategic factors determine success.

Understanding Your Key Players

Every market has dominant players whose strategies shape the landscape. In cloud computing, AWS, Google Cloud, and Microsoft Azure set pricing and features. In social media, Meta and Google define the advertising model.

Understanding these players helps you identify opportunities. Are they ignoring a segment? Is there a feature gap? Could you serve customers they're overpricing?

Sometimes the best strategy is being acquired by a major player. Instagram and WhatsApp became worth billions because Facebook (now Meta) needed to acquire their users and eliminate competition.

Opportunities in the Current Market

Several trends create opportunities for new entrants:

Remote work has exploded demand for collaboration software, virtual events, and distributed team management. Companies that solve remote work pain points well have grown dramatically.

AI and automation are transforming every industry. Tools that help businesses implement AI without deep expertise are proliferating. The companies building the best AI wrappers and integrations will capture substantial value.

Privacy and data ownership concerns are creating demand for alternatives to ad-supported services. Paid search engines, encrypted messaging, and privacy-focused analytics are emerging.

Vertical SaaS targets specific industries with tailored solutions rather than horizontal tools for everyone. Software for restaurants, medical practices, or law firms can command premium prices by solving industry-specific problems.

No-code and low-code platforms democratize software creation. As these mature, new types of businesses become possible.

Weaknesses and Risks to Navigate

No business model is perfect. Understanding weaknesses helps you mitigate them.

Subscription fatigue is real. Consumers and businesses are pushback against dozens of monthly charges. Some users are choosing one-time purchases or reducing subscriptions.

Platform dependence means your business can change overnight if Apple, Google, or Amazon changes policies. Many businesses have seen revenue disappear when App Store rules changed or Amazon adjusted search algorithms.

Competition and commoditization affect every model. As markets mature, differentiation becomes harder and prices compress. What once commanded premium prices becomes a race to the bottom.

Retention challenges plague subscription businesses. Losing 5% of customers monthly compounds into losing more than half your base in a year. Customer success and continuous value delivery are critical.

Threats on the Horizon

Several external factors could disrupt current models:

Regulation is increasing globally. Europe's Digital Markets Act forces changes to App Store fees and default browser settings. Privacy regulations restrict advertising practices. Future regulations could reshape entire business models.

Economic downturns hit different models differently. Subscription businesses often see churn spikes in recessions. Ad-supported businesses see revenue drop as marketing budgets shrink. Transaction-based businesses decline with overall economic activity.

Technology shifts can make entire categories obsolete. Mobile apps disrupted desktop software. Cloud computing disrupted on-premise software. AI might disrupt both. Companies must continuously evolve.

Security and privacy breaches destroy trust and can kill companies. As data becomes more central to business models, protecting it becomes existential.

Tax and Legal Considerations

Business models have different tax and legal implications that matter enormously.

Digital services taxation varies globally. Selling software to customers in Europe requires understanding VAT (typically 17-27%). Some US states tax SaaS, others don't. Compliance complexity grows with geographic expansion.

Revenue recognition rules differ by model. Subscriptions recognize revenue over time as services are delivered. One-time sales recognize revenue immediately. Marketplaces have specific rules for gross versus net revenue recognition. Getting this wrong can have serious accounting and legal consequences.

Data privacy compliance affects advertising and data businesses particularly. GDPR in Europe, CCPA in California, and similar laws globally create compliance obligations. Violations bring substantial fines.

Contractor versus employee classification matters for platform businesses. Uber, Lyft, and others face ongoing legal battles about whether drivers are contractors or employees. The distinction affects costs massively and has business model implications.

Metrics That Matter

Different business models require tracking different metrics.

For subscription businesses, the critical metrics are:

Monthly Recurring Revenue (MRR) and Annual Recurring Revenue (ARR)
Customer Acquisition Cost (CAC)
Lifetime Value (LTV)
Churn rate (monthly percentage of customers lost)
Net Revenue Retention (revenue from existing customers including expansions minus churn)

For marketplace businesses, track:

Gross Merchandise Value (GMV) - total transaction volume
Take rate (percentage you keep)
Active buyers and sellers
Liquidity (how quickly supply meets demand)

For advertising businesses, watch:

Daily/Monthly Active Users (DAU/MAU)
Engagement metrics (time spent, actions taken)
Cost Per Click (CPC) or Cost Per Thousand Impressions (CPM)
Revenue per user

For freemium businesses, monitor:

Free to paid conversion rate
Activation rate (percentage of signups who experience core value)
Time to conversion
Feature adoption by tier

Understanding which metrics matter for your model helps you optimize the right things.

Real-World Examples and Lessons

Theory is important, but let's look at how this plays out in practice.

Zoom started as a better video conferencing tool in a crowded market. They offered generous free tiers (40-minute meetings for up to 100 participants) while charging businesses for unlimited meeting length, more participants, and features like recording.

The freemium model drove explosive growth. Millions tried Zoom for free during the pandemic. Many upgraded when remote work became permanent. By 2023, Zoom had over 467,000 customers with more than 10 employees, most paying substantial subscriptions.

Stripe could have sold their payment processing API as a monthly subscription. Instead, they chose transaction-based pricing—2.9% plus 30 cents per charge. This aligned perfectly with customer success. Startups pay almost nothing initially, but as they grow, Stripe grows with them. Some of Stripe's largest customers process billions in payments annually, generating millions in fees.

Notion brilliantly combined freemium, subscription tiers, and viral growth. The product is genuinely useful for free, encouraging personal adoption. As teams form and need collaboration features, they upgrade. Users love Notion enough to tell others, driving organic growth. The result: a $10 billion valuation built largely through product-led growth.

Epic Games challenged the App Store model directly. They bypassed Apple's 30% commission by offering direct payment options in Fortnite. Apple banned Fortnite, leading to lawsuits and regulatory scrutiny. While Epic hasn't fully won, they've sparked global debate about fair platform fees and helped drive regulatory changes.

These examples show that business models aren't just theoretical—they're strategic decisions with massive implications.

The Future of Software Business Models

Where is this all heading? Several trends seem clear.

AI integration will become table stakes. Every software category will incorporate AI capabilities. The question becomes: do you charge extra for AI features, include them in existing tiers, or use AI as a moat? Different companies will choose different approaches.

Unbundling and rebundling will continue. Markets oscillate between integrated suites and best-of-breed point solutions. Currently, we're seeing both: some companies bundle more features (Notion adding docs, wikis, databases), while others unbundle (focused tools that do one thing excellently).

Privacy-first models may gain traction as users tire of ad-supported services that monetize attention. Paid alternatives to free, ad-supported tools are emerging. Whether consumers actually pay remains to be seen, but the shift is beginning.

Consumption-based pricing will likely expand beyond cloud infrastructure. As companies seek to align costs with value more precisely, usage-based pricing makes sense for more categories.

Platform regulation will reshape marketplace and ecosystem models. Regulators globally are scrutinizing platform power, app store fees, and default settings. Changes seem inevitable, though specifics remain uncertain.

Web3 and blockchain introduce new possibilities. Decentralized platforms owned by token holders rather than shareholders, creator tokens that let fans invest in creators directly, and NFTs that enable new digital ownership models are all experiments in progress. Most will fail, but some innovations may stick.

Conclusion: It's About Value Creation, Not Just Revenue

After exploring dozens of business models, one truth becomes clear: the best model is the one that creates and captures value most effectively for your specific situation.

Subscription models succeed when they continuously deliver value, keeping customers engaged month after month. Freemium works when the free tier genuinely helps users while premium features solve real pain points. Marketplaces thrive when they reduce friction and enable transactions that wouldn't happen otherwise.

The companies that win long-term don't just choose a model—they obsess over delivering value, then find business models that capture some portion of that value sustainably.

Understanding these models helps you make better decisions whether you're building software, investing in tech companies, or simply using digital products. You'll recognize when you're in a freemium acquisition funnel, understand why that SaaS company is pushing annual plans so hard, and see the strategic logic behind platform ecosystem moves.

The software industry continues evolving rapidly. New models emerge, existing ones adapt, and what works today might not work tomorrow. But the fundamental principle remains: create real value for real people, then build a business model that captures enough value to sustain and grow while keeping customers happy.

That's the real art of software business models—finding that sustainable balance where everyone wins.

End

That's all!

I hope you've found the article useful. I'll write more about the software business & related organizations & ecosystem soon. Feel free to share your thoughts.

Check more on

Publishing Your First NPM Package: A Real-World Guide That Actually Helps

Mir Mursalin Ankur — Sat, 22 Nov 2025 02:54:55 +0000

You know that moment when you’ve written the same utility function for the third time across different projects and suddenly think: “Wait… why am I doing this again?”
Yeah — that’s exactly how NPM packages quietly sneak into your life.

I recently went through the process of turning a simple HTML-to-PDF generator into a proper NPM package. What started as a quick utility became a small adventure — a mix of excitement, challenges, and learning-by-doing. A little confusing at times, but absolutely worth it.

And here’s the twist: NPM has updated quite a few things lately — deprecated classic tokens, changed their UI, and even updated how org-scoped packages behave. So if you’ve followed older tutorials, you’ve probably felt that “why isn’t this working?” frustration.

This guide is different.
It’s based on real steps, real mistakes, and the little details nobody tells you about until you’re already stuck.

Why Even Bother Publishing a Package?

Publishing a package does three magical things:

Reusability: Stop copy-pasting code between projects
Helping others: Someone out there is fighting the same problem right now
Learning: You'll dive into open-source workflow, versioning, CI/CD, and documentation

Plus, there's something genuinely satisfying about typing npm install your-package-name and seeing your own work install. It's a tiny piece of software craftsmanship that feels really good.

Understanding Scopes and Naming (Before You Start)

NPM packages can be:

Unscoped: your-package-name
Scoped: @yourname/your-package-name

Here's what matters: if your *NPM username *is cooldev, then @cooldev/anything is automatically your namespace. You don't need to create an organization unless your scope differs from your username.

Check if a name is available:

npm view @yourname/your-package-name
# 404 means it's free to use

Step 1: Set Up the Project Structure

Start fresh. Create a clean directory and initialize it:

mkdir your-package-name
cd your-package-name
git init
npm init -y

Keep things organized with a src/ folder for your code.

Step 2: Bring in Your Source Files

Copy your working code into the new package structure:

mkdir -p src
cp -r /path/to/your-project/src/lib/your-library/* src/

This isolation keeps your package clean and focused.

Step 3: Configure Your package.json

This is the heart of your package. Update these critical fields:

{
  "name": "@yourname/your-package-name",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourname/your-package-name.git"
  },
  "bugs": {
    "url": "https://github.com/yourname/your-package-name/issues"
  },
  "homepage": "https://github.com/yourname/your-package-name#readme"
}

Make sure:

name is unique (check NPM first)
repository.url points to your GitHub repo
bugs.url gives people a place to report issues
homepage links to documentation

Step 4: Connect to GitHub

Get your code into version control:

git add .
git commit -m "Initial commit: My Library to NPM Package"
git branch -M master
git remote add origin https://github.com/yourname/your-package-name.git
git push -u origin master

Step 5: Test Your Build Locally

Before publishing anything, make sure it actually works:

npm run build

Here's the secret weapon most beginners don't know about — test your package locally:

npm pack

This creates a .tgz file — the exact same file that would go to NPM.

Now test it in another project:

npm install /path/to/your-package-1.0.0.tgz

This catches so many issues. Seriously, multiple problems only showed up after testing in a fresh environment.

Step 6: Login to NPM Account

You can login to npm from any browser by going to npmjs.com. Login is also straightforward by command line:

npm login

You'll be prompted for:

Username
Password
Email
One-time password (if you have 2FA enabled)

Step 7: Choose Your Publishing Strategy

You have two ways to publish your package:

Manual Publishing - Quick start, publish from command line
Automated CI/CD - Professional, publish on git tag (recommended)

Let's start with manual to get you published quickly, then set up automation.

Manual Publishing (Quick Start)

npm login
npm publish --access public

The --access public flag is required for scoped packages (like @yourname/package-name).

That's it. Your package is live on NPM!

But here's the thing: manual publishing is error-prone. You might forget to build, or push the wrong version, or skip tests. Let's set up automation.

Step 8: Set Up Automated Publishing (Recommended)

Here's where it gets interesting. Classic NPM tokens are deprecated — many old tutorials still reference them, which is confusing. You need to create a Granular Access Token instead. Then use github CI/CD workflow to publish the changes to npm

Creating a Granular Access Token

This token lets GitHub Actions publish your package automatically. Here's how:

1. Go to npmjs.com and login

Navigate to your profile → Access Tokens → Generate New Token → Select Granular Access Token

2. Configure the token:

Token Name: GitHub Actions CI/CD
Expiration: 90 days (or your preference)

3. Set permissions:

Under "Packages and scopes":

Select Read and write
Choose either:
- "All packages" (easier), OR
- Select your specific package @yourname/your-package-name

4. Copy the token immediately

You won't be able to see it again! It starts with npm_...

5. Add to GitHub Secrets:

Go to your GitHub repository:

Settings → Secrets and variables → Actions
Click "New repository secret"
Name: NPM_TOKEN
Value: Paste your token
Click "Add secret"

Now GitHub Actions can publish on your behalf.

Step 9: Understanding Semantic Versioning

Before we automate, let's talk about versioning. It's not just numbers — it's a promise to your users:

Command	Example	When to Use
`npm version patch`	1.0.0 → 1.0.1	Bug fixes
`npm version minor`	1.0.0 → 1.1.0	New features
`npm version major`	1.0.0 → 2.0.0	Breaking changes

Here's the magic: each npm version command does three things:

Updates version in package.json
Creates a git commit
Creates a git tag (like v1.0.1)

That git tag is what triggers automated publishing.

Step 10: Create the GitHub Actions Workflow

Now let's set up the automation. This workflow:

Triggers when you push a version tag (like v1.2.3)
Runs your tests and builds
Verifies the version matches
Publishes to NPM with provenance (security feature)
Creates a GitHub release

Create .github/workflows/publish.yml:

name: Publish to NPM

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4
        with:
          version: 9.0.0

      - uses: actions/setup-node@v4
        with:
          node-version: '18.20.0'
          registry-url: 'https://registry.npmjs.org'
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm run typecheck
      - run: pnpm run build

      - name: Verify version matches tag
        run: |
          TAG="${GITHUB_REF#refs/tags/}"
          VERSION="${TAG#v}"
          FILE_VERSION=$(node -p "require('./package.json').version")
          if [ "$VERSION" != "$FILE_VERSION" ]; then
            echo "Version mismatch: tag=$VERSION, package.json=$FILE_VERSION"
            exit 1
          fi

      - name: Publish to NPM
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: pnpm publish --access public --provenance

Important notes about this workflow:

permissions: id-token: write enables NPM provenance (proves your package came from your GitHub repo)
The version verification step prevents accidental publishes with mismatched versions
--frozen-lockfile ensures consistent installs
Adjust pnpm to npm if you're not using pnpm

Step 11: Publishing with the Automated Workflow

Now that automation is set up, here's your new publishing workflow:

1. Make sure all changes are committed:

git status
git add .
git commit -m "feat: add new feature"
git push origin master

2. Create and push a version tag:

# For a patch release (bug fixes)
npm version patch
git push origin master --tags

# For a minor release (new features)
npm version minor
git push origin master --tags

# For a major release (breaking changes)
npm version major
git push origin master --tags

3. Watch it happen:

Go to your GitHub repository → "Actions" tab
You'll see the workflow running
Within a few minutes, your package is published!
GitHub automatically creates a release too

Pro tip: The moment you push the tag, GitHub Actions takes over. No manual npm publish needed.

Step 12: Control What Gets Published

Want to see exactly what goes into your package?

npm pack --dry-run

Typically you want:

dist/ (your compiled code)
README.md
LICENSE
package.json

Use .npmignore to exclude:

Source files (src/)
Tests
Config files
.github/
Development dependencies

Step 13: Write Documentation That Actually Helps

Your README is the first thing people see. Make it count:

Must-haves:

Quick installation command
Basic usage example (copy-paste ready)
API reference
Common problems and solutions

Nice-to-haves:

Advanced examples
Browser vs Node.js differences
Performance tips
Contribution guidelines

Good documentation increases adoption way more than perfect code does.

Step 14: Licensing and Collaboration

Choose a license: MIT is the most permissive and common for open-source libraries.

Enable collaboration:

Add CONTRIBUTING.md with guidelines
Use GitHub Issues for bug reports
Consider GitHub Discussions for questions
Tag releases properly

Note on releases:
With GitHub Actions set up, you don't need to manually create releases. The workflow automatically creates a GitHub release when you push a version tag. But you can still edit the release notes afterward to add detailed changelogs.

If it is important to create Releases manually, follow this:

Go to your repo's "Releases" tab
Click "Create new release"
Tag it as v1.x.x
Add a changelog describing what changed
Publish

Once the tag is pushed, GitHub Actions takes over and handles publishing.

Step 15: When Things Go Wrong

Yes, mistakes happen. Accidentally published version 1.1.0 instead of 1.0.3? Been there.

Within 24 hours:

npm unpublish @scope/package@version

After 24 hours:
NPM won't let you unpublish for safety reasons. Instead:

npm deprecate @scope/package@version "Broken release, use 1.0.4 instead"

Then publish the correct version and update your changelog.

Wait a minute or two after unpublishing — NPM's cache takes time to update.

Lesson learned: always double-check before tagging and pushing.

Bonus: One-Command Publishing Scripts

Want to make publishing even easier? Create these helper scripts that combine versioning and pushing in one command:

publish-patch.sh:

#!/bin/bash
npm version patch
git push origin master --tags

publish-minor.sh:

#!/bin/bash
npm version minor
git push origin master --tags

publish-major.sh:

#!/bin/bash
npm version major
git push origin master --tags

Make them executable:

chmod +x publish-*.sh

Now publishing is as simple as:

./publish-patch.sh

The script bumps the version, creates the tag, and pushes it. GitHub Actions sees the tag and handles the rest — testing, building, and publishing to NPM automatically.

Best Practices Checklist

Before Publishing:

✅ Test with npm pack and install locally
✅ Run all tests and type checks
✅ Update README with latest features
✅ Add or update CHANGELOG

Package Quality:

✅ Include TypeScript types (if applicable)
✅ Add a LICENSE file
✅ Set up CI/CD for automated testing
✅ Use .npmignore to keep package lean
✅ Include usage examples in README

Maintenance:

✅ Respond to issues promptly
✅ Tag releases with semantic versions
✅ Keep dependencies updated
✅ Document breaking changes clearly

Real-World Example: From Hobby Project to Published Package

This guide is based on a real-world transformation: turning an HTML-to-PDF generator from a single-application solution into a framework-agnostic package that any developer can use.

The package: @encryptioner/html-to-pdf-generator

What it does: Modern multi-page PDF generator from HTML content with smart pagination and styling support.

The transformation journey:

Started as tightly coupled code in a single project
Extracted the core logic into a standalone library
Made it framework-agnostic (works with React, Vue, vanilla JS, Node.js)
Added proper TypeScript types
Set up automated publishing with GitHub Actions
Documented everything in a useful README

The outcome:
A package that solves a real problem for developers who need to generate clean, multi-page PDFs from HTML without fighting with browser print dialogs or complex PDF libraries.

Installation:

npm install @encryptioner/html-to-pdf-generator

This transition from "code that works for one project" to "code that works for everyone" demonstrates what successful package publishing looks like. The technical steps matter, but the mindset shift matters more — thinking about edge cases, documentation, and user experience.

Final Thoughts

Publishing your first NPM package is a rite of passage. It's messy, confusing, and occasionally frustrating — but incredibly rewarding.

The moment you see someone install your package, report a bug, or (even better) contribute a feature — it all clicks. You're not just writing code anymore. You're building something that helps others build things.

Don't wait for the perfect moment or the perfect code. Start with something useful, document it well, and iterate. The tools are better than ever, and the community is welcoming.

And when something breaks at 2 AM (it will), don't panic. Unpublish within 24 hours, fix it, document what happened, and keep going.

The open-source world needs more builders. So go ahead — publish that package you've been thinking about.

Happy publishing! 🚀

Let's Connect

I'm always excited to hear about what you're building! If you found this guide helpful, have questions, or just want to share your NPM publishing journey:

Website: encryptioner.github.io
LinkedIn: Mir Mursalin Ankur
GitHub: @Encryptioner
X (Twitter): @AnkurMursalin
Technical Writing: Nerddevs

Drop a message if you publish your first package using this guide — I'd love to check it out!

I Built My Own Shell for Fun. You Can Too

Mir Mursalin Ankur — Fri, 01 Aug 2025 14:07:27 +0000

Ever wondered what happens when you type ls and hit Enter? I did too. So I built my own shell to find out.

The "Why" Behind the Madness

As a lead software engineer, I've spent years working with shells—Bash, Zsh—but I never really understood what was happening under the hood. Sure, I knew about processes, file descriptors, and system calls, but the actual mechanics of how a shell works? That was a black box.

Then I stumbled upon codingchallenges.fyi and their shell challenge. It gave motivation to uncover the invisible scene of most common functionalities. It was my chance to peel back the layers and understand the fundamentals that power every terminal session.

What is a Shell, Really?

When you type ls -la, here's what happens:

Read: The shell reads your input from stdin
Parse: It breaks your command into tokens (ls, -la)
Execute: It finds the ls program and runs it with -la as arguments
Wait: It waits for the program to finish
Repeat: It shows a new prompt, ready for your next command

Simple, right? But the devil is in the details.

The Journey Begins: ccsh

I decided to build ccsh (Compact C Shell)—a minimal but functional Unix-like shell. Here's what I learned along the way:

Why C?

C is the lingua franca of Unix systems. Every Linux distribution, macOS, and BSD variant comes with a C compiler. This means my shell can run anywhere without dependencies.

But more importantly, C gives me direct access to the system calls that power everything:

fork() and exec() for process creation
pipe() for inter-process communication
dup2() for file descriptor manipulation
waitpid() for process synchronization
signal() for handling interrupts

These are the same system calls that Bash, Zsh, and every other shell use under the hood.

AI as My Learning Partner

Here's the honest truth: AI generated most of my code, but I understood every line.

How AI Helped Me:

Generated boilerplate code structure - I didn't start from scratch
Explained complex system calls - When I was stuck on fork() vs exec()
Debugged memory management issues - C's manual memory management is tricky
Suggested best practices - Error handling, code organization, security considerations

The Key Insight:

AI is a tool, not a replacement. Understanding the fundamentals is crucial. Here's what I learned:

80% understanding is enough - If this isn't your core job, you don't need to memorize every system call
AI accelerates learning - When you know the basics, AI can help you build faster
Fundamentals matter - You still need to understand what fork() does, even if AI wrote the code

My Approach:

Start with understanding - Learn what each system call does conceptually
Use AI for implementation - Let AI handle the boilerplate and edge cases
Review and modify - Understand AI generated lines. If necessary, get clarification from alternate source
Test and debug - Break things to understand them better

"AI generated the code, but I understood most of the lines. That's the sweet spot."

Building the Shell

I chose to implement everything in a single main.c file for simplicity. Here's how to build it:

What is a Makefile?

A Makefile is a configuration file that tells the make utility how to build your project. It's like a recipe that automates the compilation process. Instead of typing long gcc commands, you just run make.

Simple Build

gcc -Wall -Wextra -std=c99 -g main.c -o ccsh -lreadline

What each flag does:

-Wall -Wextra: Enable all warning messages
-std=c99: Use C99 standard
-g: Include debug symbols
-lreadline: Link against the readline library (for command history)

With Makefile

# Compiler and flags
CC = gcc
CFLAGS = -Wall -Wextra -std=c99 -g
LDFLAGS = -lreadline

# Build target: ccsh depends on main.c
ccsh: main.c
    $(CC) $(CFLAGS) -o ccsh main.c $(LDFLAGS)

# Clean up build artifacts
clean:
    rm -f ccsh

# Install to system (optional)
install: ccsh
    cp ccsh ~/.local/bin/

How it works:

CC = gcc: Define the compiler
CFLAGS: Compiler flags for warnings and standards
LDFLAGS: Linker flags for external libraries
ccsh: main.c: Target ccsh depends on main.c
clean: Remove built files

Building and Running

# Build the shell
make

# Run the shell
./ccsh

# Clean up
make clean

The Cool Features I Added

1. Built-in Commands

cd /path/to/directory    # Change directory
pwd                      # Print working directory
exit                     # Exit shell
jobs                     # List background jobs
fg %1                    # Bring job to foreground
help                     # Show help information

2. Alias System

alias ll="ls -lah"       # Create alias
alias                    # List all aliases
unalias ll               # Remove alias

3. Background Job Management

sleep 10 &               # Run in background
jobs                     # List background jobs
fg %1                    # Bring to foreground

4. I/O Redirection

ls > output.txt          # Redirect output
cat < input.txt          # Redirect input
echo "hello" >> log.txt  # Append output

5. Globbing Support

ls *.txt                 # List all .txt files
cp file?.txt backup/     # Copy files matching pattern

The "Aha!" Moments

Process Groups and Sessions

I never fully understood how Ctrl+C works until I implemented it. When you press Ctrl+C, the kernel sends a SIGINT to the entire process group. The shell needs to:

Create a new process group for each command
Handle signals appropriately
Restore the shell's process group when the command finishes

Environment Variables

I always knew about PATH, but seeing how the shell searches for executables was enlightening. It's just a simple loop through directories, checking if the file exists and is executable.

The Challenges I Faced

Memory Management Nightmares

C doesn't have garbage collection, so every malloc() needs a corresponding free(). With complex command parsing and multiple processes, memory leaks were a constant threat.

Signal Handling Complexity

Getting Ctrl+C to work correctly was surprisingly tricky. The shell needs to:

Ignore SIGINT for itself
Forward SIGINT to child processes
Restore signal handlers after child completion
Handle signals during pipeline execution

Cross-Platform Quirks

While C is portable, Unix systems have subtle differences:

Different signal behavior between Linux and macOS
Varying limits on file descriptors
Different implementations of readline

Deep Dive: How C Talks to the Operating System

Let's trace through what happens when you type ls -la in my shell:

1. The Fork-Exec Dance

pid_t pid = fork();
if (pid == 0) {
    // Child process
    execvp(expanded[0], expanded);
    perror("execvp");
    exit(1);
} else if (pid > 0) {
    // Parent process
    if (background) {
        // Background job
        printf("[%d] %d\n", job_count, pid);
        add_job(pid, line);
    } else {
        // Foreground job - wait for completion
        int status;
        waitpid(pid, &status, 0);
    }
}

What's happening:

fork() creates an exact copy of the current process
The child gets a new process ID but identical memory
execvp() replaces the child's memory with the ls program
The parent waits for the child to finish

2. How Redirection Works

When you type ls > output.txt, here's what happens:

/* Handle output redirection */
if (outfile) {
    int flags = O_WRONLY | O_CREAT;
    if (append) flags |= O_APPEND;
    else flags |= O_TRUNC;

    int fd = open(outfile, flags, 0644);
    if (fd == -1) { 
        perror("output"); 
        exit(1); 
    }
    dup2(fd, STDOUT_FILENO);
    close(fd);
}

The magic is dup2(fd, STDOUT_FILENO). This makes file descriptor 1 (stdout) point to the same place as our file descriptor.

3. Globbing Implementation

For ls *.txt:

void expand_globs(char** args, char** expanded_args, int* expanded_count) {
    *expanded_count = 0;
    glob_t results;
    results.gl_offs = 0;
    results.gl_pathc = 0;
    results.gl_pathv = NULL;

    for (int i = 0; args[i] != NULL; i++) {
        int flags = GLOB_TILDE;  /* Expand ~ to home directory */
        if (strchr(args[i], '*') || strchr(args[i], '?')) {
            /* Pattern contains glob characters */
            if (*expanded_count > 0) flags |= GLOB_APPEND;
            if (glob(args[i], flags, NULL, &results) != 0) {
                /* Glob failed, use original argument */
                expanded_args[(*expanded_count)++] = args[i];
            } else {
                /* Add all matched files */
                for (size_t j = 0; j < results.gl_pathc; j++) {
                    expanded_args[(*expanded_count)++] = results.gl_pathv[j];
                }
            }
        } else {
            /* No glob characters, use as-is */
            expanded_args[(*expanded_count)++] = args[i];
        }
    }
    expanded_args[*expanded_count] = NULL;

    /* Free the glob structure */
    if (results.gl_pathv != NULL) {
        globfree(&results);
    }
}

What I Learned About Real Shells

Building my own shell gave me a new appreciation for tools like Bash and Zsh. They handle edge cases I never considered:

Complex quoting rules
Job control with multiple background processes
Signal handling in pipelines
Performance optimizations
Cross-platform compatibility

The Takeaway

Building your own shell isn't just an academic exercise. It's a practical way to understand:

Process management: How the OS handles processes
I/O systems: File descriptors, pipes, redirection
Signal handling: How programs communicate with the OS
System calls: The interface between user and kernel space
Build systems: How to create robust, portable software

Try It Yourself

If you're interested in low-level programming, I highly recommend building a shell. Start simple:

Basic command execution
Add argument parsing
Implement I/O redirection
Add pipes
Build in job control

The codingchallenges.fyi shell challenge is an excellent starting point. you can also check

What's Next?

I'm thinking about adding:

Tab completion
Better error handling
More built-in commands
Scripting capabilities
Performance optimizations

But honestly, the learning experience was the real reward. Understanding how the tools I use daily actually work has made me a better engineer.

The next time you type a command, take a moment to appreciate the complexity hidden behind that simple prompt. And maybe, just maybe, consider building your own shell to see what's really happening under the hood.

Happy coding! 🐚

End:

That's all!

I hope you've found the article useful. You should try building your own shell if you haven't already. Feel free to share your thoughts in the comments below.

Check more on

Integrating Bitbucket MCP with Cursor: A Practical Guide for Developers

Mir Mursalin Ankur — Mon, 21 Jul 2025 15:44:40 +0000

As developers, we all want our workflows to be smooth and efficient. Managing repositories, reviewing pull requests, and keeping track of changes can get tedious—especially when it means switching between your editor and browser. Recently, I set up the Bitbucket MCP (Model Context Protocol) server with Cursor IDE, and it’s made these tasks much more convenient.

While Cursor supports bugbot for GitHub PR reviews, there’s nothing similar out-of-the-box for bitbucket users. Setting up Bitbucket MCP with Cursor changed that for me—and made my dev life a lot smoother.

Here’s a practical guide based on my experience, with tips that apply even if you use other tools.

Why Integrate Bitbucket MCP with Cursor?

The main benefit is reducing context switching. With Bitbucket MCP, you can:

List and manage repositories
Create, review, and approve pull requests
Access commit history and diffs
Adjust repository settings

All from within Cursor, so you spend more time coding and less time navigating web UIs.

What You’ll Need

Cursor IDE
Node.js v16 or higher
Bitbucket account with repository access
Bitbucket Repository Access Token (not an app password)

Step-by-Step Setup

1. Install the Bitbucket MCP Server

In your project directory, run:

pnpm install -D bitbucket-mcp

You can use npm if you prefer.

2. Configure MCP

Create a .cursor/mcp.json file in your project root. Example:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
        "BITBUCKET_TOKEN": "your-repository-access-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      },
      "args": ["bitbucket-mcp"]
    }
  }
}

Replace the placeholders with your actual token and workspace name (not the URL).

3. Get a Bitbucket Access Token

Follow this guide to generate a token. Make sure it has Read/Write permissions for repositories and pull requests. Use a repository access token, not an app password.

4. Test Your Credentials

Before moving on, it’s a good idea to verify your token. Here’s a simple Node.js script:

const axios = require('axios');
const tokenCredentials = {
  url: "https://api.bitbucket.org/2.0",
  workspace: "your-workspace",
  token: "your-repository-access-token"
};

(async () => {
  try {
    const res = await axios.get(`${tokenCredentials.url}/workspaces/${tokenCredentials.workspace}`, {
      headers: { 'Authorization': `Bearer ${tokenCredentials.token}` }
    });
    console.log('Token is valid! Workspace:', res.data.name);
  } catch (e) {
    console.error('Token test failed:', e.response?.status, e.response?.statusText);
  }
})();

Save it as scripts/test-bitbucket-credentials.js and run:

node scripts/test-bitbucket-credentials.js

If you see your workspace name, you’re set.

5. Restart Cursor

Close and reopen Cursor to load the new MCP server. You should see Bitbucket MCP under Settings → Tools & Integrations → MCP Tools.

Everyday Usage

Once set up, you can run Bitbucket commands from Cursor’s agent chat or command palette. For example:

List repos: /bitbucket listRepositories
Get repo details: /bitbucket getRepository --workspace your-workspace --repo-slug your-repo
Manage pull requests: /bitbucket getPullRequests --workspace your-workspace --repo-slug your-repo

You can also create or approve PRs, check commit diffs, and manage branching models—all from your editor.

Troubleshooting Tips

MCP server not loading? Double-check your .cursor/mcp.json and environment variables.
Auth errors? Make sure you’re using a repository access token (not an app password) and that it hasn’t expired.
Commands not recognized? Restart Cursor and verify the MCP server is loaded.

If you want to avoid confirmation prompts for MCP tools, enable “Auto-run MCP Tools” in Cursor’s chat settings.

Deep Dive: How MCP Works (and How the Cursor and Bitbucket MCP Server Uses It)

To really understand the power of this integration, it helps to know what’s happening under the hood.

What is MCP?

MCP stands for Model Context Protocol. It’s an open protocol designed to let tools (like editors, IDEs, or AI agents) communicate with code hosts (like GitHub, GitLab, Bitbucket, etc.) in a standardized way. Instead of every tool building its own custom integration for each code host, MCP defines a common set of commands and data structures for things like repositories, pull requests, branches, and commits.

Think of MCP as a universal translator for developer tools. It lets your editor ask questions (“What pull requests are open?”) or take actions (“Create a new branch”) in a way that works across different platforms, as long as there’s an MCP server for that platform.

How Does the Bitbucket MCP Server Leverage MCP?

The Bitbucket MCP server is an implementation of this protocol, acting as a bridge between Cursor and Bitbucket’s API. Here’s how it works in practice:

Command Flow: When you run a Bitbucket command in Cursor (like listing repositories or creating a pull request), Cursor sends a standardized MCP request to the Bitbucket MCP server.
Translation Layer: The MCP server receives this request and translates it into the appropriate Bitbucket API call, handling authentication and formatting as needed.
Data Exchange: The server fetches the data from Bitbucket, then converts the response back into the MCP format so Cursor can display it in a consistent way, regardless of the underlying code host.
Authentication: The MCP server uses your Bitbucket repository access token to authenticate API requests securely, so you never have to expose your credentials directly to Cursor or other tools.

This architecture means you get a seamless, unified experience in your editor, while the heavy lifting of talking to Bitbucket’s API is handled by the MCP server. It also makes it easier for new tools and platforms to integrate in the future—just implement the MCP protocol, and you’re good to go.

In summary, MCP is the glue that connects your editor to your code host, and the Bitbucket MCP server is the translator that makes it all work smoothly for Bitbucket users.

How AI Chat Agents of Cursor Leverage MCP

One of the most powerful aspects of MCP is how it enables AI chat agents (like those in Cursor) to interact with your repositories in a smart, automated way. Here’s how it works:

User Request: You ask the AI agent to do something—like review a pull request, summarize recent changes, or list open issues.
MCP Command Generation: The agent formulates a standardized MCP command based on your request (for example, "get pull request details").
Data Retrieval: The MCP server fetches the relevant data from Bitbucket, translates it into the MCP format, and returns it to the agent.
AI Processing: The agent analyzes the structured data—such as code diffs, comments, or commit history—and generates a human-friendly summary, review, or action.
Action or Insight: The agent presents its findings to you (e.g., a PR review summary, a list of suggested changes, or even automates a merge if you approve).

Because MCP provides a consistent, structured interface, the AI agent doesn’t need to know the details of Bitbucket’s API. This makes it much easier to build powerful, context-aware automation and insights directly into your development workflow, regardless of which code host you use.

Broader Lessons

Even if you use GitHub, GitLab, or another platform, the principle is the same: integrating your tools saves time and helps you stay focused. Investing a little effort in setup pays off in smoother workflows and fewer distractions.

Final Thoughts

Integrating Bitbucket MCP with Cursor has made my daily work more efficient and less fragmented. If you’re looking to streamline your repo management, I recommend giving it a try—or finding similar integrations for your stack. The right tools should help you focus on what matters: building great software.

End

That's all!

I hope you've found the article useful. You should try to use mcp server if you haven't already. It has many interesting use cases. Feel free to share your thoughts and experiences.

Check more on

DEV Community: Mir Mursalin Ankur

Build Your Own IDE Extension: A Real-World Guide From Idea to Publish (VS Code and Others)

What an Extension Actually Is

The shapes extensions come in

Before You Write Code: Audit Your Idea

The thin-client principle

The VS Code Path

The fifteen-minute skeleton

The manifest: where half the work happens

Your first command

The five surfaces you'll actually use

Lessons that cost me an afternoon each

Testing like it matters

Shipping It

Start with just a file: the .vsix

The Marketplace — and the Azure detour nobody warns you about

Open VSX: one extra step, five more editors

Beyond VS Code: A Field Guide

Zed: small, sharp, sandboxed

Cursor, Windsurf, VSCodium: already done

JetBrains: a different planet, respectfully

Neovim: no ceremony, by design

The comparison, at a glance

So Which One First?

Wrapping Up

Sources and Further Reading

End:

Your Desk in Your Pocket — Free Remote Control for Mac & Ubuntu, Same Room or Anywhere on Earth

Part 1 — Same network: the phone drives the desktop

Why VNC, and not just SSH

The macOS machine: Screen Sharing, already installed

The Ubuntu machine: x11vnc

Run it

Persist across reboots — the autostart file

The phone client: RealVNC Viewer (one app, both machines)

One session, multiple monitors

Driving the desktop from the phone

Switching between applications

Multi-key shortcuts, e.g. Super+A

Right-click, and where Enter/Backspace live

Scrolling — the most common gesture of all

The everyday actions: new tab, Ctrl+C, close

Editing text in a terminal

Typing on the desktop with your phone keyboard — including voice typing

A note on global hotkeys

Part 1 — Troubleshooting & security

If the phone client won't connect (macOS)

If the phone won't connect (Ubuntu)

Part 1 security recap

Part 2 — Over the internet: the same rig, anywhere

First, the check most people skip: can you even port-forward?

Even if you can port-forward, don't — not raw VNC

The options

Tailscale: what it is and why it fits

Is Tailscale safe to trust?

On the desktop

On the phone

What changes, what doesn't

Verified from cellular

Part 2 — Security and alternatives

Security recap

If Tailscale isn't the right fit

Part 3 — Deep dive: how the rig actually works

The wire protocol: RFB, and the 8-character password

Why VNC triggers hotkeys when SSH can't

Part 2's layer: WireGuard, NAT traversal, and DERP

Part 3 — Troubleshooting

Quick start after first setup

1. Find the desk's addresses

2. Tailscale side

3. Is the server up?

4. What the phone should dial

5. Watch it live while the phone retries

6. Why the LAN IP drifts, and the fix

7. Phone error text → cause

Tools & licenses

Let's Connect

Self-Review With AI Before You Open the PR — A Practical Workflow with branchdiff

Why "before the PR" is the right moment

The workflow in 4 steps

Start with just a file: the `.vsix`

Multi-key shortcuts, e.g. `Super+A`

Agent Config: trigger-list pattern (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`)

`get_review_context_tool` — best single call for code review

`ai-vault/CLAUDE.md` (vault-level agent instructions — Claude Code example; use `AGENTS.md` or `GEMINI.md` for other agents)