DEV Community: Athreya aka Maneshwar

Teach Your Agent to Forget (On Purpose)

Athreya aka Maneshwar — Sat, 13 Jun 2026 17:26:10 +0000

Hello, I'm Maneshwar. I'm building git-lrc, a Micro AI code reviewer that runs on every commit. It is free and source-available on Github. Star git-lrc to help devs discover the project. Do give it a try and share your feedback.

Here's a thing that happens to everyone who builds a long-running agent.

At turn 10, it's brilliant.

Sharp, fast, remembers exactly what you asked, threads the needle on the tricky bug.

You feel like a wizard.

At turn 80, it's a different creature.

It re-suggests a fix you already rejected.

It "forgets" the file it edited twenty turns ago.

It contradicts a decision you both made at the start.

The same model, the same prompt, the same task and it's somehow gotten dumber as it learned more.

That's not a bug in the model.

That's the desk filling up.

In Part 1 I made the case that the context window is RAM, not a hard drive, working memory with a hard edge.

Everything the model can reason about has to fit on the desk.

The long conversation is what happens when you keep piling paper on that desk and never clear any of it.

Eventually the important sheet is buried under four hundred lines of tool output, and the model is doing your taxes at a party while standing in a paper avalanche.

Compaction is how you clear the desk without sweeping the important sheet into the trash.

Of the four moves from Part 1 — write, retrieve, compact, isolate this is the one people get most confidently wrong.

Because on the surface it looks trivial: "just summarize the conversation." And then they ship a summarizer, and their agent starts quietly losing its mind.

Let's do it properly.

What compaction actually is (and what it isn't)

Compaction is lossy compression for meaning.

You take a long, sprawling history and replace it with a shorter representation that preserves what matters for the next step and discards what doesn't.

The "lossy" part is the whole game.

If it were lossless, it wouldn't help, you'd just have the same tokens in a different font.

Compaction works precisely because it throws information away.

The skill is in what you throw away.

Two things it is not, and conflating them will hurt you:

Compaction sits between them: smarter than trimming, less destructive than clearing.

It uses a model to decide what's worth keeping and rewrites the rest into something dense.

Why "just summarize it" goes wrong

Naive compaction fails in ways that are worth naming, because once you can name them you can design against them.

Drew Breunig has a clean taxonomy of how long context rots, and every one of these can be introduced by a sloppy compaction:

Poisoning: a hallucination makes it into the summary, and now it's load-bearing. The model treats its own earlier mistake as established fact and builds on it. Compaction can launder a guess into a "decision."
Distraction: the summary keeps so much that it just recreates the original bloat. Congratulations, you compacted a 50K conversation down to 48K.
Confusion: superfluous detail survives the cut and pulls the model toward irrelevant work.
Clash: the summary and the live messages disagree, and the model has to referee a fight between two versions of reality.

And then there's the failure mode unique to repeated compaction, which is the scary one: cumulative erosion.

Each compaction is lossy.

Compact a compaction and you lose a little more.

Do it five times across a marathon session and you've played telephone with your own task, the agent is now working from a summary of a summary of a summary, and the specific constraint you set at turn 3 ("never touch the auth module") is three generations of paraphrase away from the original.

This is the real reason agents "go off the rails" after an auto-compact fires mid-task: the boundary isn't just a token reduction, it's a behavioral discontinuity.

The agent on the other side is, in a real sense, a slightly different agent working from slightly worse notes.

You can't eliminate this.

You can only be deliberate about slowing it down.

The anatomy of a good compaction

So what survives the cut? Here's the heuristic that holds up across basically every serious implementation: keep the decisions and the state, discard the process that produced them.

Remember the example from Part 1, the agent that searched the database and found the user's table is documents_v2? I told you to hold that thought. Here's why it comes back.

A good compaction keeps: "The user's table is documents_v2."

A good compaction discards: the 400 lines of JSON the model waded through to figure that out.

That single line is the entire philosophy in miniature.

The fact is durable and tiny.

The evidence for the fact is enormous and now useless, you already extracted the value from it.

Keeping the JSON is paying rent forever on information you've already cashed out.

Generalize it and you get the checklist that every good handoff summary converges on:

Keep	Drop
What was decided, and the why behind it	The deliberation that led to the decision
Current state of files / system	Intermediate states already overwritten
Explicit user constraints and preferences	Pleasantries, acknowledgements, retries
What's in progress right now	Completed-and-verified subtasks (one line each)
Concrete next steps	Raw tool output you've already digested
Critical references (table names, IDs, paths)	The search that found them

The constraints line deserves emphasis: user constraints are the most expensive thing to lose and the easiest thing to drop.

"Decided to use Postgres" looks like a fact worth keeping.

"User said never to touch the auth module" looks like old conversational noise.

The second one is the one that, when lost, makes your agent confidently do the one thing it was told not to.

Pin constraints.

They should survive every compaction unchanged, never paraphrased.

How the real tools do it

Two production coding agents are worth contrasting, because they agree on the problem and disagree on the manners.

Claude Code leans on automation.

There's a manual /compact command, but the headline behavior is auto-compaction firing at roughly 95% of the context window, it summarizes the full trajectory and starts fresh with that summary as the seed.

You can steer it (/compact "focus on the open TODOs"), and it's distinct from /clear.

The community consensus, tellingly, is that 95% is too late: by the time you're that full, the conversation's already degrading, and people compact manually well before the trigger.

OpenAI's Codex CLI is more "handoff"-flavored. Its prompt frames compaction as a checkpoint producing a summary for "another LLM that will resume the task," and tells that next model to build on the work rather than redo it.

It triggers on a token threshold, keeps the most recent user messages verbatim alongside the summary, and has retry-with-backoff for when the compaction call itself fails. (Compaction is an LLM call. LLM calls fail. Plan for it.)

If you're building your own

Synthesizing into the decisions you'll actually have to make:

Trigger earlier than you think. 95% is the cautionary tale, not the recommendation.

Around 85–90% lets you compact while the context is still good enough to summarize well.

Prune before you summarize. Run a cheap mechanical pass that drops stale tool output first.

Summarization is your expensive, lossy tool, don't spend it on 400 lines of JSON you can just delete.

Keep recent turns verbatim. Compact the distant past; preserve the present.

The model needs the live, un-paraphrased thread of what's happening right now.

Pin constraints, and tell the user it happened. Carry user constraints through every compaction as exact text, they're the thing that does the most damage when lost.

And a silent compaction that changes behavior mid-task just feels like the agent randomly got worse; one line ("compacted history to free up context") turns a mystery into a tradeoff.

And a starting prompt, since you'll need one:

Create a handoff summary so this coding session can continue in a fresh context.
The summary will be the ONLY history available, so preserve:

1. Completed work — what's done and verified (one line each)
2. Current state — files modified and their status
3. In progress — what is being worked on right now
4. Next steps — concrete actions to take
5. Constraints — user preferences and requirements, quoted exactly
6. Critical references — table names, IDs, file paths, key decisions and the why

Be dense. Drop deliberation, raw tool output, and anything already superseded.
Do not invent or assume anything not present in the conversation.

That last line — do not invent — is your cheapest defense against poisoning.

The summarizer's job is compression, not creativity.

The moment it starts filling gaps, it's manufacturing the hallucination that turn 80 will treat as gospel.

The uncomfortable part

Compaction forces you to admit something the rest of the stack lets you avoid: you cannot keep everything, so you have to decide what your agent is allowed to forget.

External memory and retrieval let you dodge that, stash it, pull it back later.

But inside a single long-running task, on a finite desk, there's no dodge left.

Something has to go, and compaction is choosing what survives on purpose, instead of letting the context window choose for you by quietly shoving your most important constraint off the edge of attention.

The best compaction, like the best engineering, is mostly subtraction.

It's keeping documents_v2 and burning the JSON, one line of constraint outliving a thousand lines of chatter.

The mantra from Part 1 gets sharper here: the best token is the one you didn't have to send.

Compaction is how you find out which tokens those were, and have the nerve to delete them.

Disclaimer: This article was written by me; AI was used to fix grammar and improve readability.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

Stop Whispering to the Model, Start Furnishing Its Brain

Athreya aka Maneshwar — Wed, 10 Jun 2026 12:36:20 +0000

There's a moment every developer hits with LLMs.

You write the perfect prompt. Crisp instructions. A nice persona. Maybe a "think step by step" sprinkled on top like seasoning. And the model... gives you something almost right but confidently wrong.

So you tweak a word. Then another. You add "IMPORTANT:" in all caps because surely that'll do it.

You're basically performing a small ritual and hoping the machine spirits are pleased.

Here's the uncomfortable truth: the prompt was never the bottleneck. The context was.

Welcome to Context Engineering: the discipline that quietly does most of the heavy lifting in every serious LLM application, while prompt engineering gets all the blog posts. (The irony of saying that in a blog post is not lost on me.)

This series is my attempt to map the whole thing out.

Today we start with the big picture: what context engineering actually is, and the five pillars we'll spend the rest of the series digging into.

Prompt Engineering vs. Context Engineering

Let's settle this cleanly, because people use these terms like they're synonyms and then act surprised when their app behaves like a confused intern.

Prompt engineering is about the instruction. You're crafting the sentence(s) that tell the model what to do. "Summarize this in three bullet points." "Act as a senior Go reviewer." It's phrasing, framing, and tone. It's important, but it's one ingredient.

Context engineering is about everything the model can see when it answers. The instruction, sure, but also: the retrieved documents, the conversation history, the tool outputs, the user's preferences, the API schema, the error from the last attempt, the relevant rows from your database. It's the entire information environment you assemble around the question.

Here's the analogy that finally made it click for me:

You can ask a brilliant question to someone staring at a blank desk and get nonsense. Or you can ask a mediocre question to someone with exactly the right three documents open and get gold.

The model is only as smart as the context you hand it at inference time.

And this matters more than ever because of one brutal constraint:

The context window is RAM, not a hard drive

A model's context window its 200K, or 1M, or whatever-K tokens — is not storage.

It's working memory.

It's the desk, not the filing cabinet.

Everything the model "knows" in the moment has to fit on that desk, and the desk has a hard edge.

Context engineering is, at its core, the art of deciding what goes on the desk, when, and in what shape.

Too little and the model guesses.

Too much and it gets distracted, slow, expensive, and weirdly forgetful in the middle (the dreaded "lost in the middle" effect).

So how do we manage the desk well? Five pillars. Let's meet them.

Pillar 1: External Memory

LLMs have a goldfish problem.

By default, the model knows two things: whatever got baked into its weights during training, and whatever you put in the current context window.

The instant the conversation ends, the second one in most cases evaporates.

External memory is how we cheat death here. Instead of cramming everything the model might ever need into its parameters (impossible) or into a single prompt (expensive and finite), we stash information outside the model i.e in databases, vector stores, knowledge graphs, plain files and pull the relevant bits back in when we need them.

Think of it as giving the model a notebook it can flip through, instead of demanding it memorize the universe.

[ Model weights ]  →  what it learned in training (frozen, generic)
[ Context window ]  →  what it can see right now (small, expensive)
[ External memory ] →  everything else (huge, cheap, retrievable on demand)

This is the foundation that makes the next pillar even possible. Because once your knowledge lives outside the model, the obvious question becomes: how do I get the right slice of it back in?

Pillar 2: RAG and Dynamic Filters

Retrieval-Augmented Generation is the workhorse of modern LLM apps.

The pitch is simple: before the model answers, go fetch relevant, fresh, factual information from your external memory and slip it into the context.

Now the model answers with your data instead of its hazy half-memory of the internet from two years ago.

If you've built anything with LLMs in the last while, you've probably done RAG even if you didn't call it that.

User asks a question → you embed it → you search a vector DB → you stuff the top results into the prompt → the model answers. Beautiful.

Except naive RAG has a dirty secret: it retrieves things that are similar, not things that are useful.

Vector similarity will happily hand the model five chunks about "billing" when the user asked about a billing bug, including that one outdated doc from 2021 and a chunk that's technically relevant but belongs to a different customer.

This is where dynamic filters earn their keep.

Instead of blindly dumping the top-k matches, you filter the retrieval based on the actual situation:

Who's asking? Filter by user, tenant, permissions. (Nobody should retrieve another customer's data into context. That's not a feature, that's an incident.)
When does it apply? Filter by recency, version, environment.
What's the intent? Route a "how do I" question to docs, a "why is this broken" question to logs.

