DEV Community: Yash Kumar Saini

I Revived DevNotion (multi agent blog workflow) — And Finally Perfected it

Yash Kumar Saini — Sat, 06 Jun 2026 13:58:54 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

Every Monday standup, someone asks: "What'd you ship last week?" And every Monday I freeze. Did I merge that PR Tuesday or Wednesday? Was the gnarly part in the harvest code or the publisher? I'd sit there scrolling my own commit history like it belonged to a stranger.

So back in March I built something to answer the question for me. DevNotion — a Mastra pipeline that reads a week of my GitHub activity, writes it up as a first-person blog post, and ships it to Notion and DEV.to. It won $500 in the Notion MCP Challenge. Then I did what everyone does with a hackathon project: nothing, for two months.

Here's the thing, though. It worked, but I never fully trusted it. One LLM, no say in it. It published the instant it finished writing — no preview, no edit, no "hang on, let me read that first." And when I opened the repo back up for the Finish-Up-A-Thon, the very first run failed in the most embarrassing way I can think of. Honestly? Best thing that could've happened. It showed me exactly what "finish this" was supposed to mean.

DevNotion v2 is the version I should've shipped the first time. It writes a draft, shows it to me, lets me edit it, and only publishes when I say go. Multiple LLM providers. Three publishing targets. A deterministic cover image, much better data, a real test suite. Seven phases, 51 tests, a one-command setup wizard — and, most of all, a failure mode that protects my name instead of betting it.

One idea ran under the whole rebuild: a tool that writes in your voice and posts under your name has to be trustworthy before it gets to be convenient.

Demo

Repo: github.com/yashksaini-coder/DevNotion

yashksaini-coder / DevNotion

DevNotion is an agentic server built using 3 mastra agents to work as a pipeline to publish weekly blogs on Notion Pages & DEV.to

DevNotion

Turn your weekly GitHub activity into a polished, illustrated blog post — narrated by an LLM, reviewed by you, and published to Notion, DEV.to, and Hashnode.

DevNotion is a Mastra pipeline of specialist agents: it harvests a week of your GitHub work, narrates it into a first-person post, generates images, and lets you preview/edit before it publishes anywhere. Originally built for the DEV.to × Notion MCP Challenge (where it won $500); v2 was rebuilt for the GitHub Finish-Up-A-Thon with multi-LLM support, a review dashboard, image generation, richer harvesting, and a fail-safe publishing flow.

What's new in v2

v1	v2
LLM	Gemini only	Gemini · OpenAI · Anthropic (provider abstraction; default `gemini-3-flash-preview`)
Publish targets	Notion + DEV.to	Notion + DEV.to + Hashnode
Flow	generate → publish immediately	generate → preview → edit → approve → publish
UI	none (CLI/cron)	web dashboard (trigger, preview, edit, history)
Images	none	deterministic stats

…

View on GitHub

Three specialist agents, with generation and publishing deliberately split by a human approval gate:

Each agent does one thing and only one thing. Harvest is pure data — two quick GraphQL/REST passes over the week, no LLM anywhere near it. Narrate is the single model call: raw data goes in, a first-person post comes out, in whatever tone you picked. Publish is plumbing — a Notion page, a DEV.to draft, a Hashnode draft if you've set it up, plus the cover and the footer. And right in the middle, between writing and shipping, there's a human. That gate is the whole reason v2 exists.

The rule I kept from v1: an LLM only shows up where it earns its spot. Harvesting the data, drawing the stats card, pushing to each platform — that's all plain deterministic code. No tokens, no rate limits, no chance of the thing inventing a number. The model writes the prose. Everything around it is code I can unit-test. That's the only reason I'm comfortable letting it post under my name without re-reading every figure first.

In practice it's quick. I kick off a run (scheduled, or by hand from the dashboard) and a few seconds later there's a draft sitting there marked Preview Ready. Not published. I read it, fix a sentence or two right in the browser, hit Approve & Publish. Then it goes out — and even then it goes out as a draft on each platform, not a live post.

The Comeback Story

Where v1 actually was

I genuinely thought I'd left v1 in decent shape. The first run set me straight in about four seconds:

Narrate step: LLM call failed: You exceeded your current quota …
  limit: 0, model: gemini-2.0-flash
Publish: Created Notion page: https://app.notion.com/…
Publish: Published DEV.to article: https://dev.to/…

Read it twice. The narration failed — and the thing published anyway. v1 had this well-meaning "always produce a blog" fallback, so a quota error quietly shipped a bare stats stub to my real DEV.to account. For a tool whose entire job is to represent my work? That's about the worst thing it could possibly do.

That one log was hiding three separate bugs:

Wrong model, wired to nothing. The live workflow read a different config key than the one I'd been carefully setting. So it quietly fell back to a retired gemini-2.0-flash, whose free quota is now 0. I'd been turning a knob connected to thin air.
The failure was silent. A try/catch swapped in a deterministic stub and marched straight on to publishing.
Nothing ever let me look. No preview, no gate, no pause before it went live.

And a sneakier one underneath all that: a week with 13 direct commits reported +0/-0 lines changed, because line stats were summed from pull requests only. The posts came out technically accurate and completely dead.

What actually bothered me wasn't any single bug. It was that the worst one was the helpful one. That try/catch-into-a-stub got added in v1 on purpose, to guarantee a post always shipped. And that good intention is exactly what turned a recoverable quota error into a published embarrassment. Turns out "always succeed" is the wrong goal for something that talks for you. "Never lie" is the right one.

So I rebuilt it in seven phases. Each one got a quick spec, a plan, the actual work, a review, and a green test run before I let myself start the next. Not ceremony — it's the fail-loud rule pointed at my own process. Every phase had to prove itself (types clean, tests green) before anything got stacked on top, so nothing could quietly rot three phases deep. Here's how it went.

Phase 1 — Make narration trustworthy

First, one place to choose the model, defaulting to gemini-3-flash-preview (which, unlike the thing it replaced, actually has a free tier). Then the part that matters most — narration that fails loud:

// src/llm/narrate.ts
// FAIL-LOUD: throws on provider error or unparseable output. NEVER returns a
// deterministic fallback — the caller decides what to do with a failure.
export async function narrateBlog(provider, data, opts = {}) {
  const system = buildNarratorSystemPrompt(opts.tone ?? 'casual', opts.focusAreas);
  const prompt = `Generate a blog post from this GitHub contribution data:\n\n${JSON.stringify(data, null, 2)}`;

  const text = await provider.generate(prompt, {
    system,
    maxTokens: opts.maxTokens ?? 8192, // Gemini 3 is a thinking model — small budgets starve the answer
  });

  const parsed = parseFrontmatter(text);
  if (!parsed.success) throw new Error(`Narration failed: ${parsed.error}`);
  return parsed.data.blog;
}

If narration throws, the step throws, the run is marked failed, and the publish step never runs. A quota error can't reach a single reader anymore. (The old deterministic builder is still in there — but now it's a manual escape hatch you reach for on purpose, never something that fires on its own.)

Trustworthy also meant not living and dying by one vendor's quota. v1 was Gemini or nothing. v2 runs every call through a tiny provider interface, so an outage or a quota wall is a config change instead of a rewrite:

// src/llm/provider.ts — one interface, three interchangeable backends
export function createProvider(env: Env): LLMProvider {
  switch (env.LLM_PROVIDER) {
    case 'openai':    return createOpenAIProvider(env);
    case 'anthropic': return createAnthropicProvider(env);
    default:          return createGeminiProvider(env);
  }
}

The Gemini side also rotates through a comma-separated list of keys (keys[keyIndex++ % keys.length]). Three free keys gets you somewhere around 1,500 requests a day between them, which is plenty for a weekly run plus a day of messing around. Swapping the whole brain of the pipeline is one env var now.

Phase 2 — Split generate from publish

This was the keystone, and it's the reason v1 never had a preview to begin with. The old workflow welded harvest → narrate → publish into one chain, and that chain's output schema dropped the blog body on the floor. There was nothing to preview because the content never survived the handoff between steps. The smoking gun was the workflow's own output type: it carried URLs and counts and no content field at all. You can't bolt a preview screen onto something that throws the draft away. So splitting it wasn't a nice-to-have stacked on v1. It was the thing that had to happen before anything else could.

v2 cuts the pipeline in half. A generate phase makes a full, previewable draft and stops. A separate publish step runs only when you approve, edits and all:

// src/server/routes/run.ts
// POST /run  → generates a draft, stores it, sets status "preview". Publishes NOTHING.
// POST /publish/:jobId → applies your edited markdown, then calls publishBlog().

That one cut bought three things at once: a safe failure mode, an editable preview in the browser, and run history that finally shows what actually got written. And the publisher turned into a single function that both the dashboard and the cron job call:

// src/publish/publish-content.ts — one publisher, used by cron AND the dashboard
export async function publishBlog(opts: {
  blog; weeklyData; publishMode: 'auto' | 'draft';
  images?: { statsCardPath?: string };
}): Promise<PublishResult> { /* notion → devto → hashnode → write planner + footer */ }

Tying it together is a little JSON-backed run store that's basically the pipeline's state machine. Every run walks a fixed path — running → preview → publishing → published, or failed — and that one record is what the dashboard lists, what the preview renders from, and what publish reads back when you hit approve. It's also where the Dev log #n counter lives, so the numbers stay in order whether a post came from the dashboard or the cron job. One ledger, two doors in.

Phase 3 — Harvest the real diff

The +0/-0 bug is dead. A second, bounded GraphQL pass walks each active repo's commits — real additions and deletions, changed-file counts, and the directories you actually touched — so the narrator can talk about specifics instead of waving its hands. That same week that used to report nothing now says:

week 2026-05-27 → totals +2,252/-293
- DevNotion:        +2,220/-282, files=25, areas=[src/server, src/tools, bin]
- yashksaini-coder: +24/-3,      files=5,  areas=[assets, .github/workflows]

It's quota-safe on purpose: hard caps on how many repos and commits it'll look at, and every commit wrapped in its own try/catch so one bad fetch can't sink the whole week:

// src/tools/github-commits.ts — bounded, best-effort changed-file harvest
for (const sha of shas) {
  try {
    const res = await fetch(`https://api.github.com/repos/${owner}/${name}/commits/${sha}`, { headers });
    if (!res.ok) continue;
    for (const f of (await res.json()).files ?? []) paths.push(f.filename);
  } catch {
    // skip this commit on any error — never sink the whole week
  }
}

Two passes, on purpose. GraphQL is great for breadth — a whole week across a pile of repos in one query. The per-commit file lists come from a few targeted REST calls instead, each one cheap and each one isolated. This was the single thing v1's readers kept telling me: commit titles are cryptic, the diff is where the story actually is. Now it's in there.

Phase 4 — Sharper writing + an author footer

I tightened the narrator's instructions. Lead with a character or a moment, not a stat line. A hard no stat-dumping rule — the numbers live on the card, the prose doesn't need to recite them. And lean on the new touched-areas data, so a post can say "a week deep in src/server" instead of "made several changes." You still get to pick the tone — casual, professional, technical, storytelling — but those rules hold no matter which one you choose. Then I gave every post, on every platform, the same author footer, built from one config file:

---
**Yash K Saini** — Engineer, building in public — AI/ML, low-level (Rust/C/C++), and open source.

[GitHub] · [X] · [LinkedIn] · [Portfolio]

It gets stamped on at publish time, not written by the narrator. So you can't accidentally delete it in the preview, and Hashnode gets it for free.

You can see the difference in the titles. One real run opened with "Bridging the Gap: TLS Interop, p2p Hardening, and Neovim Refinement" — pulled straight out of the directories I'd been living in that week. Not "This week I made 35 commits." That's what the touched-areas data buys you.

Phase 5 — The cover image

My first instinct was the obvious one: an AI cover. Nano Banana (gemini-2.5-flash-image), prompted off the week's headline. I wired the whole thing up… and found out the free tier gives image generation a quota of limit: 0. It never produced a single cover. So I was carrying a flaky, rate-limited dependency that did, in practice, nothing.

So I ripped it out and used something I already had. The stats card — a hand-built SVG rendered to PNG with @resvg/resvg-js, showing the week's exact numbers — happens to already be 1200×630, which is cover/OG size. So I just made it the cover:

// src/images/stats-card.ts — the numbers come from code, never from a model
const stats = [
  [fmt(data.totalCommits), 'commits'],
  [`+${fmt(data.totalAdditions)}`, 'added'],
  [`-${fmt(data.totalDeletions)}`, 'removed'],
  // …
];

It leads with the post title and the headline numbers (commits, PRs, reviews, lines, repos) and becomes the cover everywhere: DEV.to's main_image, the Hashnode cover, the Notion page cover. The Dev log #n bit stays on the article title, not the card, so the banner is all title and stats, and a long title wraps instead of running off the edge. Because the card is built from code, no model can ever round 2,252 down to "about 2,000." And here's the bit I liked: ripping out the AI cover made the feature more reliable, not less. It went from never working to always working in the same commit that deleted code. No API, no quota, no fallback path. It just renders.

Phase 6 — A dashboard worth screenshotting

My three dashboard routes had quietly drifted into three slightly-different stylesheets. I pulled them back into one design system — shared tokens, one shell, shared components — and gave it a deliberate Swiss / International Typographic feel: tight type scale, one orange accent, lots of breathing room. It's all server-rendered HTML, no build step, straight through tsx, which keeps the footprint tiny and the dependency list short. Most of the effort went into the preview/edit screen, because honestly that screen is the product. It's where you read the draft, tweak a line, and decide to ship.

