Forem: Mir Mursalin Ankur

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

Give Google Sheet Access Only to Form Submitters — With Apps Script

Mir Mursalin Ankur — Sun, 20 Jul 2025 16:23:40 +0000

As a lead software engineer, I've seen teams across companies rely on Google Forms + Sheets for quick data collection — feedback surveys, attendance tracking, event registration, you name it.

But here’s a common issue that comes up:
How do you restrict access to the Google Sheet so only the people who submitted the form can view it?

Google Forms doesn't offer this natively (which is honestly surprising given how common this need is). But with a little Apps Script magic, you can make it happen.

The Problem

Let's say you're running a private beta program. You collect sign-ups via Google Form. Now you want only those who signed up (and no one else) to see the list.

Manually adding viewers to the Sheet? Not scalable.
Leaving it public? Not secure.
The goal:

Give view access only to people who submit the form.
Remove access from people who are no longer in the list.
Keep certain admin/owner access always intact.

The Approach

We hook into Google Apps Script and:

Read the email column from the sheet.
Add new emails as viewers.
Remove emails who shouldn't have access anymore.
Always preserve admin users (like yourself).

Here's the battle-tested script I've used in my projects:

function updateSheetSharing() {
  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = spreadsheet.getSheets()[0]; // First sheet

  // update this column according to your sheet
  const emailColumnIndex = 2; // Column B = 2
  const startRow = 2; // Header on row 1

  const lastRow = sheet.getLastRow();
  if (lastRow < startRow) {
    return;
  }

  const ownerEmails = ['admin@gmail.com']; // Add your admin email(s)

  const emails = sheet.getRange(startRow, emailColumnIndex, lastRow - startRow + 1)
    .getValues()
    .flat()
    .filter(email => email && typeof email === 'string' && email.includes('@'));

  const uniqueEmails = [...new Set(emails.map(email => email.trim()))];
  const currentViewers = spreadsheet.getViewers().map(user => user.getEmail());

  // Add new viewers
  for (const email of uniqueEmails) {
    if (ownerEmails.includes(email) || currentViewers.includes(email)) {
      continue;
    }

    try {
      spreadsheet.addViewer(email);
    } catch (e) {
      Logger.log(`Failed to add ${email}: ${e}`);
    }
  }

  // Remove viewers not on the list
  for (const email of currentViewers) {
    if (ownerEmails.includes(email) || uniqueEmails.includes(email)) {
      continue;
    }

    try {
      spreadsheet.removeViewer(email);
    } catch (e) {
      Logger.log(`Failed to remove ${email}: ${e}`);
    }
  }
}

Deployment Tips

Trigger it on Form Submit:
Go to Triggers → Add Trigger → Choose updateSheetSharing → Event: On form submit. See Google's trigger documentation for more details.
Avoid Too Many Writes:
If your form gets hundreds of submissions daily, consider adding debounce logic or batching updates periodically.
Error Handling:
Some domains may block sharing or throw quota errors — log and monitor failures via Logger.
Security Reminder:
Never share sheet access based on user input unless you validate the email (i.e., restrict form to logged-in users and auto-capture email).
"Google hasn't verified this app" Warning:
You'll likely see this warning when first running the script. This happens because Apps Script is accessing sensitive Google services (Sheets, Drive) and requesting OAuth scopes that Google considers sensitive.

Solution for Personal/Internal Use:
When you see the warning screen:
1. Click "Advanced" at the bottom
2. Click "Go to your project name"
3. Accept the permissions manually for your account
This is safe for personal scripts or internal organizational use. The warning appears because Google hasn't reviewed your specific script, but you can authorize it yourself.
Domain Restrictions:
Some organizations block external sharing entirely. If you're in a corporate environment, check with your IT team about Google Workspace sharing policies.
Quota Limits:
Apps Script has daily quotas for API calls. For high-volume forms, monitor your usage in the Apps Script dashboard under "Quotas" to avoid hitting limits. Check Google's quota limits for current limits.
Testing in Development:
Test the script on a copy of your sheet first. Create a test form and sheet to verify everything works before deploying to production.
Execution Time Limits:
Apps Script has a maximum execution time of 6 minutes per invocation. If your script processes a large number of emails, it might timeout. For high-volume scenarios, consider batching operations or using time-based triggers instead of form submission triggers. See Google's execution limits for detailed information.
Monitoring Executions:
After setting up triggers, you can monitor their execution in the Apps Script dashboard:
- Go to Executions in the left sidebar
- See a list of all recent trigger runs with timestamps
- Check execution status (success/failed)
- Click on any execution to view detailed logs
- Failed executions show error messages and stack traces
- Successful runs show "Execution completed" status
This is crucial for debugging. If your script isn't working as expected, check the Executions menu first to see if triggers are firing and what errors might be occurring.