Pillar 3: Context Compaction

So you've got external memory, and you've got smart retrieval. Congratulations: you can now flood the context window faster than ever.

That's the new problem. Long contexts are slow, expensive, and counterintuitively often worse.

Models lose track of details buried in the middle of a giant blob.

Every redundant token is a token that pushes the important stuff toward the edges of attention.

Context compaction is the discipline of shrinking what you send without losing what matters.

It's lossy compression for meaning.

A few flavors:

Summarization:replace a 40-message conversation with a tight running summary of what's actually decided and relevant.
Filtering / pruning: drop the chunks, turns, or tool outputs that aren't pulling their weight.
Re-ranking: reorder retrieved results so the genuinely most relevant material sits where the model pays the most attention.

A concrete example: in a long agent run, you don't keep every single tool call and its full raw output forever.

You compact. "Searched the DB, found the user's table is documents_v2" is worth keeping.

The 400 lines of JSON it came from? Summarize and discard. (Hold that documents_v2 thought — there's a reason it'll come up again.)

The mantra: the best token is the one you didn't have to send. Compaction is how you free up desk space for the stuff that actually moves the needle.

Pillar 4: Context Isolation

Here's a failure mode everyone discovers eventually.

You build one mega-prompt agent that does everything: it answers support questions, writes code, queries the database, drafts emails, and waters your plants. And it's mediocre at all of it.

Why? Because you've stuffed five jobs' worth of instructions, tools, and context into one window, and they interfere with each other.

The model trying to write SQL gets distracted by the email-drafting instructions.

Unrelated information bleeds across tasks.

It's the cognitive equivalent of trying to do your taxes at a party.

Context isolation is the fix: give each task its own dedicated, clean context.

Instead of one omniscient agent, you use multiple smaller, focused agents (or sub-agents, or just separate calls) each with only the instructions, tools, and information its job requires.

The research agent doesn't need your code style guide.

The coder doesn't need to know how to phrase a customer apology.

By keeping their contexts separate, each one stays sharp, and a mess in one doesn't poison the others.

Isolation buys you reliability and keeps each individual window small enough to actually be good.

Putting the desk back together

Step back and look at the five pillars and you'll notice they're all the same idea wearing different hats:

Pillar	The question it answers
External memory	Where does knowledge live when it's not in the window?
RAG + dynamic filters	How do I pull the right knowledge back in?
Context compaction	How do I fit it without bloat?
Context isolation	How do I keep unrelated jobs from interfering?

Every one of them is a way of managing that scarce, precious desk i.e the context window, so the model sees exactly what it needs and nothing it doesn't.

That's context engineering. Not begging the model in capital letters.

Just deliberate, almost boring decisions about information: what to include, what to leave out, where to store it, and when to bring it back.

The prompt is the question. The context is everything that makes the answer good.

Disclaimer: This article was written by me; AI was used to fix grammar and improve readability.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

Wait... FDE Is Not a JavaScript Framework?

Athreya aka Maneshwar — Tue, 09 Jun 2026 17:30:36 +0000

No. And thank god, because we have enough of those.

If you've been scrolling LinkedIn lately and seen "Forward Deployed Engineer" pop up next to salaries that made you spit out your cold brew — you're not hallucinating.

The role blew up because of Palantir, got supercharged by the AI gold rush, and now everyone from Google to Razorpay to your favorite Series B startup is hiring them.

Here's the mental model:

A regular SWE ships features for millions of users they'll never meet.
An FDE ships an entire system for one customer whose engineers they're sitting next to, screen-sharing with, and occasionally absorbing the rage of.

It is the difference between cooking for a restaurant and being a private chef who flies to your client's house and cooks while they critique the knife work over your shoulder.

The non-negotiable truth: this is NOT a beginner role

Let's kill the dream early so nobody cries later.

Per the roadmap.sh FDE roadmap, the very first note on the path says it plainly: FDE is not a beginner role.

You're expected to already be a full-stack developer stepping into the role, not someone using it as a launchpad.

Real job postings back this up hard:

Fiddler wants 5+ years building production-grade ML/AI systems.
Razorpay asks for 3–10 years of hands-on engineering, people who've shipped production code and debugged it in live customer environments.

So if you're 6 months into your first bootcamp project... bookmark this, build for three more years, then come back. I'll wait.

The FDE skill tree (or: why you need to be a genuine full-stack threat)

Think of the roadmap as a literal RPG skill tree.

Here's what you have to level up.

1. Core technical skills — Frontend + Backend + Linux

FDEs need to be proficient in full-stack development, have high agency, and be able to deliver full apps for customers.

Not "I can center a div" full-stack.

More like "I can stand up a frontend, wire the backend, debug the Linux box it's running on, and explain all three to the customer's CTO" full-stack.

2. DSA & System Design

Here's the spicy one.

The roadmap is brutally honest:

Translation: yes, you still have to invert the binary tree.

The LeetCode grind doesn't end just because the job title is fancier.

3. AI Engineering skills

This is where 2026 FDEs separate from the pack.

You're expected to be fluent in at least one major cloud platform and know how to deploy infrastructure as code.

On top of that, the AI-flavored JDs want:

LLM / agentic frameworks: LangChain, LlamaIndex, LangGraph, AutoGen, MCP, RAG. (Fiddler and Razorpay both list these. "Hands-on counts, not just awareness," as Razorpay puts it.)
Building and orchestrating agents: tool bindings, eval pipelines, human-approval flows.
Responsible AI: model monitoring, drift detection, explainability, bias detection.

4. DevOps skills 🔧

FDEs are responsible for proving to customers that what they built won't break or go rogue in production.

That means you own the deploy, the monitoring, and the dreaded hypercare period.

Razorpay literally describes being the "first responder during the 15–30 day hypercare period post go-live."

Yeah. You build it, you ship it, you carry the pager. 📟

The half nobody warns you about: Customer & Field skills

This is the part that filters out 80% of brilliant engineers.

You can be a 10x coder and still bomb as an FDE because you can't do this half:

Field Skill	What it actually means
Discovery & Scoping	Run the call, gather requirements, sequence the work, and figure out integration complexity before you commit.
Tradeoffs	Constantly juggling Scope vs. Speed vs. Quality and explaining the tradeoff to a non-technical stakeholder without making them feel dumb.
Business Acumen	ROI, stakeholder management, product feedback loops. You're not just building, you're proving value.
Communication	Technical writing, clear updates, managing expectations, "closing ambiguity without hand-holding."

As Fiddler puts it, you're literally "the technical voice of the customer", embedded with their team, translating their messy reality into clean technical designs, then carrying their feedback back to your own Product and Engineering teams.

Razorpay is even blunter about what it's not:

"Okay but show me the money 💰"

Fair. Based on tracked 2026 hiring data (fdepulse.com):

FDE base salaries cluster between roughly $135K and $215K, varying by level and metro.
Hiring is concentrated, a handful of metros and the top ~10 companies hold most of the open roles.
AI labs and enterprise SaaS drive most new openings, with consulting firms a distant third.
Lots of companies are hiring their first or second FDE ever, a strong signal that brand-new teams are forming (read: ground-floor opportunity).

Top 10 companies by open FDE roles

Company	Open Roles	Median Salary
Deloitte	44	$194K
Google	31	$185K
ZipLine	11	$206K
Skyline Eco Adventures	11	$206K
JDA TSG	10	$110K
Adobe	5	$221K
Okta	5	$275K
Tenex.AI	5	Not disclosed
David Joseph & Company	5	$188K
C3 AI	3	$156K

Okta out here paying $275K to engineers who can both ship and talk.

Suddenly that public-speaking class doesn't seem like a waste, huh.

Your roadmap to becoming an FDE

If you want to actually chase this, here's the leveling order I'd suggest based on the roadmap:

Become a genuine full-stack dev first. Frontend, backend, and enough Linux to be dangerous. No shortcuts.
Grind DSA + System Design. It's the first interview gate. Period.
Get fluent in one cloud + Infrastructure as Code. Pick AWS, GCP, or Azure and go deep.
Learn the AI/agentic stack hands-on. Build something real with LangChain/LangGraph/MCP/RAG. "Awareness" gets you rejected.
Practice the soft stuff like it's a hard skill. Do discovery calls, write docs people actually read, learn to explain tradeoffs to non-engineers.
Develop high agency. This word shows up everywhere for a reason. FDEs are trusted to own ambiguous problems and just... handle them.

The roadmap also points to four follow-on tracks worth leveling into: Frontend, Backend, DevOps, and AI Engineer.

So... is it for you?

The FDE role is the rare job that rewards engineers who refused to pick a lane.

If you genuinely enjoy building and the messy human reality of why you're building it talking to customers, owning outcomes, carrying the pager and the conversation, this might be the most fun (and best-paid) seat in tech right now.

If you'd rather put on noise-canceling headphones and never speak to a stakeholder again? Totally valid.

Backend Roadmap is right over there, no judgment. 🎧

Either way ship code, talk to humans, don't let it break in prod.

That's the whole job not just for FDE, applies to all :)

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

one last peek 👀🍵 docs, a demo, and a goodbye for now

Athreya aka Maneshwar — Mon, 08 Jun 2026 19:27:13 +0000

Short one this time.

peektea now has a proper documentation site: lovestaco.github.io/peektea

Up to now, everything lived in one long README i.e install instructions, keybindings, configuration, WSL notes, all stacked on top of each other.

Useful, but not exactly a pleasant read once a project grows past a certain size.

The new site splits all of that into proper pages i.e Installation, Usage (navigation, opening files, filtering, hidden files, preview, sorting), Configuration, WSL support, and more.

Each with its own room to breathe, demos where they help, and a search bar to jump straight to what you need.

Built with MkDocs Material, themed in peektea's own palette, and deployed automatically on every push via GitHub Actions.

Go peek around: lovestaco.github.io/peektea

One last thing: the full demo

Before wrapping up, I also recorded a complete walkthrough, every feature from the series, start to finish, in one go:

This is probably the last blog post / improvement on peektea for a while.

I've got everything I wanted out of my own TUI file browser at this point.

If you're using peektea and there's something that would genuinely help your workflow, let me know in the comments.

I'm happy to build it.

For now, the pot's off the heat. 👀🍵

peektea brews on WSL (and installs in one line)

Athreya aka Maneshwar — Sat, 06 Jun 2026 17:47:41 +0000

Two things I kept putting off.

First: people on Windows asked if peektea runs on WSL. It does now.

Second: "brew it from source" is a terrible install story for a tool that's supposed to be minimal. That's fixed too.

Demo here in case above preview not showing up.

WSL support

WSL is Linux. peektea runs on Linux. So far, so good.

The problem is o the key that opens files.

On a normal Linux machine, pressing o on an image launches feh or eog. On WSL there are no Linux GUI apps.

The call fails silently or prints an error.

peektea now detects WSL at startup:

func IsWSL() bool {
    if os.Getenv("WSL_DISTRO_NAME") != "" {
        return true
    }
    data, err := os.ReadFile("/proc/version")
    return err == nil && strings.Contains(strings.ToLower(string(data)), "microsoft")
}

When WSL is detected, file opens route through wslview (from wslu) if it's installed, otherwise fall back to explorer.exe:

func WSLOpener() string {
    if _, err := exec.LookPath("wslview"); err == nil {
        return "wslview"
    }
    if _, err := exec.LookPath("explorer.exe"); err == nil {
        return "explorer.exe"
    }
    if _, err := os.Stat("/mnt/c/Windows/explorer.exe"); err == nil {
        return "/mnt/c/Windows/explorer.exe"
    }
    return ""
}

There's one more wrinkle: Windows programs can't read Linux paths like /home/taco/file.png.

They need UNC paths like \\wsl.localhost\Ubuntu\home\taco\file.png.

WSL ships wslpath for exactly this:

func WindowsPath(path string) string {
    out, err := exec.Command("wslpath", "-w", path).Output()
    if err != nil {
        return path
    }
    return strings.TrimSpace(string(out))
}

When the configured opener ends in .exe, the path gets converted before the command runs.

wslview handles conversion itself so it doesn't need this, only raw explorer.exe does.

lovestaco / peektea

Peek First. Open Later. A TUI file browser built with bubble tea

A minimal terminal file browser built with Bubble Tea.

Peek through your filesystem with arrow keys (or vim keys), then pour each file straight into the app you've configured for it.

Demo

A quick peek before you steep:

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

Download a binary (no Go required) — grab the latest release for your platform from the releases page:

Platform	File
Linux x86-64	`peektea_linux_amd64.tar.gz`
Linux arm64	`peektealinux_arm64.tar.gz`
macOS x86-64	`peekteadarwin_amd64.tar.gz`
macOS Apple Silicon	`peektea_darwin_arm64.tar.gz`

Extract and put the peektea binary anywhere on your $PATH.

Install with Go:

go install github.com/lovestaco/peektea@latest

Build from source:

git clone https://github.com/lovestaco/peektea
cd peektea
make install

make install puts the binary in ~/go/bin and figures out $PATH for you:

Already reachable — done, nothing to do.
~/.local/bin is on your PATH — symlinks the binary there, works immediately in the current shell.
Neither — appends ~/go/bin to your .bashrc…

View on GitHub

peektea init on WSL

peektea init on a normal Linux machine asks you to pick a text editor, file manager, image viewer, and PDF viewer from what's installed.

On WSL there usually aren't any Linux GUI apps. Asking you to pick between zero options isn't a great experience.

So on WSL, init skips those categories and sets the Windows opener as the fallback instead of xdg-open.

You still get the full text editor setup (vim, nvim, nano those work fine in WSL), and the Windows side handles everything visual.

Demo here in case the above preview is not showing up.

While at it, peektea init got smarter in general.

If you decline the "already exists, overwrite?" prompt, it used to just exit.

Now it keeps your config and continues to the chafa check, so you can re-run peektea init any time just to install extras without nuking your setup.

And if chafa isn't installed, it doesn't just print the install command anymore.

It offers to run it:

── Image previews
   chafa not found — it renders images right in the terminal (the `p` preview).
   Install it now? (sudo apt install -y chafa) [Y/n]:

It detects your package manager (apt, dnf, pacman, zypper, apk, brew) and runs the right command. Bare enter means yes.

Installation

The other thing that needed fixing: the only install method was cloning the repo and running make install.

That requires Go, git, and knowing where ~/go/bin is.

Too much friction for a tool that's supposed to just work.

peektea now ships pre-built binaries for Linux and macOS (x86-64 and arm64) on every release.

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

The script detects your OS and architecture, pulls the right binary from the latest release, and installs it to ~/.local/bin or /usr/local/bin whichever is already on your PATH.

With Go:

go install github.com/lovestaco/peektea@latest

peektea version now works correctly regardless of how you installed it.

When installed via go install, the binary reads its own module version from debug.ReadBuildInfo().

When built with make install, the version comes from git describe via ldflags.

Either way:

peektea version
# peektea v0.2.1 (linux/amd64)

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

peektea past the roadmap 👀 sorting and scrollable previews

Athreya aka Maneshwar — Fri, 05 Jun 2026 07:15:43 +0000

Last time I said the list was empty.

That was true.

Then I kept going anyway.

Press s and the list sorts by size. Press it again, newest-modified first.

Previwing something? Press [ and ] and scroll through the preview without leaving the peektea cli.

Sort

The s key cycles through three modes: name → size → modified → name.

The current mode is always visible in the hint bar: s:sorted by name, s:sorted by size, s:sorted by modified.

Under the hood it's a single sort.SliceStable call inside withFilters().

The sort runs on the filtered slice, so it composes with the text filter and the hidden file toggle, same composable approach as before:

sort.SliceStable(filtered, func(i, j int) bool {
    switch m.sortMode {
    case sortSize:
        ii, _ := filtered[i].Info()
        jj, _ := filtered[j].Info()
        return ii.Size() > jj.Size() // largest first
    case sortMod:
        ii, _ := filtered[i].Info()
        jj, _ := filtered[j].Info()
        return ii.ModTime().After(jj.ModTime()) // newest first
    default:
        return strings.ToLower(filtered[i].Name()) < strings.ToLower(filtered[j].Name())
    }
})

SliceStable preserves the relative order of entries that compare equal, which keeps directories grouped sensibly when names or sizes match.

Preview scroll

The preview panel used to show the first N lines of a file and stop there.

Now you can scroll through it with [ (up) and ] (down). Each press moves a quarter of the panel height.

The key insight: instead of limiting what gets loaded to the visible height, the preview now loads up to 500 lines and stores the whole thing.

The rendering step slices out the visible window:

lines := strings.Split(m.previewContent, "\n")
scroll := m.previewScroll
maxScroll := len(lines) - ph
if maxScroll < 0 {
    maxScroll = 0
}
if scroll > maxScroll {
    scroll = maxScroll
}
visible := lines[scroll:]
if len(visible) > ph {
    visible = visible[:ph]
}
body = strings.Join(visible, "\n")

previewScroll resets to zero whenever you move to a new file, so you always start at the top.

Syntax highlighting via bat

While reworking the preview loading, I added a bat check.

bat is a cat clone with syntax highlighting. If it's installed, peektea uses it for text previews:

if _, err := exec.LookPath("bat"); err == nil {
    out, err := exec.Command("bat",
        "--color=always",
        "--style=plain",
        "--line-range", ":500",
        "--terminal-width", fmt.Sprintf("%d", width),
        path,
    ).Output()
    if err == nil {
        return strings.TrimRight(string(out), "\n")
    }
}
// fallback to plain text reader

Same graceful-fallback pattern as chafa. Not installed? Plain text. Installed but fails on a particular file? Plain text. The preview never breaks.

Scrollbars

Both panels now have scrollbars.

When the preview has more content than fits on screen, a thin │ track with a ┃ thumb appears on the right edge of the preview.

Same thing in the file list when there are more entries than the terminal can show.

A single function handles both:

func buildScrollbar(total, visible, scroll int) []string {
    chars := make([]string, visible)
    track := scrollTrackStyle.Render("│")
    thumb := scrollThumbStyle.Render("┃")
    if total <= visible {
        for i := range chars {
            chars[i] = track
        }
        return chars
    }
    thumbSize := visible * visible / total
    if thumbSize < 1 {
        thumbSize = 1
    }
    thumbPos := scroll * (visible - thumbSize) / (total - visible)
    for i := range chars {
        if i >= thumbPos && i < thumbPos+thumbSize {
            chars[i] = thumb
        } else {
            chars[i] = track
        }
    }
    return chars
}

It returns a slice of styled characters, one per visible row that get appended to each rendered line.

The thumb size scales proportionally: if half the content is visible, the thumb fills half the track.

lovestaco / peektea

Peek First. Open Later. A TUI file browser built with bubble tea

A minimal terminal file browser built with Bubble Tea.

Peek through your filesystem with arrow keys (or vim keys), then pour each file straight into the app you've configured for it.

Demo

A quick peek before you steep:

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

Download a binary (no Go required) — grab the latest release for your platform from the releases page:

Platform	File
Linux x86-64	`peektea_linux_amd64.tar.gz`
Linux arm64	`peektealinux_arm64.tar.gz`
macOS x86-64	`peekteadarwin_amd64.tar.gz`
macOS Apple Silicon	`peektea_darwin_arm64.tar.gz`

Extract and put the peektea binary anywhere on your $PATH.

Install with Go:

go install github.com/lovestaco/peektea@latest

Build from source:

git clone https://github.com/lovestaco/peektea
cd peektea
make install

make install puts the binary in ~/go/bin and figures out $PATH for you:

Already reachable — done, nothing to do.
~/.local/bin is on your PATH — symlinks the binary there, works immediately in the current shell.
Neither — appends ~/go/bin to your .bashrc…

View on GitHub

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

peektea narrows its gaze 👀 filter-as-you-type and hidden files

Athreya aka Maneshwar — Thu, 04 Jun 2026 17:22:56 +0000

Last time I ended with two items left on the list.

Both ship today.

Press / and start typing, the list narrows instantly.

Press . and dotfiles appear.

Press it again and they vanish.

lovestaco / peektea

Peek First. Open Later. A TUI file browser built with bubble tea

A minimal terminal file browser built with Bubble Tea.

Peek through your filesystem with arrow keys (or vim keys), then pour each file straight into the app you've configured for it.

Demo

A quick peek before you steep:

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

Download a binary (no Go required) — grab the latest release for your platform from the releases page:

Platform	File
Linux x86-64	`peektea_*_linux_amd64.tar.gz`
Linux arm64	`peektea_*_linux_arm64.tar.gz`
macOS x86-64	`peektea_*_darwin_amd64.tar.gz`
macOS Apple Silicon	`peektea_*_darwin_arm64.tar.gz`

Extract and put the peektea binary anywhere on your $PATH.

Install with Go:

go install github.com/lovestaco/peektea@latest

Build from source:

git clone https://github.com/lovestaco/peektea
cd peektea
make install

make install puts the binary in ~/go/bin and figures out $PATH for you:

Already reachable — done, nothing to do.
~/.local/bin is on your PATH — symlinks the binary there, works immediately in the current shell.
Neither — appends ~/go/bin to your .bashrc…

View on GitHub

Filter as you type

The / key enters filter mode.

A text input appears at the bottom of the panel right above the hint bar, like vim's command line.

Type anything and only matching entries stay visible.

Press esc to clear it.

The component doing the work is textinput from charmbracelet/bubbles, a library of ready-made Bubble Tea components.

Wiring it into the model is straightforward:

type model struct {
    // ...
    filterInput textinput.Model
    filtering   bool
}

When / is pressed, focus the input and return textinput.Blink, that's the command that starts the cursor blinking animation:

case "/":
    m.filtering = true
    m.filterInput.Focus()
    return m, textinput.Blink

While filtering, most keystrokes go straight to the textinput's own Update.

Navigation keys (↑↓) are intercepted first so you can still move the cursor while typing:

if m.filtering {
    switch msg.String() {
    case "up", "k":
        if m.cursor > 0 { m.cursor-- }
    case "down", "j":
        if m.cursor < len(m.entries)-1 { m.cursor++ }
    case "esc":
        m.filtering = false
        m.filterInput.Blur()
        m.filterInput.SetValue("")
        m = m.withFilters()
    default:
        var tiCmd tea.Cmd
        m.filterInput, tiCmd = m.filterInput.Update(msg)
        m = m.withFilters()
        return m, tiCmd
    }
}

The tiCmd returned by m.filterInput.Update carries the next blink tick.

You have to pass it back out of Update, drop it and the cursor freezes.

Composable filters with withFilters()