Phase 7 — Tests

51 tests across 18 suites now cover the frontmatter parser, the fail-loud path, the deterministic fallback, tag normalization, provider and model selection, publish-target selection, the diff aggregation, and the stats-card builder (cover title-strip and wrap included). They run in under two seconds and they're deliberately boring. The point isn't cleverness — it's a regression net under the deterministic spine, so something like swapping out the cover implementation can't quietly break publishing.

Setup in one command

v1's setup was a .env scavenger hunt: copy the example, guess which keys you actually need, find out you missed one when a run blows up halfway through. npx devnotion init is a wizard instead. It asks for each credential, checks it with a live API call (green check or red error, right there in the terminal), and writes a clean .env.local. Small thing. But something that calls itself finished shouldn't make the first five minutes the worst five.

Before vs after

	Before (v1)	After (v2)
Failure mode	silently published a stub	fail-loud — publishes nothing
Review	none — instant publish	preview, edit, approve
LLMs	Gemini only	Gemini / OpenAI / Anthropic
Publish targets	Notion + DEV.to	+ Hashnode (Subscription)
Line stats	PR-only (`+0/-0` on commit weeks)	real per-commit deltas + touched areas
Cover image	none	Deterministic stats card, used as the cover
Setup	hand-edit `.env`	`npx devnotion init` wizard
Tests	a handful	51 across 18 suites

Before: "It works, but you have to trust it blindly."
After: "It works, and it gets out of your way — safely."

Publishing responsibly (the research that turned into a feature)

Around phase five I almost bolted on auto-publishing to a couple more platforms. Then I did the boring thing first and actually read the rules. The question I typed into the search bar was blunt: "is automated/AI publishing even allowed here, and can it get my account restricted?" The answers ended up reshaping the design.

Medium is a dead end for automation, on two counts. Its publishing API was archived in 2023 (no new integration tokens), and its AI content policy gives undisclosed AI writing "Network Only" distribution and can pull it outright. An auto-posted AI dev-log is exactly what that policy is aimed at — so Medium's off the roadmap by design, not by accident.
Hashnode has a real publishing API, but its Code of Conduct bans "automated or bulk posting" and self-promotion without contributing, and its terms let them suspend accounts at their discretion. A genuine weekly post is fine. Blind, scheduled, multi-account auto-posting is the pattern they're watching for.
DEV.to is the friendliest to drafts and review, which is exactly the workflow I landed on anyway.

The fix wasn't to publish less. It was to publish honestly:

Draft by default, human approval required. Every platform gets a draft; I review and edit it in the dashboard, then publish on-platform myself. Nothing ships unattended.
A disclosure footer on every post — small, bold, Generated by DevNotion. No hiding the tool.
A Dev log #n title prefix, so the series is honest about what it is.

The thread through all of it is disclosure over cleverness. A reader — and a platform's moderation team — can tell exactly what this is and whose name is on it. That's cheaper than building some workaround, and a lot cheaper than getting an account suspended.

That one search turned a feature I'd have rushed into a constraint that made the whole thing more defensible. "Finished" doesn't just mean it runs. It means it won't get your accounts pulled.

My Experience with GitHub Copilot

Reopening a codebase you haven't touched in months is mostly just remembering. You spend the first few hours working out why past-you did what they did before you can change any of it. That's where pairing with AI actually paid off, and it was almost never "write this function." It was "help me understand this again." A few moments stuck with me more than any autocomplete:

Diagnosing the silent bug. The most useful assist wasn't generated code — it was tracing why setting the model config changed nothing. Walking the two divergent code paths with an AI partner surfaced the split-brain config in minutes, instead of an afternoon of console.log archaeology.
The provider abstraction. Describing "one interface, swap Gemini / OpenAI / Anthropic" in plain English got me a clean factory I refined, instead of writing it from a blank file.
Relearning an unfamiliar API. Mastra's workflow primitives had shifted since I first used them. Rather than spelunking changelogs, I described the harvest → narrate → publish shape I wanted, let the assistant scaffold the createStep/createWorkflow calls, then fixed the schema wiring against the real types.
Knowing when to delete. I started wiring an AI cover via the Nano Banana API and paired to figure out its quirks — Gemini image models return bytes via result.files, and you call generateText, not some dedicated image function. The genuinely useful assist came right after: confirming the free tier's image quota was limit: 0, which made dropping the whole thing the obvious call instead of a stubborn one.
Tests. Generating the first pass of each unit test from the module's signature, then tightening the assertions by hand, is what made a 51-test suite cheap enough to actually write.

The thing that changed most wasn't speed. It was confidence coming back into a cold codebase. It didn't just finish my lines — it helped me remember what the code did and figure out where to take it next. Nobody warns you that's the hard part of "finishing" something. That's the part pairing helped with most.

Results & Validation

7 phases, shipped incrementally — each verified against tsc and the test suite before the next.
51 tests / 18 suites, green.
The narration path was confirmed live on the free tier (gemini-3-flash-preview), the harvest fix verified on a real week (+0/-0 → +2,252/-293), and the stats card rendered to a real 1200×630 PNG.
Proven end-to-end on real weeks. I ran v2 against three separate January 2026 weeks; each produced a Notion page and a DEV.to draft with the deterministic stats card attached as the cover — verified straight from the DEV.to API, where cover_image resolved to the generated card for every post.

None of this is theoretical. The rebuild got verified the same way it got built — incrementally. Every phase ended with a clean tsc and a green suite before the next one started. The failing first run became a passing one I watched run end to end. And the final proof was deliberately mundane: three real weeks, published as reviewable drafts, covers and all, with nothing shipped that I hadn't read first.

What "finishing" actually meant

I came into this assuming "finishing" meant features. More platforms, nicer output, an AI cover. Almost none of it was that. The phases that actually mattered were the ones that made the tool honest — failing loud instead of shipping junk, showing me the draft before it went live, putting real diffs where guesses used to be, reading each platform's rules before automating against them.

And the clearest tell? How often "finishing" turned out to mean deleting. The AI cover, gone. The silent fallback, out of the hot path. A whole config key wired to nothing, gone. The version that finally felt done wasn't the one with the most code. It was the one I'd trust to post under my name while I wasn't looking.

The repo is yashksaini-coder/DevNotion: npx devnotion init, point it at a week, and watch the draft land in the dashboard before anything ships. If you try it, open an issue — I read them now, and "I read them now" is its own small proof the thing is finished. ⭐ it if the rebuild resonates.

yashksaini-coder / DevNotion

DevNotion is an agentic server built using 3 mastra agents to work as a pipeline to publish weekly blogs on Notion Pages & DEV.to

DevNotion

Turn your weekly GitHub activity into a polished, illustrated blog post — narrated by an LLM, reviewed by you, and published to Notion, DEV.to, and Hashnode.

What's new in v2

v1	v2
LLM	Gemini only	Gemini · OpenAI · Anthropic (provider abstraction; default `gemini-3-flash-preview`)
Publish targets	Notion + DEV.to	Notion + DEV.to + Hashnode
Flow	generate → publish immediately	generate → preview → edit → approve → publish
UI	none (CLI/cron)	web dashboard (trigger, preview, edit, history)
Images	none	deterministic stats

…

View on GitHub

Connect: GitHub · X · LinkedIn · Portfolio

Built with Mastra, the Vercel AI SDK, Gemini 3 Flash for narration, @resvg/resvg-js for the stats-card cover, and the Notion / DEV.to / Hashnode APIs. By Yash K Saini — GitHub · X · LinkedIn. Star it if it made you smile.

From Rust CLI bug-hunting to a massive Portfolio overhaul

Yash Kumar Saini — Sat, 06 Jun 2026 08:34:48 +0000

23 commits, 3 PRs, and a 7-day streak. This week was a balance of deep-diving into Rust CLI logic, refining my Neovim setup, and a massive +4,500 line overhaul of my portfolio.

TL;DR

It’s been a while since I’ve had a "perfect week," but I finally hit that 7-day commit streak. 23 commits, 3 PRs, and 1 closed issue across 4 different repos—this week was the definition of a polyglot grind. I spent my time bouncing between surgical Rust fixes in a CLI tool, deep-diving into Python backend logic, and completely ripping apart my portfolio for a modern redesign.

WHAT I BUILT

The week was split between high-level visual work and low-level logic. I managed to touch four different repositories, each serving a very different purpose in my workflow.

DeepRead

I spent a good chunk of the week in DeepRead. With 8 commits, this was my most active repo in terms of frequency. It’s a Python-heavy project, and I was focused on refining the core processing logic. Python is usually my go-to for anything involving heavy data or AI-adjacent backend work, and this week was no exception. I didn't open a PR here yet, but the 8 commits represent a lot of iterative testing and refining of the internal modules.

nvim

You know it’s a productive week when you’re also tweaking your tools. I pushed 7 commits to my nvim config. Most of this was Lua-based (obviously), and I was mainly focused on tightening up my LSP settings and UI. There’s something incredibly satisfying about spending 20 minutes fixing a minor annoyance in your editor and then seeing it pay off for the rest of the week. If my environment isn't perfect, I can't get into that deep flow state.

GitBanner

I’ve been working on GitBanner, a TypeScript tool for generating GitHub profile banners. I pushed 6 commits and opened a new feature PR: feat: add ignore-languages input to filter generated/vendored files. The goal here was to give users more control over what shows up in their stats. Nobody wants their "top languages" to be skewed by a massive vendored library or a bunch of generated CSS files. It’s a small DX improvement, but those are the ones that make a tool actually usable.

trx

Finally, I did some surgical work on trx, a Rust-based CLI tool. This was a classic "scratch your own itch" situation. I noticed a bug where the tool would repeatedly prompt for an update even after I’d already upgraded. I opened an issue for it—bug: TRX repeatedly prompts for update even after successfully updating—and then immediately went in to fix it. Rust is great for this kind of thing because once you get the logic right and the compiler is happy, you know it’s solid.

PULL REQUESTS

I opened three PRs this week, and they tell the story of where my head was at.

The most significant one in terms of sheer volume was for my portfolio. The PR, feat: portfolio modern redesign + scrolling GitHub PR sidebar, clocked in at a massive +4,509 lines. I decided it was time to move away from my old layout and go for something much more modern. The highlight of this redesign is a new scrolling sidebar that pulls in my latest GitHub PRs. It’s a bit meta—building a tool to show the tools I’m building—but I love how it looks. It’s still open as I’m fine-tuning some of the CSS transitions, but the bulk of the work is done.

On the Rust side, I got fix: stop re-prompting update after user skips or upgrades merged into trx. This was the fix for the bug I mentioned earlier. It involved tightening up the version check logic to ensure the CLI respects the user's choice to skip an update or correctly identifies when the local version matches the remote.

I also have the GitBanner PR open, which adds the ignore-languages input. This was a fun bit of TypeScript logic, essentially filtering the language data before it hits the rendering engine.

ISSUES & DISCUSSIONS

I only opened one issue this week, but it was a productive one. I reported the update prompt bug in trx and then closed it myself with the PR I mentioned above. I’m a big believer in documenting bugs even if you’re the one fixing them five minutes later. It creates a paper trail for anyone else who might run into the same weird behavior.

TECH STACK

This was a true polyglot week. My language breakdown is all over the place:

Python for the heavy lifting in DeepRead.
TypeScript for the GitBanner logic and the massive Portfolio redesign.
Rust for the CLI stability in trx.
Lua for the Neovim configuration.

The numbers tell an interesting story: +4,614 additions and -1,081 deletions. That’s a huge net positive, mostly driven by the portfolio redesign. Usually, I like to see more deletions (refactoring is a gift), but when you’re shipping a whole new UI, the additions are going to win every time.

And of course, the 7-day streak. It wasn't a forced grind; I just happened to be in a really good rhythm where I had something I wanted to ship every single day.

WHAT'S NEXT

Next week is all about landing those open PRs. I want to get the portfolio redesign merged and live—there are still a few responsive design bugs I need to squash in that new scrolling sidebar. I also want to see the GitBanner feature through to completion. Beyond that, I’m planning to dive back into the Python side of things with DeepRead. There’s some performance optimization I’ve been putting off, and now that my environment is dialed in and my portfolio is looking fresh, I’ve got no excuses left.

Catch you all next week!

python #typescript #rust #frontend #dx #consistency · 4 min read · Generated 2026-05-24 by DevNotion

Polishing the Rust CLI and Planning the Long Game

Yash Kumar Saini — Sat, 06 Jun 2026 08:34:30 +0000

39 commits, 11 PRs, and 50 issues across 5 repos. This week was all about making trx feel like a first-class tool and dumping my entire brain into the issue tracker to map out the future. Hit a perfect 7-day streak, too.

TL;DR

It’s been one of those weeks where the code just flows. I managed to hit a perfect 7-day streak, pushing 39 commits and merging 9 out of 11 PRs. Most of my energy went into trx, my Rust-based package manager CLI, where I focused on hardening the Homebrew backend and refining the UI. I also went on a bit of a documentation and planning spree, opening 50 issues to define the roadmap for the next few months.

What I Built

The star of the show this week was definitely trx. If you’ve been following along, you know I’m trying to build a unified interface for package management that doesn't feel like a chore to use.