Deep Dive: How Google Handles Millions of Triggers

Ever wonder how Google manages Apps Script triggers for millions of users worldwide? Here's what's happening behind the scenes:

Google's Trigger Infrastructure

Event-Driven Architecture: Google uses a sophisticated event-driven system where every Google Workspace action (form submission, sheet edit, time-based events) generates events that flow through their infrastructure.

Distributed Processing: When you submit a form, Google's systems:

Detect the form submission event
Route it to the appropriate Apps Script project
Execute your script in a sandboxed environment
Handle the response and any side effects (like sharing permissions)

Scalability Challenges: Google processes billions of events daily across:

Form submissions
Sheet modifications
Time-based triggers
Calendar events
Email triggers

Why the 6-Minute Limit?

The execution time limit isn't arbitrary. Google's infrastructure needs to:

Resource Management: Prevent runaway scripts from consuming excessive resources
Fair Usage: Ensure all users get reasonable access to computing resources
Cost Control: Apps Script runs on Google's infrastructure, and they need to manage operational costs
Reliability: Shorter execution times mean faster recovery from failures

Event Processing Pipeline

Form Submission → Event Queue → Trigger Router → Script Execution → Result Handler

Event Queue: Google maintains massive queues of events waiting to be processed
Trigger Router: Routes events to the correct Apps Script projects
Script Execution: Runs your code in isolated containers
Result Handler: Processes the output and applies changes (like sharing permissions)

Why Triggers Sometimes Fail

Rate Limiting: Google implements sophisticated rate limiting to prevent abuse and ensure fair resource distribution.

Resource Contention: During peak hours, the system might be under higher load, causing occasional delays or failures.

Network Issues: Between Google's internal services (Forms → Sheets → Apps Script), network hiccups can cause temporary failures.

Quota Management: Google tracks usage across all services to prevent any single user from overwhelming the system.

The Magic of "Eventually Consistent"

Google's systems are designed for "eventual consistency" - meaning:

Your trigger might not fire immediately
There might be a few seconds delay
But the system guarantees it will eventually process your event

This design allows Google to handle massive scale while maintaining reliability.

Why I Use This

I’ve used this in social group's data collection, closed feedback loops, and classroom setups. It works beautifully when:

You want lightweight access control without complex infrastructure
You trust the form submitters (or validate their identity)
You don't want to set up a whole database + auth system
You need something that "just works" without ongoing maintenance

It's not enterprise-grade security — but for small teams and quick workflows, it's a surprisingly robust solution that I've seen work reliably in production.

Final Thoughts

Apps Script has a quiet superpower: It brings automation to everyday Google tools that teams already use daily.

What I love about this approach is its simplicity. With just ~50 lines of code, you can build a simple access control system that feels like it was always meant to be there — tailored to your specific workflow.

And that's why I still reach for Apps Script for glue code like this — it's the Swiss Army knife of Google Workspace automation.

Feel free to adapt this script for your own use case. If you're dealing with something more complex (like edit permissions, or syncing to multiple sheets), you'll want to add further checks — but this core pattern will get you a long way.

End

That's all!

I hope you've found the article useful. You should try to use Apps Script if you haven't already. It has many interesting use cases. Feel free to share your thoughts and experiences.

Check more on

📬 My Go-To Engineering Newsletters (30+ Summarized)

Mir Mursalin Ankur — Thu, 22 May 2025 02:19:25 +0000

Engineering newsletters offer a streamlined way for professionals to stay informed about industry trends, learn new skills, and connect with a community. They are a convenient way to access curated information and expert insights, keeping you ahead of the curve in a rapidly evolving field.

Here’s a quick breakdown of the newsletters I read regularly, their key topics, and why they’re valuable for software engineers.

🧠 A. Software Engineering & System Design

1. ByteByteGo

Focus: System design, scalability, and backend architecture.
Why Read: Offers visual explanations of complex system design concepts, beneficial for technical interviews and architectural understanding.
Subscription: bytebytego.com

2. Quastor

Focus: System design, big tech engineering blog summaries, technical deep dives.
Why Read: Summaries of big tech engineering blogs and guides on API design, database paradigms, and performance optimization
Subscription: blog.quastor.org

3. System Design One by Neo Kim