The model now stores two entry slices: allEntries (everything os.ReadDir returned) and entries (what's visible after filters).

Every filter change calls withFilters() to recompute:

func (m model) withFilters() model {
    q := strings.ToLower(m.filterInput.Value())
    var filtered []os.DirEntry
    for _, e := range m.allEntries {
        if !m.showHidden && strings.HasPrefix(e.Name(), ".") {
            continue
        }
        if q != "" && !strings.Contains(strings.ToLower(e.Name()), q) {
            continue
        }
        filtered = append(filtered, e)
    }
    m.entries = filtered
    if m.cursor >= len(m.entries) {
        m.cursor = max(0, len(m.entries)-1)
    }
    return m
}

Hidden toggle and text filter compose naturally, you can filter by name with dotfiles visible or hidden simultaneously.

Adding a third filter later means touching one function.

withFilters returns a new model value rather than mutating in place, which fits cleanly with Bubble Tea's immutable-update pattern.

Hidden file toggle

The . key flips showHidden and calls withFilters():

case ".":
    m.showHidden = !m.showHidden
    m = m.withFilters()
    needPreview = true

The hint bar reflects the current state so you always know where you are:

. show hidden   ← dotfiles hidden
. hide hidden   ← dotfiles visible

Navigating into a directory clears the filter, the search you ran in one folder doesn't carry over to its children.

Makes the behaviour predictable without any extra state to manage.

The vim-style bottom bar

The filter input sits at the bottom of the panel, one line above the hint bar.

That's the slot vim uses for its command line, /pattern, :w, :q so it feels immediately familiar.

When filtering is active the text input renders there instead of the hint.

When you press enter to confirm and leave filter mode, the active filter stays visible:

/main  esc to clear
↑/↓  →/enter  o open  / filter  . hide hidden  p preview  ←/h  q

The hint never disappears, even in filter mode it's always one line below.

The layout calculates how many rows the file list consumed and pads blank lines to push both the filter bar and the hint bar to the very bottom of the terminal.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

peektea opens a second eye 👀 side-by-side file previews

Athreya aka Maneshwar — Tue, 02 Jun 2026 19:31:31 +0000

Last time, I ended with a "what's next" list.

At the top of it:

Today both of those ship.

Press p. A preview panel opens on the right. Press p again. It closes.

That's it. That's the whole feature from the outside.

The inside is more interesting.

lovestaco / peektea

Peek First. Open Later. A TUI file browser built with bubble tea

A minimal terminal file browser built with Bubble Tea.

Peek through your filesystem with arrow keys (or vim keys), then pour each file straight into the app you've configured for it.

Demo

A quick peek before you steep:

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/lovestaco/peektea/master/scripts/install.sh | sh

Download a binary (no Go required) — grab the latest release for your platform from the releases page:

Platform	File
Linux x86-64	`peektea_*_linux_amd64.tar.gz`
Linux arm64	`peektea_*_linux_arm64.tar.gz`
macOS x86-64	`peektea_*_darwin_amd64.tar.gz`
macOS Apple Silicon	`peektea_*_darwin_arm64.tar.gz`

Extract and put the peektea binary anywhere on your $PATH.

Install with Go:

go install github.com/lovestaco/peektea@latest

Build from source:

git clone https://github.com/lovestaco/peektea
cd peektea
make install

make install puts the binary in ~/go/bin and figures out $PATH for you:

Already reachable — done, nothing to do.
~/.local/bin is on your PATH — symlinks the binary there, works immediately in the current shell.
Neither — appends ~/go/bin to your .bashrc…

View on GitHub

The preview panel

peektea now renders in two columns when preview is on.

Left: the file browser. Right: whatever's under the cursor.

It handles four cases:

Text files: first N lines, tab-expanded, truncated to panel width
Images: rendered inline via chafa
Directories: lists the contents with the same dir/file styling as the browser
Binary files: a [binary file] notice instead of garbage

The preview updates as you navigate.

Move the cursor, a new preview loads.

Navigate into a directory, it previews the new selection.

Async loading with tea.Cmd

The preview can't block the TUI, reading a large file or running chafa takes time.

In Bubble Tea, anything that takes time is a tea.Cmd: a function that runs off the main loop and returns a message when it's done.

type previewMsg struct{ content string }

func loadPreview(path string, entry os.DirEntry, width, height int) tea.Cmd {
    return func() tea.Msg {
        if entry.IsDir() {
            return previewMsg{content: previewDir(path, width, height)}
        }
        if isImageExt(entry.Name()) {
            return previewMsg{content: previewImage(path, width, height)}
        }
        return previewMsg{content: previewText(path, width, height)}
    }
}

The model sets previewLoading = true and fires the command.

The panel shows loading….

When the goroutine finishes, previewMsg comes back through Update and the panel renders the result.

The TUI stays responsive the whole time, you can keep navigating while a slow preview loads.

Image previews via chafa

chafa is a terminal image viewer that converts images into coloured Unicode blocks.

It respects --size WxH so the output fits exactly inside the preview panel.

func previewImage(path string, width, height int) string {
    if _, err := exec.LookPath("chafa"); err != nil {
        return "[image — install chafa for inline preview]"
    }
    out, err := exec.Command("chafa",
        "--size", fmt.Sprintf("%dx%d", width, height),
        path,
    ).Output()
    if err != nil {
        return fmt.Sprintf("[image preview failed: %v]", err)
    }
    return strings.TrimRight(string(out), "\n")
}

If chafa isn't installed, the panel tells you so. No crash, no silent blank.

peektea init now checks for chafa at the end of setup and prints the install command for your distro if it's missing.

Binary detection

Opening a binary file as text gives you noise.

So before reading, peektea checks the first 512 bytes for null bytes, that's the standard heuristic used by git diff and most editors.

func isBinary(path string) bool {
    f, err := os.Open(path)
    if err != nil {
        return false
    }
    defer f.Close()
    buf := make([]byte, 512)
    n, _ := f.Read(buf)
    for _, b := range buf[:n] {
        if b == 0 {
            return true
        }
    }
    return false
}

If it's binary, the preview says [binary file] and moves on.

Terminal size and the adaptive left panel

To split the screen correctly, peektea needs to know how big it is.

Bubble Tea sends a tea.WindowSizeMsg whenever the terminal is resized.

The model stores width and height and uses them to calculate panel dimensions on every render.

case tea.WindowSizeMsg:
    m.width = msg.Width
    m.height = msg.Height

The left panel width isn't fixed, it starts at a minimum of 50 chars and then expands to fit the longest filename in the current directory:

func (m model) leftWidth() int {
    const minWidth = 50
    w := minWidth
    for _, e := range m.entries {
        nameW := 2 + len([]rune(e.Name()))
        if e.IsDir() {
            nameW++
        }
        if nameW > w {
            w = nameW
        }
    }
    // Always leave at least 30 chars for the preview panel.
    if max := m.width - 32; w > max {
        w = max
    }
    return w
}

Navigate into a directory with long filenames and the left panel widens to accommodate. Navigate out and it shrinks back.

The preview panel takes whatever's left.

The hint bar

One last small thing: the hint bar at the bottom of the left panel is pinned to the very last row of the terminal, not floating just below the last entry.

The panel counts how many lines the file list consumed and fills the gap with blank lines so the hint always sits at the floor.

Feels more like a proper pane and less like text that happened to end there.

What's next

The list is getting shorter:

~~Image previews inline~~ ✓
~~Split-pane file preview~~ ✓
Filter as you type — Bubble Tea's textinput component from bubbles is sitting there waiting
Hidden file toggle — show/hide dotfiles

The model grows, Update handles new keys, View renders the new state.

That's still the whole pattern. It still scales. The puns still never run dry.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

peektea v2: yesterday it peeked, today it actually opens things

Athreya aka Maneshwar — Mon, 01 Jun 2026 21:12:39 +0000

Yesterday I shipped peektea, a tiny terminal file browser in Go.

It browsed.

It peeked.

And then it just... stood there, staring at your files, unable to do anything with them. All peek, no pour.

Like a golden retriever that fetches the ball and won't drop it.

Today that changes. peektea can now:

open files in your configured editor, image viewer, file manager, whatever you set up
detect your installed software and walk you through setup with peektea init
tell you what it can do with peektea -h
uninstall itself cleanly with peektea uninstall (and ask nicely if you want your config deleted too)

Here's the whole brew in action:

The config problem (or: how do you take your tea?)

The moment you add "open files" to a file browser, you hit a question: open them how?

.md files want vim.

.png wants an image viewer.

A directory wants a file manager.

And everyone's machine is different, you might have thunar, I might have nautilus, someone else is running dolphin and judging us both.

So peektea reads ~/.peektea.toml.

The keys are derived straight from the file extension:

file.md        → _md_config
archive.tar.gz → _tar_gz_config
hello.xd.dd    → _xd_dd_config
directory      → _dir_config

Dots become underscores, wrapped with _ and _config. The whole config is one flat file:

Unknown extension?

Falls through to _default_config.

Completely missing key?

Falls through to vim. The bag never comes up empty.

You can configure literally any extension, including made-up ones like _xd_dd_config for hello.xd.dd.

The lookup is fully generalised. No extension is too obscure to brew.

peektea init: it takes a peek at your system first

Writing that config by hand is annoying.

So peektea init does it for you.

It scans your $PATH, finds what's actually installed, and asks you to pick:

If there's only one option for a category it auto-selects it and moves on.

If there are multiple, you get a picker — arrow keys or just type the number and it jumps immediately. Pick your poison, or your potion.

The whole wizard is a Bubble Tea program running inside a CLI command. (Yes, the puns write themselves here.)

That last part is the interesting bit.

The picker isn't a plain stdin readline, it's a full tea.Model:

type pickerModel struct {
    options []string
    cursor  int
}

func (m pickerModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "up", "k":
            if m.cursor > 0 { m.cursor-- }
        case "down", "j":
            if m.cursor < len(m.options)-1 { m.cursor++ }
        case "enter", " ":
            return m, tea.Quit
        default:
            // type a number → jump and confirm immediately
            if n, err := strconv.Atoi(msg.String()); err == nil && n >= 1 && n <= len(m.options) {
                m.cursor = n - 1
                return m, tea.Quit
            }
        }
    }
    return m, nil
}

