DEV Community: Suraj lama

DevDocs Navigator: An AI Agent That Traces API Breaking Change Dependencies

Suraj lama — Tue, 29 Sep 2026 17:19:02 +0000

What I Built

DevDocs Navigator is a CLI agent that helps developers navigate multi-version API documentation. It connects to a Sanity Context MCP knowledge base of structured API docs and answers questions that keyword search simply can't — like generating ordered migration plans that respect breaking change dependencies, or explaining why a 409 error in v2 becomes a 422 in v3.

The agent is built with the Claude SDK (TypeScript) and connects to Sanity Context via MCP. It queries a knowledge base of structured PayFlow API documentation spanning 3 major versions.

Repo: github.com/suraj16thjan/devdocs-navigator

Sanity Project ID: oqa25u7d

Why Structure Matters Here

Developer documentation is one of the best examples of content where structure is the entire point. Consider this question:

"I'm on PayFlow API v1 and need to get to v3. What do I do?"

A keyword search finds pages mentioning "v1", "v3", and "migration" — maybe even the right pages. But it can't tell you:

JWT auth must be implemented first — every v3 endpoint requires it, so nothing else works until this is done
Multi-currency amounts depend on JWT auth — you can't test the new amount format without v3 access
Webhook signature changes depend on JWT auth too — re-registering webhooks requires v3 API calls
Subscription event renames depend on the webhook signature change — the new event names only fire on v3 webhook registrations
The webhook envelope format change (from v1→v2) must happen AFTER renaming charges to payments — the new event types reference "payment" objects

That ordering isn't in any single document. It emerges from the relationships between documents: breaking changes reference which other breaking changes they depend on, migration paths link to the breaking changes they address in a specific order, and endpoints track which version introduced and deprecated them.

This is exactly what Sanity Context enables — structured content where the relationships are first-class data, not implicit context a reader has to reconstruct.

The Content Model

The knowledge base contains 32 structured documents across 5 schema types:

API Versions (3 documents)

Each version tracks its status (stable/deprecated/sunset), release date, sunset date, and key highlights.

Endpoints (12 documents)

Each endpoint records its HTTP method, path, which version introduced it, which version deprecated it, what replaced it (a reference to another endpoint document), auth requirements, rate limits, parameters (with version-specific additions/removals), and version-specific behavior notes.

Breaking Changes (9 documents)

This is where the structure shines. Each breaking change records:

Severity (critical/major/minor)
Affected endpoints (references to endpoint documents)
Affected categories (payments, webhooks, etc.)
Migration steps (ordered)
Dependencies — references to other breaking changes that must be applied first
Before/after code examples

The dependency chain between breaking changes is what makes the agent's migration plans correct and ordered. For example:

bc-v3-jwt-auth (no dependencies)
  ↳ bc-v3-multi-currency (depends on JWT auth)
  ↳ bc-v3-webhook-signatures (depends on JWT auth)
    ↳ bc-v3-subscription-events (depends on webhook signatures)
  ↳ bc-v3-idempotency-uuid (depends on JWT auth)

Migration Paths (3 documents)

Pre-computed migration guides (v1→v2, v2→v3, v1→v3) with ordered steps, each referencing the relevant breaking change. The v1→v3 path is particularly interesting — it combines and reorders steps from both incremental paths, noting where changes can be collapsed (e.g., skip the v2 amount format and go straight to multi-currency).

Error Codes (5 documents)

Each error code has version-specific behavior — the same error code can return different HTTP status codes, different response body structures, and have different root causes depending on the API version. For example:

Error	v1	v2	v3
`IDEMPOTENCY_CONFLICT`	Not supported	HTTP 409, any string key	HTTP 422 (changed!), UUID v4 required
`AUTH_INVALID`	API key only	API key or OAuth, detailed error	JWT only, specific sub-codes
`CURRENCY_MISMATCH`	Doesn't exist	Doesn't exist	HTTP 422, shows expected vs received