Focus: In-depth system design case studies and architectural patterns.
Why Read: Provides practical insights into designing robust systems, enhancing your architectural skills.
Subscription: systemdesign.one

4. Michael Thiessen

Focus: Vue.js development, component design, and frontend architecture.
Why Read: Delivers actionable tips and patterns for building scalable Vue applications.
Subscription: michaelnthiessen.com

🧑‍💼 B. Engineering Leadership & Management

5. Engineering Leadership by Gregor Ojstersek

Focus: Engineering management, career growth, industry insights, career development, and personal journey.
Why Read: Covers team scaling, stakeholder management, and overcoming imposter syndrome to improve leadership skills for tech leads/EMs.
Subscription: newsletter.eng-leadership.com

6. The Pragmatic Engineer by Gergely Orosz

Focus: Software engineering leadership, industry insights, and career development.
Why Read: Offers deep dives into engineering practices and management strategies from a seasoned leader.
Subscription: newsletter.pragmaticengineer.com

7. Pointer by Suraj

Focus: Curated articles for engineering leaders, covering management and technical topics.
Why Read: Provides a concise selection of high-quality reads to stay updated on leadership trends.
Subscription: pointer.io

8. Refactoring by Luca Rossi

Focus: Engineering management, team dynamics, and productivity.
Why Read: Delivers practical advice on improving team performance and engineering processes.
Subscription: refactoring.fm

9. Manager.dev by Anton

Focus: Resources and insights for engineering managers.
Why Read: Offers tools and articles to enhance management skills and team leadership.
Subscription: manager.dev

10. The Caring Techie by Irina Stanescu

Focus: Empathetic leadership and team well-being.
Why Read: Emphasizes the human aspect of tech leadership, promoting a caring work culture.
Subscription: thecaringtechie.substack.com

11. Engineer’s Codex

Focus: Engineering principles and leadership insights.
Why Read: Explores the intersection of technical excellence and effective leadership.
Subscription: engineercodex.substack.com

12. Thrive Engineering

Focus: Engineering team growth and productivity.
Why Read: Provides strategies to build thriving engineering teams and foster innovation.
Subscription: thriveengineering.substack.com

📈 C. Product, Growth & Career Development

13. Lenny's Newsletter by Lenny Rachitsky

Focus: Product management, growth strategies, and career advice.
Why Read: Offers actionable insights from industry experts to accelerate your career.
Subscription: lennyrachitsky.com

14. Sarah Tavel's Newsletter

Focus: Investment perspectives and product-market fit.
Why Read: Provides valuable insights into building products that resonate with users.
Subscription: sarahtavel.substack.com

15. One Useful Thing by Ethan Mollick

Focus: Practical applications of research in work and life.
Why Read: Translates academic findings into actionable advice for professionals.
Subscription: oneusefulthing.substack.com

16. Nathan Baugh from World Builders

Focus: Storytelling and content creation strategies.
Why Read: Enhances your ability to communicate and build a personal brand.
Subscription: nathanbaugh.substack.com

17. The Developing Dev by Ryan Peterman

Focus: Weekly insights to accelerate your software engineering career, written by a Staff Software Engineer at Instagram.
Why Read: Offers actionable advice and mentorship for engineers aiming to progress from junior to senior roles.
Subscription: read.developing.dev

🧪 D. Data, AI & Analytics

18. Chartr

Focus: Data storytelling and visualizations.
Why Read: Simplifies complex data into engaging visuals, aiding in data literacy.
Subscription: chartr.co

19. SeattleDataGuy

Focus: Data engineering and analytics.
Why Read: Shares practical advice and industry trends in data engineering.
Subscription: seattledataguy.substack.com

20. DataEngineer.io by Zach Wilson

Focus: Data engineering education and career development.
Why Read: Offers courses and resources to advance in data engineering.
Subscription: dataengineer.io

🧰 E. Frontend & Web Development

21. Addy Osmani from Elevate

Focus: Web performance and frontend engineering.
Why Read: Provides deep dives into optimizing web applications.
Subscription: addyosmani.com

22. Hybrid Hacker

Focus: Full-stack development and tech tutorials.
Why Read: Shares hands-on guides and coding tips for developers.
Subscription: hybridhacker.substack.com

23. Tech World With Milan by Dr. Milan Milanovic

Focus: Technology trends and software development.
Why Read: Explores emerging technologies and their applications.
Subscription: techworldwithmilan.substack.com

🧑‍💻 F. Coding Challenges & Skill Development

24. Coding Challenges by John Crickett