tea.NewProgram(pickerModel{options: found}).Run() — that's the whole pot.

You get a full keyboard-driven selector inside what looks like a plain terminal prompt.

Bubble Tea handles all the rendering and input, you just describe the model and let it steep.

Opening files: the terminal vs GUI problem

The o key opens whatever's under the cursor. One keystroke and you're peeking inside.

Simple enough, except there's a catch in the kettle.

For terminal editors like vim, you want to hand the terminal over completely.

Vim needs raw input, it needs to own the screen - the whole table, not just a saucer.

The right Bubble Tea API for this is tea.ExecProcess:

cmd := exec.Command(prog, path)
return m, tea.ExecProcess(cmd, func(err error) tea.Msg {
    return openResultMsg{err: err}
})

tea.ExecProcess suspends the Bubble Tea event loop, gives the child process the full terminal, and resumes peektea when you quit.

It's the same trick that lets you run vim from inside ranger or lf.

For GUI apps like nautilus or feh, you do the opposite, launch them in the background and keep the TUI brewing:

cmd := exec.Command(prog, path)
cmd.Start()
go cmd.Wait() // reap the child so it doesn't become a zombie

But how does peektea know which is which?

It keeps a set of known terminal programs like vim, nvim, nano, micro, helix, etc. and anything not in that set gets backgrounded.

You can extend it in your config:

terminal_programs = ["vim", "nvim", "nano", "hx"]

peektea -h

Every proper CLI tool deserves a -h. Consider it the menu before you order.

Here's what it looks like now:

And yes, peektea uninstall exists.

It finds the binary via os.Executable(), tells you exactly what it's about to delete, asks for confirmation, and then asks separately if you want the config gone too.

No silent nuke. No tea spilled without warning.

What's next

The original dream was ncdu-style navigation with inline image previews in the terminal. A proper sneak peek, right in the pane.

That's still where this is headed:

Image previews inline — render images in the terminal via Kitty/iTerm protocols or chafa
Split-pane file preview — selected file content on the right, so you can peek without leaving
Filter as you type — Bubble Tea ships a textinput component in bubbles for exactly this
Hidden file toggle — show/hide dotfiles for the leaves that like to lurk

The model grows, Update handles new keys, View renders the new state.

That's the whole Bubble Tea pattern. It scales surprisingly cleanly and the puns never run dry.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs — without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

peektea: brewing a terminal file browser with Bubble Tea

Athreya aka Maneshwar — Sun, 31 May 2026 19:00:22 +0000

What I actually want is an ncdu-style file browser fully keyboard-driven, where I can hop through directories and open files straight into Nautilus, vim, Nemo, whatever, even preview images right in the terminal.

No mouse, no leaving the keyboard.

But that's a big pot to brew.

So I started small and used it as an excuse to learn Bubble Tea, Charmbracelet's Go TUI framework.

The result is peektea: a minimal version that, for now, just browses.

Run it, arrow your way through directories, pop back up to the parent.

That's the whole cup of tea so far.

~140 lines of Go: the opening-files-and-previewing-images part is where it's headed next.

So what's Bubble Tea?

Bubble Tea is a Go framework for building terminal UIs, built on the Elm Architecture.

Which is a fancy way of saying your entire app boils down to three things:

Model — the state of your program
Update — a function that takes events and returns a new model
View — a function that renders the model to a string

No mutation, no spilled state.

Update and View are pure functions.

The framework handles the event loop, terminal I/O, and all the redrawing so you don't have to.

You just describe what things should look like and it does the dishes.

The model

type model struct {
    dir     string
    entries []os.DirEntry
    cursor  int
    err     error
}

That's the entire state of peektea.

The current directory, what's in it, where the cursor sits, and whether something went sideways.

When you navigate into a new directory you don't mutate anything in place, Update hands back a fresh model with the new values.

The update loop (where the tea gets stirred)

Every keypress shows up as a tea.KeyMsg.

You pattern-match on it and return the next model:

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "right", "l", "enter":
            if len(m.entries) > 0 && m.entries[m.cursor].IsDir() {
                next := filepath.Join(m.dir, m.entries[m.cursor].Name())
                entries, err := os.ReadDir(next)
                if err == nil {
                    m.dir = next
                    m.entries = entries
                    m.cursor = 0
                }
            }
        // ...
        }
    }
    return m, nil
}

That second return value, tea.Cmd, is a function that runs asynchronously and produces the next message.

Here Update is fully synchronous, so we just return nil.

But the moment you want to fetch data or read files in the background, Cmd is how you do it without blocking the UI.

Think of it as putting the kettle on and getting pinged when it's ready, instead of standing there watching it.

One small touch worth calling out: when you go back up to the parent directory, the cursor lands right back on the folder you just came out of, instead of snapping to the top.

It's just a little loop over the entries to find the matching name but it makes navigation feel natural instead of jarring.

The view

Rendering is a pure string transformation.

Bubble Tea calls View() after every Update and redraws the terminal for you.

Styling comes from Lipgloss, also from Charmbracelet (they really committed to the tea house aesthetic).

You define styles once at the package level:

var (
    cursorStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("212")).Bold(true)
    dirStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("39"))
    fileStyle   = lipgloss.NewStyle().Foreground(lipgloss.Color("252"))
)

Then call .Render(s) on them anywhere in your view. Directories get a trailing / and a cyan tint, the cursor row gets a background highlight, and the selected entry gets a ▶ so you always know where you are.

Wiring it up

func main() {
    dir, _ := os.Getwd()
    p := tea.NewProgram(newModel(dir), tea.WithAltScreen())
    p.Run()
}

The one line worth highlighting is tea.WithAltScreen().

It flips the terminal into the alternate screen buffer — the same trick vim and htop use.

Your TUI takes over the whole terminal, and when you quit, your shell session comes back clean like nothing happened.

Without it, your UI just dumps into the scrollback like any other output.

Nobody wants tea stains on their terminal history.

What I'd steep next

This is where the ncdu-style dream actually starts brewing:

Open files in your editor/app — enter on a file shells out to vim, or hands it to Nautilus/Nemo/xdg-open based on type
Image previews in the terminal — render images inline via Kitty/iTerm protocols or chafa
File previews — split the screen, show the selected file's content on the right
Filtering — type to narrow the list (Bubble Tea ships a textinput in bubbles)
Hidden file toggle — h to show/hide dotfiles

All of it stays keyboard-driven no reaching for the mouse. As they land, they'll be in the repo.

The nice thing is the framework makes each one refreshingly easy: you extend the model and handle new keys in Update.

That's the whole pattern.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.*

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

You Have a Free AI Model Sitting in Chrome Right Now

Athreya aka Maneshwar — Sat, 30 May 2026 18:47:06 +0000

You might not have noticed, but Chrome quietly started shipping a local AI model called Gemini Nano bundled right into the browser.

No API keys. No cloud round-trips. No per-token cost. It just runs on your machine.

The interface to talk to it is called the Prompt API, and it landed in Chrome 138.

I spent some time going through the full API surface and built a playground that lets you experiment with every feature session management, streaming, structured output, multimodal input, response prefixing, and more in one page.

This post walks you through all of it.

Why does this matter?

On-device AI flips the usual tradeoffs:

Free at runtime — the model runs on the user's hardware, not your servers
Private by default — no data leaves the device once the model is downloaded
Works offline — after the initial download, no network required
Low latency — no round-trip to a data centre

The catch is that Gemini Nano is a small model.

It's great for classification, summarization, Q&A on focused content, and structured extraction.

It won't replace GPT-4 for complex reasoning.