I spent a significant chunk of time on the Homebrew backend. In PR #30, I completely overhauled how we handle search results. Instead of just dumping raw text, I’m now pulling in rich JSON details. This means better metadata, more accurate versioning, and a much cleaner internal data structure. I also had to fix a gnarly little edge case in PR #26 where the tool would try to clean up /usr/local/bin on macOS even if the directory didn't exist. (Pro tip: always guard your filesystem operations, even if you think the path is 'standard'.)

On the UI side, I’m obsessed with making the terminal feel responsive. I added tiered match priorities to the fuzzy search scoring in PR #28. Now, if you type a direct match, it actually floats to the top instead of getting buried by some weird partial match logic. I also added distinct empty states in PR #32—so instead of a blank screen, you get "Start typing", "Searching…", or "No results found". It sounds minor, but it makes the tool feel alive.

Outside of the Rust world, I did some maintenance on my nvim config (7 commits of Lua tweaking) and touched my DeepRead Python project. I also pushed a small update to claude-skills, which is a little Shell-based helper I've been tinkering with.

Pull Requests

I opened 11 PRs this week, and seeing 9 of them get merged feels like a solid win.

One of the most functional updates was adding new keybindings. In PR #34, I added a per-package update command bound to the u key. I followed that up in PR #36 with a manual update-check bound to C. I’m trying to make the entire experience navigable without ever touching the mouse, and these shortcuts are a big part of that.

I also spent some time on the "boring" but necessary stuff. PR #31 was a massive README overhaul. I added a full keybinding reference, a configuration guide, and an updated roadmap. If I want people to actually use this thing, the docs need to be as sharp as the code.

