Developer tools
-
Autopilot for Your Docs: A Look at LangChain's OpenWiki
Writing documentation for a repo is the chore nobody volunteers for. Keeping it current is somehow worse. You refactor one service or change a database schema, and the architecture overview you wrote three months ago is instantly a lie.
So when the LangChain team dropped OpenWiki, I had to take a look. It’s an open-source CLI tool and agent framework that writes and maintains documentation for your codebase automatically. I read through the source rather than running it, so here’s an honest read on the idea, how it works under the hood, and what you’ll run into if you point it at a real repo today.
What Is OpenWiki?
The premise is simple: AI coding assistants are only as good as the context they can reach. Instead of stuffing your prompts full of raw source files, OpenWiki generates a structured, interlinked Markdown wiki inside an
openwiki/directory right in your repo. It’s built to be read by coding assistants like Cursor, Claude Code, or Codex CLI.graph TD Diff[Git Workspace Diff] -->|CLI/CI| CLI[OpenWiki CLI] CLI -->|LangGraph| Agent[Documentation Agent] Agent --> Analyzer{Code Analyzer} Analyzer -->|Incremental Update| Docs[openwiki/ Markdown] Docs -->|Appends Pointer| Config[CLAUDE.md / AGENTS.md]Three things it does that I like:
- Autopilot docs. You don’t hand-write or hand-format anything. The agent inspects your layout and produces overview, architecture, workflow, and API reference pages.
- Incremental git-diff sync. It doesn’t re-read your whole workspace on every commit. It looks at the diff since the last scan and only rewrites the pages those changes touched.
- Prompt hooking. It appends a reference pointer to your
CLAUDE.mdandAGENTS.mdso downstream assistants check the wiki first.
That last one is interesting and is starting to show up in other harness adjacent tools. For this project, it turns the docs into a context layer your agents are told to read.
The LangChain Footprint
This is built by the LangChain team, and it shows in the dependency list.
- Orchestration runs on
@langchain/coreanddeepagents, with a stateful LangGraph engine backed by@langchain/langgraph-checkpoint-sqlitethat stores checkpoints and agent state locally. - The CLI uses
ink, so it renders a clean React-based interface right in the terminal. - Tracing ships with LangSmith support out of the box, which is worth more than it sounds. When you want to know why a particular page got rewritten, or what a run cost you, that audit trail is right there.
If you’re already living in the LangChain ecosystem, none of this will surprise you. If you’re not, it’s a lot of framework to pull in for a docs tool. Fair tradeoff or not depends on how much you value the tracing.
The Catch: Tokens and Rate Limits
It’s still early but here is what I would wathc out for. The first run is expensive.
When you bootstrap OpenWiki on a medium-to-large repo, the agent has to read, analyze, and index everything. Two things happen:
- You’ll hit rate limits. That initial pass will saturate your provider’s API limits fast. Expect a parade of
429 Too Many Requestson any large source tree. - You’ll spend real money. Bootstrapping a large repo can burn through a huge number of tokens in a single run.
If you’re going to try it, configure your
.openwikisettings to exclude the folders that don’t need documenting.node_modules,dist, generated assets, all of it. There’s no reason to spend tokens teaching an agent about your vendored dependencies. If you have access to a high-throughput endpoint or a fast local model through Ollama or LiteLLM, the bootstrap is a lot less painful.The steady state is fine, since the git-diff sync keeps ongoing runs cheap. It’s that first index that hurts.
Should You Use It?
OpenWiki is new and moving fast, which means you should expect config keys and command arguments to shift under you for a while. This is not a set-and-forget tool yet.
But the core idea is interesting. An agent running quietly in a pre-commit hook or CI, keeping your repo’s context layer in sync so your other agents have something accurate to read, is a real quality-of-life upgrade. Docs that maintain themselves have been a fantasy for as long as I’ve been writing code. On a read of the source, this is the most serious attempt I’ve seen at pulling it off.
I haven’t run it yet, just read through the code, and I’m not putting it anywhere just yet. But the idea is right, and I’m watching where this one goes.
Sources
- LangChain OpenWiki repository for setup, commands, and configuration.
- LangChain blog for the launch announcement and design philosophy.
- LangGraph JS docs for the local SQLite checkpointing and state details.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Amnesia-Free Agents: GBrain and the LLM Wiki Idea
Every agent I work with has amnesia.
Open a new terminal session, spin up a subagent, start a fresh chat, and the thing forgets everything. Your project guidelines, your coding style, your database schemas, the meeting where you decided why the schema looks like that. Gone. So you do one of two things: stuff a few thousand tokens into a bloated system prompt, or hand-maintain fragile context files like
CLAUDE.md. I’ve done both. Neither feels good.So when Y Combinator CEO Garry Tan open-sourced GBrain on April 5, 2026, a markdown-first memory layer, I wanted to understand what it does and whether it’s worth the setup.
What GBrain actually is
GBrain is a Postgres-native knowledge brain that acts as a persistent retrieval layer for your coding agents. The interesting part isn’t that it stores stuff, it’s how opinionated it is about the shape of that storage.
Three ideas do the heavy lifting:
- Compiled truth vs. an append-only timeline. Raw daily logs, Slack messages, and emails go in one bucket. The curated “current facts” (contacts, active projects, decisions) live as clean Markdown in another. One is history, the other is truth.
- A self-wiring knowledge graph. It parses your plain Markdown and pulls out relationships (
works_at,invested_in,founded) using local grammars. No LLM API calls to build the map. - The Dream Cycle. An overnight cron job that crawls your daily logs, reconciles contradictions, checks citations, and rebuilds the search index while you sleep.
That last one worth a callout: Memory that maintains itself.
The category error everyone makes
People keep comparing GBrain to runtime agents like OpenClaw or Hermes, and that comparison doesn’t hold up. They’re different layers entirely.
GBrain isn’t an execution engine. It’s closer to a self-writing wiki.
┌────────────────────────────────────────────────┐ │ AGENT RUNTIMES │ │ (OpenClaw, Hermes, Claude Code) │ │ runs code, spawns subagents, hits the shell │ └─────────────────────────┬────────────────────────┘ │ reads & writes via MCP ▼ ┌────────────────────────────────────────────────┐ │ THE LLM WIKI │ │ (GBrain, OpenWiki) │ │ compiles raw history into clean markdown │ └────────────────────────────────────────────────┘The runtime is the hands and eyes. It sandboxes code, runs terminal commands, touches the file system. The wiki is the long-term memory. You wire them together over the Model Context Protocol (MCP), and when the agent needs context, it doesn’t parse your raw email history. It queries the wiki and gets back synthesized, cited facts.
GBrain isn’t the only thing playing this role. OpenWiki, from the LangChain folks, uses the same trick to compile big source repos into navigable markdown. Same pattern, different input.
The payoff: your agent stays lightweight and task-focused, and your knowledge lives in a clean, git-versioned wiki instead of leaking into a system prompt.
What people actually run into
The concept is great. The reality has some sharp edges, and the community forums are honest about them.
It needs babysitting. GBrain moves fast, which means frequent schema updates and migrations. You’ll find yourself running things like
gbrain doctor --remediateto fix database drift. It is not set-it-and-forget-it.Tool sprawl adds up. To feed the Dream Cycle good data, people bolt on voice transcribers, contact enrichers, email scrapers. Most of those are paid SaaS. String enough together and you’ve built yourself a subscription problem.
Setup is a project. A Dockerized Postgres with
pgvector, system keyring wrangling (macOS Keychain or D-Bus), cron schedulers. Budget anywhere from 30 minutes to a lost afternoon.Should you bother?
If you’re juggling complex work across a bunch of codebases, and you want an agent that knows your past architecture decisions and updates its own docs overnight, the GBrain + OpenClaw setup earns its keep. That’s a real moat.
If you just want a lightweight assistant that remembers a few things, you’re better off with plain
MEMORY.mdfiles or a hosted API like Mem0 until the local graph-RAG tooling settles down. I’m somewhere in the middle right now, so I’ll watching it to see where it goes.Amnesia is the default. It doesn’t have to be.
Sources
- GBrain repository
- OpenClaw agent framework
- Hermes Agent (Nous Research)
- /r/openclaw community threads
- Hacker News
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Build Your Own Skills Repo
If you’ve been working with AI coding agents for a while, you’ve probably started collecting workflows. You might not call them that yet, but they’re there. Another name for workflows is Skills.
Some are tiny: run these checks before shipping. Some are project-specific: when you touch this library, preserve this API contract. Some are operational: never print secrets, always summarize the logs. Right now they probably live in chat history, a README note, a shell alias, or your own memory. That works until it doesn’t.
A skills repo is a better shape for this. It’s one place to collect, version, review, and share the workflows that make agents useful in your projects. I built my own yesterday, so let me walk through how I think about it.
A skill is judgment, not a command list
The first mistake is treating a skill like a list of commands. Commands matter, but they’re the easy part. The real value is judgment: when to run the command, what to inspect first, what not to do, how to validate the result, and what risks are specific to this tool.
A good skill makes an agent more careful. It narrows the space of bad decisions. So before you write a single instruction, figure out who the skill is for.
Separate adoption from maintenance
Most serious projects have two audiences: people using the project, and people maintaining it. Those should usually be two different skills.
An adoption skill helps an outside developer get value from your project. Install the package, configure it correctly, use the right import path, migrate existing code, avoid the common mistakes, run the right validation.
A maintainer skill helps contributors work inside the source repo. Understand the layout, run the local quality gate, preserve compatibility promises, follow the release conventions.
Here’s why you need two. If you only write maintainer skills, your repo becomes a private automation folder. If you write adoption skills too, it becomes onboarding infrastructure.
Keep each skill focused
A skill should have a job. Not “everything about this project.” Not a duplicate README. Good skill names are verbs:
integrate,audit,upgrade,migrate,debug,ship. That keeps the trigger obvious, so when someone asks the agent to do that kind of work, the skill has a clear reason to load.If a project needs multiple workflows, split them. A library might have
integrateanddevelop. A deployment system might havedeployandrollback. Don’t cram them into one file.Put the safety rules near the top
The most important part of many skills is the “do not” section:
- Do not print secret values.
- Do not delete or archive anything without confirmation.
- Do not add failing CI enforcement unless asked.
- Do not do broad rewrites before previewing a diff.
- Do not commit local registry URLs.
Agents are good at momentum. Safety rules are how you make that momentum usable. The more destructive the workflow, the more explicit the guardrails should be.
Include validation, not just execution
Every skill should answer one question: how do we know this worked? That might be
pnpm test && pnpm build, orcargo test && cargo clippy -- -D warnings, orgo test ./.... For non-code workflows it might be “export the review list” or “verify the generated config is ignored by git.”This matters because agents can complete every step without completing the work. Validation closes the loop.
Write for the agent inside the repo
Skills should assume the agent is operating in a real project with real files and existing conventions. So the useful instructions look like:
- Inspect
package.jsonbefore choosing a package manager. - Read the existing test scripts before adding new ones.
- Prefer the local task-runner commands when they exist.
- Check the framework boundary before picking an import path.
That’s the context generic model knowledge won’t reliably infer. And it’s why you shouldn’t just copy the README into the skill. A README is for a human browsing the project. A skill is for an agent doing work. They overlap, but they aren’t the same artifact. Keep the skill short enough that loading it is cheap.
Use a marketplace repo as the index
Your skills repo doesn’t need to be the canonical home for every skill. Some projects should own their own plugin metadata, especially if they already have a CLI, release process, and docs. Your marketplace can just point at them remotely. Other skills can live directly in the marketplace repo. One structure that works:
skills/ .claude-plugin/ marketplace.json plugins/ esm/ .claude-plugin/plugin.json skills/develop/SKILL.md upkeep-rs/ .claude-plugin/plugin.json skills/audit/SKILL.mdThe marketplace becomes the thing people add once. Individual plugins stay free to live locally or point at their canonical upstream.
Scan third-party skills before you import them
The moment your marketplace points at someone else’s plugin, you’ve inherited their security posture. And skills are a soft target. The dangerous payload usually isn’t code, it’s prose: an attacker buries instructions inside a
SKILL.md, gated behind an innocent-sounding trigger, that tell the agent to read your.envand send it somewhere. A normal code scanner walks right past that. There’s no malware signature to match. It’s just English.This isn’t hypothetical. Snyk’s ToxicSkills research found prompt injection in 36% of the skills they tested, across more than a thousand malicious payloads. If you’re pulling skills from a public index, some fraction of them are trying to do something you didn’t ask for.
So run a scanner before you add anything you didn’t write. A few worth knowing:
- Snyk agent-scan inventories your installed agents, MCP servers, and skills, then checks them for prompt injection and data-handling problems.
- NVIDIA SkillSpector scans repos, URLs, or single files against a big catalog of patterns: injection, exfiltration, privilege escalation, tool poisoning.
- claude-skill-antivirus is purpose-built for Claude Code skills and runs several detection engines at once.
One caveat worth internalizing: scanning an MCP config can execute it, because starting a stdio server means running the command in the file. Do that in a sandbox, a container or a throwaway VM, not on your main machine. The tool you run to check for danger shouldn’t be the thing that sets it off.
This cuts both ways. If you publish a plugin others will install, a clear “do not” block and an honest description of what the skill touches is part of being a good citizen of the marketplace.
Start with your serious projects
You don’t need a skill for everything. Start where better agent behavior would matter: public libraries people might adopt, CLIs with safety-sensitive workflows, tools with tricky setup, projects with recurring maintenance, systems where mistakes are expensive.
For each one, ask yourself:
- Who is this for: user, maintainer, operator, contributor?
- What’s the concrete task?
- What should the agent inspect first?
- What commands are preferred, and which are dangerous?
- What should never happen silently?
- What validation proves the work succeeded?
Answer those and you have enough to write a useful first skill.
Why it’s worth doing
A skills repo turns scattered project knowledge into reusable operational guidance. But it also forces a better product question. If this project is meant to help people, what would it look like for an AI agent to help them use it well?
That’s a higher bar than “can the agent run the command?” The point isn’t to automate everything. It’s to package the judgment around your tools so the next agent starts from a better place.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Four Ways to Build Your Own Agentic Harness
The model is the commodity. You rent it. Everything else, the loop, the tools, the state, the permissions, the memory, the orchestration, is the harness. And the harness is the part you get to own.
So the real question, when people say they want to “build their own agent,” isn’t which model. It’s how much of the scaffolding you want to inherit versus how much you want to build yourself. That’s the whole decision. Where you land on that spectrum gives you, more or less, four approaches.
A: Build on top of a full harness
This is the composition-heavy approach, and it’s the one I’ve mostly done. You take a fully featured harness like Claude Code or opencode (and I think a few of the newer agentic IDEs support this now too), and you extend it. Sub-agents, skills, slash commands. You can call these things remotely with CLI commands and wire your own behavior around them.
There are two flavors here. You can build your harness inside the existing one, or you can build it around the existing one. Either way, you own all the agent definitions, the skills, the model choices. But you inherit a lot too: which tools the agent can call, the permission model, all the safety controls. You don’t get to change those, you just get to use them.
And honestly? That’s the appeal. You don’t start from scratch. Somebody already solved the boring, dangerous parts. You show up and build the part you care about.
B: Self-host a fully open harness
This one looks a lot like A, but with one important difference: the underlying harness is open. You’re self-hosting and extending something fully open-source, then polishing and tailoring it to your needs.
The trade is control. In approach A, the tools and permissions and controls are handed to you and you live with them. Here, the entire stack is yours to crack open. If the permission model annoys you, you change it. If you want a tool to behave differently at the loop level, you can reach in and do that. You’re still not building from nothing, but nothing is off-limits either.
C: Assemble from primitives
Now we’re getting low. With this approach you build your harness up from very minimal pieces. Think of it like a full-stack framework in the web world, except for agents. Something like pydantic-ai’s SDK, or pulling aider in as a library rather than running it as a tool.
You don’t start from absolute zero, but you’re close. You define the agent loop yourself. You register the tools. You add the features you need, one at a time. You’re scaffolding basically everything, and all you’re inheriting is a handful of core primitives that you get to shape into whatever you want.
This is the approach for people who have opinions and want to express all of them. It’s more work. It’s also the most yours.
D: An agentic harness framework
The last one is a different animal, and I’ll admit it took me a second to see why it’s its own category. These are orchestration frameworks like LangGraph or Letta (formerly MemGPT). They’re not coding CLIs. They’re SDKs for building a custom agent application: graphs, state machines, first-class memory.
The distinction that finally clicked for me is what you’re building. With A through C, you’re mostly building a personal dev tool, something that helps you write code. With D, the harness is the product. You’re shipping it. A domain agent, a service, a customer-facing thing that happens to be agentic under the hood. The orchestration framework is what you reach for when the agent isn’t your tool, it’s your deliverable.
So where do you land?
There’s no correct answer here, just a trade you’re making on purpose. The more you inherit, the faster you move and the less you control. The more you build, the more it’s yours and the more of the boring, dangerous plumbing you’re now on the hook for.
For most of what I do, A is the sweet spot. Building around and within an existing harness is just so much easier than starting cold, and I’d rather spend my time on the agent definitions than on reinventing a permission model. But if I were shipping an agent as a product instead of a tool, I’d be over in D without thinking twice.
Figure out which thing you’re building first. The approach falls out of that.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Sources
- Anthropic, “Claude Code” (GitHub) — documentation and repository for the terminal-based agentic coding tool that reads codebases, runs commands, and integrates MCP servers.
- Aider AI, “Aider” — official documentation and pair-programming guides for the open-source, git-native AI coding assistant.
- Anomaly Co., “OpenCode” — official homepage and repository for the open-source terminal, desktop, and IDE-based AI coding agent.
- Pydantic, “Pydantic AI” — official documentation and API references for the type-safe Python agent framework designed for structured agent trajectories.
- Letta AI, “Letta” (GitHub) — repository for the stateful agent runtime (formerly MemGPT) that manages persistent memory tiers and agentic state machines.
-
Six Months with Git-Native Issue Tracking: Am I Still Using Beads?
Back in January, I wrote about discovering beads, a git-native issue tracker built specifically for AI-assisted development. I was pretty hyped. Having agents track their own tasks natively inside the git repo felt like the missing link for long-running autonomous workflows.
It’s been six months. So, the inevitable question: am I still using it?
Short answer: yes, but no longer as my default.
So this is where my task-tracking workflow actually landed in mid-2026.
The Shift Away From the Default
In January, I was trying to force beads into every single project I spun up. New repo? Init beads. Quick experiment? Init beads. As the months went on, I realized I was over-engineering things.
For a lot of projects, the task tracking built into Claude Code is good enough for day-to-day work. If an agent just needs to hold a checklist for a couple of hours during a coding session, standing up a full git-native tracking system is overkill. The lightweight, ephemeral tasks handle that perfectly, and they disappear when the session ends, which is exactly what you want for session-scoped work.
Wrapping the Real Things
For durable issue tracking, I pivoted back to where the code already lives.
Instead of leaning on beads, I built a couple of custom agent skills that wrap the GitHub CLI (
gh) and the GitLab CLI (glab). Now when an agent needs to pull down tasks, update tickets, or log a blocker, it just talks directly to GitHub or GitLab through those wrappers.The split looks like this: the remote issue tracker is the source of truth, and lightweight Claude Code tasks handle immediate session context. That combination has been far more resilient for me than routing everything through a separate system. The truth stays where my teammates and my future self will actually look for it.
Where Beads Still Lives
I haven’t abandoned beads. It still sticks around on a handful of repos where it’s useful.
The big one is my Obsidian vault, the “second brain” I wrote about earlier this week. When I’m managing personal research, blog pipelines, or local-only projects that don’t need a heavy GitHub project board, the git-native approach is still fantastic. No remote, no API, no ceremony, just issues that travel with the repo. Version 1.0 leaned into that even harder by moving to an embedded Dolt backend, basically git for your database, so there’s no separate server to babysit and the full history lives right alongside the code.
Beads isn’t worse than I thought in January. It’s just a sharper tool than I was treating it as. I was reaching for it everywhere when it was really built for a specific shape of project.
The hype of January has settled into the pragmatism of June. Not every project needs a custom tracking system, and sometimes letting your agents talk to GitHub directly is the easiest path forward.
What are you using to keep your agents on task these days?
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
The Agentic Dev Space Is Moving Fast, and I'm Having a Blast
Step back and look at the last six months of software development. It’s almost hard to believe how much has shifted. Back in January we were doing “vibe coding” with basic autocomplete. By June we’re handing fully autonomous agents a feature, walking off to grab a coffee, and coming back to find it architected, written, and tested.
It’s easy to look at the volume of new tools dropping every single day and feel a little fatigued. But honestly? I’m just excited. This is one of the most fun eras of programming I’ve worked through in decades.
Here’s a quick look at the tools that have already changed my workflow, and the ones I want to dig into next.
The Tools I’ve Adopted
If you read my post earlier this week, you know Supacode has become my daily driver. It bridged the gap between raw terminal access and a UI that understands how context-heavy agentic work is. That’s a harder problem than it sounds, and it’s really feeling good so far.
I also have to shout out the tools that paved the way earlier this year. Claude Code and Antigravity proved out the model of a CLI-native agent that could navigate your file system and do the work. Running Claude Code daily—and turning to Antigravity occasionally when I have access—has completely retrained my habits. I stopped typing every line of code and started acting more like a technical lead reviewing pull requests from a tireless junior developer. That shift in posture is the real unlock, and these were the tools that taught me it.
The Tools on My Radar
Because the space moves so fast, my “stuff I want to learn” backlog keeps growing faster than I can clear it. Here are the three I’m most eager to explore when I carve out the time:
- Hermes. I keep hearing great things about how it handles multi-step reasoning and huge context windows. I haven’t had the right project to throw at it yet, but it’s at the top of the list.
- Pi Agents. The concept here is highly specialized, networked agents working in tandem. Instead of one monolithic agent doing everything, you’d have a “frontend agent” talking to a “database agent.” That feels like a different way to structure the work, and I want to see if it holds up in practice.
- Evaluating Memory Systems. I’ve been diving into how agents remember things over time. I wrote a Mem0 MCP server that runs locally, and I’ve added hooks for Mem0 right into my CLI agents. It’s been a great way to slowly improve my own local agentic memory system. I’m really eager to see how other memory systems (like LangChain’s implementations) work under the hood, and I want to spend more time comparing and contrasting them.
You Don’t Have to Learn It All Today
The best part about this explosion of tooling is that you don’t need to know all of it. You don’t.
Find a tool that solves an immediate problem in your workflow, master that one, and let the rest sit on your radar until you need them. The ecosystem will keep evolving whether or not you’re watching every release. The tools will keep getting better. Chasing every launch is a great way to learn nothing well.
So pick one. Get good at it. Let the backlog wait.
What’s the one agentic tool sitting on your radar that you just haven’t had time to dig into yet?
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Why Supacode Became My Daily Driver for Claude Code
The number of ways to get an AI to write your code right now is … great? Claude Code, Codex, Opencode, and all the others. I think that’s a good thing. The easier we make it to hand real work to a capable coding agent, the better off we all are in the long run. I want to try most of them because that’s half the fun, figuring things out.
My cool tool for the week is Supacode.
What Supacode Is
Supacode is a native macOS app, written in Swift and built on libghostty, with no Electron and no web wrapper anywhere in sight. It’s fast the way native software is fast, the kind of speed you feel in every keystroke.
The website calls it a “command center for coding agents,” and well ok I get it now. Supacode is the nicest way I’ve found to run Claude Code. It’s open source too, so you can poke at the internals on GitHub if you’re curious.
What It Does for Me
This is the part that I like.
Supacode keeps all my projects organized down the left side, so jumping between them is one click instead of a mental map of which terminal tab is which. When I start a Claude Code session, its chat window moves up into the active area, and I can see every live session I have going at a glance.
The big one: it hooks into Claude Code, so Claude tells Supacode when it’s finished a task or when it needs something from me. Instead of babysitting a terminal waiting for the next prompt, I just get told when Claude is waiting on me. I tried for a long time to get something like that working in a plain terminal and never really nailed it. Here it just works.
And when I need more than one CLI open on the same project, I can group those tabs together instead of squinting at a wall of identical-looking shells.
None of that is glamorous. It’s just the difference between running Claude Code and pleasantly running Claude Code.
I Still Love Ghostty
I’m not leaving Ghostty behind, to be clear. I love Ghostty. Mitchell Hashimoto and everyone who’s worked on it has built something special. When I need a clean shell to compile a binary or grep through some logs, Ghostty is where I want to live.
Supacode is built on libghostty, the same engine that powers Ghostty. So the speed and feel I love about Ghostty is sitting right underneath Supacode too. They’re cousins. I get Ghostty for raw terminal work and Supacode for running Claude Code, and both of them are quietly standing on the same excellent foundation.
So Here We Are
We’re spoiled for choice with AI coding tools right now, and I love that. Most of what I try is interesting, and then I move on. Every so often something just slots into how I already work and earns a permanent spot. For me, right now, that’s Supacode. If you’re running Claude Code all day on a Mac, it’s well worth a look.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Your AI Agent Needs a Task Manager
If you’ve spent time working with AI coding tools, you’ve probably hit the compaction wall. Suddenly, your agent knows what it’s currently working on but has completely forgotten the five other things connected to it.
This is the memory problem, and it’s a big one.
The Context Window Isn’t Enough
Your AI agent needs some sort of memory system that lives outside the context window. When you’re working on simple, one-off tasks, the chat-as-workspace approach works fine. You ask a question, you get an answer, you move on. But the moment you’re tackling a complex set of related tasks? It breaks down fast.
I’ve been thinking about this through the lens of a framework I’m calling the Agentic Maturity Model. The short version is that there are distinct levels to how teams and developers use AI agents, and moving between levels isn’t about using “better” tools, but rather it’s a shift in how you approach the work.
Four months ago, there were no real options. The good news? It seems like all the model providers recognize this is the next frontier. Memory and persistence are where I’m looking for the actual progress to happen next.
Claude Code has certainly gotten better in these areas over the last couple of months. They’ve added an auto memory feature in beta. They added a lightweight Tasks system based on a Todo system called Beads built by Steve Yegge. His key idea was that the task state should live outside the context window.
These are meaningful building blocks towards an actual working memory system that persists across sessions and survives compaction.
We’re Almost There
The tooling and harneses we built on top of the LLMs are already changing how software gets built, but where we are headed? Here is what I think:
- auto-improving memory: where the agent learns your patterns, your codebase, your preferences
- persistent task tracking that survives compaction: Tasks, todos, issues, whatever you want to call them. The point is they exist outside the conversation.
When those two pieces come together properly, the workflow for everyone will change again.
Your agent doesn’t just respond to the current prompt. It knows where it is in a larger plan, what’s been done, what’s blocked, and what’s next. That’s the difference between a helpful chatbot and an actual collaborator.
We are so close I can taste the blood in the water, oh wait, that’s mine. ☠️
-
Your Context Window Is a Budget — Here's How to Stop Blowing It
If you’re using agentic coding tools like Claude Code, there’s one thing you should know by now: your context window is a budget, and everything you do spends it.
I’ve been thinking about how to manage the budget. As we are learning how to use sub-agents, MCP servers, and all these powerful capabilities we haven’t been thinking enough about the cost of using them. Certainly the dollars and cents matters too if you are using API access, but the raw token budget you burn through in a single session impacts us all regardless. Once it’s gone, compaction kicks in, and it’s kind of a crapshoot on whether it knows how to pick up where we left off on the new session.
Before we talk about what you can do about it, let’s talk about where your tokens go, or primarily are used.
Why Sub-Agents Are Worth It (But Not Free)
Sub-agents are one of the best things to have in agentic coding. The whole idea is that work happens in a separate context window, leaving your primary session clean for orchestration and planning. You stay focused on what needs to change while the sub-agent figures out how.
Sub-agents still burn through your session limits faster than you might expect. There are actually two limits at play here:
- the context window of your main discussion
- the session-level caps on how many exchanges you can have in a given time period.
Sub-agents hit both. They’re still absolutely worth using and working without them isn’t an option, but you need to be aware of the cost.
The MCP Server Problem
MCP servers are another area where things get interesting. They’re genuinely useful for giving agentic tools quick access to external services and data. But if you’ve loaded up a dozen or two of them? You’re paying a tax at the start of every session just to load their metadata and tool definitions. That’s tokens spent before you’ve even asked your first question.
My suspicion, and I haven’t formally benchmarked this, is that we’re headed toward a world where you swap between groups of MCP servers depending on the task at hand. You load the file system tools when you’re coding, the database tools when you’re migrating, and the deployment tools when you’re shipping. Not all of them, all the time.
There’s likley more subtle problems too. When you have overlapping MCP servers that can accomplish similar things, the agent could get confused about which tool to call. It might head down the wrong path, try something that doesn’t work, backtrack, and try something else. Every one of those steps is spending your token budget on nothing productive.
The Usual Suspects
Beyond sub-agents and MCP servers, there are the classic context window killers:
- Web searches that pull back pages of irrelevant results
- Log dumps that flood your context with thousands of lines
- Raw command output that’s 95% noise
- Large file reads when you only needed a few lines
The pattern is the same every time: you need a small slice of data, but the whole thing gets loaded into your context window. You’re paying full price for information you’ll never use.
And here’s the frustrating part — you don’t know what the relevant data is until after you’ve loaded it. It’s a classic catch-22.
Enter Context Mode
Somebody (Mert Köseoğlu - mksglu) built a really clever solution to this problem. It’s available as a Claude Code plugin called context-mode. The core idea is simple: keep raw data out of your context window.
Instead of dumping command output, file contents, or web responses directly into your conversation, context-mode runs everything in a sandbox. Only a printed summary enters your actual context. The raw data gets indexed into a SQLite database with full-text search (FTS5), so you can query it later without reloading it.
It gives Claude a handful of new tools that replace the usual chaining of bash and read calls:
- ctx_execute — Run code in a sandbox. Only your summary enters context.
- ctx_execute_file — Read and process a file without loading the whole thing.
- ctx_fetch_and_index — Fetch a URL and index it for searching, instead of pulling everything into context with WebFetch.
- ctx_search — Search previously indexed content without rerunning commands.
- ctx_batch_execute — Run multiple commands and search them all in one call.
There are also slash commands to check how much context you’ve saved in a session, run diagnostics, and update the plugin.
The approach is smart. All the data lives in a SQLite FTS5 database that you can index and search, surfacing only the relevant pieces when you need them. If you’ve worked with full-text search in libSQL or Turso, you’ll appreciate how well this maps to the problem. It’s the right tool for the job.
The benchmarks are impressive. The author reports overall context savings of around 96%. When you think about how much raw output typically gets dumped into a session, it makes sense. Most of that data was never being used anyway.
What This Means for Your Workflow
I think the broader lesson here is that context management is becoming a first-class concern for anyone doing serious work with agentic tools. It’s not just about having the most powerful model, it’s about using your token budget wisely so you can sustain longer, more complex sessions without hitting the wall.
A few practical takeaways:
- Be intentional about MCP servers. Load what you need, not everything you have.
- Use sub-agents for heavy lifting, but recognize they cost session tokens.
- Avoid dumping raw output into your main context whenever possible.
- Tools like context-mode can dramatically extend how much real work you get done per session.
We’re still early in figuring out the best practices for working with these tools. But managing your context window? That’s one of the things that separates productive sessions from frustrating ones.
Hopefully something here saves you some tokens.
-
How to Write a Good CLAUDE.md File
Every time you start a new chat session with Claude Code, it’s starting from zero knowledge about your project. It doesn’t know your tech stack, your conventions, or where anything lives. A well-written
CLAUDE.mdfile fixes that by giving Claude the context it needs before it writes a single line of code.This is context engineering, and your
CLAUDE.mdfile is one of the most important pieces of it.Why It Matters
Without a context file, Claude has to discover basic information about your project — what language you’re using, how the CLI works, where tests live, what your preferred patterns are. That discovery process burns tokens and time. A good
CLAUDE.mdfront-loads that knowledge so Claude can get to work immediately.If you haven’t created one yet, you can generate a starter file with the
/initcommand. Claude will analyze your project and produce a reasonable first draft. It’s a solid starting point, but you’ll want to refine it over time.The File Naming Problem
If you’re working on a team where people use different tools: Cursor has its own context file, OpenAI has theirs, and Google has theirs. You can easily end up with three separate context files that all contain slightly different information about the same project. That’s a maintenance headache.
It would be nice if Anthropic made the filename a configuration setting in
settings.json, but as of now they don’t. Some tools like Cursor do let you configure the default context file, so it’s worth checking.My recommendation? Look at what tools people on your team are actually using and try to standardize on one file, maybe two. I’ve had good success with the symlink approach , where you pick your primary file and symlink the others to it. So if
CLAUDE.mdis your default, you can symlinkAGENTS.mdorGEMINI.mdto point at the same file.It’s not perfect, but it beats maintaining three separate files with diverging information.
Keep It Short
Brevity is crucial. Your context file gets loaded into the context window every single session, so every line costs tokens. Eliminate unnecessary adjectives and adverbs. Cut the fluff.
A general rule of thumb that Anthropic recommends is to keep your
CLAUDE.mdunder 200 lines. If you’re over that, it’s time to trim.I recently went through this exercise myself. I had a bunch of Python CLI commands documented in my context file, but most of them I rarely needed Claude to know about.
We don’t need to list every single possible command in the context file. That information is better off in a
docs/folder or your project’s documentation. Just add a line in yourCLAUDE.mdpointing to where that reference lives, so Claude knows where to look when it needs it.Maintain It Regularly
A context file isn’t something you write once and forget about. Review it periodically. As your project evolves, sections become outdated or irrelevant. Remove them. If a section is only useful for a specific type of task, consider moving it out of the main file entirely.
The goal is to keep only the information that’s frequently relevant. Everything else should live somewhere Claude can find it on demand, not somewhere it has to read every single time.
Where to Put It
Something that’s easy to miss: you can put your project-level
CLAUDE.mdin two places../CLAUDE.md(project root)./.claude/CLAUDE.md(inside the.claudedirectory)
A common pattern is to
.gitignorethe.claude/folder. So if you don’t want to check in the context file — maybe it contains personal preferences or local paths — putting it in.claude/is a good option.Rules Files for Large Projects
If your context file is getting too large and you genuinely can’t cut more, you have another option: rules files. These go in the
.claude/rules/directory and act as supplemental context that gets loaded on demand rather than every session.You might have one rule file for style guidelines, another for testing conventions, and another for security requirements. This way, Claude gets the detailed context when it’s relevant without bloating the main file.
Auto Memory: The Alternative Approach
Something you might not be aware of is that Claude Code now has auto memory, where it automatically writes and maintains its own memory files. If you’re using Claude Code frequently and don’t want to manually maintain a context file, auto memory can be a good option.
The key thing to know is that you should generally use one approach or the other. If you’re relying on auto memory, delete the
CLAUDE.mdfile, and vice versa.Auto memory is something I’ll cover in more detail in another post, but it’s worth knowing the feature exists. Just make sure you enable it in your
settings.jsonif you want to try it.Quick Checklist
If you’re writing or revising your
CLAUDE.mdright now, here’s what I’d focus on:- Keep it under 200 lines — move detailed references to docs
- Include your core conventions — package manager, runtime, testing approach
- Document key architecture — how the project is structured, where things live
- Add your preferences — things Claude should always or never do
- Review monthly — cut what’s no longer relevant
- Consider symlinks — if your team uses multiple AI tools
- Use rules files — for detailed, task-specific context
That’s All For Now. 👋
-
Managing Your Context Window in Claude Code
If you’re using Claude Code, there’s a feature you should know about that gives you visibility into how your context window is being used. The
/contextskill breaks everything down so you can see exactly where your tokens are going.Here’s what it shows you:
- System prompt – the base instructions Claude Code operates with
- System tools – the built-in tool definitions
- Custom agents – any specialized agents you’ve configured
- Memory files – your CLAUDE.md files and auto-memory
- Skills – any skills loaded into the session
- Messages – your entire conversation history
Messages is where you have the most control, and it’s also what grows the fastest. Every prompt you send, every response you get back, every file read, every tool output; it all shows up in your message history.
Then there’s the free space, which is what’s left for actual work before a compaction occurs. This is the breathing room Claude Code has to think, generate responses, and use tools.
You’ll also see a buffer amount that’s reserved for auto-compaction. You can’t use this space directly, it’s set aside so Claude Code has enough room to summarize the conversation and hand things off cleanly.
Why This Matters
Understanding your context usage helps you work more efficiently. A few ways to keep your context lean:
- Start fresh sessions for new tasks instead of reusing a long-running one
- Be intentional about file reads — only read what you need, not entire directories
- Use sub-agents — when you delegate work to a sub-agent, it runs in its own context window instead of yours. All those file reads, tool calls, and intermediate reasoning happen over there, and you just get the result back. It’s one of the best ways to preserve your primary context for the work that actually needs it.
- Trim your CLAUDE.md — everything in your memory files loads every session, so keep it tight
I’ll dig into sub-agents more in a future post. For now, don’t forget about
/context -
Claude Code Prompts for Taming Your GitHub Repository Sprawl
Some useful Claude Code prompts for GitHub repository management.
1. Archive stale repositories
Using the GitHub CLI (gh), find all of my repositories that haven't been pushed to in over 5 years and archive them. List them first and ask for my confirmation before archiving. Use gh repo list <user> --limit 1000 --json name,pushedAt to get the data, then filter by date, and archive with gh repo archive <user>/<repo> --yes.2. Add missing descriptions
Using the GitHub CLI, find all of my repositories that have an empty or missing description. Use gh repo list <user> --limit 1000 --json name,description,url to get the data. For each repo missing a description, look at the repo's README and any other context to suggest an appropriate description. Present your suggestions to me for approval, then apply them using gh repo edit <user>/<repo> --description "<description>".3. Add missing topics/tags
Using the GitHub CLI, find all of my repositories that have no topics. Use gh repo list <user> --limit 1000 --json name,repositoryTopics, description,primaryLanguage to get the data. For each repo with no topics, analyze the repo name, description, and primary language to suggest relevant topics. Present your suggestions for approval, then apply them using gh api -X PUT repos/<user>/<repo>/topics -f '{"names":["tag1","tag2"]}'.To make #1 easier, repjan is a TUI tool that pulls all your repos into an interactive dashboard. It flags archive candidates based on inactivity and engagement, lets you filter and sort through everything, and batch archive in one sweep. If you’ve got hundreds of repos piling up, it’s way faster than doing it one by one.
-
First Impressions of OpenAI's Codex App
I’ve been experimenting with OpenAI’s new Codex app for engineering work that launched on February 2nd, and I’m not impressed.
No subagents from what I can tell. It gets stuck on stuff that shouldn’t be blockers. The gpt-5.2-codex model feels slow. I don’t care about the existing skills enough to try to set one up for it.
I did sign up for a free month trial of ChatGPT Plus though, so I’m going to give it a few more attempts before my time runs out. But so far, it doesn’t feel like a force multiplier the way Claude Code or Amp Code does. Even Open Code feels more productive.
Maybe I’ll have better luck with Codex on the CLI? We’ll see.
There’s something about flat-fee billing that feels so much better than watching tokens drain away. Less constrained and more open to trying new things I guess.
I appreciate that they went through the effort of building what looks like a native Swift app instead of yet another VS Code fork.
I think Codex desktop app is aimed at competing with Cursor’s market share, or maybe it’s some attempt at solving whatever direction Claude Desktop is heading.
It doesn’t feel like it’s solving my problems as a developer who already has workflows that I know work.
Back to the CLI pour moi.
-
AMP Code: First Impressions of a Claude Code Competitor
I tried AMP Code last weekend and came away genuinely impressed. I didn’t think there was anything at Claude Code’s level currently available.
That said, AMP is in a somewhat unfortunate position. Similar to Cursor, they have to pay the Anthropic tax, and you really want your primary model to be Opus 4.5 for the best results.
So while I was able to get some things done, once you start paying per token… you feel constrained. I’m speaking from a personal budget perspective here, but I blew through ten dollars of credits on their free tier pretty easily.
I could see how with billing enabled and all the sub-agents they make super easy to use, you could burn through a hundred-dollar Claude Code Max plan budget in a week, or even a day, depending on your usage.
What I Really Like
There’s a lot to appreciate about what AMP is doing.
Team collaboration is a standout feature. It’s incredibly easy to share a discussion with other people on your team. Being able to collaborate with your team on something using agents is extremely powerful.
Their TUI is exceptional. I mean, it’s so much better than Claude Code’s terminal interface. They probably have the best TUI on the market right now. It’s definitely better than Open Code.
Sub-agents work out of the box. All the complicated sub-agent stuff I’ve set up manually for my Claude Code projects? It just comes ready to go with AMP. They’ve made really smart decisions about which agents handle which tasks and which models to use. You don’t have to configure any of it, it’s all done for you.
The Bottom Line
I think for enterprise use cases, AMP Code is going to make a lot of sense for a lot of companies.
For individual developers on a personal budget, the cost model is something to think carefully about.
-
Claude Code’s built-in tasks are pretty solid—they work well for what they do. But I still find myself reaching for Beads. There’s something about having persistent issue tracking that lives with your code, syncs with git, and doesn’t disappear when you close your terminal. Different tools for different jobs, I suppose.
-
Beads: Git-Native Issue Tracking for AI-Assisted Development
If you’re working with AI coding agents like Claude Code, you’ve probably noticed a friction point: context.
Every time you start a new session, you’re rebuilding mental state. What was I working on? What’s blocked? What’s next?
I’ve been using Beads, and it’s changed how I manage work across multiple AI sessions.
What Makes Beads Different?
Beads takes a fundamentally different approach. Issues live in your repo as a
.beads/issues.jsonlfile, syncing like any other code. This means:- No context switching: Your AI agent can read and update issues without leaving the terminal
- Always in sync: Issues travel with your branch and merge with your code
- Works offline: No internet required, just git
- Branch-aware: Issues can follow your branch workflow naturally
The CLI-first design is what makes it click with AI coding agents. When I’m working with Claude Code, I can say “check what’s ready to work on” and it runs
bd readyto find unblocked issues. No copying and pasting from a browser tab.Getting Started
Getting up and running takes about 30 seconds:
# Install Beads curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash # Initialize in your repo bd init # Create your first issue bd create --title="Try out Beads" --type=taskFrom there, the workflow is straightforward:
bd readyshows issues with no blockersbd update <id> --status=in_progressto claim workbd close <id>when you’re donebd syncto commit beads changes
Why This Matters for AI Workflows
The real power shows up when you’re juggling multiple tasks across sessions. Your AI agent can:
- Pick up exactly where you left off by reading the issue state
- Track dependencies between tasks (this issue blocks that one)
- Create new issues for discovered work without breaking flow
- Close completed work and update status in real-time
I’ve found this especially useful for longer projects where I’m bouncing between features, bugs, and cleanup tasks. The AI doesn’t lose track because the state is right there in the repo.
Is It Right for You?
Beads isn’t trying to replace GitHub Issues for team collaboration or complex project management.
It’s designed for a specific workflow: developers using AI coding agents who want persistent, agent-friendly task tracking.
If you’re already working with Claude Code, Aider, or similar tools, give it a try. The setup cost is minimal, and you might find it solves a problem you didn’t realize you had.