Think of it as a smart, free, always-available layer you can add on top of your existing product.

Enabling the API

The Prompt API isn't on by default in all Chrome builds. Enable two flags:

Step 1 — Go to chrome://flags/#optimization-guide-on-device-model and set it to Enabled BypassPerfRequirement.

Step 2 — Go to chrome://flags/#prompt-api-for-gemini-nano and enable both the base API and the multimodal option.

Relaunch Chrome.

Then visit chrome://on-device-internals to check the model download status. First use will trigger a download — Gemini Nano is a few gigabytes.

The Playground

I put together a single-file HTML playground that covers the entire API surface.

Clone it and open playground.html directly in Chrome no build step, no server.

git clone https://github.com/lovestaco/gemini-brow

Then open playground.html in Chrome 138+.

Session Setup and Context Window

Everything starts with a session.

You create one with LanguageModel.create(), optionally passing a system prompt and expected input/output modalities.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' }
  ],
  expectedInputs:  [{ type: 'text', languages: ['en'] }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});

Always call LanguageModel.availability() with the same options you'll pass to create() before creating a session the model may not support certain modalities on every device.

const avail = await LanguageModel.availability({
  expectedInputs:  [{ type: 'text', languages: ['en'] }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});
// 'available' | 'downloadable' | 'downloading' | 'unavailable'

Each session has a context window a token budget that tracks everything in the conversation.

When it fills up, the oldest prompt/response pairs are dropped (but the system prompt is never dropped).

You can monitor it:

console.log(`${session.contextUsage} / ${session.contextWindow} tokens used`);

session.addEventListener('contextoverflow', () => {
  console.log('Oldest turns are being dropped to make room');
});

The playground shows a live progress bar for context usage, and a warning badge on overflow.

You can also clone a session to fork the conversation at a point in time — the clone is fully independent and won't see future messages sent to the original.

const forkedSession = await session.clone();

And destroy it when you're done to free resources:

session.destroy();

Prompting the Model

Request-based (wait for the full response)

Use prompt() when you want the complete output before rendering:

const result = await session.prompt('Write me a short haiku about coffee.');
console.log(result);

Pass an AbortController signal to add a stop button:

const controller = new AbortController();
stopBtn.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

Streaming (show output as it generates)

Use promptStreaming() for longer responses.

It returns a ReadableStream where each chunk is a delta the new tokens only.

Accumulate them yourself:

const stream = session.promptStreaming('Explain how a browser renders a web page.');

let fullText = '';
for await (const chunk of stream) {
  fullText += chunk;
  outputEl.textContent = fullText;
}

This is the right pattern, don't replace the display with each raw chunk or you'll get flickering (each chunk is only a word or two).

Append Messages

session.append() lets you pre-load context into the session without triggering a response. This is useful when you want the model to process heavy inputs (like images) while the user is still typing their question.

// Pre-load context
await session.append([{
  role: 'user',
  content: 'Here is the document you will answer questions about: ...'
}]);

// Later, ask the question
const answer = await session.prompt('What are the key takeaways?');

The promise from append() resolves once the input has been processed and is ready in the session's context.

Image Input (Multimodal)

If your device has a GPU with more than 4 GB VRAM, the model can process images.

Image input needs its own session you must declare { type: 'image' } in expectedInputs at creation time, and check availability separately since not all devices support it.

const imageAvail = await LanguageModel.availability({
  expectedInputs:  [{ type: 'text', languages: ['en'] }, { type: 'image' }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});

if (imageAvail === 'unavailable') {
  // GPU requirement not met
  return;
}

const imageSession = await LanguageModel.create({
  expectedInputs:  [{ type: 'text', languages: ['en'] }, { type: 'image' }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});

const imageBlob = await fetch('photo.jpg').then(r => r.blob());

const result = await imageSession.prompt([{
  role: 'user',
  content: [
    { type: 'text',  value: 'What is in this image?' },
    { type: 'image', value: imageBlob },
  ],
}]);

The API accepts Blob, HTMLImageElement, HTMLCanvasElement, ImageBitmap, ImageData, and more. In the playground, you can upload any image file and ask the model about it.

Response Prefix — Force an Output Format

One of my favourite features.

You can prefill the start of the assistant's response by passing an assistant-role message with prefix: true.

The model is forced to continue from that prefix.

This is a clean way to lock in an output format without relying on instruction-following:

// Force the model to start its response with ```
{% endraw %}
toml
const result = await session.prompt([
  {
    role: 'user',
    content: 'Create a character sheet for a gnome barbarian.',
  },
  {
    role: 'assistant',
    content: '
{% raw %}
```toml\n',
    prefix: true,
  },
]);
// result continues from the prefix: ```
{% endraw %}
toml\n[character]\nname = "...
{% raw %}

In the playground, you can set any prefix string and watch the model continue from exactly that point.

Boolean Classification

Need a fast yes/no answer? Pass { type: 'boolean' } as the responseConstraint and you'll always get back a raw true or false — no parsing, no prompt engineering around output format:


js
const raw = await session.prompt(
  `Is this post about pottery?\n\n"${text}"`,
  { responseConstraint: { type: 'boolean' } }
);

const result = JSON.parse(raw); // true or false

This is great for content moderation, topic detection, or gating features based on page content.

Structured Output with JSON Schema

The full power of responseConstraint is a complete JSON Schema.

The model is constrained to produce valid JSON that matches your schema no hallucinated keys, no wrong types.


js
const schema = {
  type: 'object',
  properties: {
    sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
    score:     { type: 'number', minimum: 0, maximum: 10 },
    summary:   { type: 'string' },
  },
  required: ['sentiment', 'score', 'summary'],
};

const raw = await session.prompt(
  `Analyze the sentiment of this review:\n\n"${reviewText}"`,
  { responseConstraint: schema }
);

const data = JSON.parse(raw);
// { sentiment: 'positive', score: 8.5, summary: '...' }

Putting it all together

Here's how these features combine in a real use case.

Say you're building a Chrome Extension that summarises product reviews on any e-commerce page:


js
// 1. Check availability
const avail = await LanguageModel.availability({
  expectedInputs:  [{ type: 'text', languages: ['en'] }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});
if (avail === 'unavailable') return;

// 2. Create a session with context
const session = await LanguageModel.create({
  initialPrompts: [{
    role: 'system',
    content: 'You analyse product reviews and extract structured insights.',
  }],
  expectedInputs:  [{ type: 'text', languages: ['en'] }],
  expectedOutputs: [{ type: 'text', languages: ['en'] }],
});

// 3. Pre-load the reviews while user looks at the page
await session.append([{
  role: 'user',
  content: `Here are the reviews:\n\n${scrapedReviews}`,
}]);

// 4. Get structured output
const schema = {
  type: 'object',
  properties: {
    verdict:  { type: 'string', enum: ['buy', 'skip', 'depends'] },
    pros:     { type: 'array', items: { type: 'string' } },
    cons:     { type: 'array', items: { type: 'string' } },
    summary:  { type: 'string' },
  },
  required: ['verdict', 'pros', 'cons', 'summary'],
};

const result = JSON.parse(
  await session.prompt('Summarise these reviews.', { responseConstraint: schema })
);

Zero API cost.

Runs entirely on the user's machine.

Works offline after first load.

Try the playground

The full playground is one HTML file no dependencies, no build step:

github.com/lovestaco/gemini-brow

Clone it, open playground.html in Chrome 138+, enable the flags above, and every feature in this post is wired up and ready to experiment with.

The Prompt API is still evolving, language support is limited (en, ja, es for now), mobile isn't supported yet, and the model is small.

But the fundamentals are solid and the use cases where it shines classification, summarization, extraction, Q&A on focused content are genuinely useful without touching your server budget.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.*

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub

What actually happens when you run `go run main.go`

Athreya aka Maneshwar — Fri, 29 May 2026 10:11:16 +0000

# What actually happens when you run go run main.go

You've typed it hundreds of times.

The program runs.

But what's actually going on between pressing Enter and your first fmt.Println?

The full picture

Step 0: You press Enter

Your shell finds go in $PATH, usually /usr/local/go/bin/go or wherever your version manager (like asdf or goenv) installed it.

Unlike npm run dev, there's no separate launcher script.

The go binary is the single front-end to your whole toolchain build driver, dependency manager, test runner, and more.

Step 1: The `go` command parses your arguments

go run is one of many subcommands (go build, go test, go mod tidy...).

The go binary dispatches accordingly.

For go run main.go it does essentially two things: build and then exec the result.

One thing worth clearing up: the go command itself doesn't compile anything.

It's a driver that orchestrates the build, invoking the individual toolchain programs compile, asm, link, pack that live in $GOROOT/pkg/tool/$GOOS_$GOARCH/, each as a separate process.

You can watch the whole sequence with go build -x, which prints every tool invocation it makes.

lovestaco@i3nux-mint:~/pers/blogs/go-rate-limiters$ go build -x 01_token_bucket_basic.go
WORK=/tmp/go-build1951611363
mkdir -p $WORK/b001/
cat >/tmp/go-build1951611363/b001/importcfg << 'EOF' # internal
# import config
packagefile context=/home/lovestaco/.cache/go-build/15/1575351e64b96edf357d10ac88f3cab30fcb1cfa9a191331bcad6190a73853f4-d
packagefile fmt=/home/lovestaco/.cache/go-build/51/516c0f36e371fc103e5e31bffc64e8899c256a1d9278377baeaee3c3d67d5990-d
packagefile golang.org/x/time/rate=/home/lovestaco/.cache/go-build/d5/d5dd928826b919bdb04e4142718ffda25ffa97a1f788e61444596c150f6df76a-d
packagefile time=/home/lovestaco/.cache/go-build/2b/2ba963660e1b7abf46deaef03614f8cce1f6230e971041e2f60a9b8b5bca5326-d
packagefile runtime=/home/lovestaco/.cache/go-build/f0/f09fa4ced4d67a86c477e2daecfaf39fccd7d0cb936478c5d73427221189029e-d
EOF
cd /home/lovestaco/pers/blogs/go-rate-limiters
/usr/local/go/pkg/tool/linux_amd64/compile -o $WORK/b001/_pkg_.a -trimpath "$WORK/b001=>" -p main -lang=go1.24 -complete -buildid cR1ay72gpouW8Dj1wpHA/cR1ay72gpouW8Dj1wpHA -goversion go1.24.4 -c=4 -nolocalimports -importcfg $WORK/b001/importcfg -pack ./01_token_bucket_basic.go
/usr/local/go/pkg/tool/linux_amd64/buildid -w $WORK/b001/_pkg_.a # internal
cp $WORK/b001/_pkg_.a /home/lovestaco/.cache/go-build/7f/7fa4c76fda90e3f91bee04d9326171d548b473efc9a5a49059e5650d52c7ed40-d # internal
cat >/tmp/go-build1951611363/b001/importcfg.link << 'EOF' # internal
packagefile command-line-arguments=/tmp/go-build1951611363/b001/_pkg_.a
packagefile context=/home/lovestaco/.cache/go-build/15/1575351e64b96edf357d10ac88f3cab30fcb1cfa9a191331bcad6190a73853f4-d
packagefile internal/oserror=/home/lovestaco/.cache/go-build/38/38a0285b4078334a8d1c6a928e079b3ee65331a955fae62da547452857e18da5-d
packagefile path=/home/lovestaco/.cache/go-build/24/24092a25546a3b8c3771592daca75c8fb2d416c84952f466cc92fcb99959688c-d
modinfo "0w\xaf\f\x92t\b\x02A\xe1\xc1\a\xe6\xd6\x18\xe6path\tcommand-line-arguments\ndep\tgolang.org/x/time\tv0.5.0\th1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=\nbuild\t-buildmode=exe\nbuild\t-compiler=gc\nbuild\tDefaultGODEBUG=asynctimerchan=1,gotestjsonbuildtext=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,multipathtcp=0,randseednop=0,rsa1024min=0,tls10server=1,tls3des=1,tlsmlkem=0,tlsrsakex=1,tlsunsafeekm=1,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1,x509rsacrt=0,x509usepolicies=0\nbuild\tCGO_ENABLED=1\nbuild\tCGO_CFLAGS=\nbuild\tCGO_CPPFLAGS=\nbuild\tCGO_CXXFLAGS=\nbuild\tCGO_LDFLAGS=\nbuild\tGOARCH=amd64\nbuild\tGOOS=linux\nbuild\tGOAMD64=v1\n\xf92C1\x86\x18 r\x00\x82B\x10A\x16\xd8\xf2"
EOF
mkdir -p $WORK/b001/exe/
cd .
GOROOT='/usr/local/go' /usr/local/go/pkg/tool/linux_amd64/link -o $WORK/b001/exe/a.out -importcfg $WORK/b001/importcfg.link -X=runtime.godebugDefault=asynctimerchan=1,gotestjsonbuildtext=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,multipathtcp=0,randseednop=0,rsa1024min=0,tls10server=1,tls3des=1,tlsmlkem=0,tlsrsakex=1,tlsunsafeekm=1,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1,x509rsacrt=0,x509usepolicies=0 -buildmode=exe -buildid=wvZLsb-w6x3yjmaurfAY/cR1ay72gpouW8Dj1wpHA/ipt4_u-REyDFqYjqF2h5/wvZLsb-w6x3yjmaurfAY -extld=gcc $WORK/b001/_pkg_.a
/usr/local/go/pkg/tool/linux_amd64/buildid -w $WORK/b001/exe/a.out # internal
cp $WORK/b001/exe/a.out 01_token_bucket_basic
rm -rf $WORK/b001/

Step 2: Package loading — reading the import graph

Before a single line is compiled, Go needs to know what it's compiling.

It reads your go.mod to establish the module root and dependency versions.

Then it walks your imports recursively, building a directed acyclic graph of packages.

Standard library package sources (fmt, os, net/http) live in $GOROOT/src.

Your own packages are resolved relative to the module root.

Third-party packages come from the module cache at $GOPATH/pkg/mod.

This graph is the foundation everything else depends on.

Step 3: The compilation pipeline

This is where Go earns its reputation for speed.

Each package in the import graph goes through this pipeline independently:

Lexer → turns raw source characters into a flat stream of tokens (func, main, (, ), ...).

Parser → builds an Abstract Syntax Tree from those tokens.
Go's parser is hand-written (not generated) and intentionally simple, the language grammar is small enough to fit in your head.

Type checker → walks the AST and verifies every expression is well-typed.
This is also where Go resolves identifiers and builds its scope chain.

IR & middle-end optimisations → the typed AST is converted into the compiler's intermediate representation (IR), and this is where the big high-level optimisations run: function inlining, devirtualisation, and escape analysis (which decides whether a variable lives on the stack or escapes to the heap).

SSA → the optimised IR is then lowered into Static Single Assignment form, a lower-level representation where the compiler runs passes like dead-code elimination and common-subexpression elimination, followed by the machine-specific lowering that prepares for codegen.

Codegen → SSA is turned into native machine code, written out as a per-package object file and packed into a .a archive that the linker later consumes.

Two things make this fast:

Packages compile in parallel. If A imports B and C, Go compiles B and C concurrently, then A once they're done. On an 8-core machine this is real parallelism.
$GOCACHE. Go caches compiled packages (on Linux, in ~/.cache/go/build; macOS uses ~/Library/Caches/go-build), keyed by a hash of the source + build flags. Change nothing? Every package is a cache hit. Only the packages you touched recompile.

Step 4: The linker

Once all .a files exist, the linker combines them into a single self-contained binary.

For go run, this binary lands in a temporary work directory (something like $TMPDIR/go-buildXXXXXXXX/) rather than your working directory, and is then exec'd.

Go's linker includes the entire Go runtime in every binary.

There's no shared runtime DLL to worry about.

This is why pure-Go binaries are statically linked by default and why you can scp one to any compatible machine and it just runs, no dependency installation step. (The caveat: programs that use cgo, or certain stdlib packages like net and os/user that can pull in the system C resolver, may link dynamically against libc unless you build with CGO_ENABLED=0.)

Step 5: The runtime initializes — before your code runs

Here's the part most Go developers never think about. When the OS loads your binary, the first thing that runs is not main().

It's the Go runtime bootstrap, written in assembly (rt0_amd64.s or equivalent).

Stack and TLS setup — the runtime allocates the initial goroutine stack (starts at 8KB, grows dynamically) and sets up thread-local storage so each OS thread knows which goroutine it's running.

The M:P:G scheduler — Go's concurrency model involves three abstractions. G (goroutines) are lightweight green threads.

M (machine) are OS threads that actually run goroutines.

P (processor) is a logical processor with a run queue; there are GOMAXPROCS of them. That defaults to the number of logical CPUs — though since Go 1.25, on Linux, if the process runs under a cgroup CPU limit (as in most containers) that's lower than the core count, GOMAXPROCS defaults to that limit instead, and the runtime re-checks it periodically.

All this infrastructure spins up before main() is reached.

Garbage collector — the GC's data structures are initialized.

init() functions — every package can define init() functions.

The runtime calls them in dependency order: a package's init() runs only after all of its imports' init() functions have completed.

Your main package's init() is last.

Only then does the runtime call main.main().

Step 6: `main()` runs

Your code finally executes, on the main goroutine.

One subtle point: if main() returns, the process exits — even if other goroutines are still running.

The main goroutine is special; it doesn't go back to a pool.

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.*

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

⭐ Star it on GitHub:

HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit

git-lrc

Free, Micro AI Code Reviews That Run on Commit

AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

git-lrc-intro-60s.mp4

Why

🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
…

View on GitHub