How the Agent Works

The agent uses a standard MCP client-server architecture:

User Question
     ↓
Claude (with MCP tools)
     ↓
Sanity Context MCP Server
     ↓
Knowledge Base (structured PayFlow docs)
     ↓
Grounded Answer

On startup, the agent connects to the Sanity Context MCP endpoint and discovers available tools
User asks a question
Claude receives the question along with the MCP tools from the knowledge base
Claude calls the appropriate tools to query the structured content
Tool results come back with the structured data — including references, dependencies, and version-specific fields
Claude synthesizes the answer, respecting the structure (dependency ordering, version applicability, etc.)

Example Interactions

"What changed between v2 and v3?"

The agent queries breaking changes introduced in v3, finds 5 of them, and presents them in dependency order — not alphabetical, not by severity, but by the order you'd need to apply them. It notes that JWT auth is the critical first step since everything else depends on it.

"I'm getting a 429 after upgrading to v2, what's different?"

The agent queries the RATE_LIMIT_EXCEEDED error code and surfaces the version-specific behavior: v1 had a hard cap at 100/min with X-RateLimit-* headers, while v2 uses 60/min sustained with burst to 120 and IETF RateLimit-* headers. It also notes the Retry-After header is now available.

"How do I migrate webhooks from v1 to v3?"

This is where dependency chains matter. The agent traces:

First apply bc-v2-charges-renamed (charges → payments)
Then bc-v2-webhook-format (flat → envelope, depends on step 1)
Then bc-v3-jwt-auth (needed for v3 webhook registration)
Then bc-v3-webhook-signatures (SHA-1 → SHA-256, depends on step 3)
Then bc-v3-subscription-events (event renames, depends on step 4)

No keyword search could produce this ordered sequence. It requires traversing the dependency graph in the structured content.

Tech Stack

Content: Sanity Studio v3 with TypeScript schemas
Knowledge Base: Sanity Context with GROQ dataset binding
Agent: Node.js + Claude SDK (@anthropic-ai/sdk) + MCP SDK (@modelcontextprotocol/sdk)
Transport: Streamable HTTP / SSE to Sanity Context MCP endpoint

What I'd Do Differently

If I had more time, I'd:

Add a web UI with interactive migration checklists
Support real API documentation (Stripe, Twilio) instead of a fictional API
Add a "diff my code" feature where you paste your integration code and the agent identifies which breaking changes affect it
Enable auto-refresh so the knowledge base stays in sync as docs change

The Structured Content Advantage

The core insight: developer documentation is inherently relational. An endpoint exists in some versions but not others. A breaking change affects specific endpoints and depends on other breaking changes being applied first. An error code behaves differently across versions. Migration is an ordered graph traversal, not a text search.

Sanity Context makes these relationships queryable through MCP, which means an AI agent can reason about them — generating correct migration plans, version-aware error explanations, and dependency-ordered change lists that no amount of keyword searching could produce.

gitsmith: A Terminal UI for Both GitLab and GitHub

Suraj lama — Mon, 31 Aug 2026 08:30:48 +0000

I keep one foot in GitLab and the other in GitHub. Both have solid CLIs — glab and gh — but when I need to scan a list of merge requests, check a failing pipeline, read a diff, and approve something, that's four commands, four walls of JSON, four context switches. The web UI works, but it's slow, and I lose my terminal flow every time I reach for it.

I wanted one screen where I could do all of it with a keyboard. So I built gitsmith.

What it does

gitsmith is a terminal UI that wraps glab and gh. Run it inside any git repo and it auto-detects the host from your remote. Run it outside a repo and it asks which forge to use, lists your projects, and drops you in.

There are 11 tabs — Issues, MRs/PRs, Pipelines, Runners, Releases, Tags, Branches, Commits, Todos, Milestones, Members — and every state is listed. Closed issues show up below open ones, so you can reopen something without opening a browser. Protected branches sit above the rest. The tab bar is reorderable, and you can hide tabs you don't use.