Focus: Programming challenges and problem-solving.
Why Read: Enhances coding skills through regular challenges.
Subscription: codingchallenges.substack.com

25. Developing Skills by John Crickett

Focus: Career growth and skill enhancement.
Why Read: Provides strategies for continuous professional development.
Subscription: developingskills.substack.com

26. Craft Better Software by Daniel Moka

Focus: Software craftsmanship and best practices.
Why Read: Offers insights into writing clean and maintainable code.
Subscription: danielmoka.substack.com

27. Biweekly Engineering

Focus: Engineering updates and industry news.
Why Read: Keeps you informed about the latest in software engineering.
Subscription: biweekly-engineering.beehiiv.com

28. Level Up Coding by Trey Huffine

Focus: Simplifying complex programming concepts, system design, and AI through engaging visuals and tutorials.
Why Read: Ideal for developers seeking to deepen their understanding of coding and system design with accessible content.
Subscription: levelupcoding.substack.com

📰 G. General Tech & Industry News

29. The Engineer Newsletter

Focus: Cutting-edge engineering trends (semiconductors, space tech, clean energy) and industry breakthroughs.
Why Read: Quick updates on tech milestones (e.g., Intel’s 18A chips, SpaceX Starship launches) and premium deep dives.
Subscription: theengineernews.substack.com

30. The Medium Newsletter

Focus: Curated articles across various topics.
Why Read: Discover diverse perspectives and stories from the Medium community.
Subscription: medium.com/newsletter

By subscribing to these newsletters, you can stay updated on various aspects of software engineering, from technical skills to leadership and industry trends.

End

That's all!

I hope you’ve found the article useful. If you haven’t already, you should read the newsletters. They are full of knowledge and experience. Reading newsletters could be part of your career growth and personal improvement.

Check more on

Apps Script - List all the newsletters filling up your Gmail. Selective unsubscribing got easy

Mir Mursalin Ankur — Sun, 26 Jan 2025 14:57:46 +0000

Are you subscribed to many newsletters that are filling up your Gmail? You can clean up all newsletters by filtering Gmail's unsubscribe text. You may have known that already. And I am not writing to describe that procedure. You are intelligent enough to do that with a little googling.

The Problem

I am writing to tell you about a special case that happened to me. I was subscribed to many newsletters I felt interesting. I used to read newsletters almost daily. However, little by little I got overwhelmed with the increasing number of subscribed newsletters.

So, I decided to filter my subscribed newsletter. I didn't want to delete old newsletters. I just wanted to list my current subscribed newsletters (which are unique). Check them a bit and unsubscribe which feels unnecessary.

The Solution

Turns out, there is no easy way to do it from Gmail. So, I had to do a little code. Google has a service called Apps Script. It lets you run some code. You can fetch and manipulate data from your used Google products. So, you can automate many boring manual tasks. Believe it or not, I had subscriptions to around 100 newsletters from different websites, services, and tech newsletters. I reduced my subscribed newsletters to only those that seemed appropriate.

So, Here's the instructional summary of what I did:

Create a new Google Sheet
Go to Extensions > Apps Script of my new Google sheet
Write the necessary code in the code editor of Apps Script which does the following:
- Get unique mail list senders with other necessary info like name
- Wrote that data in an existing Google sheet
Save the script and give it a name
Go to Run > main, then grant permissions
The unique email addresses will populate your spreadsheet
After that, from Gmail you can unsubscribe from unwanted senders

My code had the following parts:

A main function that calls _getUniqueMailingListSenders function
The _getUniqueMailingListSenders takes the following parameters:
- applicable filter which will be applied to filter the Gmail
- The column title of the Google sheet
- A boolean parameter clearSheet, which declares if I want to clear my existing sheet or not
Inside the _getUniqueMailingListSenders function, it filters all the emails of my Gmail
Later, it loops through the filtered emails and adds the From email to a javascript set
The from field in Gmail filter also keeps the name of the email sender
So, A loop runs on javascript set, and regular expression gets applied to separate the name and email and save in a map
This could also be done in an earlier loop, but I kept it in a separate loop for simplicity.
The result can be checked via Execution log using the console.log() of javascript
However, adding that result in Google sheet is more convenient
So, the active sheet gets fetched (From where Extensions > Apps Script was called) and cleared (depending on clearSheet boolean parameter)
Then, it finds the last used column and sets the columns for emails and names dynamically after the last used column
It sets the column title of Google sheet (with current date info for checking later)
And writes each unique email address and corresponding name to the new columns

Full Code:

function _getUniqueMailingListSenders(
  searchOption,
  title,
  clearSheet = true,
) {

  // Search in Gmail to check all threads
  const threads = GmailApp.search(searchOption);

  // Use a Set to store unique senders
  const senders = new Set();

  // Loop through each thread
  threads.forEach(thread => {
    const messages = thread.getMessages();
    // Loop through each message in the thread
    messages.forEach(message => {
      senders.add(message.getFrom());
    });
  });

  const emailData = new Map();

  // Find email and sender name and save it in a map
  senders.forEach((sender) => {
    const emailMatch = sender.match(/<([^>]+)>/);
    const email = emailMatch ? emailMatch[1] : sender;
    const name = sender.replace(`<${email}>`, '').trim();

    if (!emailData.has(email)) {
      emailData.set(email, name);
    }
  });

  // Get the active sheet
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

  if (clearSheet) {
    sheet.clear();
  }

  // Find the last used column
  const lastColumn = sheet.getLastColumn();

  // Set the columns for emails and names dynamically after the last used column
  const emailColumn = lastColumn + 1;
  const nameColumn = lastColumn + 2;
  const currentDate = new Date().toLocaleDateString();

  // Add headers with the current date in the new columns
  sheet.getRange(1, emailColumn).setValue(`${title} - Email - ${currentDate}`);
  sheet.getRange(1, nameColumn).setValue(`${title} - Name - ${currentDate}`);

  // Start writing below the header
  let row = 2;

  // Write each unique email address and corresponding name to the new columns
  emailData.forEach((name, email) => {
    console.log(`Adding data on column (${emailColumn}, ${nameColumn}) and row ${row}: `, {email, name});
    sheet.getRange(row, emailColumn).setValue(email);
    sheet.getRange(row, nameColumn).setValue(name);
    row++;
  });
}

function main() {
  // Search for emails that belong to a mailing list
  _getUniqueMailingListSenders(
    'list:(<*>)',
    'Unique Email Sender',
    false,
  );

  // Search for emails that belong to a substack mailing list
  // _getUniqueMailingListSenders(
  //   // 'list:(<*techworldwithmilan@substack.com>)',
  //   'list:(<*.substack.com>)',
  //   'Unique Substack Email Sender',
  //   false,
  // );
}

End

That's all!

I hope you've found the article useful. You should try to use Apps Script if you haven't already. It has many interesting use cases. Feel free to share your thoughts and experiences.

Check more on

Forem: Mir Mursalin Ankur

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

Real Numbers from Two Test Projects

How Each Tool Works

Graphify — Two-Pass Graph with Communities

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

Installation

Ubuntu

macOS

Step 1: Create Ignore Files

Step 2: Build the Graphs Manually

code-review-graph

Graphify (AST-only, no LLM cost)

Step 3: Register with Your AI Agent

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

Graphify (AI Agent Integration)

Auto-Update on Commit (the full picture)

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

Enforcing Graph-First: The Smart Grep Hook

Real Token Cost Comparison

Symbol and concept lookups

What grep cannot do at all

get_review_context_tool — best single call for code review

The winner by query type

Real session measurement: complete token accounting

Strip Unused CRG Tools (Cuts Schema Overhead 70%)

Expensive Calls to Avoid

Making This Work for Any Project

Step 4: Verify Your Setup

Check CLI installation

Check graph outputs exist

Check GRAPH_REPORT.md freshness

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

Check MCP server config

Check git hooks

Test incremental update speed

Test vault sync (if vault is configured)

Step 5: Query the Graphs

Graphify CLI

Inside Your AI Agent

Step 6: Auto-Update Strategies

Strategy A: Manual Update (Always Available)

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

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

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

Step 7: Generate Additional Outputs

Wiki (Markdown pages per community)

Interactive Visualization

Blast-Radius Analysis

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

Three Vault Modes

Mode 1: Browser Only (Zero Setup)

Mode 2: Project Vault

Mode 3: Global Vault (Multiple Projects)

Cross-Repo Merged View

Switching Between Vaults

Graph View Filters

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

Keeping the Vault Fresh

Add vault regen to git hooks

Complete Auto-Update Flow

Quick Reference

Installation

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

Verify (run only the rows for tools you installed)

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

Watch Mode

Why Not a Vector Database?

Files Created / Modified

References

Let's Connect

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

The mental model: source of truth vs. working surface

Opening any PR locally in seconds

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

Comment sync — both directions, both opt-in

A concrete 90-second flow

Why this matters for AI-assisted review

What it honestly saves you

Where it stops

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)

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

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