I did have two PRs that I ended up closing without merging (PR #29 and PR #27). Usually, this happens when I realize I’m trying to do too much in one go. I ended up breaking those features down into smaller, more manageable PRs like #34 and #35 to keep the git history clean.

Issues & Discussions

If you look at my activity graph, you’ll see a massive spike in issues. I opened 50 issues this week, almost all of them in trx.

I realized that I had a dozen different ideas floating around in my head and nowhere to put them. So, I sat down and did a massive brain dump. I categorized them into [UI], [Backend], [Feature], and [Performance].

Some of the ones I’m most excited about:

[Backend] Flatpak and DNF support: This is the next big hurdle for making trx truly cross-distro.
[UI] Real-time Installation Progress: Right now, the installation happens, but I want to pipe that stdout directly into a pretty UI component.
[Performance] Adaptive Search Debounce: To make the fuzzy search even snappier on older hardware.

I also closed out a Comprehensive Backend Guide issue, which was a big milestone for the project's internal documentation.

Tech Stack

This was a very polyglot week, though Rust was the clear winner for the heavy lifting.

Rust: 27 commits and nearly 1,000 lines of code. I’m really leaning into the type system to handle the different package manager backends.
Lua: Used for my Neovim setup. I’m constantly tweaking my dev environment to shave off those extra seconds of friction.
Python & Shell: Mostly for utility scripts and my AI-related side projects.

The stats show 970 additions and 279 deletions. That’s a healthy ratio for a feature-heavy week. I’m building out new functionality, but I’m also not afraid to rip out old code when I find a better way to do things (like the Homebrew backend refactor).

And yeah, that 7-day streak? It wasn't a grind. When you're working on tools that you actually use every day, the motivation just takes care of itself.

What's Next

Next week is going to be about tackling that mountain of issues I just created. I want to start with the [UI] improvements—specifically the scrollable help overlay and the keyboard hints in the status bar. I also want to start prototyping the Flatpak backend.

If I can get the real-time installation progress working, that’ll be a huge UX win. There’s something incredibly satisfying about watching a progress bar move in the terminal.

Catch you in the next update!

rust #cli #devtools #consistency #backend · 4 min read · Generated 2026-05-31 by DevNotion

I built a local document Q&A tool around Gemma 4 E4B's 128K context — five days, no RAG, no cloud

Yash Kumar Saini — Sun, 24 May 2026 07:16:52 +0000

Five days, an 8 GB laptop GPU, and a stubborn belief that for the kind of documents I actually read — research papers, internal memos, the API docs of one project — RAG is over-engineering. DeepRead loads PDFs into Gemma 4 E4B's 128K context as page images and answers questions with footnote citations pointing to the exact page. No vector DB. No chunker. No retriever. ~500 lines of Python.

This is my submission for the Build with Gemma 4 prompt. The full repo is at github.com/yashksaini-coder/DeepRead. The model is gemma4:e4b (the 4-billion-parameter Gemma 4) served by Ollama. Everything runs offline.

What it does

You start with an empty chat. The right sidebar has a Papers picker — five classic CS papers ship bundled (Attention, GFS, MapReduce, Raft, Bitcoin), or you upload your own PDF. Click one and it ingests in about half a second; the sidebar's Plotly bar fills green to show how much of the 128K window is now in your prompt.

Then you ask whatever you want. The answer streams back with footnote markers [^1], [^2] that resolve to specific pages of specific papers at the bottom of the message. The model is constrained at prompt-construction time to use only page IDs from a known list — so it physically can't hallucinate a page number.

Diagnostics live in the same chat as slash commands. /bench show renders the latest needle-in-a-haystack sweep as three Plotly charts (pass rate, tok/s, time-to-first-token). /bench run --ctx 5000 20000 60000 --needles 5 kicks off a fresh sweep. No tab switching, no separate session, no chat clearing.

Why E4B specifically

I'm going to quote the model-selection paragraph straight from the README, because the rubric explicitly weights this and I don't want to bury it:

E4B is the only model in the Gemma 4 family — and arguably the only open model at this size today — that combines four properties at once: a 128K context window wide enough to hold a complete research paper plus supplementary material in a single call; native vision that handles PDF pages rendered at 150 DPI without an OCR pipeline; native audio input (held in reserve for the next iteration); and a ~9.6 GB on-disk footprint that runs on an 8 GB laptop GPU. The 26B and 31B variants would push reasoning quality up, but they would kill the laptop story — and the whole point of DeepRead is that nothing leaves the machine. E2B was tempting for portability but loses fidelity on multi-step reasoning across long context. E4B is the precise sweet spot.

Three sentences, one decision, the rest of the build defends it.

The decision I'm most proud of: no RAG

Every "AI document assistant" I've used in the past two years has the same shape — chunk, embed into a vector DB, retrieve top-k, prompt a hosted LLM with the retrieved chunks. RAG. It works. It's also a small mountain of moving parts that all need to stay aligned: chunk size, overlap, embedding model version, top-k value, rerank threshold. And at the end of all that, your documents have been shipped to someone else's machine.

DeepRead is a bet that for a non-trivial class of documents — research papers, internal memos, a few weeks of meeting notes — none of that is necessary. Drop the PDFs into the prompt as rendered page images, ask the question, get an answer with page citations. The whole tool is gemma4:e4b running locally via Ollama, plus about 500 lines of Python.

I did a full math comparison which I will post in a later article. The TL;DR: DeepRead spends ~28% more tokens per page than a text-embedding pipeline, in exchange for zero offline preprocessing, zero retrieval failure mode, and the ability to reason about figures, tables, equations, and handwritten margin notes the same way a human reader does.

What 100K tokens actually costs on a laptop GPU

I built benchmarks/run_context_sweep.py to answer the question honestly. It runs a needle-in-a-haystack test: five 4-character codes seeded at fixed positions (5/25/50/75/95%) inside a long synthetic document, and the model has to recover each in isolation. From an RTX 5050 Laptop, 8 GB VRAM:

Context	Pass rate (5/5 needles)	Tokens/sec	Time to first token
20K	5/5 ✓	8.6	15 s
60K	5/5 ✓	7.6	38 s
100K	5/5 ✓	6.8	72 s

The recall result genuinely surprised me. I expected E4B to degrade past 60K and it didn't — the window held all the way to 80% of its 128K spec. What broke was latency: TTFT grew nearly linearly with context size. Generation throughput stayed flat around 7-9 tok/s; the consumer-GPU tax shows up entirely in the prefill phase.

The practical mental model for someone building on this hardware:

< 20K is the interactive zone. Answers start within 15 seconds; conversation feels alive.
20K – 60K is the research-assistant zone. Drop in a whole paper, go make coffee, come back to the answer.
60K – 100K is the batch zone. Load a codebase, kick off a query, accept that you'll come back to a notification.

The Plotly chart in the right sidebar surfaces these zones live as you load papers, so you know what your context choices will feel like before you ask.

Five-day build log

Tuesday. Scaffolded the project, wrote the deepread/ package: ingest.py (PyMuPDF rasterization), budget.py (token estimator), citations.py ([[id]] grammar), llm.py (Ollama wrapper). 16 unit tests. End of day, I could ingest a PDF and stream an answer from the terminal.

Wednesday. Built the first Gradio UI. Got immediately bitten by Gradio's gr.HTML(value=...) rendering rule — it sets .innerHTML, which the browser refuses to execute scripts from for security. I shipped three different "fixes" for the same paper-click bug before I realized I was reading the wrong stack trace. Lost most of the afternoon.

Thursday morning. Got the UI working with an <img onerror="..."> trick. Looked at it. Decided I hated it. The chat-shaped product was wearing document-tool clothes. Migrated to Chainlit. The migration was about three hours because deepread/ was UI-independent from day one — only app.py got rewritten.

Thursday night. Wrote benchmarks/run_context_sweep.py and let it run overnight on E4B at 5K / 20K / 60K / 100K. Spoiler: the numbers above are the result. The 100% recall at 100K was a relief — it meant the whole no-RAG thesis was actually defensible.

Friday. Polish day. Moved the context-budget chart from chat into the right ElementSidebar. Built a cl.CustomElement React component for the paper picker so the buttons live in the sidebar (Chainlit's ElementSidebar accepts Elements but not Actions — the picker bridges that gap). Pinned a floating "Context" toggle to the top-right of the chrome with :has(img[src*="/avatars/sidebar_toggle"]).

Saturday morning. Killed the cl.ChatProfile second tab. The profile-switch dialog ("This will clear your chat history") was a constant friction every time I wanted to check a benchmark. Replaced it with /bench slash commands inside the same chat. One session, no clearing.

Saturday afternoon. Wrote the posts. (You're reading them.)

The code I'd point a reviewer at first

deepread/llm.py is the whole model contract:

def stream_chat(question, images=(), *, history=None, num_ctx=24_000, model=MODEL):
    payload = [_encode_media(i) for i in images]
    user_msg = {"role": "user", "content": question}
    if payload:
        user_msg["images"] = payload
    stream = ollama.chat(
        model=model,
        messages=list(history or []) + [user_msg],
        stream=True,
        options={"num_ctx": num_ctx},
    )
    for chunk in stream:
        delta = chunk.get("message", {}).get("content", "")
        if delta:
            yield delta

That's it. There's a health_check(model) next to it that returns a typed HealthReport(ok, reason, hint) instead of raising — the caller decides how to surface it. The Chainlit handler runs it once per session and caches the result.

deepread/citations.py is the part I'm sneakiest about:

def citation_prompt(shards):
    catalog = "\n".join(f"- {s.cite_id}" for s in shards)
    return (
        "You are a research assistant. When you make a factual claim that "
        "comes from a specific page or image, cite it inline using the "
        "format [[cite_id]]. Use ONLY these citation ids:\n"
        f"{catalog}\n"
        "If a fact isn't supported by the provided material, say so."
    )

Then _format_answer(raw, known_cite_ids) regex-replaces [[id]] markers with numbered [^N] footnotes — but only if id is in the catalog. So even if the model emits [[some-fake-id]], the formatter leaves it as literal text. The page-citation hallucination is structurally impossible.

What I cut for time

Voice input. Gemma 4 E4B accepts raw WAV bytes in the same images: [...] field, but I never got the Chainlit cl.Audio plumbing solid enough to ship. Two days of work I didn't have.
Per-paper exclude/remove from the library. EXCLUDED_KEY exists in session state and the working-set logic respects it — there's just no UI button to flip it. A 30-minute add I'll do after the deadline.
Conversation export. Save / share a Q&A session as Markdown. Easy to add, not on the rubric.
Multi-language UI. Chainlit ships 20+ locale files; English-only for now.

What I learned

Framework choice matters more than you think. Gradio is more flexible; Chainlit is more aligned with the chat-shaped problem I had. Five UI iterations to recognize it. Pick the framework whose defaults match your shape.

The model-selection paragraph is the highest-leverage paragraph in the submission. Judges read it. Don't bury the reasoning.

Benchmark first, blog second. I'd written the article-1 stress-test draft before I had the numbers. When the numbers came in, the article got better, sharper, and shorter. The opposite order would have left me defending claims that the data didn't support.

Try it

git clone https://github.com/yashksaini-coder/DeepRead.git
cd DeepRead
ollama pull gemma4:e4b           # ~9.6 GB, one-time
make install                      # uv sync
make run                          # http://127.0.0.1:8000

Pick Bitcoin · 2008 for the fastest demo (smallest paper) and ask What problem does proof-of-work solve in this paper?. The answer streams back with citations resolving to specific pages.

Companion posts

I stress-tested Gemma 4 E4B's 128K context on a laptop GPU — the benchmark numbers in long form, plus the reproducible test rig

yashksaini-coder / DeepRead

Local document Q&A with Gemma 4 E4B's 128K context — no RAG, no cloud, answers cite the exact page they came from.

DeepRead

Local, long-context document Q&A with Gemma 4 E4B — load PDFs, ask anything, get page-cited answers. The model runs on your machine. Your documents never leave it.

DeepRead is the build submission for the dev.to Gemma 4 Challenge. It demonstrates that a high-quality document-intelligence experience can run entirely on consumer hardware — no cloud, no per-query cost, no telemetry — by leaning on Gemma 4 E4B's 128K context window instead of a RAG pipeline.

Highlights

One chat, two modes. Document Q&A is the default. Type /bench show or /bench run --ctx 5000 20000 --needles 3 in the same chat to render the context-window stress-test charts inline — no profile switching, no history loss.
Native multimodality. Pages go in as rendered images via Gemma 4's vision path — no OCR pipeline.
Live context budget. A right-side sidebar shows the working set against the 128K ceiling, color-coded by latency tier…

View on GitHub

Star DeepRead on GitHub

Connect with me:

• Website
• GitHub
• LinkedIn
• X (Twitter)

I stress-tested Gemma 4 E4B's 128K context on a laptop GPU — recall is great, prefill is not

Yash Kumar Saini — Sun, 24 May 2026 06:44:15 +0000

Thursday night I let a benchmark run while I slept. By Friday morning Gemma 4 E4B had answered fifteen needle-in-a-haystack questions across four context sizes on my RTX 5050 laptop. The recall numbers were better than I expected. The latency numbers were worse. Here's both, with the ~30 lines of Python to reproduce it on your own hardware.

I keep seeing "Gemma 4 E4B has a 128K context window" repeated as if it were a single property, like "the engine is 3.5 litres". It is not a single property. A context-window number means at least three different things — will the model accept this many tokens?, will it remember what's in the middle of them?, and how fast does the first answer token arrive? — and the answers diverge sharply once you leave the laptop-GPU regime that most spec sheets assume.

This is the post I wish I'd had when I started building on E4B. The TL;DR is in the table further down. The reproducible test rig is at the bottom.

The setup

Hardware: RTX 5050 Laptop, 8 GB VRAM, 24 GB system RAM, Intel i7-13620H
Software: Ollama 0.24.0, gemma4:e4b (Q4_K_M, ~9.6 GB on disk), Linux 7.x
Test: needle-in-a-haystack — five unique 4-character codes embedded at fixed positions inside a long synthetic English document; the model has to recover each one in isolation by exact match.

The test is deliberately simple. I want to know whether the model can find a fact at a known position, not whether it can paraphrase it. Reasoning quality is a different benchmark and needs human evaluation, which I didn't have budget for.

I ran the sweep at 5K, 20K, 60K, and 100K target context sizes. I didn't push to the 128K spec because Ollama's num_ctx setting interacts with the K/V cache headroom in ways I didn't have time to characterize cleanly, and 100K is already 80% of the spec.

The numbers

Context	Pass rate (5/5)	Tokens/sec	Time to first token
5K	5/5 ✓	9.2	4 s
20K	5/5 ✓	8.6	15 s
60K	5/5 ✓	7.6	38 s
100K	5/5 ✓	6.8	72 s

Three things stand out.

Recall stayed perfect. I expected E4B to wobble somewhere past 60K — that's the failure mode I see most reported for 4B-class models, the "middle of the context is fuzzy" problem. The needles at 25% and 75% are exactly where I'd expect drop-off. They held. I re-ran the sweep twice to be sure.

Generation throughput barely moved. 9.2 tok/s at 5K vs. 6.8 tok/s at 100K. That's a 26% drop across a 20x context increase. The K/V cache is the obvious culprit, but in practical terms: once the answer starts streaming, it streams at roughly the same speed.

Time to first token blew up. 4s at 5K, 72s at 100K. Almost linear in context size. This is the prefill phase — the model encoding everything you sent it before producing the first output token. On a laptop GPU, prefill is where the consumer-hardware tax lives.

What this means if you're building on E4B

Let me write the practical zones the way I actually think about them, not the marketing version:

Under 20K tokens: interactive. First token in ~15 seconds, full answer in ~25-30s. This feels like a real conversation. Most single-paper Q&A lives here.
20K to 60K tokens: research-assistant. 30-40 second TTFT. You're going to glance away from the screen. That's fine, the answer will be there when you look back. Multi-paper comparisons, longer contexts.
60K to 100K tokens: batch. You're queuing a job. 60-80 second TTFT means you might as well make coffee. Loading a whole codebase, a textbook chapter, a quarter's worth of meeting notes.
Above 100K: I didn't measure. The prefill cost was already breaching my "is this still interactive?" threshold and the use case I was solving for didn't need it.

If you're designing a UI on top of this model, surface these zones to the user. A progress bar or a tier label ("interactive / research / batch") tells someone what their next click will feel like before they ask. The 128K spec is honest; it just doesn't tell you when it'll start.

Reproduce it yourself

The whole rig is about 30 lines once you strip the CLI scaffolding. Save this as bench.py, install ollama (pip install ollama), then run it:

import random, time
import ollama

MODEL = "gemma4:e4b"
NEEDLE_POSITIONS = [0.05, 0.25, 0.50, 0.75, 0.95]

def make_needles(k=5, seed=20260521):
    rng = random.Random(seed)
    chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
    return [(f"box-{i+1}", "".join(rng.choices(chars, k=4))) for i in range(k)]

def build_haystack(target_tokens: int, needles):
    # Filler ~ 80 tokens per sentence, English-ish prose.
    filler = (
        "The committee continued its review of the operational notes "
        "submitted during the prior fiscal quarter, with particular "
        "attention paid to procedural anomalies. "
    )
    sentences_needed = target_tokens // 20  # ~4 tok/word, 5 words/sentence avg
    body = (filler * sentences_needed)[: target_tokens * 4]
    # Splice needles in at fixed positions
    out = body
    for pos, (label, code) in zip(NEEDLE_POSITIONS, needles):
        i = int(pos * len(out))
        out = out[:i] + f"\n\nNote: {label} contains the code {code}.\n\n" + out[i:]
    return out

def ask(haystack: str, label: str, num_ctx: int) -> tuple[str, float, float]:
    t0 = time.time()
    first_t = None
    chunks = []
    for r in ollama.chat(
        model=MODEL,
        messages=[
            {"role": "system", "content": "Answer with only the 4-character code, nothing else."},
            {"role": "user", "content": haystack + f"\n\nWhat code is in {label}?"},
        ],
        stream=True,
        options={"num_ctx": num_ctx},
    ):
        delta = r.get("message", {}).get("content", "")
        if delta:
            first_t = first_t or time.time()
            chunks.append(delta)
    answer = "".join(chunks).strip()
    return answer, (first_t - t0) if first_t else 0, time.time() - t0

if __name__ == "__main__":
    needles = make_needles()
    for ctx in (5_000, 20_000, 60_000, 100_000):
        hay = build_haystack(ctx, needles)
        passed = 0
        for label, code in needles:
            ans, ttft, total = ask(hay, label, num_ctx=ctx + 4_000)
            passed += code in ans
            print(f"  ctx={ctx:>6,}  {label}  expected={code}  got={ans!r}  ttft={ttft:.1f}s  total={total:.1f}s")
        print(f"ctx={ctx:>6,}  pass={passed}/{len(needles)}")

It writes to stdout. If you want JSON-lines results to plot, redirect to a file and parse the ctx=… pass=… lines. The whole sweep takes ~30 minutes on an RTX 5050; longer on smaller GPUs.

The seed is fixed (20260521) so the needle strings are deterministic. If your pass rate doesn't match mine at the same (model, ctx, seed), that's a real signal — likely Ollama version, quantization, or hardware-driver path.

Things this rig deliberately doesn't measure

Quality of paraphrase. The needles are literal 4-character codes. I'm measuring can the model find it?, not can the model reason about it?. Those are different benchmarks.

VRAM consumption. Ollama owns the K/V cache and I'm not going to fight it for memory accounting. nvidia-smi says it sits around 7.4 GB at 100K context, but I haven't characterized the curve.

Cross-document attention. Each needle is asked in isolation. Multi-fact composition ("how does the figure on page 12 of paper A relate to section 3 of paper B?") is a different problem. I don't have a clean benchmark for it. I'm working on it.

When RAG is still the right call

I'm not going to pretend the no-RAG architecture is universally correct. Bluntly:

Library > 128K tokens total. Half a book. A whole textbook. A corpus of fifty papers. Then you need retrieval. Don't fight it.
Sub-second latency required. Customer-facing chatbot over a knowledge base. RAG is faster on the hot path — see the TTFT numbers above.
Incremental index updates. Adding one document without re-prefilling. A vector DB lets you do that. Long-context doesn't.
The question genuinely needs only a small slice of one document. "What's the customer's last order?" over a 50K-record SQL table. SQL is the right tool. Not RAG, not long-context, just SQL.

For everything else in the "I have some documents, I want to ask them things" category — research, internal docs, technical reading — I think the no-RAG architecture is the right default in 2026. The frontier models have gotten long-context-capable enough that retrieval is now a premature optimization for most workloads. The benchmark numbers above are the evidence; the per-page-token math is the framework for deciding.

The line that summarizes it

Traditional RAG: make the model see less, faster.
Long-context: make the model see everything, once.

Both are valid. The question is which trade-off your workload actually has. Mine had the second shape. The benchmark told me the cost. I shipped accordingly.

The honest comparison

Qwen 3.5 27B has ~190K effective context on similar hardware. Llama 3.1 70B (if you can fit it) goes further. On raw context size alone, Gemma 4 E4B isn't the winner.

What E4B is the winner at is the combination: 128K context + native vision + native audio + ~9.6 GB on disk, all in one model. That combination is what makes whole-document workloads tractable on a laptop. Qwen 27B doesn't fit in 8 GB of VRAM. Llama 3.1 70B doesn't either. If your hardware constraint is "consumer GPU", E4B is the only model in this class with 128K context and multimodality.

That's the framing I'd give someone choosing an open-weights model for a single-machine deployment in 2026.

Three places I'd take this benchmark next

Mixed-modality recall. Embed half the needles in text, half in rendered images. See if vision-encoded needles degrade differently from text-encoded ones. (This is the part most relevant to anyone building doc-Q&A.)
Cross-document needles. Two documents in context, the needle in paper A, the question phrased to require paper B's vocabulary. The actual "I have a library, I want to ask questions" workload.
Long-document Q&A with human evaluation. Pay five grad students to grade 100 questions about a single 25-page research paper. Real quality numbers, not synthetic ones.

If you run any of these, I'd genuinely like to read the results.

yashksaini-coder / DeepRead

Local document Q&A with Gemma 4 E4B's 128K context — no RAG, no cloud, answers cite the exact page they came from.

DeepRead

Local, long-context document Q&A with Gemma 4 E4B — load PDFs, ask anything, get page-cited answers. The model runs on your machine. Your documents never leave it.

Highlights

One chat, two modes. Document Q&A is the default. Type /bench show or /bench run --ctx 5000 20000 --needles 3 in the same chat to render the context-window stress-test charts inline — no profile switching, no history loss.
Native multimodality. Pages go in as rendered images via Gemma 4's vision path — no OCR pipeline.
Live context budget. A right-side sidebar shows the working set against the 128K ceiling, color-coded by latency tier…

View on GitHub

Star DeepRead on GitHub

Connect with me:

• Website
• GitHub
• LinkedIn
• X (Twitter)

Dev Log #5 Building a Claude-style SRE terminal and tackling WebRTC

Yash Kumar Saini — Thu, 07 May 2026 06:47:34 +0000

11 commits, 5 PRs, 1 issue, and 3 reviews across 4 repos. This week was all about infrastructure—from RabbitMQ RCA tools to massive WebRTC scaffolding in Python. Hit a 7-day streak and pushed over 11k lines of code.

TL;DR

It’s been one of those weeks where the terminal felt like my natural habitat. I managed to keep the streak alive for seven straight days, which always feels great, but the real win was the sheer volume of infrastructure work I got through.

I logged 11 commits, 5 PRs, and 3 reviews across 4 different repositories. The highlight? Diving deep into the py-libp2p stack to start the WebRTC transport scaffolding and pushing the vision for a persistent SRE terminal in opensre. With over 11,000 lines added and only about 200 deleted, this wasn't a week for refactoring—it was a week for building the foundation of some pretty ambitious features.

What I Built

Most of my energy this week was split between two major domains: SRE tooling and p2p networking.

opensre: The SRE Terminal Vision

I’ve been spending a lot of time thinking about how we interact with infrastructure during an incident. In the opensre repo, I’m working toward making it a persistent SRE terminal—something inspired by the flow of tools like Claude-Code but specifically tuned for system reliability.

I opened a PR for an interactive REPL, which is really the first step toward that "SRE terminal" experience. It’s about 2,400 lines of new code focused on creating a seamless environment where you can run diagnostics without jumping between a dozen browser tabs.

Alongside the terminal work, I also shipped a RabbitMQ integration. This is specifically for queue and broker Root Cause Analysis (RCA). If you’ve ever had a message broker fall over under load, you know how painful it is to piece together the "why" while the system is down. This integration aims to automate that detective work.

py-libp2p: The WebRTC Beast

On the open-source side, I’m still heavily involved with py-libp2p. This week, I tackled a massive task: WebRTC transport scaffolding. This PR alone is over 6,000 lines. It’s mostly spec compliance and tests right now, but getting the transport layer right is critical for browser-to-node connectivity.

I also did some much-needed cleanup in the transport layer by removing the nursery parameter from IListener.listen. This was a follow-up to some architectural changes we’ve been discussing, and it makes the interface much cleaner. (Honestly, passing nurseries around everywhere was starting to feel like a bit of a code smell, so I’m glad to see it go).

Personal Setup & Maintenance

I also spent some time in my nvim config. I pushed 7 commits there—mostly Lua tweaks to keep my environment snappy while I’m jumping between Python and TypeScript. It’s the small things, like optimizing LSP behavior or fixing a keybinding conflict, that keep the flow state going during these high-output weeks. I also touched 100xsolana and DevNotion for some minor maintenance, keeping the lights on while I focused on the bigger infra tasks.

Pull Requests

I had 5 PRs in flight this week, and they really tell the story of the week's progress.

The MariaDB integration docs was my only merge this week, but it was an important one. It closed out an issue I opened earlier in the week to ensure our Mintlify docs stay up to date with the actual capabilities of the tool.

The other four PRs—the WebRTC scaffolding, the transport fix, the RabbitMQ integration, and the REPL—are all currently open. They represent a lot of "work in progress" that I’m looking to land early next week. The WebRTC PR is the one I’m most nervous/excited about; it’s a lot of code to review, and I want to make sure the spec compliance is spot on before we go any further.

Issues & Discussions

I’m really trying to be more intentional about the "why" behind the code, not just the "how." I started a discussion in opensre about whether we should bundle or split the next phases of the persistent SRE terminal.

It’s a classic architectural dilemma: do we keep everything in one tight package for ease of use, or do we start modularizing now to prevent a monolith? No one has answered yet, but getting my thoughts down in a discussion thread helps me clarify the roadmap before I start writing more code.

Code Reviews

I spent a good chunk of time reviewing other people's work in py-libp2p. I think it’s important to give back to the projects you use, and reviewing is often more taxing than writing.

I gave feedback on a QUIC address unpacking PR, specifically looking at how we handle both IPv4 and IPv6. I also requested changes on a BasicHost shutdown enhancement. Shutdown logic is notoriously tricky in asynchronous Python, and I want to make sure we aren't leaving any dangling tasks or resources. Finally, I left some comments on a PR regarding peer identity persistence.

Reviewing these while working on my own massive WebRTC PR was a bit of a balancing act, but it keeps me grounded in the codebase as a whole, not just my own little corner of it.

Tech Stack

This was a very Python-heavy week. Between opensre and py-libp2p, I was deep in the world of asyncio, type hinting, and infrastructure logic.

The language breakdown shows Python as the clear leader, followed by TypeScript and Lua. The 11,185 additions versus 201 deletions really highlights that this was a "feature push" week. I wasn't cleaning up old debt as much as I was laying down new tracks.

And that 7-day streak? It’s not about the "grind"—it’s about the fact that I was genuinely excited to get back to the keyboard every morning to see if I could get that WebRTC transport to behave.

What's Next

Next week is all about the "Merge." I want to get the WebRTC scaffolding in py-libp2p to a state where it can be merged, which means writing a lot more tests and probably responding to a lot of review comments.

In opensre, I’m going to keep pushing the REPL. I want to get to a point where I can actually use it for my own freelance work—eating your own dog food is the best way to find the friction points in a CLI tool.

Catch you all next week! Hopefully with a few more "MERGED" labels on those PRs.

Connect with me:

• Website
• GitHub
• LinkedIn
• X (Twitter)

Dev Log #4 A Week of Deep Integrations

Yash Kumar Saini — Mon, 13 Apr 2026 05:41:21 +0000

A high-output week with 33 commits and over 3,000 lines of new code. I focused heavily on database RCA integrations for OpenSRE and kept the momentum going with a perfect 7-day streak across TypeScript, Python, and C.

TL;DR

There’s something about hitting a 7-day streak that just feels right. It’s not about the grind; it’s about that rare alignment where every time I sit down at the keyboard, the path forward is clear. This week was a massive "building" phase—33 commits, 2 major PRs, and a staggering 3,221 lines of code added (with only 27 deletions).

The bulk of that energy went into the opensre ecosystem, specifically hardening Root Cause Analysis (RCA) for managed and relational databases. When I wasn't deep in Python land, I was pushing updates to varcouch, tweaking my Neovim setup, and getting my hands dirty with some low-level C in PiEngine.

WHAT I BUILT

If I had to summarize the week in one word, it would be Integrations.

OpenSRE & The RCA Engine

Most of my "heavy lifting" happened in the opensre repository. If you’ve ever had a production database go sideways, you know that the "why" is often buried under layers of logs and metrics. I spent the week building out the logic to automate that discovery.

I added support for MongoDB Atlas and MariaDB. This wasn't just about writing a few connection strings; it was about mapping out how these databases behave under stress and ensuring the RCA engine can pull the right signals to tell a coherent story when things break. Adding over 3,000 lines of code here felt like a marathon, but seeing the logic come together for managed document stores and relational clusters makes the effort worth it.

Varcouch

Over in varcouch, I pushed 15 commits. This project is becoming a bit of a staple in my weekly workflow. It’s TypeScript-based, and this week was all about refining the core internals. I didn't do a massive refactor (the 0 deletions tell that story), but I focused on iterative feature adds. I’m trying to keep the DX (Developer Experience) high here, making sure the API remains intuitive as the complexity grows.

The Low-Level & The Personal

I also spent some time in PiEngine, which is my current outlet for C programming. 6 commits there—mostly incremental progress on the engine's core. There’s a specific kind of satisfaction in switching from high-level Python or TypeScript back to C; it forces you to think about memory and execution in a way that makes you a better developer overall.

And of course, no week is complete without some nvim tinkering. 8 commits to my Lua config. I’m at that stage where I’m optimizing my workflow for the specific types of backend work I’ve been doing lately. If my editor isn't helping me move faster, it's getting in the way, so I spent some time smoothing out those friction points.

PULL REQUESTS

I opened two significant PRs this week, both targeting the opensre repo.

The first was feat: add MongoDB Atlas integration for managed document-store RCA. This one is already merged! It adds 1,227 lines of logic specifically designed to handle the nuances of Atlas. Managed services are great until they aren't, and having automated RCA for document stores is a huge win for the project.

The second, which is still open and currently under the microscope, is feat: add MariaDB integration for database RCA. This is a beast of a PR—1,994 additions. MariaDB has its own set of quirks compared to standard MySQL, especially when you're looking at performance schema and thread states for root cause analysis. I’m looking forward to getting this one across the finish line next week.

TECH STACK

This was a polyglot week through and through. My language stats show a massive lean toward Python (over 84MB of context), which makes sense given the heavy lifting in opensre and some minor touches on p2pCalc and Hack-Agent-Server.

TypeScript remains my go-to for tooling and frontend work, represented by my commits in varcouch and my portfolio. I also had a healthy dose of Rust (11MB) and Lua in the mix.

The most telling stat of the week is the add/delete ratio. 3,221 additions against 27 deletions. Usually, I like to see more deletions—it means I’m cleaning up and simplifying. But this week was purely about expansion. I was laying down new tracks, not pulling up old ones.

WHAT'S NEXT

The immediate goal is to get that MariaDB PR merged. It’s a lot of code to review, so I’ll likely spend the early part of next week addressing feedback and hardening the tests.

I also want to dive back into varcouch. With the core starting to feel stable, I’m thinking about how to expand its utility for other devs. And as always, there’s a list of "nice-to-have" features for PiEngine that I’m itching to get to if I can find a few hours of quiet time.

Seven days of commits, a ton of new code in the wild, and a clear plan for the next sprint. Can't ask for much more than that. See you all next week!

Connect with me:

• Website
• GitHub
• LinkedIn
• X (Twitter)

VarCouch — I Built an AI Therapist for Your Code Variables (They Need It)

Yash Kumar Saini — Sat, 11 Apr 2026 09:42:42 +0000

This is a submission for the DEV April Fools Challenge

What I Built

Your variables have been through a lot. The endless renaming. The silent judgment from code reviewers. That one time someone called temp2 a "perfectly fine name." They deserve better. They deserve a couch.

VarCouch is the world's first AI-powered therapy platform for emotionally neglected code variables. You paste your code, and Dr. VarCouch — a licensed Variable Therapist with a PhD in Computational Psycholinguistics from MIT (the Massachusetts Institute of Transpilation) — conducts a full psychological assessment of every identifier.

No, it doesn't solve any real problem. Yes, I'm very serious about it.

Every variable gets:

A clinical diagnosis (e.g., "Chronic Hoisting-Induced Dissociative Fugue")
A distress level from 1 to 10 with a color-coded progress bar
A backstory explaining the trauma that led it here
Session notes that type out like the therapist is writing in real time
A therapist's recommendation for emotional recovery
Coping mechanisms the variable has developed over the years
A downloadable PDF clinical discharge report that looks disturbingly official

The whole thing is wrapped in a warm, dark-gold theme because therapy should feel cozy, even for code.

The Teapot Protocol

This wouldn't be a proper 418 Challenge entry without paying respect to Larry Masinter and RFC 2324.

If any of your variables are named teapot, coffee, brew, espresso, latte, cappuccino, chai, mocha, or kettle, Dr. VarCouch flags them as falling under HTCPCP jurisdiction. They get a special golden glow, an "RFC 2324 Certified" badge, and a note that they need to be referred to a qualified barista-therapist — because Dr. VarCouch is not licensed to treat beverages.

There's also a dedicated /api/teapot endpoint that returns a proper HTTP 418 with custom headers:

{
  "status": 418,
  "error": "I'm a teapot",
  "drNote": "Dr. VarCouch cannot treat teapots. Please consult a qualified barista-therapist.",
  "protocol": "HTCPCP/1.0",
  "prescription": "Two shots of espresso and a code review in the morning."
}

With headers X-Teapot-Status: short-and-stout and X-Masinter-Protocol: HTCPCP/1.0, because if you're going to implement a joke protocol, you should commit to it.

The PDF Discharge Report

You can download a clinical discharge report for each variable — a real PDF that looks like it came from an actual therapist's office. Gold letterhead reading "VarCouch Therapeutic Services, LLC", color-coded distress levels, the attending physician listed as "Dr. VarCouch, PhD (Computational Psycholinguistics, MIT — Massachusetts Institute of Transpilation)", and a footer disclaimer: "No actual variables were harmed in the making of this report."

It's HIPAA-adjacent. Not HIPAA-compliant.

Demo

Live: varcouch.vercel.app

Code

yashksaini-coder / varcouch

DEV April Fools 2026 Challenge

VarCouch

AI-powered therapy for emotionally neglected code variables.

Your variables have feelings. We have a couch.

Live Demo · Report Bug · Request Feature

This project is a submission for the DEV April Fools 2026 Challenge -- a challenge to build something completely useless or silly that solves zero real-world problems.

Prize categories targeted:

Best Google AI Usage -- Powered by Google Gemini 3 Flash with structured JSON output, variable-aware system prompts, and schema-enforced therapy sessions
Best Ode to Larry Masinter -- Features a dedicated /api/teapot endpoint returning HTTP 418, RFC 2324 (HTCPCP) references throughout, and automatic detection of teapot/coffee variable names for specialized barista-therapist referrals

About The Project

VarCouch is the world's first AI-powered mental wellness platform for emotionally neglected code variables. Paste your code, and Dr. VarCouch -- a licensed Variable Therapist with 20 years of clinical experience -- will conduct a deep…

View on GitHub

How I Built It

The stack is honestly overkill for something this useless, and I wouldn't have it any other way.

Frontend:

Next.js 16 with App Router and React 19
Tailwind CSS 4 with a custom warm dark theme — aurora gradient background, glassmorphism cards, animated grain texture
Fraunces variable font for headings (it has a "WONK" axis, which felt appropriate for a therapy app)
Monaco Editor for the code input — your variables deserve a proper IDE, even on the couch
Framer Motion for page transitions, typewriter effects, floating code symbols during loading

Backend & AI:

Google Gemini 3 Flash with structured JSON output and a schema-enforced response format
A system prompt that never breaks character — Dr. VarCouch has 20 years of clinical experience and takes this very seriously
Input validation, size limits, rate limit handling, and prompt injection defense (even joke apps deserve good security)

Other bits:

jsPDF for client-side PDF generation with proper page-break handling
Regex-based variable extraction for 5 languages (JavaScript, TypeScript, Python, Go, Rust)
A hand-crafted loading screen where code symbols ({, }, ;, =, ()) float around the therapy couch

The Gemini integration uses structured output with a full JSON schema, so every therapy session comes back with the exact same shape — diagnosis, distress level, backstory, session notes, recommendation, coping mechanisms. No hoping the AI returns something parseable. It either matches the schema or it doesn't.

What I Learned

Building something deliberately useless taught me a few things:

Structured AI output is underrated. Gemini's JSON schema mode meant I never had to parse free-text AI responses. Every field was guaranteed. This is genuinely useful knowledge I'll take to real projects.
Committing to the bit makes everything better. The PDF discharge report, the RFC 2324 references, the "Massachusetts Institute of Transpilation" — none of these are necessary, but they make the whole thing feel like a complete world rather than a half-baked joke.
Dark themes with warm colors feel really good. The gold-on-black palette with aurora gradients and glassmorphism came together better than any "serious" UI I've designed. Turns out removing the pressure of building something useful frees you up to actually experiment with design.

Prize Category

I'm submitting for two categories:

Best Google AI Usage — VarCouch uses Google Gemini 3 Flash with structured JSON output, a character-committed system prompt, schema-enforced response validation, and differentiated error handling for rate limits, safety filters, and API failures. The AI never breaks character and every response is type-safe.

Best Ode to Larry Masinter — Dedicated /api/teapot endpoint with HTTP 418 and HTCPCP headers, automatic teapot variable detection, RFC 2324 badges on flagged variables, and Larry Masinter's wisdom preserved in the footer of every page. Because any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot."

In loving memory of RFC 2324 (HTCPCP) and all the teapots that just wanted to brew coffee.

"Remember: there are no bad variables, only misunderstood identifiers." — Dr. VarCouch

Turning Weekly GitHub Activity Into Blog Posts on Notion + DEV.to

Yash Kumar Saini — Fri, 27 Mar 2026 19:07:08 +0000

This is a submission for the Notion MCP Challenge

What I Built

Every Monday standup, someone asks: "What did you work on last week?" And every Monday, I stare at my screen trying to remember. Did I merge that PR on Wednesday or Thursday? Was that refactor in the auth module or the pipeline? How many repos did I even touch?

I got tired of that blank moment. So I built DevNotion — a 3-agent pipeline powered by Mastra that harvests my entire week of GitHub activity, narrates it into a first-person blog post using Gemini, and publishes it to Notion (as a planner-style page with structured tables) and DEV.to (as a draft article). Every Sunday, automatically, via GitHub Actions.

No more Monday amnesia. The blog writes itself.

What it actually does

Harvests my GitHub activity via GraphQL — commits, PRs, issues, code reviews, discussions, language stats, contribution streak
Narrates the raw data into a casual, first-person blog post using Gemini (with a deterministic fallback if the LLM is unavailable)
Publishes to two platforms simultaneously:
- Notion — a planner-style page with stats tables, repo breakdowns, PR/issue/review tables, language breakdown, and the full blog post
- DEV.to — a draft article ready for review

Key features

3 specialized agents — each does one thing well (harvest, narrate, publish)
LLM only where it adds value — harvest and publish are deterministic, zero token overhead
4 blog tone profiles — casual (default), professional, technical, storytelling
Planner-style Notion pages — not just a wall of text, but structured tables with stats, repos, PRs, issues, reviews, and languages
Notion MCP integration — full Notion API surface via Model Context Protocol
Notion Markdown Content API — write rich markdown directly to pages (the real game changer)
DEV.to draft publishing — articles created as drafts, ready to review and publish
GitHub Actions CI — weekly cron (Sundays 08:00 UTC) + manual dispatch
Blog log in README — CI auto-commits a metrics table after each run
Fallback chain — always produces a blog post, even if Gemini is down
Rate limiting everywhere — p-queue + p-retry for both Notion and DEV.to APIs

Architecture

Step	Agent	What it does
Harvest	`github-harvest-agent`	Fetches weekly GitHub data via GraphQL (deterministic)
Narrate	`narrator-agent`	Writes a first-person blog post from the data
Publish	`publisher-agent`	Creates Notion planner page + DEV.to draft via direct APIs

The pipeline only uses an LLM where it genuinely adds value — narration. Harvest and publish are pure function calls. No token overhead, no hallucination risk, faster execution.

Architecture Deep-Dive

Why 3 agents, not 1?

I could've built one mega-agent that does everything. But that's a recipe for:

Burning tokens on deterministic work (fetching GitHub data doesn't need an LLM)
Hallucinating URLs and stats (the publish step should never make things up)
Debugging nightmares (which part of the monolith failed?)

Instead, each agent is a specialist. The workflow chains them together:

export const weeklyDispatchWorkflow = createWorkflow({
  id: 'weekly-dispatch',
  inputSchema: z.object({ weekStart: z.string() }),
  outputSchema: PublishOutputSchema,
})
  .then(harvestStep)
  .then(narrateStep)
  .then(publishStep)
  .commit();

Three steps, chained with .then(), committed as a single workflow. Mastra handles the data handoff between steps automatically.

Harvest: deterministic data, zero LLM

The harvest step calls GitHub's GraphQL API directly — no agent reasoning needed:

const harvestStep = createStep({
  id: 'harvest-github',
  inputSchema: z.object({ weekStart: z.string() }),
  outputSchema: WeeklyDataSchema,
  execute: async ({ inputData }) => {
    const data = await fetchWeeklyContributions(inputData.weekStart);
    return WeeklyDataSchema.parse(data);
  },
});

One GraphQL query pulls commits, PRs, issues, reviews, discussions, language stats, and contribution streak for the week. The response gets validated through a Zod schema. No LLM in the loop — this is pure data fetching.

Narrate: LLM with a fallback chain

This is where the LLM earns its keep. The narrator agent takes raw JSON and writes a blog post that sounds like I wrote it myself. The system prompt has a full personality profile — it writes in first person, knows my tech stack (Python, Rust, TypeScript), references my OSS work, and matches one of four tone profiles.

But LLMs can be flaky. So the narrate step has a fallback chain:

const narrateStep = createStep({
  id: 'narrate',
  execute: async ({ inputData, mastra }) => {
    const agent = mastra!.getAgent('narrator-agent');
    let blog;

    try {
      const result = await agent.generate(prompt);
      const parsed = parseFrontmatter(result.text);
      if (parsed.success) {
        blog = parsed.data.blog;
      } else {
        blog = buildFallbackNarration(inputData).blog;
      }
    } catch (err) {
      blog = buildFallbackNarration(inputData).blog;
    }

    return { blog, weeklyData: inputData };
  },
});

Gemini generates a markdown blog with YAML frontmatter
If parsing fails → deterministic fallback builds a basic post from raw data

A blog post is always produced, even if Gemini is completely down.

Publish: Notion planner + DEV.to draft

The publish step is where things get interesting. It doesn't just dump text into Notion — it builds a planner-style page with structured tables:

const publishStep = createStep({
  id: 'publish',
  execute: async ({ inputData }) => {
    const { blog, weeklyData } = inputData;

    // 1. Create Notion page
    const createResult = await createNotionPage(title);

    // 2. Create DEV.to draft (so the link goes into the Notion planner)
    const devtoResult = await createDevtoArticle({
      title: blog.headline,
      body_markdown: buildDevtoMarkdown(blog),
      tags: blog.tags,
      published: false,
    });

    // 3. Write planner markdown to Notion (includes DEV.to link)
    const plannerMd = buildPlannerMarkdown(weeklyData, blog, links);
    await writeNotionMarkdown(notionPageId, plannerMd);
  },
});

The order matters: DEV.to draft gets created before writing the Notion page content, so the Notion planner can include a link to the DEV.to draft. Cross-platform linking, done right.

Each Notion page includes:

Published Links table — Notion page URL + DEV.to draft edit link
Week at a Glance — commits, PRs, issues, reviews, lines added/removed, streak
Active Repositories — repo name, commits, language, line changes
Pull Requests / Issues / Reviews / Discussions — structured tables
Languages — top languages by commit count
Full blog post — the narrated content below a separator

// Detect dark theme var iframe = document.getElementById('tweet-2038152048533979142-927'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2038152048533979142&theme=dark" }

Star DevNotion on GitHub

How I Used Notion MCP

This is the part I'm most excited about. DevNotion uses the Notion MCP Server in two complementary ways:

1. Notion MCP Server via `@mastra/mcp`

The publisher agent integrates with the official @notionhq/notion-mcp-server through Mastra's MCP client. This gives the agent access to the full Notion API surface via Model Context Protocol:

import { MCPClient } from '@mastra/mcp';

export const notionMcp = new MCPClient({
  servers: {
    notion: {
      command: 'npx',
      args: ['-y', '@notionhq/notion-mcp-server'],
      env: {
        OPENAPI_MCP_HEADERS: JSON.stringify({
          Authorization: `Bearer ${env.NOTION_TOKEN}`,
          'Notion-Version': '2022-06-28',
        }),
      },
    },
  },
  timeout: 30000,
});

The MCP tools are loaded lazily with a graceful fallback — if the MCP server fails to start, the direct tools still work independently:

export async function getNotionMcpTools(): Promise<Record<string, any>> {
  try {
    return await notionMcp.listTools();
  } catch (err) {
    console.warn('MCP: Notion MCP server unavailable, using direct tools only');
    return {};
  }
}

2. Direct tools + MCP tools merged

The publisher agent merges both tool sets — MCP tools for the full Notion API surface, and direct tools for capabilities MCP doesn't cover:

// Direct tools (Markdown Content API + DEV.to — not available via MCP)
const directTools = {
  createNotionPage: createNotionPageTool,
  writeMarkdown: writeMarkdownTool,
  searchNotion: searchNotionTool,
  updateNotionPage: updateNotionPageTool,
};

// Merge: Notion MCP tools + direct tools
const mcpTools = await getNotionMcpTools();
const tools = { ...mcpTools, ...directTools };

This dual approach means the publisher agent gets the best of both worlds — MCP's broad API surface for interactive use in the Mastra playground, plus direct tools for the automated workflow.

3. The Markdown Content API (the game changer)

This is the Notion feature that made the planner-style pages possible. Instead of constructing Notion blocks one by one (which is painful and rate-limit-heavy), I write the entire page as markdown in one API call:

const response = await fetch(
  `https://api.notion.com/v1/pages/${pageId}/markdown`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${env.NOTION_TOKEN}`,
      'Content-Type': 'application/json',
      'Notion-Version': '2026-03-11',
    },
    body: JSON.stringify({
      type: 'replace_content',
      replace_content: { new_str: markdown },
    }),
  },
);

One PATCH request replaces the entire page content with rich markdown — including tables, headings, blockquotes, links, code blocks, everything. This is what powers the planner-style layout with structured stats tables + the full blog post, all in a single API call.

4. Rate limiting

Notion's API allows roughly 3 requests per second. Every Notion call (MCP and direct) goes through a shared rate limiter:

const queue = new PQueue({ concurrency: 1, interval: 334, intervalCap: 1 });

async function rateLimited<T>(fn: () => Promise<T>): Promise<T> {
  return queue.add(() => pRetry(fn, { retries: 3 })) as Promise<T>;
}

p-queue throttles concurrency, p-retry handles transient failures. I learned this the hard way — without rate limiting, the Notion API will 429 you into oblivion when you're creating a page, writing markdown, and updating the icon in quick succession.

Lessons Learned

Rate limits are the real boss

Notion (3 req/s), DEV.to (30 req/30s), GitHub GraphQL (5000 points/hr) — every API has its own throttle. I ended up with p-queue + p-retry wrappers around everything. The rate limiter code is almost identical across all three services, and honestly, it should probably be a shared utility. But three similar lines of code is better than a premature abstraction.

Structured output is slower than you'd think

I originally used Gemini's native JSON schema for structured output (agent.generate(prompt, { structuredOutput: { schema } })). It worked, but added 20-40 seconds per call. Switching to plain text generation with YAML frontmatter parsing was 3-4x faster and just as reliable. The deterministic fallback catches the rare parsing failure.

Gemini model musical chairs

I've been through three Gemini models on this project: gemini-2.5-flash-preview-04-17 (retired), gemini-2.5-flash (stable but slow for structured output), and now gemini-3-flash-preview (current). The lesson: always make the model configurable via env vars. Hardcoding model IDs is a recipe for broken deploys.

The Zod conflict that broke everything

Mastra and my code both depend on Zod, but different versions. Having two Zod instances means z.string() from one isn't recognized by the other — schema validation just silently fails. The fix: a single line in package.json:

{
  "pnpm": {
    "overrides": {
      "zod": "$zod"
    }
  }
}

Forces pnpm to deduplicate to one Zod version. Took me way too long to figure that out.

Direct API calls beat agent reasoning for deterministic work

The harvest and publish steps started as full agent calls. But an LLM doesn't add anything when the task is "call this GraphQL endpoint and return the result." Switching to direct function calls made the pipeline faster, cheaper, and more predictable. Only use an LLM where you need creativity or reasoning — everywhere else, just write a function.

Built with Mastra, Gemini, Notion API, and a lot of coffee. If you've ever forgotten what you worked on last week, give DevNotion a try.

Simulating P2P Attacks and Teaching AI to Resume Sessions

Yash Kumar Saini — Fri, 27 Mar 2026 18:12:28 +0000

TL;DR

It’s been one of those weeks where the terminal never really closed. I clocked 78 commits and pushed 4 PRs across 9 different repositories, maintaining a perfect 7-day streak. The bulk of the heavy lifting happened in the P2P space—specifically simulating network attacks—and adding some much-needed session persistence to my AI coding tool, nanocoder. With over 21,000 lines added and about 6,500 deleted, it was a high-output week focused on building out complex systems and then immediately refining them.

WHAT I BUILT

The star of the show this week was definitely P2P-Attack-Simulation. I’ve been obsessed with how decentralized networks handle adversarial conditions, and I finally merged a massive PR for Topology ts simulation. We’re talking 18,756 additions and 6,436 deletions. I essentially rewrote how the network topology is represented in TypeScript to make it more modular. Before, the simulation was a bit too rigid; now, I can spin up different node behaviors and see how the gossip protocols hold up when half the network starts acting malicious. It’s one thing to read about Sybil attacks in a paper, but seeing the message propagation latency spike in your own simulation is a different kind of satisfying.

Over in nanocoder, I spent a good chunk of time on the developer experience. If you’ve used AI coding assistants, you know the pain of losing context or having to restart a session from scratch. I implemented a new Feature /resume command to continue session. This involved a fair bit of state management (about 2,300 lines of code) to ensure that when you come back to a project, the AI knows exactly where you left off. It’s all about reducing friction. I want to spend my time coding, not re-explaining my file structure to a LLM.

I also dipped back into the low-level world with the networking repo. This is where I get my Rust fix. I merged two PRs here: one to Implement proper RST generation and another to refactor: remove timer module and associated functionality. The RST (Reset) generation is crucial for proper TCP handling—basically telling the other side "I have no idea what you're talking about, let's start over." The refactor felt great, too. I realized the custom timer module was overkill for what we needed, so I ripped out 137 lines of brittle code. Less code, fewer bugs.

Beyond the big features, I kept the wheels turning on several other projects. I pushed 10 commits to py-libp2p and 1 to dotnet-libp2p, mostly keeping the Python and C# implementations of the p2p stack in sync. I also spent some time tweaking my environment, with 8 commits to my nvim config (because a dev's work is never done when it comes to Lua plugins) and 7 commits to my notes repo, which is where I dump my raw thoughts on C and systems programming.

PULL REQUESTS

I managed to get four significant PRs merged this week, and they really tell the story of my transition from "building the foundation" to "polishing the experience."

The Topology ts simulation PR was the most exhausting but rewarding. It wasn't just about adding lines; it was about restructuring the entire simulation engine. I had to ensure that the TypeScript types correctly reflected the state of a peer at any given millisecond during an attack.

On the AI side, the Feature /resume command in nanocoder was a fun challenge in serialization. Making sure the session state could be saved and reloaded without losing the "vibe" of the conversation took a few iterations, but it's finally in a place where it feels seamless.

The Rust work in the networking repo was much more surgical. Implementing RST generation required me to get back into the weeds of packet headers, while the timer module refactor was a classic "addition by subtraction" move.

CODE REVIEWS

I only did one formal review this week, but it was a deep one. I looked at a PR for py-ipld-dag titled Add Block API, IPLD data model, codecs, registry, and tests.

I actually ended up requesting changes on this one. IPLD (InterPlanetary Linked Data) is the backbone of how we structure data in the p2p world, and the proposed implementation of the Block API felt a bit too coupled to specific codecs. I suggested a more registry-based approach to make it easier for others to plug in new data formats later. It’s important to get these base-level APIs right early on, or you end up paying for it in technical debt for years.

TECH STACK

This week was a true polyglot marathon.

TypeScript was my primary driver for the simulation work and the AI tooling. With over 15 million bytes of TS in my environment, it’s definitely my "get things done" language. But Python isn't far behind—especially with the work on py-libp2p and the IPLD reviews.

The Rust work in the networking repo reminded me why I love the language: the compiler is a jerk until you get it right, and then your code just works. I also touched some Lua for my Neovim setup and a bit of C for my personal notes and experiments.

My add/delete ratio was pretty high (21k vs 6k), which usually means I'm in a heavy feature-building phase. However, that 6k deletions in the P2P repo shows I'm not just piling code on top of code—I'm actively replacing the old stuff as I go.

And yeah, that 7-day streak feels good. It wasn't a forced grind; I just genuinely had something I wanted to solve every single morning when I woke up.

WHAT'S NEXT

Next week, I’m planning to take the P2P simulation even further. Now that the topology is flexible, I want to start implementing specific Eclipse attack scenarios to see how quickly a node can be isolated from the rest of the network.

I’m also keeping an eye on the feedback for the /resume command in nanocoder. There are probably some edge cases with large file buffers that I’ll need to iron out.

On the Rust side, now that RST generation is handled, I might start looking into better congestion control mechanisms for the networking library. There’s always more to optimize. See you in the commit logs!

Beyond the Panic: Hardening the Rust SDK

Yash Kumar Saini — Fri, 27 Mar 2026 14:41:20 +0000

TL;DR

Engineering is often the art of managing the "unhappy path." This week was a testament to that philosophy. With 74 commits, 2 PRs, 3 issues, and 3 reviews across 5 repositories, the focus shifted from building new features to fortifying the foundations. The headline? A concerted effort to purge unwrap() and panic calls from our Rust SDKs in favor of robust, Result-based error handling.

The Work: Velocity in the Engine Room

The bulk of the week's momentum was concentrated in the Python ecosystem, specifically within p2pCalc and AgentPay. These two repositories accounted for 54 of the week's 74 commits, representing a high-velocity push in our core logic layers.

p2pCalc & AgentPay

In p2pCalc (32 commits), we focused on the computational integrity of our peer-to-peer logic. While the additions and deletions were kept internal to the commit history, the sheer volume of activity suggests a deep dive into the algorithmic core. Parallel to this, AgentPay (22 commits) saw significant movement. When dealing with payment agents, there is no room for ambiguity. My focus here was on ensuring that the state machine governing agent transactions is both predictable and idempotent.

DevNotion & The Developer Environment

Meanwhile, DevNotion (14 commits) continues to evolve. As a TypeScript-based project, it serves as the bridge between our raw data and the narratives we share. The work here was iterative, likely refining the very engine that powers these weekly field notes.

I also took a moment to sharpen the saw. Five commits to my nvim configuration (Lua) might seem like minor housekeeping, but for a principal engineer, the editor is the primary instrument. A well-tuned environment isn't a luxury; it’s a prerequisite for the kind of deep work required to handle complex refactors.

The Pull Requests: The Safety Initiative

The most critical architectural work happened within the Appwrite ecosystem. We are currently in the process of maturing the Rust SDK, and that means moving away from "prototype-grade" code.

Title	Repo	State	Impact
fix(rust): replace unwrap/panic with Result-based error handling	sdk-generator	OPEN	Prevents generator-level crashes during SDK synthesis.
refactor: replace unwrap with error handling in Client methods	sdk-for-rust	CLOSED	Shifts error responsibility to the library consumer, avoiding runtime panics.

The PR in sdk-for-rust (#9) was a substantial undertaking, involving 149 additions and 46 deletions. In Rust, using .unwrap() is a debt you eventually have to pay. By replacing these with proper Result types, we ensure that the SDK doesn't bring down a user's entire application just because of a transient network failure or a malformed response. It’s about respecting the caller’s right to decide how to handle failure.

The work continues in sdk-generator (#1398), where I am applying similar logic to the generator itself. If the generator panics, the entire CI/CD pipeline halts. By implementing Result-based handling, we allow the system to fail gracefully and provide actionable feedback.

The Conversations: Setting the Standard

Collaboration this week was centered on documentation and issue tracking. I closed two critical issues in the sdk-for-rust repo:

Issue #8: The bug report that initiated the unwrap() refactor.
Issue #7: The creation of CONTRIBUTING.md.

The latter is particularly important. As we scale, we need to ensure that external contributors understand the quality bar we’ve set. A clear CONTRIBUTING.md is the first step in building a healthy open-source community around the Rust SDK.

The Reviews: Raising the Bar

Reviewing 3 PRs while authoring 2 is a healthy ratio for a week focused on quality. My reviews on awesome-py-libp2p-examples resulted in "CHANGES_REQUESTED" for two separate PRs (#6 and #3).

When reviewing collaborative tools like a "Whiteboard" or "p2p model checking," I look for more than just "does it run?" I look for idiomatic patterns and clear documentation. If an example is meant to be "awesome," it must serve as a gold standard for others to follow. My comments on py-libp2p (#1222) regarding the reorganization of example scripts follow this same theme: structure dictates usability.

The Craft: A Polyglot Reality

This week’s data reveals a truly polyglot workflow. While Python remains the dominant language by volume (over 77MB of context), the most impactful changes were written in Rust and TypeScript.

The add/delete ratio (+227/-80) indicates a week of net-new growth, but the nature of that growth was defensive. We weren't just adding features; we were adding safety nets. The lack of a commit streak this week is a reminder that engineering isn't always a daily sprint; sometimes it’s a series of deep-dive sessions separated by the necessary time to think through architectural implications.

The Horizon

As we look toward next week, the primary objective is to land the open PR in the sdk-generator. Once the generator is hardened, we can begin rolling out these safety improvements across all generated Rust SDKs.

We’ve moved the needle on reliability this week. The transition from "it works" to "it's resilient" is often invisible to the end-user until something goes wrong and the system doesn't crash. That is the quiet victory of the seasoned architect.

Onward.

I Built a TUI That Makes Rust Code Inspection Feel Like Magic ✨

Yash Kumar Saini — Sun, 15 Feb 2026 22:34:42 +0000

This is a submission for the GitHub Copilot CLI Challenge

The "Why Did I Build This?" Moment

Okay so here's the thing. I was working on this Rust project at 2 AM (as you do), trying to figure out where the hell DeserializeOwned was actually implemented. The codebase had like 50,000 lines, and there were these 17 different impl blocks just... everywhere. Scattered across 8 files like someone playing hide and seek with code.

And I'm sitting there thinking about my options:

Fire up VSCode? My SSH connection was lagging harder than my reaction time on Monday mornings
Use grep? Sure, if I wanted to scroll through 400 lines of garbage output
Try ripgrep with regex? I'd rather debug segfaults than write another regex at 2 AM
Make coffee and pretend the problem doesn't exist? Tempting...

But you know what? I got frustrated enough to actually do something about it.

So I built Oracle — basically a code inspector that lives in your terminal and actually doesn't suck to use. And to flex it more, Github Copilot helped me build, review, clean, optimize and vibe code all of this in just under 3 days.

What I Built

So 🔮 Oracle is basically a terminal-based code inspector for Rust projects. Think of it like... if grep and VSCode had a baby, and that baby grew up to be really good at understanding Rust code. No GUI bloat, no browser tabs eating your RAM, just your terminal doing cool stuff.

Here's what it does:

📦 Deep Code Analysis

Look, it parses everything. And I mean everything:

Functions (with those fancy async/const/unsafe badges, plus all the parameters and return types)
Structs (every field, every derive, all the generics — no more squinting at code trying to figure out field types)
Enums (it shows you ALL the variants with their field types spelled out)
Traits (methods, associated types, supertraits, the works)
Impl blocks (both the regular ones and trait implementations)
Modules, type aliases, constants, statics... basically if Rust can define it, Oracle can show it

🔍 Intelligent Search

The search is actually pretty smart (if I do say so myself):

Fuzzy matching that updates as you type (using fuzzy-matcher under the hood)
Context-aware, so when you're in the Functions tab, it only searches functions (no more wading through noise)
You can search for functions like and will get fully qualified paths like serde::de::Deserialize and it just works
Filter stuff by visibility (public/private/crate-level)

📋 Dependency Inspector

This part's kinda cool — it reads your Cargo.toml and shows you:

Your entire dependency tree visualized nicely
Live info from crates.io (descriptions, GitHub stars, license info)
All the crates installed in your ~/.cargo/registry folder
Press o to open docs.rs, press c to open crates.io — boom, instant browser tabs

🎨 Beautiful Themes

Because apparently I care about aesthetics even in my terminal:

Default Dark (clean and professional-ish)
Nord (if you like cool blues)
Catppuccin Mocha (cozy vibes)
Dracula (for the dramatic folks)
Just press t to cycle through them

⚡ Smooth Animations

Yeah I added animations to a CLI tool. Fight me.

Selection highlights that fade in smoothly
Tab transitions that don't feel jarring
Scrolling with momentum (it feels buttery smooth)
Real-time syntax highlighting

Honestly, I spent way too much time on the animations, but they make it feel really nice to use.

Demo

GitHub Repository: github.com/yashksaini-coder/oracle

Quick Start

# Install from source
git clone https://github.com/yashksaini-coder/oracle.git
cd oracle
cargo install --path .

# Run on any Rust project
oracle /path/to/rust/project

# Or analyze current directory
oracle

Sample Usage

# Inspect a famous crate
cargo new test_project
cd test_project
cargo add tokio

# Launch Oracle
oracle

# Now press:
# - Tab 4 times to get to Crates tab
# - Navigate to "tokio"
# - Press Enter
# - Search for "copy" with /
# - Browse copy methods and implementations

My Experience with GitHub Copilot CLI

Alright, confession time: This was my first serious Rust project that involved terminal UI stuff. I'd never touched Ratatui before, barely understood how syn worked, and was basically figuring everything out as I went.

GitHub Copilot CLI basically became my rubber duck, my Stack Overflow, and my patient senior developer all rolled into one. And the best part? I never had to leave my terminal.

🎯 How Copilot Saved My Sanity

1. Wrestling with the `syn` Crate

So Rust's syn crate is amazing for parsing Rust code, but holy hell the learning curve is steep. I needed to extract function signatures, struct fields, enum variants, all the trait bounds... basically everything.

I was staring at the docs feeling like I was reading ancient Greek, so I just asked Copilot:

gh copilot suggest "parse rust struct with syn crate extract all fields and visibility"

And it straight up gave me this:

use syn::{ItemStruct, Fields};

fn analyze_struct(st: &ItemStruct) -> Vec<Field> {
    match &st.fields {
        Fields::Named(named) => {
            named.named.iter().map(|f| Field {
                name: f.ident.as_ref().unwrap().to_string(),
                ty: quote!(#ty).to_string(),
                visibility: parse_visibility(&f.vis),
            }).collect()
        }
        // ... Tuple and Unit variants
    }
}

Like, it just worked. This became the foundation for parsing everything else — enums, traits, impl blocks, you name it. I just extended this pattern to handle all the other Rust item types.

Honestly? Saved me probably 8-10 hours of banging my head against the syn docs. Worth it.

2. Making the TUI Not Look Like Garbage

I wanted something that looked good. Not just functional, but actually pleasant to use. Panels, borders, smooth scrolling, the whole nine yards.

Problem: Ratatui's layout system made my brain hurt. How do you even compose these things?

Asked Copilot: gh copilot explain "ratatui layout constraints horizontal vertical split"

It explained that layouts are basically Lego blocks — you can compose them with Constraint::Percentage and Constraint::Length, and nest them for complex UIs. That made it click.

Then I was like: gh copilot suggest "ratatui scrollable panel with borders and title"

Got this back:

let block = Block::default()
    .borders(Borders::ALL)
    .title(" Inspector ");

let paragraph = Paragraph::new(lines)
    .block(block)
    .scroll((scroll_offset as u16, 0));

Beautiful. That became the core of my inspector panel. Later on I added the animations by interpolating the scroll_offset with some easing functions (because I'm extra like that).

3. Making Search Feel Snappy

I wanted the search to feel like VSCode's Ctrl+P — you know, where you just start typing and boom, instant results. No lag, no BS.

Asked Copilot: gh copilot suggest "rust fuzzy search crate with scoring"

It recommended fuzzy-matcher with SkimMatcherV2. Here's what I ended up with:

use fuzzy_matcher::skim::SkimMatcherV2;

let matcher = SkimMatcherV2::default();
let scored: Vec<_> = items
    .iter()
    .filter_map(|item| {
        matcher.fuzzy_match(&item.name, query)
            .map(|score| (item, score))
    })
    .collect();

scored.sort_by(|a, b| b.1.cmp(&a.1)); // Highest score first

And guess what? It worked perfectly on the first try. No debugging, no tweaking, just... worked. Those moments are rare in programming and should be celebrated.

4. Parsing Cargo.toml Without Crying

Dependencies and Cargo.toml can get complex real fast, especially with workspaces and transitive deps. I needed to parse all of that and build a proper dependency tree.

I was dreading this part until I asked: gh copilot explain "cargo metadata crate rust get all dependencies"

Turns out there's a crate called cargo_metadata (who knew?) that gives you structured JSON output. Copilot showed me:

How to get the root package
How to traverse the dependency tree
How to detect direct vs transitive dependencies
How to handle workspace crates

Here's what came out of it:

use cargo_metadata::MetadataCommand;

let metadata = MetadataCommand::new()
    .manifest_path(&manifest_path)
    .exec()?;

let root = metadata.root_package();
let dependencies = root.dependencies.iter()
    .filter(|d| d.kind == DependencyKind::Normal)
    .collect();

Simple, clean, and it actually works. Love it when code is like that.

5. Fetching Live Crate Info

I wanted to show real crate info when someone's browsing dependencies — descriptions, GitHub stars, license info, all that good stuff. Which meant hitting the crates.io API.

Me, having zero experience with async HTTP in Rust: gh copilot suggest "rust async http request to crates.io api"

Copilot pointed me to reqwest and showed me the blocking client pattern for background threads:

use reqwest::blocking::Client;

fn fetch_crate_docs(name: &str) -> Option<CrateDoc> {
    let client = Client::new();
    let url = format!("https://crates.io/api/v1/crates/{}", name);

    let response = client.get(&url).send().ok()?;
    let json: serde_json::Value = response.json().ok()?;

    Some(CrateDoc {
        name: json["crate"]["name"].as_str()?.to_string(),
        description: json["crate"]["description"].as_str().map(String::from),
        // ...
    })
}

Then I needed GitHub repo stats too, so I asked how to parse GitHub URLs and hit their API. Got that working too.

The whole crates.io + GitHub integration took one evening instead of... I don't know, a week of reading API docs?

6. Cross-Platform Path Hell

You know what's annoying? File paths. Windows uses backslashes, Unix uses forward slashes, and I needed to convert file paths to module paths (src/analyzer/parser.rs → ["analyzer", "parser"]).

Asked: gh copilot suggest "rust strip src directory from pathbuf get module path"

Got this beauty:

fn derive_module_path(path: &Path) -> Vec<String> {
    path.iter()
        .skip_while(|c| c != &"src")
        .skip(1) // Skip "src" itself
        .map(|c| c.to_string_lossy().to_string())
        .collect()
}

Works on Windows, macOS, Linux. No #[cfg] needed. Just works everywhere.

7. Making Animations Not Suck

Okay so this is where I got a bit carried away. I wanted smooth scrolling with momentum, not that janky jump-scroll thing most TUIs have.

Asked Copilot: gh copilot suggest "rust easing functions ease in out cubic"

It gave me the classic easing formulas:

pub fn ease_out(t: f64) -> f64 {
    1.0 - (1.0 - t).powi(3)
}

pub fn ease_in_out(t: f64) -> f64 {
    if t < 0.5 {
        4.0 * t * t * t
    } else {
        1.0 - (-2.0 * t + 2.0).powi(3) / 2.0
    }
}

8. Integrating Copilot within itself

At this point I was just too deep into the rabbit hole and wanted to see how far I can reach, and so decided to give it a AI chat interface area, completely powered by Copilot and guess what ....

It Actually Works, it was mind blowing telling copilot to build and integrate yourself within my tool.

Applied these to scroll offset interpolation and boom — butter-smooth 60fps scrolling. Completely unnecessary for a CLI tool? Yes. Did I do it anyway? Also yes.

The Stuff That Almost Broke Me

Challenge 1: Not Freezing the Terminal When Parsing Big Projects

The Problem: So I tried running Oracle on the tokio codebase (which has like 200+ files), and my terminal just... froze. For a solid 10 seconds. Completely unresponsive. Not great.

The Solution:
I moved all the parsing to background threads so the UI could stay responsive. Added a splash screen with this little wave animation (because if users have to wait, at least make it pretty). Also pre-computed search indices so that wouldn't lag either.

Copilot helped me figure out the threading patterns and how to show progress without blocking the UI. Game changer.

Challenge 2: Making Search Feel Instant (Even When It's Not)

The Problem: When you have 10,000+ items to search through, every keystroke was taking like 100ms. That's noticeable lag, and it felt janky.

The Solution:

Only search within the active tab (if you're in Functions, only search functions)
Limit results to top 50 (nobody scrolls past that anyway)
Used fuzzy-matcher's batch scoring (it's faster than one-by-one)
Cached search results for repeated queries
Only rendered visible items on screen

Result? Search now takes < 16ms per keystroke. That's 60fps territory. Smooth.

Challenge 3: GitHub Rate Limits Are Real

The Problem: The GitHub API rate-limits unauthenticated requests to 60 per hour. I was hitting that limit basically immediately when testing the crates.io features.

The Solution:

Added support for GITHUB_TOKEN environment variable (gives you 5000/hour when authenticated)
Cached responses per crate so we don't re-fetch
Graceful fallback when rate-limited (just show "rate limited" instead of crashing)
Added a hint to users: "Set GITHUB_TOKEN for more requests"

Copilot helped explain the GitHub API auth flow and how to parse rate limit headers. Much better now.

Challenge 4: Scrollable Content That Doesn't Suck

The Problem: When you select an item, the inspector panel shows all its details. But what if the docs are really long? It just got cut off. Not ideal.

The Solution:
Had to track scroll offset per selected item, bind j/k and arrow keys to scroll up/down, show a scrollbar indicator when content overflows, and reset scroll position when switching items.

Copilot showed me Ratatui's Scrollbar widget and how to manage scroll state properly. Works great now.

Why You Might Actually Want to Use This

🚀 It's Fast (Like, Really Fast)

Parses 200+ files in under 2 seconds
Search responds instantly (< 16ms per keystroke)
60fps animations (yes, in a terminal)
Zero network calls for local analysis (your code never leaves your machine)

🎨 It Doesn't Look Like Hot Garbage

4 hand-crafted themes (Nord is chef's kiss)
Smooth scrolling with easing (because I have standards)
Context-aware UI (functions show parameter hints, structs show field types)
Professional documentation formatting

🔧 Actually Designed for Terminal Use

Works perfectly over SSH (no GUI needed, no X forwarding BS)
Vim-style keybindings (j/k for life)
One command: oracle — that's it
Installable via cargo install (once I publish it to crates.io)

📚 It Actually Understands Rust

Most code search tools are just fancy grep. Oracle:

Analyzes ALL Rust item types (functions, structs, enums, traits, impls, modules)
Shows qualified paths (serde::de::Deserialize works perfectly)
Handles visibility modifiers properly
Understands generics, lifetimes, trait bounds, async, const, unsafe — all of it

Basically, it doesn't just search your code, it understands it.

How I Actually Use This Thing

Before Oracle:

# Trying to find all trait implementations
rg "impl.*for" | less  # Scroll through 200 lines of noise

# Trying to understand a struct
rg "struct Config" -A 20 | grep "pub"  # Miss half the fields

# Finding function signatures
rg "pub fn connect"  # Get incomplete matches without parameters

With Oracle:

oracle
# Tab to Functions, type "connect", press Enter
# See:
#   - Full signature with all parameters and types
#   - Complete documentation
#   - Return type with error handling
#   - Source location (file + line number)
# Press 'o' to open in your editor

It's just... so much faster. And less annoying.

Another example: You add tokio to your project and want to understand how spawn works.

Old way:

Clone the tokio repo
grep for "pub fn spawn"
Get 47 matches
Try to figure out which one is the right one
Give up and read the docs instead

With Oracle:

oracle ~/.cargo/registry/src/*/tokio-*
# Press 4 for Crates tab
# Navigate to "tokio", press Enter
# Type "spawn" in search
# See signature, docs, parameters, trait bounds
# Press 'o' for docs.rs if you want more details

Time saved: Like 5 minutes every single time.

Installation & Usage

Install

# From source (recommended for now)
git clone https://github.com/yashksaini-coder/oracle.git
cd oracle
cargo install --path .

# Or use cargo directly (once published)
cargo install oracle-tui

Usage

# Analyze current directory
oracle

# Analyze specific project
oracle ~/code/my-rust-project

# Set GitHub token for better crate.io API limits
export GITHUB_TOKEN=ghp_yourtoken
oracle

What's Next (If People Actually Use This)

Got some ideas for future versions:

Symbol references: Show where a function/type is actually being used (would be super helpful)
Jump to definition: Press a key, open the source file at the exact line
Macro expansion viewer: See what those cryptic macros expand to
Call graph visualization: Show which functions call which (could get messy but cool)
Git integration: Show recent changes per item, like "this function was modified 3 days ago"
Export to JSON/HTML: Generate static docs from your codebase
LSP integration: Hook into rust-analyzer for even deeper analysis

No promises on timeline though. This is still a side project I hacked together because I was annoyed.

Why Rust?

Performance: Parsing is CPU-bound. Rust's zero-cost abstractions mean fast parsing without GC pauses.

Safety: No segfaults when traversing complex ASTs. The borrow checker caught 20+ bugs during development.

Ecosystem: syn is the gold standard for Rust parsing. ratatui makes TUIs actually fun to build.

Cross-platform: One binary works on Linux, macOS, Windows — no Python/Node runtime needed.

Lessons Learned

1. TUI State Management is Hard

Managing focus, scroll positions, search state, animations — all simultaneously — is trickier than React state. Had to build a small state machine.

2. Parsing is Expensive

Even with syn's fast parser, analyzing 200+ files takes time. Had to optimize with:

Lazy loading (only parse visible items)
Caching parsed results
Background threads for heavy work

3. Terminal Rendering is Delicate

Drawing too frequently causes flicker. Drawing too infrequently feels laggy. Found the sweet spot: 60fps when animating, 10fps when idle.

4. Copilot CLI is a Force Multiplier

Seriously. Having an AI explain syn patterns, Ratatui layouts, async patterns, easing formulas — all without leaving the terminal — was incredible.

Wrapping Up

So yeah, that's Oracle. Built it because I was frustrated with existing tools, learned a ton about Rust, TUIs, and parsing along the way.

GitHub Copilot CLI was honestly a lifesaver. Having an AI that could explain syn patterns, show me Ratatui layouts, help with async patterns, and even provide easing formulas — all without leaving my terminal — was incredible. Saved me probably 30+ hours of reading docs and Stack Overflow.

The result is a tool I actually use every day now. Every time I clone a new Rust project, I run oracle first to get the lay of the land. It's just become part of my workflow.

If you work with Rust, give it a shot. Worst case, you wasted 2 minutes installing it. Best case, it changes how you explore code.

Links:

Yash Saini - @yashksaini-coder
X: 0xcrackedDev
GitHub: github.com/yashksaini-coder/oracle
Crates: oracle-tui
Latest Release: Latest releases

Got feedback? Found a bug? Want a feature? Open an issue or drop a comment. I actually read them.

Built with way too much coffee, Rust, Ratatui, and GitHub Copilot CLI being an absolute legend.

Star Oracle

If you liked this, consider giving the repo a star. It makes me feel good about my life choices. ⭐

devchallenge #githubchallenge #cli #rust #tui #opensource