Side-by-side diffs

This is where I spent the most time. gitsmith renders syntax-highlighted side-by-side diffs using syntect, with line numbers, a sticky file header, and a file list that follows your scroll. Press v on any MR or Enter on a commit.

[ and ] jump between files. The whole thing runs in the terminal — no browser, no latency.

Pipeline drill-down

Enter a pipeline to see its jobs. Enter a job to get its live-tailing ANSI log with severity coloring — ERROR lines in red, WARN in yellow, timestamps dimmed, and the CI's own ANSI colors passed through untouched. It follows the latest output like GitLab's trace view.

Bridge jobs drill into downstream pipelines automatically.

Actions, not just views

gitsmith isn't read-only:

Approve, merge, and close MRs/PRs
Close, reopen, and comment on issues (opens $EDITOR for the comment body)
Retry or cancel pipelines and individual jobs
Create new MRs/PRs, issues, pipelines, and tags
Add members with a role picker

All destructive actions are behind a [y/n] confirm.

Zero auth setup

gitsmith shells out to glab and gh, so it uses your existing authentication. No tokens to configure, no OAuth flows. If you've already run glab auth login or gh auth login, you're set.

It reads the config files of both CLIs directly — glab's config.yml and gh's hosts.yml — checking $GLAB_CONFIG_DIR, $XDG_CONFIG_HOME, ~/.config, and platform-specific paths. Only host names are read; tokens in those files are never touched.

Multi-host, multi-instance

Press S to switch between GitLab and GitHub (or between self-hosted instances) without restarting. Press P to fuzzy-search your repos on the current host.

Every configured instance from both CLIs is offered instantly.

Under the hood

gitsmith is written in Rust, about 10,500 lines across a handful of focused modules. The UI is built with ratatui, and syntax highlighting uses syntect with the pure-Rust regex backend so cargo install needs no C toolchain.

Lists pull 100 rows per page and keep fetching in the background (up to 500) while you read, so you don't hit the API's default 20-30 row ceiling.

Nine built-in themes — Neon, Tokyo Night, Gruvbox, Rose Pine, Catppuccin, Nord, Dracula, Solarized, Everforest — press t to pick one with a live preview.

Get started

Quick install on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/suraj16thjan/gitsmith/main/install.sh | bash

Or via Cargo:

cargo install gitsmith --locked

Requirements: glab authenticated for GitLab repos, and/or gh authenticated for GitHub repos.

gitsmith is MIT-licensed and open source. Contributions, bug reports, and feature ideas are welcome.

suraj16thjan / gitsmith

Terminal UI for GitLab & GitHub: issues, MRs/PRs, pipelines, live job logs, diffs, and a fuzzy repo switcher — one keyboard-driven interface over glab & gh.

gitsmith

A fast terminal UI for GitLab and GitHub, built with ratatui. gitsmith wraps the official glab and gh CLIs and auto-detects which one to use from your git remote — one keyboard-driven interface for issues, merge/pull requests, pipelines, jobs, logs, diffs, and more.

Installation

Quick install (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/suraj16thjan/gitsmith/main/install.sh | bash

Downloads the prebuilt binary for your platform from the latest GitHub release and installs it to ~/.local/bin (or /usr/local/bin when writable). Pin a version with GITSMITH_VERSION=v0.2.2 or change the target with GITSMITH_BIN_DIR=~/bin. No Rust toolchain required.

From crates.io

cargo install gitsmith --locked

From source

git clone https://github.com/suraj16thjan/gitsmith
cd gitsmith
cargo install --path . --locked   # installs the `gitsmith` binary to ~/.cargo/bin

Or just run it in place without installing:

cargo run --release

Requirements

Rust (stable)
glab authenticated for GitLab repos, and/or gh authenticated for GitHub repos
Run it anywhere — inside a…

View on GitHub