\n screenshot: twitter_taskbot.png\n
\n ![\"ZeroWork](\"/images/twitter_taskbot.png\")
\nTL;DR: I asked opencode to audit this repo's config against best practices for a private solo repo. Secrets hygiene came back clean. The genuine surprise was line 7 of my own .gitignore, which said /package-lock.json, so my lockfile was never tracked, and Dependabot vulnerability alerts were switched off. Also ~40 stale branches, a loud git branch -d refusal, and the last command in the && chain silently never running because of it. Fixed in commit 42cf1f0, plus two git aliases that encode the right cleanup order, git pull && git sweep.
I asked my agent (opencode) to review this repo's config. The whole ask was to check ManningWorks/lukemanning-site against best practices for a private solo-dev repo and tell me if anything needs changing.
\nMy honest expectation was a list of green ticks and maybe a nitpick about something I'd decided on purpose. The site builds, Vercel deploys it, nothing's on fire. What could be wrong?
\nMost of it was fine. Some of it really wasn't.
\nSecrets hygiene, the part I actually cared about, came back clean. .env* is gitignored and .env.local holds a real GITHUB_TOKEN and a DEV_TO_API_KEY, untracked. Better still, the audit ran this check
git log --all --oneline -- '.env*'Empty output. No env file was ever committed, on any branch, ever. That's the check I'd never have thought to run.
\nIgnores for node_modules, .next, .velite, tsbuildinfo were all correct. No LICENSE file, also correct for a private repo. No license means all rights reserved by default.
Then it got to line 7 of my .gitignore.
/package-lock.json\nMy own lockfile. At some point I told git to ignore it, deliberately, and then apparently never thought about it again.
\nI pushed back on this one, because ignoring a lockfile is a real opinion. Plenty of library maintainers do exactly that, and I've shipped a library myself, so the instinct has history.
\nBut this isn't a library, it's a deployed app. Vercel builds this site from the repo, and with no tracked lockfile every build resolves dependencies fresh. What package-lock.json actually does is pin those resolutions to exact versions, which is what makes deploys reproducible. Without it, a transitive dependency can publish a breaking version and break a deploy with zero code changes on my side. Dependabot also needs the lockfile to open version update PRs at all.
\nExtra mess in the same area was pnpm archaeology. A .pnpmfile.cjs in the repo root and a pnpm block in package.json, leftovers from a pnpm phase. Meanwhile .npmrc and package-lock.json say npm is the actual current tool, the lockfile sitting on disk, untracked. Two package managers' worth of config, one of them dead.
Dependabot alerts are GitHub watching my dependencies for known vulnerabilities and telling me when it finds one. They were off, so nothing would have told me when a dependency picked up a CVE. The audit caught it via the API.
\ngh api repos/ManningWorks/lukemanning-site/vulnerability-alerts404. On this endpoint that's just how GitHub says off, which threw me because 404 usually means the repo name is wrong. The docs say 204 means enabled, and this endpoint never returns 200.
\nThe fix was a PUT.
\ngh api -X PUT repos/ManningWorks/lukemanning-site/vulnerability-alertsEnabling alerts is free even on private repos. One API call.
\nBranch protection on private repos needs GitHub Pro. The API says so directly.
\nUpgrade to GitHub Pro or make this repository public\nSecret scanning and push protection aren't available on free private repos either. My first thought was that both are moot for a solo dev, but that's only half true. Secret scanning would have real value here, because I'm the most likely person to leak my own secrets. That one's a genuine gap, and closing it costs GitHub Pro money. Push protection, fair enough, there's nobody else's push to protect against. At least now I know it's a plan limit and not a config miss.
\nThe pile was ~40 stale branches, local and remote. Every PR merged on GitHub left its head branch behind, and I'd clearly never gone back to clean up. Mostly merged, long forgotten.
\nI set the bar before deleting anything. Only branches proven merged get deleted. Two checks. git branch --merged master and its -r twin for ancestry, plus a cross-check against gh pr list --state merged.
One branch failed the ancestry check and was still safe to delete, and that's the interesting case.
\n8ca8fd1 feat: auto-inject referral boxes... (#26)\nThat's the output of git log master..feat/referral-link-injection --oneline. One commit, and it wasn't an ancestor of master. But the (#26) suffix is a squash-merge fingerprint. My PRs land as squash merges, and squash doesn't carry a branch's commits into master. It forges one fresh commit and stamps \"title (#PR)\" on it.
Which leaves a question. That stamp belongs on the commit squash forges on master, not on anything sitting at a branch tip. How this one got there, I never fully reconstructed. My best guess is the branch picked up a squash-style commit somewhere along the way, a cherry-pick of one or a reset onto one.
\nThe cross-check showed the branch actually went out through PR #53, same name, merged, feature live on master. It got reused across PRs at some point and the stale #26 fingerprint never washed off. An orphaned copy, in other words. Tip not in master's history anywhere, changes already live.
\nThe branch was a husk.
\ngit branch -d would refuse it forever, so it needed -D (force-delete, the shortcut for --delete --force), with the receipt above as justification.
Then the batch deletion failed halfway through.
\nThe chain was a long run of git branch -d calls for the proven-merged branches, then git branch -D feat/referral-link-injection at the very end. One of the -d deletions refused for merge/review-publisher-published-posts-into-master because it apparently wasn't merged into master, but it was. The reason is a rule I didn't know existed. From the git man page on -d.
\n\nThe branch must be fully merged in its upstream branch, or in HEAD if no upstream was set.
\n
This branch tracked a differently named remote upstream, origin/review/publisher-published-posts. The refusal explained it clearly enough. Not yet merged to 'refs/remotes/origin/review/publisher-published-posts', even though it is merged to HEAD.
AI figured it out and helped me clean it up.
\nFirst instinct for the cleanup was git sweep && git pull. Wrong order, and for a different reason than the -d refusal earlier. The sweep's filter, git branch --merged <base>, reads whatever base branch it points at. That's a separate check from the -d safety rule above. The filter decides what makes the delete list, and the -d check gives each branch its final veto. If I swept before pulling, my local master didn't yet contain the merge I'd just done on GitHub, so the freshly merged branch never even made the delete list. No error, just a sweep that did nothing useful, so I needed a second sweep anyway. Pull first, then sweep.
The aliases that landed in ~/.gitconfig
[alias]\n\tsync = \"!f() { git pull && git sweep; }; f\"\n\tsweep = \"!f() { git fetch --prune; b=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null) || b=$(git rev-parse --verify -q main >/dev/null 2>&1 && echo main || echo master); git branch --merged \\\"$b\\\" | grep -vE \\\"^\\\\*\\\" | grep -Fvx \\\" $b\\\" | xargs -r git branch -d; }; f\"(-r is a GNU xargs thing, it makes xargs do nothing on empty input. macOS's BSD xargs doesn't have it.)
The real protection for the drafts is the filter, not the -d. git branch --merged <base> only lists branches that are ancestors of the base branch, so the unmerged feat/draft-* branches never make the delete list at all. The -d is the backstop. And as that merge/review-publisher... refusal showed, the backstop has its own opinions about upstreams and can refuse mid-sweep. It just refuses safely, which is why it's still -d and not -D. Every sweep run so far: drafts untouched.
The first cut of the sweep alias had a bug I noticed after: the grep skipped any branch name containing \"master\", so merge/review-publisher-published-posts-into-master would never make the sweep list. It would just sit there forever. That bugged me enough to rewrite it, and the alias above is the rewrite. It resolves the base branch now, origin/HEAD if set, then a main/master fallback, and the greps only skip the current branch and the base itself. The into-master branch gets swept like everything else.
Then one more API call to set delete_branch_on_merge=true, so merged PR head branches auto-delete on the remote from now on, and the pile can't quietly rebuild itself.
TL;DR: I asked opencode to audit this repo's config against best practices for a private solo repo. Secrets hygiene came back clean. The genuine surprise was line 7 of my own .gitignore, which said /package-lock.json, so my lockfile was never tracked, and Dependabot vulnerability alerts were switched off. Also ~40 stale branches, a loud git branch -d refusal, and the last command in the && chain silently never running because of it. Fixed in commit 42cf1f0, plus two git aliases that encode the right cleanup order, git pull && git sweep.
I asked my agent (opencode) to review this repo's config. The whole ask was to check ManningWorks/lukemanning-site against best practices for a private solo-dev repo and tell me if anything needs changing.
\nMy honest expectation was a list of green ticks and maybe a nitpick about something I'd decided on purpose. The site builds, Vercel deploys it, nothing's on fire. What could be wrong?
\nMost of it was fine. Some of it really wasn't.
\nSecrets hygiene, the part I actually cared about, came back clean. .env* is gitignored and .env.local holds a real GITHUB_TOKEN and a DEV_TO_API_KEY, untracked. Better still, the audit ran this check
git log --all --oneline -- '.env*'Empty output. No env file was ever committed, on any branch, ever. That's the check I'd never have thought to run.
\nIgnores for node_modules, .next, .velite, tsbuildinfo were all correct. No LICENSE file, also correct for a private repo. No license means all rights reserved by default.
Then it got to line 7 of my .gitignore.
/package-lock.json\nMy own lockfile. At some point I told git to ignore it, deliberately, and then apparently never thought about it again.
\nI pushed back on this one, because ignoring a lockfile is a real opinion. Plenty of library maintainers do exactly that, and I've shipped a library myself, so the instinct has history.
\nBut this isn't a library, it's a deployed app. Vercel builds this site from the repo, and with no tracked lockfile every build resolves dependencies fresh. What package-lock.json actually does is pin those resolutions to exact versions, which is what makes deploys reproducible. Without it, a transitive dependency can publish a breaking version and break a deploy with zero code changes on my side. Dependabot also needs the lockfile to open version update PRs at all.
\nExtra mess in the same area was pnpm archaeology. A .pnpmfile.cjs in the repo root and a pnpm block in package.json, leftovers from a pnpm phase. Meanwhile .npmrc and package-lock.json say npm is the actual current tool, the lockfile sitting on disk, untracked. Two package managers' worth of config, one of them dead.
Dependabot alerts are GitHub watching my dependencies for known vulnerabilities and telling me when it finds one. They were off, so nothing would have told me when a dependency picked up a CVE. The audit caught it via the API.
\ngh api repos/ManningWorks/lukemanning-site/vulnerability-alerts404. On this endpoint that's just how GitHub says off, which threw me because 404 usually means the repo name is wrong. The docs say 204 means enabled, and this endpoint never returns 200.
\nThe fix was a PUT.
\ngh api -X PUT repos/ManningWorks/lukemanning-site/vulnerability-alertsEnabling alerts is free even on private repos. One API call.
\nBranch protection on private repos needs GitHub Pro. The API says so directly.
\nUpgrade to GitHub Pro or make this repository public\nSecret scanning and push protection aren't available on free private repos either. My first thought was that both are moot for a solo dev, but that's only half true. Secret scanning would have real value here, because I'm the most likely person to leak my own secrets. That one's a genuine gap, and closing it costs GitHub Pro money. Push protection, fair enough, there's nobody else's push to protect against. At least now I know it's a plan limit and not a config miss.
\nThe pile was ~40 stale branches, local and remote. Every PR merged on GitHub left its head branch behind, and I'd clearly never gone back to clean up. Mostly merged, long forgotten.
\nI set the bar before deleting anything. Only branches proven merged get deleted. Two checks. git branch --merged master and its -r twin for ancestry, plus a cross-check against gh pr list --state merged.
One branch failed the ancestry check and was still safe to delete, and that's the interesting case.
\n8ca8fd1 feat: auto-inject referral boxes... (#26)\nThat's the output of git log master..feat/referral-link-injection --oneline. One commit, and it wasn't an ancestor of master. But the (#26) suffix is a squash-merge fingerprint. My PRs land as squash merges, and squash doesn't carry a branch's commits into master. It forges one fresh commit and stamps \"title (#PR)\" on it.
Which leaves a question. That stamp belongs on the commit squash forges on master, not on anything sitting at a branch tip. How this one got there, I never fully reconstructed. My best guess is the branch picked up a squash-style commit somewhere along the way, a cherry-pick of one or a reset onto one.
\nThe cross-check showed the branch actually went out through PR #53, same name, merged, feature live on master. It got reused across PRs at some point and the stale #26 fingerprint never washed off. An orphaned copy, in other words. Tip not in master's history anywhere, changes already live.
\nThe branch was a husk.
\ngit branch -d would refuse it forever, so it needed -D (force-delete, the shortcut for --delete --force), with the receipt above as justification.
Then the batch deletion failed halfway through.
\nThe chain was a long run of git branch -d calls for the proven-merged branches, then git branch -D feat/referral-link-injection at the very end. One of the -d deletions refused for merge/review-publisher-published-posts-into-master because it apparently wasn't merged into master, but it was. The reason is a rule I didn't know existed. From the git man page on -d.
\n\nThe branch must be fully merged in its upstream branch, or in HEAD if no upstream was set.
\n
This branch tracked a differently named remote upstream, origin/review/publisher-published-posts. The refusal explained it clearly enough. Not yet merged to 'refs/remotes/origin/review/publisher-published-posts', even though it is merged to HEAD.
AI figured it out and helped me clean it up.
\nFirst instinct for the cleanup was git sweep && git pull. Wrong order, and for a different reason than the -d refusal earlier. The sweep's filter, git branch --merged <base>, reads whatever base branch it points at. That's a separate check from the -d safety rule above. The filter decides what makes the delete list, and the -d check gives each branch its final veto. If I swept before pulling, my local master didn't yet contain the merge I'd just done on GitHub, so the freshly merged branch never even made the delete list. No error, just a sweep that did nothing useful, so I needed a second sweep anyway. Pull first, then sweep.
The aliases that landed in ~/.gitconfig
[alias]\n\tsync = \"!f() { git pull && git sweep; }; f\"\n\tsweep = \"!f() { git fetch --prune; b=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null) || b=$(git rev-parse --verify -q main >/dev/null 2>&1 && echo main || echo master); git branch --merged \\\"$b\\\" | grep -vE \\\"^\\\\*\\\" | grep -Fvx \\\" $b\\\" | xargs -r git branch -d; }; f\"(-r is a GNU xargs thing, it makes xargs do nothing on empty input. macOS's BSD xargs doesn't have it.)
The real protection for the drafts is the filter, not the -d. git branch --merged <base> only lists branches that are ancestors of the base branch, so the unmerged feat/draft-* branches never make the delete list at all. The -d is the backstop. And as that merge/review-publisher... refusal showed, the backstop has its own opinions about upstreams and can refuse mid-sweep. It just refuses safely, which is why it's still -d and not -D. Every sweep run so far: drafts untouched.
The first cut of the sweep alias had a bug I noticed after: the grep skipped any branch name containing \"master\", so merge/review-publisher-published-posts-into-master would never make the sweep list. It would just sit there forever. That bugged me enough to rewrite it, and the alias above is the rewrite. It resolves the base branch now, origin/HEAD if set, then a main/master fallback, and the greps only skip the current branch and the base itself. The into-master branch gets swept like everything else.
Then one more API call to set delete_branch_on_merge=true, so merged PR head branches auto-delete on the remote from now on, and the pile can't quietly rebuild itself.
In April I wrote a post called I Shipped a Component Library. I Have No Idea If Anyone Actually Uses It.
\nFor anyone who hasn't read that post, Projex is an npm library that renders a searchable, filterable grid of project cards from a config file.
\nCode review found twelve issues, the review agent asked if I could demo Projex in 60 seconds, I couldn't, and the conclusion was that the code wasn't the blocker. The first-time experience was. The fix I gestured at was a single component: <ProjectGrid>, one component that accepts the config and handles the data fetching internally. No manual async, no server/client split.
\"The thing I need is something like a <ProjectGrid> component.\"
That was the unlock I named.
\nI built it. It shipped in Projex 1.4.0 on August 7th and it's live on npm, where the package went from 755 downloads in April to 143 last month.
\nThen I sat down and asked whether it actually did what I said it would.
\nIt didn't.
\nHere's the component. Stripped down (the actual export is SmartProjectGrid; the April post called it <ProjectGrid>, so I'll keep using that name):
<SmartProjectGrid projects={projects} showSearch showFilters>\n {(project) => <MyCard project={project} />}\n</SmartProjectGrid>Vs the old way:
\nconst [query, setQuery] = useState('')\nconst [tags, setTags] = useState<string[]>([])\nconst searched = useProjectSearch(projects, query)\nconst filtered = useProjectFilters(searched, tags)That's the diff. The April post described a component that handles the data fetching internally, no manual async. The shipped one takes projects as a prop. You still write the fetching code yourself. That part of the idea didn't survive.
The new wrapper saves you maybe twenty lines of boilerplate per page where you want a sortable, filterable, searchable grid. Real savings. Worth shipping.
\nIt does not solve the demo problem. Not even a little bit.
\nThe April post framed the demo problem like this:
\n\n\nHere's what getting Projex running actually involves right now:
\n\n
\n- Install it
\n- Write async data fetching code
\n- Understand that GitHub data only loads at build time, not dev time
\n- Wire up a server component for the data fetch
\n- Wire up a client component for search
\n- Deal with the server/client split
\n
The conclusion was that this list is what blocks the 60-second demo. Six steps, server/client split, build-time fetching that doesn't show up in pnpm dev. None of that is the <ProjectGrid> fix.
What <ProjectGrid> actually does is collapse steps 4 through 6. It does not collapse steps 1 through 3. Steps 1 through 3 happen before any code matters. Someone lands on the npm page, reads the README, finds out the data fetching is manual and the GitHub data only loads at build time, and decides whether to install it at all. The wrapper component isn't visible at that moment. They haven't installed it yet. They're trying to imagine what their portfolio would look like.
If they install it, they get the wrapper. If they don't install it, the wrapper doesn't matter.
\nThe wrapper helps the people who already decided they wanted it. It does not help the people who are deciding.
\nThe demo problem is not \"the API has too many steps.\"
\nThe demo problem is \"I cannot show someone what Projex does without them first installing it.\"
\nTo show someone what Projex does, I need a URL. A page on the internet that renders Projex output with real data, that doesn't require them to clone a repo, that doesn't require them to wire up a Next.js project.
\nThe npm page is a README. The README is text. Text is not a demo.
\nThe <ProjectGrid> component does not solve that. It cannot solve that. No component can solve that. Only a URL solves that.
I already had one. My projects page has been rendering straight from the Projex package since March, pulling its data from this blog's projex.config.ts. The April post links to it as proof the library works. I named a component as the unlock in the same post that linked to the actual unlock.
In April I named the wrong thing. I named a component because Projex is code, so code felt like the answer. What I needed was something to send someone, and I already had it. The URL existed before the post did.
\nIf I'd asked in April \"can someone see what this does without installing it?\", the answer would have been yes: my own projects page. I could have gone straight from that question to the Product Hunt launch, the thing the April post said couldn't happen without a demo. I asked \"can I demo this in 60 seconds?\" instead, which framed the answer as code I hadn't written yet. So I waited for code that was never the blocker.
\nThe component itself is fine, for what it is. It saves maybe twenty lines per page for people who install Projex, and I moved this blog's catalogue onto Projex's own search, filter and sort helpers so the page and the library share one implementation. That's real. It was never the unlock.
\nSo the next thing is a real demo site: a standalone URL whose whole job is showing what Projex does. This post is the soft launch of that idea. The demo doesn't exist yet. The post does.
", "url": "https://lukemanning.ie/blog/i-built-the-projectgrid-it-still-doesnt-solve-the-problem", "title": "I Built the ProjectGrid. It Still Doesn't Solve the Problem.", "summary": "In April I wrote a post called I Shipped a Component Library. I Have No Idea If Anyone Actually Uses It.
\nFor anyone who hasn't read that post, Projex is an npm library that renders a searchable, filterable grid of project cards from a config file.
\nCode review found twelve issues, the review agent asked if I could demo Projex in 60 seconds, I couldn't, and the conclusion was that the code wasn't the blocker. The first-time experience was. The fix I gestured at was a single component: <ProjectGrid>, one component that accepts the config and handles the data fetching internally. No manual async, no server/client split.
\"The thing I need is something like a <ProjectGrid> component.\"
That was the unlock I named.
\nI built it. It shipped in Projex 1.4.0 on August 7th and it's live on npm, where the package went from 755 downloads in April to 143 last month.
\nThen I sat down and asked whether it actually did what I said it would.
\nIt didn't.
\nHere's the component. Stripped down (the actual export is SmartProjectGrid; the April post called it <ProjectGrid>, so I'll keep using that name):
<SmartProjectGrid projects={projects} showSearch showFilters>\n {(project) => <MyCard project={project} />}\n</SmartProjectGrid>Vs the old way:
\nconst [query, setQuery] = useState('')\nconst [tags, setTags] = useState<string[]>([])\nconst searched = useProjectSearch(projects, query)\nconst filtered = useProjectFilters(searched, tags)That's the diff. The April post described a component that handles the data fetching internally, no manual async. The shipped one takes projects as a prop. You still write the fetching code yourself. That part of the idea didn't survive.
The new wrapper saves you maybe twenty lines of boilerplate per page where you want a sortable, filterable, searchable grid. Real savings. Worth shipping.
\nIt does not solve the demo problem. Not even a little bit.
\nThe April post framed the demo problem like this:
\n\n\nHere's what getting Projex running actually involves right now:
\n\n
\n- Install it
\n- Write async data fetching code
\n- Understand that GitHub data only loads at build time, not dev time
\n- Wire up a server component for the data fetch
\n- Wire up a client component for search
\n- Deal with the server/client split
\n
The conclusion was that this list is what blocks the 60-second demo. Six steps, server/client split, build-time fetching that doesn't show up in pnpm dev. None of that is the <ProjectGrid> fix.
What <ProjectGrid> actually does is collapse steps 4 through 6. It does not collapse steps 1 through 3. Steps 1 through 3 happen before any code matters. Someone lands on the npm page, reads the README, finds out the data fetching is manual and the GitHub data only loads at build time, and decides whether to install it at all. The wrapper component isn't visible at that moment. They haven't installed it yet. They're trying to imagine what their portfolio would look like.
If they install it, they get the wrapper. If they don't install it, the wrapper doesn't matter.
\nThe wrapper helps the people who already decided they wanted it. It does not help the people who are deciding.
\nThe demo problem is not \"the API has too many steps.\"
\nThe demo problem is \"I cannot show someone what Projex does without them first installing it.\"
\nTo show someone what Projex does, I need a URL. A page on the internet that renders Projex output with real data, that doesn't require them to clone a repo, that doesn't require them to wire up a Next.js project.
\nThe npm page is a README. The README is text. Text is not a demo.
\nThe <ProjectGrid> component does not solve that. It cannot solve that. No component can solve that. Only a URL solves that.
I already had one. My projects page has been rendering straight from the Projex package since March, pulling its data from this blog's projex.config.ts. The April post links to it as proof the library works. I named a component as the unlock in the same post that linked to the actual unlock.
In April I named the wrong thing. I named a component because Projex is code, so code felt like the answer. What I needed was something to send someone, and I already had it. The URL existed before the post did.
\nIf I'd asked in April \"can someone see what this does without installing it?\", the answer would have been yes: my own projects page. I could have gone straight from that question to the Product Hunt launch, the thing the April post said couldn't happen without a demo. I asked \"can I demo this in 60 seconds?\" instead, which framed the answer as code I hadn't written yet. So I waited for code that was never the blocker.
\nThe component itself is fine, for what it is. It saves maybe twenty lines per page for people who install Projex, and I moved this blog's catalogue onto Projex's own search, filter and sort helpers so the page and the library share one implementation. That's real. It was never the unlock.
\nSo the next thing is a real demo site: a standalone URL whose whole job is showing what Projex does. This post is the soft launch of that idea. The demo doesn't exist yet. The post does.
", "date_modified": "2026-08-19T00:00:00.000Z", "tags": [ "projex", "reflections" ] }, { "id": "https://lukemanning.ie/blog/i-have-41-posts-i-audited-their-tags-11-survived", "content_html": "I have 41 blog posts. They each have tags. Until last week, those tags were whatever I thought made sense when I wrote the post. Some recurred. Most didn't. The rest were categories I wanted to exist, or aspects I wanted to mention.
\nI had no system. I had vibes.
\nThen I ran the audit that wiped the registry.
\nI wanted four content pillars, four primary niches that described the shape of my blog. Every published post had to declare a pillar. Tags had to map to pillars. A build-time validator had to fail if a published post declared a pillar that no tag supported.
\nFour pillars:
\nai — AI tooling, agents, OpenCode, Claude Code, agentic coding workflowshomelab — self-hosting, hardware, Unraid, servers, OS setup on machinesrabbit-holes — broad technical pillar: shipping projects + debugging/learning while building thingsreflections — non-tech, opinion, career, expanded thoughtsThe pillars themselves were the easy part.
\nThe hard part was the tags.
\nI ran the audit as a wayfinder pass. One decision per tag.
\nThe mechanics were dull. Every tag lives in a post's frontmatter, so I pulled the frontmatter from all 41 posts, listed every tag with its count, and sorted by that. The agent did the tallying. The judgment calls were all mine.
\nSome tags were obviously load-bearing. projex showed up on every post that mentioned my component library. velite showed up on every post about my content pipeline. homelab showed up on the server posts. github showed up on the recovery and the deprecation posts.
Some tags were obviously decorative. debugging showed up on three posts, all of which were about different kinds of debugging. workflow showed up on five posts, all of which were about different kinds of workflows. ai-assisted-development showed up on one post.
The first rule was: if it recurs, keep it. That got me a first registry with about 48 tags in it, more than the posts actually used. Some were categories I wanted to exist rather than categories I had. It took reading the five workflow posts back to back to see the problem: they had nothing in common. The rule was measuring the wrong thing.
A tag earns its place if there's evidence of a series. At least one other post has to anchor it. A tag that could be folded into a broader existing tag gets folded. A tag that's used once and not part of a series dies. The count gets a hearing, but the posts have to actually belong together.
\napt died. Used once. Subsumed by ubuntu. No reason to keep it.
github stayed. Multiple posts: the Ubuntu apt deprecation post and the git corruption recovery post. A real series about GitHub-shaped problems.
workflow died. Five uses, zero series. The tag was a context label, not a topic.
claude-code stayed. Two posts already, more coming. Real series.
The death rate was high. Of 41 tags that appeared across the 41 posts (the equal counts were an accident), 30 died. 11 survived.
\nThe 11:
\nai: opencode, hermes, claude-codehomelab: docker, zerowork, obsidianrabbit-holes: projex, velite, nextjs, github, ubuntu(The registry also carries the pillar names themselves as tags: ai, homelab, reflections. Those aren't series. They're just the pillars.)
Yes, I could tag any post with the bare pillar name and the validator would wave it through. The validator catches accidents. The coherent-series test is what catches lies. Tagging a post reflections just to get through a build is workflow all over again.
reflections is the only pillar with no series tags. The first genuinely reflective post has to bring its tag through the PR process.
A tag is a promise. When I tag a post workflow, if you click this tag, you'll find a series of posts about workflows. The reader lands on a tag page expecting a coherent collection.
If the tag delivers three posts about three different things, the tag lied. Anyone who clicked it got a pile of nothing. That's on me.
\nI keep going back and forth on whether the test is too strict. It's not, really. A tag with no series is just noise on a tag page.
\nThe 30 tags that died weren't wrong. They were over-promised. They were:
\ndebugging, thinking, meta, lessons-learned, retrospective, burnout)css, styling, build-time, production, ai-assisted-development)apt, devto, router) that fit better as a broader existing tagThe 11 that survived are the tags I actually write in.
\nThe build-time validator lives in velite.config.js, the config for Velite, my content pipeline. It runs on every build, for anything published. It checks: the declared pillar of a post must equal the pillar of at least one tag in tags[]. If it doesn't, the build fails.
This sounds bureaucratic. It isn't. It's the way I keep myself honest.
\nSay I write something about what two years of blogging taught me, and I mention in passing that the site runs in Docker. Tag: docker. Declared pillar: reflections. Build dead:
[content-pillars] post 'what-blogging-taught-me' declares pillar='reflections' but no tag in tags[] maps to that pillar. Either add a tag whose registered pillar is 'reflections' or change the declared pillar.\ndocker is registered as homelab. Nothing on the post maps to reflections. The validator won't let me silently have a post that doesn't belong to any tag series. If a post can't anchor any tag series, it shouldn't be published as a tag-anchored post. It should be published as something else, or it should get a tag that earns its place.
The validator also changes how I write. When I sit down to write a post and I want to tag it workflow, I have to ask: is this post part of a series I'm willing to commit to? If yes, fine. If no, the tag dies and I pick a real one.
I don't know if that counts as discipline or just an elaborate way to make my own builds fail. But the vibes never made me stop and ask.
\nThe whole taxonomy lives in two architecture decision records, under docs/adr/ in this site's repo.
ADR 0001 — the four pillars, the tag registration rule, the coherent-series test. This is the constitution.
\nADR 0002 — the SEO policy. How tag pages render, what metadata they expose, how they relate to pillar pages. This is the policy that turns the constitution into something Google can crawl.
\nThe wayfinder pass gave me a rule I could encode in the validator.
\nI knew what the blog was about. I had been writing it for two years. I didn't have the taxonomy for what it was about until I counted the tags.
\nThere will be new tags. New tags require a PR to the registry (src/data/content-pillars.ts) with a one-line rationale that passes the coherent-series test. No agent mediates this. I'm the curator.
That's the right shape. Tags are mine. The agent can write the post, can audit the existing tags, can build the validator. The decision about whether a new tag earns its place is mine.
\nThe death rate felt bad while I was doing it. Felt like I was throwing things away, or being too strict.
\nThen I read a tag page with three posts that actually belonged together, and I realized what the page would have looked like with seven tags on it, half of which lied. The page would have been unreadable. The reader would have clicked and bounced. The tag would have meant nothing.
\nMost of the work in this was deletion. 30 tags out of 41 went. The posts stayed. They're still about what they were about. The surviving tags earned their place.
", "url": "https://lukemanning.ie/blog/i-have-41-posts-i-audited-their-tags-11-survived", "title": "I Have 41 Posts. I Audited Their Tags. 11 Survived.", "summary": "I have 41 blog posts. They each have tags. Until last week, those tags were whatever I thought made sense when I wrote the post. Some recurred. Most didn't. The rest were categories I wanted to exist, or aspects I wanted to mention.
\nI had no system. I had vibes.
\nThen I ran the audit that wiped the registry.
\nI wanted four content pillars, four primary niches that described the shape of my blog. Every published post had to declare a pillar. Tags had to map to pillars. A build-time validator had to fail if a published post declared a pillar that no tag supported.
\nFour pillars:
\nai — AI tooling, agents, OpenCode, Claude Code, agentic coding workflowshomelab — self-hosting, hardware, Unraid, servers, OS setup on machinesrabbit-holes — broad technical pillar: shipping projects + debugging/learning while building thingsreflections — non-tech, opinion, career, expanded thoughtsThe pillars themselves were the easy part.
\nThe hard part was the tags.
\nI ran the audit as a wayfinder pass. One decision per tag.
\nThe mechanics were dull. Every tag lives in a post's frontmatter, so I pulled the frontmatter from all 41 posts, listed every tag with its count, and sorted by that. The agent did the tallying. The judgment calls were all mine.
\nSome tags were obviously load-bearing. projex showed up on every post that mentioned my component library. velite showed up on every post about my content pipeline. homelab showed up on the server posts. github showed up on the recovery and the deprecation posts.
Some tags were obviously decorative. debugging showed up on three posts, all of which were about different kinds of debugging. workflow showed up on five posts, all of which were about different kinds of workflows. ai-assisted-development showed up on one post.
The first rule was: if it recurs, keep it. That got me a first registry with about 48 tags in it, more than the posts actually used. Some were categories I wanted to exist rather than categories I had. It took reading the five workflow posts back to back to see the problem: they had nothing in common. The rule was measuring the wrong thing.
A tag earns its place if there's evidence of a series. At least one other post has to anchor it. A tag that could be folded into a broader existing tag gets folded. A tag that's used once and not part of a series dies. The count gets a hearing, but the posts have to actually belong together.
\napt died. Used once. Subsumed by ubuntu. No reason to keep it.
github stayed. Multiple posts: the Ubuntu apt deprecation post and the git corruption recovery post. A real series about GitHub-shaped problems.
workflow died. Five uses, zero series. The tag was a context label, not a topic.
claude-code stayed. Two posts already, more coming. Real series.
The death rate was high. Of 41 tags that appeared across the 41 posts (the equal counts were an accident), 30 died. 11 survived.
\nThe 11:
\nai: opencode, hermes, claude-codehomelab: docker, zerowork, obsidianrabbit-holes: projex, velite, nextjs, github, ubuntu(The registry also carries the pillar names themselves as tags: ai, homelab, reflections. Those aren't series. They're just the pillars.)
Yes, I could tag any post with the bare pillar name and the validator would wave it through. The validator catches accidents. The coherent-series test is what catches lies. Tagging a post reflections just to get through a build is workflow all over again.
reflections is the only pillar with no series tags. The first genuinely reflective post has to bring its tag through the PR process.
A tag is a promise. When I tag a post workflow, if you click this tag, you'll find a series of posts about workflows. The reader lands on a tag page expecting a coherent collection.
If the tag delivers three posts about three different things, the tag lied. Anyone who clicked it got a pile of nothing. That's on me.
\nI keep going back and forth on whether the test is too strict. It's not, really. A tag with no series is just noise on a tag page.
\nThe 30 tags that died weren't wrong. They were over-promised. They were:
\ndebugging, thinking, meta, lessons-learned, retrospective, burnout)css, styling, build-time, production, ai-assisted-development)apt, devto, router) that fit better as a broader existing tagThe 11 that survived are the tags I actually write in.
\nThe build-time validator lives in velite.config.js, the config for Velite, my content pipeline. It runs on every build, for anything published. It checks: the declared pillar of a post must equal the pillar of at least one tag in tags[]. If it doesn't, the build fails.
This sounds bureaucratic. It isn't. It's the way I keep myself honest.
\nSay I write something about what two years of blogging taught me, and I mention in passing that the site runs in Docker. Tag: docker. Declared pillar: reflections. Build dead:
[content-pillars] post 'what-blogging-taught-me' declares pillar='reflections' but no tag in tags[] maps to that pillar. Either add a tag whose registered pillar is 'reflections' or change the declared pillar.\ndocker is registered as homelab. Nothing on the post maps to reflections. The validator won't let me silently have a post that doesn't belong to any tag series. If a post can't anchor any tag series, it shouldn't be published as a tag-anchored post. It should be published as something else, or it should get a tag that earns its place.
The validator also changes how I write. When I sit down to write a post and I want to tag it workflow, I have to ask: is this post part of a series I'm willing to commit to? If yes, fine. If no, the tag dies and I pick a real one.
I don't know if that counts as discipline or just an elaborate way to make my own builds fail. But the vibes never made me stop and ask.
\nThe whole taxonomy lives in two architecture decision records, under docs/adr/ in this site's repo.
ADR 0001 — the four pillars, the tag registration rule, the coherent-series test. This is the constitution.
\nADR 0002 — the SEO policy. How tag pages render, what metadata they expose, how they relate to pillar pages. This is the policy that turns the constitution into something Google can crawl.
\nThe wayfinder pass gave me a rule I could encode in the validator.
\nI knew what the blog was about. I had been writing it for two years. I didn't have the taxonomy for what it was about until I counted the tags.
\nThere will be new tags. New tags require a PR to the registry (src/data/content-pillars.ts) with a one-line rationale that passes the coherent-series test. No agent mediates this. I'm the curator.
That's the right shape. Tags are mine. The agent can write the post, can audit the existing tags, can build the validator. The decision about whether a new tag earns its place is mine.
\nThe death rate felt bad while I was doing it. Felt like I was throwing things away, or being too strict.
\nThen I read a tag page with three posts that actually belonged together, and I realized what the page would have looked like with seven tags on it, half of which lied. The page would have been unreadable. The reader would have clicked and bounced. The tag would have meant nothing.
\nMost of the work in this was deletion. 30 tags out of 41 went. The posts stayed. They're still about what they were about. The surviving tags earned their place.
", "date_modified": "2026-08-19T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/my-agent-closed-most-projex-issues-in-one-round", "content_html": "On a Saturday afternoon in August, I told my agent to fix every open issue in the Projex repo and prepare a release. There were ten open. Some were HIGH priority. Some were LOW.
\nI went for a walk.
\nWhen I came back, the work had landed across three branches. Each subagent had worked in its own worktree on its own branch. The build was green on each one. The tests were green. The lint was green. The typecheck was green. The release manager subagent had drafted the changelog. Nine of the ten issues were closed. The tenth stayed open — it needed a real union restructure, not a mechanical fix.
\nI had not read a single line of the diff yet.
\nI had a backlog of small things in the Projex repo. Tagged-union cleanups. Type tightening. Documentation gaps. A bug where one of the smart-grid props was a documented prop but a no-op at runtime. A redundancy where two functions with slightly different spellings did the same thing.
\nI described this to my main agent. The main agent looked at the issue tracker, saw the labels (bug, enhancement, documentation), grouped them by file area, and dispatched three subagents in parallel.
One subagent got the package.json + bundling issues. One got the type-system + tagged-union issues. One got the documentation + test-coverage issues. Each one worked in a separate worktree on a separate branch. Each one committed locally and reported back. A fourth subagent, the release manager, handled release prep alongside them: the version bump and the changelog.
\nI watched the transcript. Mostly I stayed out of the way. I made tea.
\nI saw the dispatch messages. I saw the report-back messages. I did not read the intermediate diffs. The subagents were set up to commit per-issue. Each commit was meant to be independently reviewable.
\nA few things I noticed in the report-backs:
\nnormalizeStats and normaliseStats, with the American and British spellings. Both did the same thing. The codebase had drifted to the British spelling in the actual logic. The American spelling was the alias. Both were exported. The subagent deprecated the American one with a JSDoc tag and updated the docs to point at the British spelling.ProjectStats union, it noticed FetchProjectDataResult.commits was using undefined while sibling fields used null. The subagent opened a new issue and included the fix in the same branch.ts-morph, chalk, @inquirer/prompts, commander) were installed by every consumer, even ones who only imported the components. The subagent moved them to optional peerDependencies so consumers importing only components stopped dragging in the CLI bundle.None of these were in my original brief. The subagents went past the edges of what I asked for, in the direction of \"things that were obviously wrong in the same file area.\"
\nThe first time I read any of the code was after all three subagents finished and opened their PRs. I skimmed the diffs before merging. Not a line-by-line review. A sanity check.
\nI was looking for decisions the AI made without asking me. Function names I wouldn't have picked. Behaviour that wasn't in the brief. Edits that touched code outside the file area I asked about. The kind of things a real code review catches, except I was reviewing the decisions, not the code.
\nSome of the diffs were four lines. Some were thirty. None of them were complex enough to need a real review. They were tagged-union narrowings, JSDoc additions, dependency relocations. The kind of work where you skim it once, you understand it, you move on.
\nIf I'd skimmed each PR as it landed, I'd have read the rename with no idea the docs were about to change under it. Reading the batch, I could see the normaliseStats deprecation and the docs update pointing at it in the same sitting. The batch skim was faster than piecemeal would have been.
I didn't push back on any of the code. The three branches each shipped clean. I steered the architecture around the loop, not the code inside it.
\nThe dispatch went out as three parallel opencode run invocations, not three subagents. I asked for that change when the opencode TUI failed on the first attempt and the right path was to skip the interactive layer. I also argued for splitting the release prep out from the fix work, because trying to do both in the same dispatch kept blocking on the release-manager hitting its timeout before the fix branches landed.
My previous loop was one PR at a time. I'd describe an issue to the agent. The agent would open a PR. I'd skim it, sanity-check the decisions, merge or push back. One issue, one PR, one round of skimming. Repeat.
\nFor this kind of small mechanical work, that's fine. It works. But the context switching adds up. Each PR is its own session — its own dispatch, its own transcript, its own review pass. The overhead is small per PR and large per backlog.
\nThe new loop:
\nThe release prep runs alongside the fix work instead of after it. One description covers all of them.
\nI want to be careful about what I'm claiming here. I'm not claiming the subagents did better work than the agent would have done one PR at a time. Most of these issues were mechanical. The interesting decisions — which redundancy to deprecate, which naming to standardize — the agent would have surfaced them either way, given the brief. What I'm claiming is that the per-PR overhead moved out of my hands and the interesting decisions stayed in my hands.
\nI did not read the code while it was being written.
\nIn the old loop, I skimmed each PR after the agent opened it. One PR at a time.
\nIn the new loop, the skim happened after the writing finished across all three PRs. The subagents were the feedback loop during the work. I was the feedback loop at the end.
\nThere's a different cost structure. A wrong fix in the old loop was caught in the per-PR skim, or it shipped. A wrong fix in the new loop is caught in the batch skim, or it ships.
\nI shipped none of the wrong fixes in this batch. The issues were mechanical and the code area was small. If I'd asked the subagents to redesign the normalise function, I would have read every line, pushed back, rewritten pieces.
The loop works for the kind of work that has a clear right answer. The loop does not work for the kind of work that needs taste. I haven't found the line yet.
\nFor this batch, the line was \"moves stuff around, adds JSDoc, narrows types.\" Below the line, I delegated. Above the line, I didn't. The line is in a different place than I would have guessed.
\nI'm going to run this loop again. On a different repo. On a different kind of work.
\nI want to see what happens when the issues aren't mechanical. I want to see where the line moves. I want to see what kinds of work I delegate that I later wish I hadn't, and what kinds I keep that the loop could have handled.
\nI'm not going to delegate design decisions. I'm not going to delegate \"what should this library do\". I'm going to delegate \"make this library do what it already says it does, correctly.\"
\nThe batch skim at the end is non-negotiable. That's the part I own.
", "url": "https://lukemanning.ie/blog/my-agent-closed-most-projex-issues-in-one-round", "title": "My Agent Closed Most of the Open Projex Issues in One Round Without Me Reading the Code", "summary": "On a Saturday afternoon in August, I told my agent to fix every open issue in the Projex repo and prepare a release. There were ten open. Some were HIGH priority. Some were LOW.
\nI went for a walk.
\nWhen I came back, the work had landed across three branches. Each subagent had worked in its own worktree on its own branch. The build was green on each one. The tests were green. The lint was green. The typecheck was green. The release manager subagent had drafted the changelog. Nine of the ten issues were closed. The tenth stayed open — it needed a real union restructure, not a mechanical fix.
\nI had not read a single line of the diff yet.
\nI had a backlog of small things in the Projex repo. Tagged-union cleanups. Type tightening. Documentation gaps. A bug where one of the smart-grid props was a documented prop but a no-op at runtime. A redundancy where two functions with slightly different spellings did the same thing.
\nI described this to my main agent. The main agent looked at the issue tracker, saw the labels (bug, enhancement, documentation), grouped them by file area, and dispatched three subagents in parallel.
One subagent got the package.json + bundling issues. One got the type-system + tagged-union issues. One got the documentation + test-coverage issues. Each one worked in a separate worktree on a separate branch. Each one committed locally and reported back. A fourth subagent, the release manager, handled release prep alongside them: the version bump and the changelog.
\nI watched the transcript. Mostly I stayed out of the way. I made tea.
\nI saw the dispatch messages. I saw the report-back messages. I did not read the intermediate diffs. The subagents were set up to commit per-issue. Each commit was meant to be independently reviewable.
\nA few things I noticed in the report-backs:
\nnormalizeStats and normaliseStats, with the American and British spellings. Both did the same thing. The codebase had drifted to the British spelling in the actual logic. The American spelling was the alias. Both were exported. The subagent deprecated the American one with a JSDoc tag and updated the docs to point at the British spelling.ProjectStats union, it noticed FetchProjectDataResult.commits was using undefined while sibling fields used null. The subagent opened a new issue and included the fix in the same branch.ts-morph, chalk, @inquirer/prompts, commander) were installed by every consumer, even ones who only imported the components. The subagent moved them to optional peerDependencies so consumers importing only components stopped dragging in the CLI bundle.None of these were in my original brief. The subagents went past the edges of what I asked for, in the direction of \"things that were obviously wrong in the same file area.\"
\nThe first time I read any of the code was after all three subagents finished and opened their PRs. I skimmed the diffs before merging. Not a line-by-line review. A sanity check.
\nI was looking for decisions the AI made without asking me. Function names I wouldn't have picked. Behaviour that wasn't in the brief. Edits that touched code outside the file area I asked about. The kind of things a real code review catches, except I was reviewing the decisions, not the code.
\nSome of the diffs were four lines. Some were thirty. None of them were complex enough to need a real review. They were tagged-union narrowings, JSDoc additions, dependency relocations. The kind of work where you skim it once, you understand it, you move on.
\nIf I'd skimmed each PR as it landed, I'd have read the rename with no idea the docs were about to change under it. Reading the batch, I could see the normaliseStats deprecation and the docs update pointing at it in the same sitting. The batch skim was faster than piecemeal would have been.
I didn't push back on any of the code. The three branches each shipped clean. I steered the architecture around the loop, not the code inside it.
\nThe dispatch went out as three parallel opencode run invocations, not three subagents. I asked for that change when the opencode TUI failed on the first attempt and the right path was to skip the interactive layer. I also argued for splitting the release prep out from the fix work, because trying to do both in the same dispatch kept blocking on the release-manager hitting its timeout before the fix branches landed.
My previous loop was one PR at a time. I'd describe an issue to the agent. The agent would open a PR. I'd skim it, sanity-check the decisions, merge or push back. One issue, one PR, one round of skimming. Repeat.
\nFor this kind of small mechanical work, that's fine. It works. But the context switching adds up. Each PR is its own session — its own dispatch, its own transcript, its own review pass. The overhead is small per PR and large per backlog.
\nThe new loop:
\nThe release prep runs alongside the fix work instead of after it. One description covers all of them.
\nI want to be careful about what I'm claiming here. I'm not claiming the subagents did better work than the agent would have done one PR at a time. Most of these issues were mechanical. The interesting decisions — which redundancy to deprecate, which naming to standardize — the agent would have surfaced them either way, given the brief. What I'm claiming is that the per-PR overhead moved out of my hands and the interesting decisions stayed in my hands.
\nI did not read the code while it was being written.
\nIn the old loop, I skimmed each PR after the agent opened it. One PR at a time.
\nIn the new loop, the skim happened after the writing finished across all three PRs. The subagents were the feedback loop during the work. I was the feedback loop at the end.
\nThere's a different cost structure. A wrong fix in the old loop was caught in the per-PR skim, or it shipped. A wrong fix in the new loop is caught in the batch skim, or it ships.
\nI shipped none of the wrong fixes in this batch. The issues were mechanical and the code area was small. If I'd asked the subagents to redesign the normalise function, I would have read every line, pushed back, rewritten pieces.
The loop works for the kind of work that has a clear right answer. The loop does not work for the kind of work that needs taste. I haven't found the line yet.
\nFor this batch, the line was \"moves stuff around, adds JSDoc, narrows types.\" Below the line, I delegated. Above the line, I didn't. The line is in a different place than I would have guessed.
\nI'm going to run this loop again. On a different repo. On a different kind of work.
\nI want to see what happens when the issues aren't mechanical. I want to see where the line moves. I want to see what kinds of work I delegate that I later wish I hadn't, and what kinds I keep that the loop could have handled.
\nI'm not going to delegate design decisions. I'm not going to delegate \"what should this library do\". I'm going to delegate \"make this library do what it already says it does, correctly.\"
\nThe batch skim at the end is non-negotiable. That's the part I own.
", "date_modified": "2026-08-19T00:00:00.000Z", "tags": [ "ai", "opencode", "projex", "github" ] }, { "id": "https://lukemanning.ie/blog/gh-issue-view-failing-ubuntu-deprecation-apt-pin", "content_html": "TL;DR: Ubuntu 24.04's packaged gh (2.45.0) is broken. GitHub sunset Projects (classic), and 2.45.0 still requests that field in its GraphQL query, so what reads like a deprecation warning is actually a hard error that kills every gh issue view and gh pr view. Three problems stacked: the warning was the error, GitHub's apt repo lives at /packages not /apt, and Ubuntu ESM out-pins GitHub at priority 510 vs 500. Fixed on 2.97.0.
I was trying to read an issue on this site's repo:
\ngh issue view 28 --repo ManningWorks/lukemanning-site --commentsWhat came back was this:
\nGraphQL: Projects (classic) is being deprecated in favor of the new Projects\nexperience, see: https://github.blog/changelog/2024-05-23-sunset-notice-projects-classic/.\n(repository.issue.projectCards)\nI asked my AI assistant (opencode) what it meant. It told me it was just a deprecation warning, not an error, and the command works fine.
\nExcept it kept telling me the command had failed. So I pushed back: \"You keep telling me that command fails though.\" It ran the command, and a different error surfaced. This one was mine. In my message I'd written gh issue view 28 --repo --comments with no repo value, assuming it would fill in the blanks. It ran exactly what I'd written. --repo with no value swallowed --comments:
expected the \"[HOST/]OWNER/REPO\" format, got \"--comments\"\nFine. My shorthand, my missing value. With the repo filled in, the original failure came straight back:
\nExit code 1. Zero bytes on stdout. The deprecation message, alone, on stderr.
\nThat's when it clicked. The \"warning\" was the failure. The command produced nothing except a note formatted like a heads-up about the future.
\nThe assistant then decided the deprecation message was a red herring that would only appear once the repo resolved. Also wrong. Twice in one conversation.
\nUbuntu ships gh 2.45.0. That version requests repository.issue.projectCards as part of its GraphQL query for issue views. GitHub sunset Projects (classic) in May 2024 and now returns that field as a hard GraphQL error. A hard error kills the whole query, so every gh issue view and gh pr view on 2.45.x fails with output that reads like a deprecation notice.
This is a known thing: cli/cli#11992. The maintainers' answer is to stop using distro packages and install from GitHub's official repo. GitHub's Linux install docs now say it outright: as of November 2025 they strongly recommend the official Debian packages, since the community-distributed 2.45.x and 2.46.x are broken against current GitHub APIs.
\nSo Ubuntu's gh is broken in a way GitHub officially acknowledges. Weirdly comforting.
\ngh api goes through REST, not GraphQL, so it still worked:
gh api repos/ManningWorks/lukemanning-site/issues/28 --jq '.title, .body'\ngh api repos/ManningWorks/lukemanning-site/issues/28/comments --jq '.[] | .author.login, .body'Clunky, but it let me read the issue while I sorted out the upgrade.
\nThe assistant set up GitHub's apt repo from memory: https://cli.github.com/apt.
The repository 'https://cli.github.com/apt stable Release' does not have a Release file.\nThat's a 404. The repo isn't there. I enjoyed this one. The assistant guessed a URL instead of checking the docs, which is the exact thing it tells me not to do constantly.
\nGitHub's own install docs say it's https://cli.github.com/packages. The assistant followed them this time, keyring staged through /tmp since wget can't write to /etc/apt/keyrings as me:
wget -nv -O /tmp/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg\ncat /tmp/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null\nsudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg\necho \"deb [arch=amd64 signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\" | sudo tee /etc/apt/sources.list.d/github-cli.listRepo added, apt update clean, apt install gh... nothing. Still 2.45.0. Three failure layers, for anyone counting.
apt-cache policy gh explained it:
gh:\n Installed: 2.45.0-1ubuntu0.3+esm3\n Candidate: 2.45.0-1ubuntu0.3+esm3\n Version table:\n 2.97.0 500\n 500 https://cli.github.com/packages stable/main amd64 Packages\n *** 2.45.0-1ubuntu0.3+esm3 510\n 510 https://esm.ubuntu.com/apps/ubuntu noble-apps-security/main amd64 Packages\nGitHub's repo offers 2.97.0 at priority 500, the apt default. Ubuntu ESM pins its version at 510. ESM is Expanded Security Maintenance, the security-update stream that comes with Ubuntu Pro, and this machine is Ubuntu 24.04 (noble), amd64, with Pro enabled. Higher priority wins the candidate slot, even though ESM's 2.45.0 is ancient.
\nAn explicit version bypasses the priority contest:
\nsudo apt install gh=2.97.0That worked. gh --version reported 2.97.0, and gh issue view 28 --comments (from the repo root, so no --repo needed) finally exited 0 with full output.
The explicit install worked, but the candidate was still ESM's 2.45.0. The assistant said I needed a pin file so GitHub's repo wins going forward. Before touching anything in /etc/apt/preferences.d/, I asked it to validate that. Do Ubuntu or GitHub actually document this, or is it forum folklore?
Three primary sources:
\nMy own machine. /etc/apt/preferences.d/ubuntu-pro-esm-apps, shipped by ubuntu-pro-client, pins release o=UbuntuESMApps at 510. The file's own comment says it's deliberate: when ESM is enabled, ESM packages are preferred over non-ESM ones.
man apt_preferences. Priorities from 500 to 990 install a version unless a newer one is already installed. 1000 or higher is required to downgrade. So ESM can't drag me back to 2.45.0, but a plain apt upgrade would never pick up a future GitHub release either. I'd be frozen on 2.97.0.
Canonical's tracker and docs. ubuntu-pro-client issue #3330 is someone hitting exactly this: a newer fish from a PPA, ignored in favour of ESM's. A Canonical maintainer closed it as intended, because cloud customers didn't want ESM security fixes silently reverted. The stated remedy:
\n\n\nmanually configure apt... by creating a preferences file pinning the PPA to a higher version than ESM.
\n
Canonical's Pro Client docs say close to the same: give the third-party repo at least 510.
\nSo the pin is real, and documented. Good.
\nThose two sources don't quite agree, it turns out. The docs allow equal: at least 510. The issue thread says higher than ESM. And what apt actually does when two repos sit at the same priority, I couldn't find in man apt_preferences. Maybe there's a tie-break rule somewhere. I didn't find it.
I let the assistant pick the number in the end, within the bounds the man page had already given me. It went with 600: unconditionally \"GitHub's repo is authoritative for gh\", above both suggested floors, and below 1000 so nothing can ever downgrade me.
\nWorks for me. 510 would satisfy the docs, but a pin that only ties the thing it's fighting isn't a config I want to reason about again in six months.
\n/etc/apt/preferences.d/gh:
# gh: prefer GitHub official apt repo over Ubuntu ESM pin (510).\n# ESM gh 2.45.x is broken vs current GitHub APIs - see cli/cli#11992.\n# Canonical documents this remedy: https://documentation.ubuntu.com/pro-client/en/latest/explanations/about_esm/\nPackage: gh\nPin: origin cli.github.com\nPin-Priority: 600\nThen I verified with apt-cache policy gh, which now shows *** 2.97.0 600. I checked because the assistant had flagged the failure mode to watch for: if the origin in the pin doesn't match the host in the sources list, there's no error. The pin just doesn't apply.
Any one of these three alone would have been a proper rabbit hole.
\nThe assistant was confidently wrong twice, and that's the part I keep relearning. First that the message was harmless, then that it was a red herring. Both times, actually running the command with stdout and stderr separated settled it in seconds. Asking an AI what a command does is asking it to hallucinate from training data. The apt URL guess showed exactly how that goes.
\ngh works now. Which is nice, because I originally just wanted to read one issue.
", "url": "https://lukemanning.ie/blog/gh-issue-view-failing-ubuntu-deprecation-apt-pin", "title": "gh issue view Kept Failing Because Ubuntu's ESM Outranks GitHub's Repo", "summary": "TL;DR: Ubuntu 24.04's packaged gh (2.45.0) is broken. GitHub sunset Projects (classic), and 2.45.0 still requests that field in its GraphQL query, so what reads like a deprecation warning is actually a hard error that kills every gh issue view and gh pr view. Three problems stacked: the warning was the error, GitHub's apt repo lives at /packages not /apt, and Ubuntu ESM out-pins GitHub at priority 510 vs 500. Fixed on 2.97.0.
I was trying to read an issue on this site's repo:
\ngh issue view 28 --repo ManningWorks/lukemanning-site --commentsWhat came back was this:
\nGraphQL: Projects (classic) is being deprecated in favor of the new Projects\nexperience, see: https://github.blog/changelog/2024-05-23-sunset-notice-projects-classic/.\n(repository.issue.projectCards)\nI asked my AI assistant (opencode) what it meant. It told me it was just a deprecation warning, not an error, and the command works fine.
\nExcept it kept telling me the command had failed. So I pushed back: \"You keep telling me that command fails though.\" It ran the command, and a different error surfaced. This one was mine. In my message I'd written gh issue view 28 --repo --comments with no repo value, assuming it would fill in the blanks. It ran exactly what I'd written. --repo with no value swallowed --comments:
expected the \"[HOST/]OWNER/REPO\" format, got \"--comments\"\nFine. My shorthand, my missing value. With the repo filled in, the original failure came straight back:
\nExit code 1. Zero bytes on stdout. The deprecation message, alone, on stderr.
\nThat's when it clicked. The \"warning\" was the failure. The command produced nothing except a note formatted like a heads-up about the future.
\nThe assistant then decided the deprecation message was a red herring that would only appear once the repo resolved. Also wrong. Twice in one conversation.
\nUbuntu ships gh 2.45.0. That version requests repository.issue.projectCards as part of its GraphQL query for issue views. GitHub sunset Projects (classic) in May 2024 and now returns that field as a hard GraphQL error. A hard error kills the whole query, so every gh issue view and gh pr view on 2.45.x fails with output that reads like a deprecation notice.
This is a known thing: cli/cli#11992. The maintainers' answer is to stop using distro packages and install from GitHub's official repo. GitHub's Linux install docs now say it outright: as of November 2025 they strongly recommend the official Debian packages, since the community-distributed 2.45.x and 2.46.x are broken against current GitHub APIs.
\nSo Ubuntu's gh is broken in a way GitHub officially acknowledges. Weirdly comforting.
\ngh api goes through REST, not GraphQL, so it still worked:
gh api repos/ManningWorks/lukemanning-site/issues/28 --jq '.title, .body'\ngh api repos/ManningWorks/lukemanning-site/issues/28/comments --jq '.[] | .author.login, .body'Clunky, but it let me read the issue while I sorted out the upgrade.
\nThe assistant set up GitHub's apt repo from memory: https://cli.github.com/apt.
The repository 'https://cli.github.com/apt stable Release' does not have a Release file.\nThat's a 404. The repo isn't there. I enjoyed this one. The assistant guessed a URL instead of checking the docs, which is the exact thing it tells me not to do constantly.
\nGitHub's own install docs say it's https://cli.github.com/packages. The assistant followed them this time, keyring staged through /tmp since wget can't write to /etc/apt/keyrings as me:
wget -nv -O /tmp/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg\ncat /tmp/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null\nsudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg\necho \"deb [arch=amd64 signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\" | sudo tee /etc/apt/sources.list.d/github-cli.listRepo added, apt update clean, apt install gh... nothing. Still 2.45.0. Three failure layers, for anyone counting.
apt-cache policy gh explained it:
gh:\n Installed: 2.45.0-1ubuntu0.3+esm3\n Candidate: 2.45.0-1ubuntu0.3+esm3\n Version table:\n 2.97.0 500\n 500 https://cli.github.com/packages stable/main amd64 Packages\n *** 2.45.0-1ubuntu0.3+esm3 510\n 510 https://esm.ubuntu.com/apps/ubuntu noble-apps-security/main amd64 Packages\nGitHub's repo offers 2.97.0 at priority 500, the apt default. Ubuntu ESM pins its version at 510. ESM is Expanded Security Maintenance, the security-update stream that comes with Ubuntu Pro, and this machine is Ubuntu 24.04 (noble), amd64, with Pro enabled. Higher priority wins the candidate slot, even though ESM's 2.45.0 is ancient.
\nAn explicit version bypasses the priority contest:
\nsudo apt install gh=2.97.0That worked. gh --version reported 2.97.0, and gh issue view 28 --comments (from the repo root, so no --repo needed) finally exited 0 with full output.
The explicit install worked, but the candidate was still ESM's 2.45.0. The assistant said I needed a pin file so GitHub's repo wins going forward. Before touching anything in /etc/apt/preferences.d/, I asked it to validate that. Do Ubuntu or GitHub actually document this, or is it forum folklore?
Three primary sources:
\nMy own machine. /etc/apt/preferences.d/ubuntu-pro-esm-apps, shipped by ubuntu-pro-client, pins release o=UbuntuESMApps at 510. The file's own comment says it's deliberate: when ESM is enabled, ESM packages are preferred over non-ESM ones.
man apt_preferences. Priorities from 500 to 990 install a version unless a newer one is already installed. 1000 or higher is required to downgrade. So ESM can't drag me back to 2.45.0, but a plain apt upgrade would never pick up a future GitHub release either. I'd be frozen on 2.97.0.
Canonical's tracker and docs. ubuntu-pro-client issue #3330 is someone hitting exactly this: a newer fish from a PPA, ignored in favour of ESM's. A Canonical maintainer closed it as intended, because cloud customers didn't want ESM security fixes silently reverted. The stated remedy:
\n\n\nmanually configure apt... by creating a preferences file pinning the PPA to a higher version than ESM.
\n
Canonical's Pro Client docs say close to the same: give the third-party repo at least 510.
\nSo the pin is real, and documented. Good.
\nThose two sources don't quite agree, it turns out. The docs allow equal: at least 510. The issue thread says higher than ESM. And what apt actually does when two repos sit at the same priority, I couldn't find in man apt_preferences. Maybe there's a tie-break rule somewhere. I didn't find it.
I let the assistant pick the number in the end, within the bounds the man page had already given me. It went with 600: unconditionally \"GitHub's repo is authoritative for gh\", above both suggested floors, and below 1000 so nothing can ever downgrade me.
\nWorks for me. 510 would satisfy the docs, but a pin that only ties the thing it's fighting isn't a config I want to reason about again in six months.
\n/etc/apt/preferences.d/gh:
# gh: prefer GitHub official apt repo over Ubuntu ESM pin (510).\n# ESM gh 2.45.x is broken vs current GitHub APIs - see cli/cli#11992.\n# Canonical documents this remedy: https://documentation.ubuntu.com/pro-client/en/latest/explanations/about_esm/\nPackage: gh\nPin: origin cli.github.com\nPin-Priority: 600\nThen I verified with apt-cache policy gh, which now shows *** 2.97.0 600. I checked because the assistant had flagged the failure mode to watch for: if the origin in the pin doesn't match the host in the sources list, there's no error. The pin just doesn't apply.
Any one of these three alone would have been a proper rabbit hole.
\nThe assistant was confidently wrong twice, and that's the part I keep relearning. First that the message was harmless, then that it was a red herring. Both times, actually running the command with stdout and stderr separated settled it in seconds. Asking an AI what a command does is asking it to hallucinate from training data. The apt URL guess showed exactly how that goes.
\ngh works now. Which is nice, because I originally just wanted to read one issue.
", "date_modified": "2026-08-14T00:00:00.000Z", "tags": [ "github", "ubuntu" ] }, { "id": "https://lukemanning.ie/blog/hermes-profiles-to-docker-part-two", "content_html": "This is a follow-up to my post on running Hermes profiles in Docker containers. In that post I described mounting each profile to its own container, setting up systemd to start them on boot, and declaring victory.
\nI was wrong.
\nNot wrong about the architecture. Wrong about whether it was actually working.
\nTL;DR: I declared the Docker setup working. Then cron jobs vanished into the wrong database, sage was running two Hermes instances, and the actual bug turned out to be a Python loop that had nothing to do with Docker.
\nI ran docker exec hermes-sage ps aux to verify sage was healthy. It showed one process. Good. I fired a test cron on sage. It said it created successfully. I fired a test cron on rex. It said it created successfully. I waited.
Nothing arrived.
\nI assumed the Telegram bots weren't set up correctly. I went down a whole path of checking bot tokens, allowed user lists, TELEGRAM_HOME_CHANNEL settings. Then I checked the logs and found something stranger.
Sage's cron engine wasn't running the jobs. Neither was rex's. They were being created (the CLI returned success), but they were going into the host's state database, not the container's.
\nAnd underneath that, I discovered something worse: sage wasn't running one Hermes instance. It was running two.
\nThe Docker entrypoint for the Hermes image is /init, which is s6-overlay. s6-overlay scans /run/service/ and starts everything it finds there. My compose file passed --profile sage to the gateway command, which should have meant \"run sage profile only.\"
What actually happened: the compose command: was ignored. The ENTRYPOINT (/init) runs as PID 1, starts s6, and s6 starts all the services in /run/service/, gateway-default and gateway-sage both. Two Hermes instances, same process tree.
The ps aux I'd run to \"verify\" sage was healthy showed one gateway at the top of the output, so I stopped reading. The output ran longer than one screen. When I finally ran docker exec hermes-sage ps aux | grep gateway, two gateway processes showed up: the one I expected, and a second one nested under s6 that I'd scrolled straight past.
The compose command: instruction doesn't override an ENTRYPOINT. It gets handed to the entrypoint as arguments instead. That's in Docker's docs under how ENTRYPOINT and CMD interact. I'd never internalised it.
Once I grasped that sage was running two instances, the cron mystery made more sense. The CLI command hermes cron create was running inside the container, but it reads its config from environment variables, HOME especially, since that's where Hermes looks for its config directory.
I checked what HOME actually was inside the container:
\n$ docker exec hermes-sage env | grep HOME\nHOME=/home/lukeThat's the hermes user's passwd entry, not /opt/data. So when hermes cron create ran without --profile sage, it looked for config at /home/luke/.hermes, which doesn't exist in the container, and fell back to writing jobs to /opt/data/cron/jobs.json instead of /opt/data/profiles/sage/cron/jobs.json.
The sage gateway was reading from the right place. The cron CLI was writing to the wrong place. Jobs created successfully. Jobs never fired.
\nThe fix was passing --profile sage to every cron command inside the container. But I also had to fix HOME, which led to the next problem.
I wanted the hermes process to run with HOME=/opt/data so it read from the right config. The entrypoint script ran as root, then used su hermes to drop privileges. Easy enough.
su -m is meant to preserve the parent environment, so I set HOME=/opt/data before calling su and expected it to carry through. It didn't. The shell su spawned was resetting HOME back to the hermes user's passwd entry (/home/luke) on the way up, undoing what su -m had preserved. By the time hermes actually ran, HOME had been clobbered again.
The reliable fix was env -i, which wipes the environment entirely before setting only what I want. Nothing left for the shell to reset:
exec env -i HOME=/opt/data HERMES_HOME=/opt/data HERMES_PROFILE=sage \\\n su -m -s /bin/sh hermes -c \"exec hermes gateway run --profile sage\"env -i clears everything, the explicit vars set what I need, and su -m preserves that clean state. hermes starts with exactly the HOME I specify.
To stop gateway-default from starting, I needed to keep s6 from scanning it. The cleanest approach was replacing PID 1 entirely with a custom script that:
stage2-hook.sh for Hermes bootstrap (UID remapping, chown)gateway-default via s6-svc -denv -i exec line from aboveThen the compose file binds the script as the entrypoint:
\nentrypoint: [\"/entrypoint.sh\"]\nvolumes:\n - /home/luke/.hermes/docker/entrypoints/sage-only.sh:/entrypoint.sh:roNow sage starts exactly one Hermes instance. No gateway-default. No confusion.
\nOnce I had real isolation working, the crons fired. The sage cron engine ran its job. The rex cron engine ran its job. Both logged completed successfully.
No Telegram messages arrived.
\nThe error: Telegram send failed: Chat not found.
Sage has its own Telegram bot. Rex has its own Telegram bot. Separate bots, separate tokens. A Telegram bot can only send messages to people who have messaged that specific bot first. I'd only ever messaged the default Hermes bot, which knew about my chat. Sage's bot had never seen me.
\nThe second issue was TELEGRAM_HOME_CHANNEL=RealLukeManning in the .env. That's a username, not a chat ID. The Telegram Bot API accepts numeric chat_id for any chat, but only public channels and supergroups can be addressed via @username — for private chats (the home chat here), the API silently fails on a username. Sage was using the username and failing silently.
The fix: message each bot directly first, or use numeric chat IDs in the delivery target (telegram:491962736, not telegram:RealLukeManning).
I thought the Telegram issue was just setup. Then I noticed sage's logs showed its Telegram module attempting to connect, but the bot token wasn't in the container's config.
\nThe .env with the bot token was on the host at ~/.hermes/profiles/sage/.env. The container mounts the profile directory to /opt/data/profiles/sage. The hermes process runs from /opt/data. No .env at /opt/data.
The compose file wasn't passing it through:
\n# Missing\nenv_file:\n - /home/luke/.hermes/profiles/sage/.envWithout the token, the Telegram connection failed gracefully, logged a warning, and didn't die. Messages never arrived.
\nWith all fixes in place, I fired simultaneous test crons on both containers. Both ran. Both Telegram bots delivered. Five seconds apart, completely independent.
\nSage: one instance, sage profile, sage bot, sage cron. Rex: one instance, rex profile, rex bot, rex cron. Each container starting independently via systemd, each with its .env passed through, cron jobs created with --profile and numeric chat IDs.
I thought that was it. The containers were finally doing what I'd built them to do.
\nThen last Tuesday I got a message from Sage at 8am.
\nThe daily system health check I'd set up months ago, before Docker and before any of this, was delivering through Sage's Telegram bot instead of the default gateway.
\nI swore up and down I'd fixed this. I had not fixed this.
\nThe health check runs every morning at 8am. Disk, swap, fail2ban, SSH failures. Then it delivers the result to Telegram. Crucially, it runs on the bare-metal default gateway, the one I never put in a container. Not sage, not rex.
\nThe job itself was fine. The delivery was the problem. I opened the health-check cron job to see what it actually called, and found it was running a skill called hermes-telegram-send, one I didn't write, generated by an LLM using a template. That skill had one job: send a Telegram message from a cron context.
The skill worked by loading environment variables from profile .env files, in this order:
for profile in [\"rex\", \"sage\", \"default\"]:\n env_file = Path(f\"/home/luke/.hermes/profiles/{profile}/.env\")\n if env_file.exists():\n for line in env_file.read_text().splitlines():\n # load the tokenrex/.env exists, loads token. sage/.env exists, overwrites the token. default/.env doesn't exist, skipped.
Sage's Telegram bot token was the last one loaded. So when the health check cron ran, it used Sage's bot to send the message.
\nThe message came from Sage. Because the skill hardcoded [\"rex\", \"sage\", \"default\"] and default didn't exist.
This is the part that felt stupid to realise.
\nSage was never misconfigured. She wasn't \"replying when she shouldn't.\" She was doing exactly what her container was set up to do. The Docker isolation I'd spent a whole post documenting and debugging was completely correct. Separate containers, separate bots, separate processes. All working.
\nThe bug wasn't in Docker. It wasn't in the architecture. It was in a Python loop in a skill that was generated without thinking about what happens when one of the hardcoded profile names doesn't exist.
\nThe loop was supposed to try multiple profiles in case one didn't have a token. It would load rex, then sage, then default. The last one loaded would be the one used.
But there's no default profile directory. There's a bare-metal Hermes gateway running directly on the host, with its own .env at ~/.hermes/.env. That file has the actual Telegram token for the main bot.
The skill didn't know about ~/.hermes/.env. It only knew about the profile subdirectories.
The skill now loads ~/.hermes/.env first as a baseline (the bare-metal gateway's token), then profile .env files only fill in empty slots. They never overwrite what's already set.
# ~/.hermes/.env loads FIRST as baseline\nmain_env = Path(f\"{hermes_home}/.env\")\nif main_env.exists():\n for line in main_env.read_text().splitlines():\n if not line.strip() or line.lstrip().startswith(\"#\") or \"=\" not in line:\n continue\n k, v = line.split(\"=\", 1)\n os.environ[k] = v # no guard, this is the baseline\n\n# Profile files only fill empty slots, never overwrite\nprofile_order = ([current_profile] if current_profile else []) + [\"rex\", \"sage\"]\nfor profile in profile_order:\n env_file = Path(f\"{hermes_home}/profiles/{profile}/.env\")\n if env_file.exists():\n for line in env_file.read_text().splitlines():\n if not line.strip() or line.lstrip().startswith(\"#\") or \"=\" not in line:\n continue\n k, v = line.split(\"=\", 1)\n if k not in os.environ: # only fill empty slots\n os.environ[k] = vThe old code had two problems. First, when HERMES_PROFILE is empty (bare-metal default), the current profile list is empty and [\"rex\", \"sage\"] loads in that order, so sage overwrites rex. Second, the profile loop had no guard. os.environ[k] = v always overwrites, so even if the main .env loaded last, it was already too late. The fix: main .env first (no guard), profile files second (with if k not in os.environ guard).
The health check at 8am tomorrow should come from the right bot. For real this time.
\nThe implementation had three layers of subtle breakage. The compose command: doesn't override an ENTRYPOINT; if the image has one, the command gets passed to it as arguments. HOME matters more than I expected when su-ing to another user; env -i is the reliable way to lock it. And separate containers don't mean isolated if the entrypoint starts everything inside them regardless.
I fixed all of that. It was real work. And then the bug that actually mattered turned out to be none of it.
\nThree things I keep having to re-learn:
\nInfrastructure work doesn't protect you from code bugs. I spent weeks on Docker containers, systemd services, separate Telegram bots. All correct, all irrelevant to the actual symptom. A hardcoded list of profile names in a Python loop. The containers couldn't catch that, because containers don't catch Python logic errors.
\nLLM-generated skills inherit LLM failure modes. The skill came from a template with [\"rex\", \"sage\", \"default\"] baked in. Nobody stopped to ask what happens when default doesn't exist. That kind of assumption sits in code for months before anyone notices.
A fix I didn't verify was never really a fix. I thought I'd solved the Sage problem once isolation was working. The real fix had two subtle bugs hiding in it: an empty HERMES_PROFILE that silently disabled the \"current profile first\" logic, and a profile loop that overwrote tokens without checking if one was already set. I should have verified instead of trusting it.
The Docker setup is better now than before I started. The isolation is real. But the real fix required iterating on a Python loop that had nothing to do with Docker.
", "url": "https://lukemanning.ie/blog/hermes-profiles-to-docker-part-two", "title": "My Docker Containers Were Working. The Bug Was in a Python Loop.", "summary": "This is a follow-up to my post on running Hermes profiles in Docker containers. In that post I described mounting each profile to its own container, setting up systemd to start them on boot, and declaring victory.
\nI was wrong.
\nNot wrong about the architecture. Wrong about whether it was actually working.
\nTL;DR: I declared the Docker setup working. Then cron jobs vanished into the wrong database, sage was running two Hermes instances, and the actual bug turned out to be a Python loop that had nothing to do with Docker.
\nI ran docker exec hermes-sage ps aux to verify sage was healthy. It showed one process. Good. I fired a test cron on sage. It said it created successfully. I fired a test cron on rex. It said it created successfully. I waited.
Nothing arrived.
\nI assumed the Telegram bots weren't set up correctly. I went down a whole path of checking bot tokens, allowed user lists, TELEGRAM_HOME_CHANNEL settings. Then I checked the logs and found something stranger.
Sage's cron engine wasn't running the jobs. Neither was rex's. They were being created (the CLI returned success), but they were going into the host's state database, not the container's.
\nAnd underneath that, I discovered something worse: sage wasn't running one Hermes instance. It was running two.
\nThe Docker entrypoint for the Hermes image is /init, which is s6-overlay. s6-overlay scans /run/service/ and starts everything it finds there. My compose file passed --profile sage to the gateway command, which should have meant \"run sage profile only.\"
What actually happened: the compose command: was ignored. The ENTRYPOINT (/init) runs as PID 1, starts s6, and s6 starts all the services in /run/service/, gateway-default and gateway-sage both. Two Hermes instances, same process tree.
The ps aux I'd run to \"verify\" sage was healthy showed one gateway at the top of the output, so I stopped reading. The output ran longer than one screen. When I finally ran docker exec hermes-sage ps aux | grep gateway, two gateway processes showed up: the one I expected, and a second one nested under s6 that I'd scrolled straight past.
The compose command: instruction doesn't override an ENTRYPOINT. It gets handed to the entrypoint as arguments instead. That's in Docker's docs under how ENTRYPOINT and CMD interact. I'd never internalised it.
Once I grasped that sage was running two instances, the cron mystery made more sense. The CLI command hermes cron create was running inside the container, but it reads its config from environment variables, HOME especially, since that's where Hermes looks for its config directory.
I checked what HOME actually was inside the container:
\n$ docker exec hermes-sage env | grep HOME\nHOME=/home/lukeThat's the hermes user's passwd entry, not /opt/data. So when hermes cron create ran without --profile sage, it looked for config at /home/luke/.hermes, which doesn't exist in the container, and fell back to writing jobs to /opt/data/cron/jobs.json instead of /opt/data/profiles/sage/cron/jobs.json.
The sage gateway was reading from the right place. The cron CLI was writing to the wrong place. Jobs created successfully. Jobs never fired.
\nThe fix was passing --profile sage to every cron command inside the container. But I also had to fix HOME, which led to the next problem.
I wanted the hermes process to run with HOME=/opt/data so it read from the right config. The entrypoint script ran as root, then used su hermes to drop privileges. Easy enough.
su -m is meant to preserve the parent environment, so I set HOME=/opt/data before calling su and expected it to carry through. It didn't. The shell su spawned was resetting HOME back to the hermes user's passwd entry (/home/luke) on the way up, undoing what su -m had preserved. By the time hermes actually ran, HOME had been clobbered again.
The reliable fix was env -i, which wipes the environment entirely before setting only what I want. Nothing left for the shell to reset:
exec env -i HOME=/opt/data HERMES_HOME=/opt/data HERMES_PROFILE=sage \\\n su -m -s /bin/sh hermes -c \"exec hermes gateway run --profile sage\"env -i clears everything, the explicit vars set what I need, and su -m preserves that clean state. hermes starts with exactly the HOME I specify.
To stop gateway-default from starting, I needed to keep s6 from scanning it. The cleanest approach was replacing PID 1 entirely with a custom script that:
stage2-hook.sh for Hermes bootstrap (UID remapping, chown)gateway-default via s6-svc -denv -i exec line from aboveThen the compose file binds the script as the entrypoint:
\nentrypoint: [\"/entrypoint.sh\"]\nvolumes:\n - /home/luke/.hermes/docker/entrypoints/sage-only.sh:/entrypoint.sh:roNow sage starts exactly one Hermes instance. No gateway-default. No confusion.
\nOnce I had real isolation working, the crons fired. The sage cron engine ran its job. The rex cron engine ran its job. Both logged completed successfully.
No Telegram messages arrived.
\nThe error: Telegram send failed: Chat not found.
Sage has its own Telegram bot. Rex has its own Telegram bot. Separate bots, separate tokens. A Telegram bot can only send messages to people who have messaged that specific bot first. I'd only ever messaged the default Hermes bot, which knew about my chat. Sage's bot had never seen me.
\nThe second issue was TELEGRAM_HOME_CHANNEL=RealLukeManning in the .env. That's a username, not a chat ID. The Telegram Bot API accepts numeric chat_id for any chat, but only public channels and supergroups can be addressed via @username — for private chats (the home chat here), the API silently fails on a username. Sage was using the username and failing silently.
The fix: message each bot directly first, or use numeric chat IDs in the delivery target (telegram:491962736, not telegram:RealLukeManning).
I thought the Telegram issue was just setup. Then I noticed sage's logs showed its Telegram module attempting to connect, but the bot token wasn't in the container's config.
\nThe .env with the bot token was on the host at ~/.hermes/profiles/sage/.env. The container mounts the profile directory to /opt/data/profiles/sage. The hermes process runs from /opt/data. No .env at /opt/data.
The compose file wasn't passing it through:
\n# Missing\nenv_file:\n - /home/luke/.hermes/profiles/sage/.envWithout the token, the Telegram connection failed gracefully, logged a warning, and didn't die. Messages never arrived.
\nWith all fixes in place, I fired simultaneous test crons on both containers. Both ran. Both Telegram bots delivered. Five seconds apart, completely independent.
\nSage: one instance, sage profile, sage bot, sage cron. Rex: one instance, rex profile, rex bot, rex cron. Each container starting independently via systemd, each with its .env passed through, cron jobs created with --profile and numeric chat IDs.
I thought that was it. The containers were finally doing what I'd built them to do.
\nThen last Tuesday I got a message from Sage at 8am.
\nThe daily system health check I'd set up months ago, before Docker and before any of this, was delivering through Sage's Telegram bot instead of the default gateway.
\nI swore up and down I'd fixed this. I had not fixed this.
\nThe health check runs every morning at 8am. Disk, swap, fail2ban, SSH failures. Then it delivers the result to Telegram. Crucially, it runs on the bare-metal default gateway, the one I never put in a container. Not sage, not rex.
\nThe job itself was fine. The delivery was the problem. I opened the health-check cron job to see what it actually called, and found it was running a skill called hermes-telegram-send, one I didn't write, generated by an LLM using a template. That skill had one job: send a Telegram message from a cron context.
The skill worked by loading environment variables from profile .env files, in this order:
for profile in [\"rex\", \"sage\", \"default\"]:\n env_file = Path(f\"/home/luke/.hermes/profiles/{profile}/.env\")\n if env_file.exists():\n for line in env_file.read_text().splitlines():\n # load the tokenrex/.env exists, loads token. sage/.env exists, overwrites the token. default/.env doesn't exist, skipped.
Sage's Telegram bot token was the last one loaded. So when the health check cron ran, it used Sage's bot to send the message.
\nThe message came from Sage. Because the skill hardcoded [\"rex\", \"sage\", \"default\"] and default didn't exist.
This is the part that felt stupid to realise.
\nSage was never misconfigured. She wasn't \"replying when she shouldn't.\" She was doing exactly what her container was set up to do. The Docker isolation I'd spent a whole post documenting and debugging was completely correct. Separate containers, separate bots, separate processes. All working.
\nThe bug wasn't in Docker. It wasn't in the architecture. It was in a Python loop in a skill that was generated without thinking about what happens when one of the hardcoded profile names doesn't exist.
\nThe loop was supposed to try multiple profiles in case one didn't have a token. It would load rex, then sage, then default. The last one loaded would be the one used.
But there's no default profile directory. There's a bare-metal Hermes gateway running directly on the host, with its own .env at ~/.hermes/.env. That file has the actual Telegram token for the main bot.
The skill didn't know about ~/.hermes/.env. It only knew about the profile subdirectories.
The skill now loads ~/.hermes/.env first as a baseline (the bare-metal gateway's token), then profile .env files only fill in empty slots. They never overwrite what's already set.
# ~/.hermes/.env loads FIRST as baseline\nmain_env = Path(f\"{hermes_home}/.env\")\nif main_env.exists():\n for line in main_env.read_text().splitlines():\n if not line.strip() or line.lstrip().startswith(\"#\") or \"=\" not in line:\n continue\n k, v = line.split(\"=\", 1)\n os.environ[k] = v # no guard, this is the baseline\n\n# Profile files only fill empty slots, never overwrite\nprofile_order = ([current_profile] if current_profile else []) + [\"rex\", \"sage\"]\nfor profile in profile_order:\n env_file = Path(f\"{hermes_home}/profiles/{profile}/.env\")\n if env_file.exists():\n for line in env_file.read_text().splitlines():\n if not line.strip() or line.lstrip().startswith(\"#\") or \"=\" not in line:\n continue\n k, v = line.split(\"=\", 1)\n if k not in os.environ: # only fill empty slots\n os.environ[k] = vThe old code had two problems. First, when HERMES_PROFILE is empty (bare-metal default), the current profile list is empty and [\"rex\", \"sage\"] loads in that order, so sage overwrites rex. Second, the profile loop had no guard. os.environ[k] = v always overwrites, so even if the main .env loaded last, it was already too late. The fix: main .env first (no guard), profile files second (with if k not in os.environ guard).
The health check at 8am tomorrow should come from the right bot. For real this time.
\nThe implementation had three layers of subtle breakage. The compose command: doesn't override an ENTRYPOINT; if the image has one, the command gets passed to it as arguments. HOME matters more than I expected when su-ing to another user; env -i is the reliable way to lock it. And separate containers don't mean isolated if the entrypoint starts everything inside them regardless.
I fixed all of that. It was real work. And then the bug that actually mattered turned out to be none of it.
\nThree things I keep having to re-learn:
\nInfrastructure work doesn't protect you from code bugs. I spent weeks on Docker containers, systemd services, separate Telegram bots. All correct, all irrelevant to the actual symptom. A hardcoded list of profile names in a Python loop. The containers couldn't catch that, because containers don't catch Python logic errors.
\nLLM-generated skills inherit LLM failure modes. The skill came from a template with [\"rex\", \"sage\", \"default\"] baked in. Nobody stopped to ask what happens when default doesn't exist. That kind of assumption sits in code for months before anyone notices.
A fix I didn't verify was never really a fix. I thought I'd solved the Sage problem once isolation was working. The real fix had two subtle bugs hiding in it: an empty HERMES_PROFILE that silently disabled the \"current profile first\" logic, and a profile loop that overwrote tokens without checking if one was already set. I should have verified instead of trusting it.
The Docker setup is better now than before I started. The isolation is real. But the real fix required iterating on a Python loop that had nothing to do with Docker.
", "date_modified": "2026-07-20T00:00:00.000Z", "tags": [ "hermes", "homelab", "docker" ] }, { "id": "https://lukemanning.ie/blog/hermes-profiles-to-docker", "content_html": "I ran Hermes (the self-hosted agent I use for reading and research and a few other jobs) with three profiles: default, sage, and rex. Each was a separate persona with its own skills and its own Telegram bot.
\nThey were gateway profiles. In Hermes, the gateway is the long-running process that polls Telegram, runs scheduled jobs, and executes skills. \"Profiles\" means one gateway binary, one process manager, just different configs passed in via --profile.
One thing worth saying up front. This post is the \"why I tried containers\" half of the story. When I went to verify the setup, it wasn't actually working yet, and that's covered in part two of the series. I'm keeping this one focused on the reasoning and the container plumbing, because that part still stands even though my diagnosis turned out to be off.
\nThe symptom was cron replies coming from the wrong profile, and it was inconsistent, which is what made it hard to pin down. Sometimes a scheduled job would fire and default and sage would both reply. Sometimes only rex would send the update, when it wasn't his job to. It never happened with messages I sent directly — only cron.
\nMy theory at the time was that the profiles shared too much. One scheduler, one process tree, no hard boundary between them, so jobs bled across. Three profiles all live in the same process, so when a cron job fired, I figured whichever gateway instance was free picked it up.
\nThat theory turned out to be mostly wrong, which is a whole separate story. I'm laying it out anyway, because it's what drove me to containers, and the architecture reasoning is sound even if the diagnosis wasn't.
\nWhat I didn't realise at the time: gateway profiles aren't separate services. They're separate config directories, separate skill directories, separate .env files, and a --profile flag handed to the same gateway binary. Same process tree. Same supervisor. No hard boundary when one of them misbehaves.
I'd been treating them like independent services. They're not.
\nThe Hermes docs recommend one container hosting all profiles, with s6-overlay (a process supervisor designed for containers) managing each profile as a first-class service. Mount the whole ~/.hermes directory to /opt/data, create profiles with hermes profile create, let s6 start and stop them.
I didn't think that would solve what I was seeing. With one container and s6 running every profile, sage and rex are still co-located processes sharing a network namespace and a data directory. If the problem was jobs bleeding across profiles, bundling them into one container wouldn't stop any of it. They'd just be supervised versions of the same shared setup.
\nSo I ran separate containers for sage and rex, each mounting only its own profile directory. Real process isolation: separate network namespaces, separate PID 1, separate Telegram polling loops. At the process level they genuinely cannot interfere with each other.
\nThe architecture was right, it just wasn't the cause of what I was seeing. That part's in the verification post.
\nThe mount paths. I spent far too long on this.
\nThe profile needs to live at /opt/data/profiles/<name> inside the container, not at /opt/data. I kept mounting the rex profile to /opt/data, and Hermes would log Error: Profile 'rex' does not exist. Create it with: hermes profile create rex. Same files on the host, same mount command, but Hermes couldn't find the profile because it was looking in the wrong place.
The fix was obvious once I saw it:
\n# Wrong — mounts to /opt/data, Hermes expects /opt/data/profiles/rex\n- /home/luke/.hermes/profiles/rex:/opt/data\n\n# Right\n- /home/luke/.hermes/profiles/rex:/opt/data/profiles/rexThe containers weren't the wrong architecture. The paths were wrong. A simple mistake that cost more time than it should have.
\nContainers don't start themselves. Bare-metal services auto-start through systemd. I needed the Docker containers to come up on boot too.
\ndocker compose has no native systemd integration. The cleanest approach was a systemd user service that runs docker compose up -d for each profile's compose file. It feels slightly off, systemd managing containers instead of services, but it's straightforward and it works.
When I was running three gateway profiles on bare metal, I was already past what profiles are designed for. They're great for development. Spinning up a new persona with different skills takes seconds. For anything that needs to actually stay separated, the isolation story falls apart.
\nContainers were the right architecture for that. The operational complexity is real (two compose files, a custom systemd service, separate log streams), but it's the right kind of complexity. Explicit, manageable, debuggable. When rex goes wrong, I look at the rex container, not a shared process tree.
\nI still run default bare-metal. Default is the daily driver; it has no scheduled cron that fires critical replies. Sage and rex are the workers. They get containers.
\nWhat I got wrong was assuming that building the right architecture meant the problem was solved. It didn't. When I went to verify the containers were actually doing their job, nothing worked. Sage was running two Hermes instances, cron jobs were vanishing into the wrong database, and the symptom that started all of this was still happening.
\nThat's the debugging follow-up.
", "url": "https://lukemanning.ie/blog/hermes-profiles-to-docker", "title": "Why I Ditched Hermes Profiles for Docker Containers", "summary": "I ran Hermes (the self-hosted agent I use for reading and research and a few other jobs) with three profiles: default, sage, and rex. Each was a separate persona with its own skills and its own Telegram bot.
\nThey were gateway profiles. In Hermes, the gateway is the long-running process that polls Telegram, runs scheduled jobs, and executes skills. \"Profiles\" means one gateway binary, one process manager, just different configs passed in via --profile.
One thing worth saying up front. This post is the \"why I tried containers\" half of the story. When I went to verify the setup, it wasn't actually working yet, and that's covered in part two of the series. I'm keeping this one focused on the reasoning and the container plumbing, because that part still stands even though my diagnosis turned out to be off.
\nThe symptom was cron replies coming from the wrong profile, and it was inconsistent, which is what made it hard to pin down. Sometimes a scheduled job would fire and default and sage would both reply. Sometimes only rex would send the update, when it wasn't his job to. It never happened with messages I sent directly — only cron.
\nMy theory at the time was that the profiles shared too much. One scheduler, one process tree, no hard boundary between them, so jobs bled across. Three profiles all live in the same process, so when a cron job fired, I figured whichever gateway instance was free picked it up.
\nThat theory turned out to be mostly wrong, which is a whole separate story. I'm laying it out anyway, because it's what drove me to containers, and the architecture reasoning is sound even if the diagnosis wasn't.
\nWhat I didn't realise at the time: gateway profiles aren't separate services. They're separate config directories, separate skill directories, separate .env files, and a --profile flag handed to the same gateway binary. Same process tree. Same supervisor. No hard boundary when one of them misbehaves.
I'd been treating them like independent services. They're not.
\nThe Hermes docs recommend one container hosting all profiles, with s6-overlay (a process supervisor designed for containers) managing each profile as a first-class service. Mount the whole ~/.hermes directory to /opt/data, create profiles with hermes profile create, let s6 start and stop them.
I didn't think that would solve what I was seeing. With one container and s6 running every profile, sage and rex are still co-located processes sharing a network namespace and a data directory. If the problem was jobs bleeding across profiles, bundling them into one container wouldn't stop any of it. They'd just be supervised versions of the same shared setup.
\nSo I ran separate containers for sage and rex, each mounting only its own profile directory. Real process isolation: separate network namespaces, separate PID 1, separate Telegram polling loops. At the process level they genuinely cannot interfere with each other.
\nThe architecture was right, it just wasn't the cause of what I was seeing. That part's in the verification post.
\nThe mount paths. I spent far too long on this.
\nThe profile needs to live at /opt/data/profiles/<name> inside the container, not at /opt/data. I kept mounting the rex profile to /opt/data, and Hermes would log Error: Profile 'rex' does not exist. Create it with: hermes profile create rex. Same files on the host, same mount command, but Hermes couldn't find the profile because it was looking in the wrong place.
The fix was obvious once I saw it:
\n# Wrong — mounts to /opt/data, Hermes expects /opt/data/profiles/rex\n- /home/luke/.hermes/profiles/rex:/opt/data\n\n# Right\n- /home/luke/.hermes/profiles/rex:/opt/data/profiles/rexThe containers weren't the wrong architecture. The paths were wrong. A simple mistake that cost more time than it should have.
\nContainers don't start themselves. Bare-metal services auto-start through systemd. I needed the Docker containers to come up on boot too.
\ndocker compose has no native systemd integration. The cleanest approach was a systemd user service that runs docker compose up -d for each profile's compose file. It feels slightly off, systemd managing containers instead of services, but it's straightforward and it works.
When I was running three gateway profiles on bare metal, I was already past what profiles are designed for. They're great for development. Spinning up a new persona with different skills takes seconds. For anything that needs to actually stay separated, the isolation story falls apart.
\nContainers were the right architecture for that. The operational complexity is real (two compose files, a custom systemd service, separate log streams), but it's the right kind of complexity. Explicit, manageable, debuggable. When rex goes wrong, I look at the rex container, not a shared process tree.
\nI still run default bare-metal. Default is the daily driver; it has no scheduled cron that fires critical replies. Sage and rex are the workers. They get containers.
\nWhat I got wrong was assuming that building the right architecture meant the problem was solved. It didn't. When I went to verify the containers were actually doing their job, nothing worked. Sage was running two Hermes instances, cron jobs were vanishing into the wrong database, and the symptom that started all of this was still happening.
\nThat's the debugging follow-up.
", "date_modified": "2026-07-19T00:00:00.000Z", "tags": [ "hermes", "homelab", "docker" ] }, { "id": "https://lukemanning.ie/blog/setting-up-camoufox-with-hermes", "content_html": "I'd send Hermes links to read. Reddit threads, a couple of docs sites, the occasional opinion piece. Half of them wouldn't load. Bot detection. Just blocked.
\n(Hermes is the local agent I use for reading and research. Pointing it at a URL and expecting it to come back with something useful was the whole idea.)
\nI didn't really know where to go with it until I stumbled on a thread in the Hermes subreddit about this exact problem. People recommended Camoufox, a Firefox fork with fingerprint spoofing built in, designed to look like a real browser to detection systems. I forwarded the thread to Hermes and said let's do this.
\nHermes took it from there. The thread pointed at a recommended architecture: a Node.js server called camofox-browser that wraps Camoufox and exposes a REST API, which Hermes has native support for. Hermes pulled it down, wired up the config, and started it.
Here's what it configured. In ~/.hermes/.env:
CAMOFOX_URL=http://localhost:9377\nCAMOFOX_ADOPT_EXISTING_TAB=true\nAnd in ~/.hermes/config.yaml under browser.camofox:
camofox:\n managed_persistence: true\n adopt_existing_tab: trueHealth check came back clean. Looked done.
\nIt wasn't done. The first time Hermes tried to actually open a tab:
\ntab create timed out after 30000ms\nbrowserContext.newPage: Target page, context or browser has been closed\nThe browser launched. It just wouldn't open tabs. I assumed it was a resources thing at first. Wrong direction.
\nSo I asked Hermes to go digging. It traced it through the code — firefox.launch(options) was succeeding, but the IPC pipe (the juggler interface Playwright uses to talk to Firefox) was being blocked. Hermes grepped the camoufox package for sandbox-related flags and found nothing in the application code, which meant the problem was at the Firefox runtime level.
It was. Firefox's content sandbox, a security feature that isolates content processes, was sealing off that IPC pipe. The browser launches fine, but the moment it tries to sandbox its child content processes, the pipe gets closed and the tab request dies before it ever gets a page.
\nTwo environment variables fixed it:
\nMOZ_DISABLE_CONTENT_SANDBOX=1\nMOZ_ENABLE_WAYLAND=0\nMOZ_DISABLE_CONTENT_SANDBOX=1 turns the content sandbox off, unblocking the pipe. MOZ_ENABLE_WAYLAND=0 forces Firefox onto X11 instead of Wayland — the sandbox behaviour was worse on Wayland, or the IPC just works more reliably over X11 for headless automation. Hermes set both in the same patch and restarted.
The health check came back with browserConnected: true and browserRunning: true. Tab creation worked. Felt anticlimactic after all that back and forth.
The persistence instinct was familiar — I'd already containerised my Hermes profiles for basically the same reason. Hermes wrapped the camofox server in a user-level systemd service (~/.config/systemd/user/camofox.service) so it survives reboots, carrying both environment variables.
The [Service] block ends up looking like:
[Service]\nEnvironment=MOZ_DISABLE_CONTENT_SANDBOX=1\nEnvironment=MOZ_ENABLE_WAYLAND=0Now it survives reboots.
\nReddit loads cleanly now. That was the whole point.
\nSessions persist too. Cookies survive restarts because managed_persistence keeps a browser profile on disk at ~/.camofox/profiles/. The browser is pre-warmed when the service starts, so the first navigation isn't sluggish. I notice it most on the cold first read of the day.
The core problem, Hermes flat-out refusing to load half the links I sent it, is mostly gone. A few sites still clock me occasionally, but it's the exception now rather than the default.
", "url": "https://lukemanning.ie/blog/setting-up-camoufox-with-hermes", "title": "Camoufox Tab Creation Kept Timing Out on Hermes", "summary": "I'd send Hermes links to read. Reddit threads, a couple of docs sites, the occasional opinion piece. Half of them wouldn't load. Bot detection. Just blocked.
\n(Hermes is the local agent I use for reading and research. Pointing it at a URL and expecting it to come back with something useful was the whole idea.)
\nI didn't really know where to go with it until I stumbled on a thread in the Hermes subreddit about this exact problem. People recommended Camoufox, a Firefox fork with fingerprint spoofing built in, designed to look like a real browser to detection systems. I forwarded the thread to Hermes and said let's do this.
\nHermes took it from there. The thread pointed at a recommended architecture: a Node.js server called camofox-browser that wraps Camoufox and exposes a REST API, which Hermes has native support for. Hermes pulled it down, wired up the config, and started it.
Here's what it configured. In ~/.hermes/.env:
CAMOFOX_URL=http://localhost:9377\nCAMOFOX_ADOPT_EXISTING_TAB=true\nAnd in ~/.hermes/config.yaml under browser.camofox:
camofox:\n managed_persistence: true\n adopt_existing_tab: trueHealth check came back clean. Looked done.
\nIt wasn't done. The first time Hermes tried to actually open a tab:
\ntab create timed out after 30000ms\nbrowserContext.newPage: Target page, context or browser has been closed\nThe browser launched. It just wouldn't open tabs. I assumed it was a resources thing at first. Wrong direction.
\nSo I asked Hermes to go digging. It traced it through the code — firefox.launch(options) was succeeding, but the IPC pipe (the juggler interface Playwright uses to talk to Firefox) was being blocked. Hermes grepped the camoufox package for sandbox-related flags and found nothing in the application code, which meant the problem was at the Firefox runtime level.
It was. Firefox's content sandbox, a security feature that isolates content processes, was sealing off that IPC pipe. The browser launches fine, but the moment it tries to sandbox its child content processes, the pipe gets closed and the tab request dies before it ever gets a page.
\nTwo environment variables fixed it:
\nMOZ_DISABLE_CONTENT_SANDBOX=1\nMOZ_ENABLE_WAYLAND=0\nMOZ_DISABLE_CONTENT_SANDBOX=1 turns the content sandbox off, unblocking the pipe. MOZ_ENABLE_WAYLAND=0 forces Firefox onto X11 instead of Wayland — the sandbox behaviour was worse on Wayland, or the IPC just works more reliably over X11 for headless automation. Hermes set both in the same patch and restarted.
The health check came back with browserConnected: true and browserRunning: true. Tab creation worked. Felt anticlimactic after all that back and forth.
The persistence instinct was familiar — I'd already containerised my Hermes profiles for basically the same reason. Hermes wrapped the camofox server in a user-level systemd service (~/.config/systemd/user/camofox.service) so it survives reboots, carrying both environment variables.
The [Service] block ends up looking like:
[Service]\nEnvironment=MOZ_DISABLE_CONTENT_SANDBOX=1\nEnvironment=MOZ_ENABLE_WAYLAND=0Now it survives reboots.
\nReddit loads cleanly now. That was the whole point.
\nSessions persist too. Cookies survive restarts because managed_persistence keeps a browser profile on disk at ~/.camofox/profiles/. The browser is pre-warmed when the service starts, so the first navigation isn't sluggish. I notice it most on the cold first read of the day.
The core problem, Hermes flat-out refusing to load half the links I sent it, is mostly gone. A few sites still clock me occasionally, but it's the exception now rather than the default.
", "date_modified": "2026-07-19T00:00:00.000Z", "tags": [ "hermes" ] }, { "id": "https://lukemanning.ie/blog/i-shipped-a-library-now-what", "content_html": "I built a component library. It's called Projex. It's on npm at @manningworks/projex. It does one thing: makes it stupidly easy to put your GitHub repos, npm packages, Product Hunt launches, Gumroad products — all of it — on a portfolio page with stat counters, links, learnings and zero manual updating.
\nI wrote about building Projex and dogfooding it on dev.to if you want to read the full story.
\nv1.3.1 is shipped as of this article. It's Public on Github and npm.
\nOver six hundred people downloaded it last month according to NPM stats.
\nI have no idea if any of them actually used it.
\nI wanted a portfolio page. I didn't want to manually update it every time I pushed a commit. I wanted live data — GitHub stars, npm downloads, that kind of thing — to just be there.
\nI looked around. GitHub Readme Stats exists. It's just badges. README generators are for READMEs. Nothing I found did the thing I wanted: a proper portfolio page, shadcn-style, where you own the components, where the data comes from the actual APIs.
\nSo I described the problem to my AI agent and we started building.
\nThat was months ago.
\nLast week I asked my AI agent to do a proper review. Line by line through the normalisation function, the fetchers, the component API. I wanted it to evaluate code but I also wanted to consider the perspective of a user trying to implement Projex.
\nIt found twelve issues.
\nSome of them were real problems I'd missed. The error handling was inconsistent — Zod validation throws, but API failures return null and warn. The 400-line normalise function does too much: validation, seven different API calls, field resolution, commits fetching. The TypeScript output types don't match runtime behavior — a github type project can theoretically have Lemon Squeezy revenue stats in the type system even though it never will.
Twelve issues. The code still works. My own Projects page is proof of that.
\nThe issues were real. They were also not the problem.
\nI was talking through the findings with my agent and it asked me something I didn't have a good answer for.
\n\"Could you demo this in 60 seconds?\"
\nI sat with that for a while. Here's what getting Projex running actually involves right now:
\npnpm dev shows empty cards until you actually buildThat is not demoable.
\nI couldn't show you what Projex does in 60 seconds because to see what it does, you have to build something with it. The value is hidden behind implementation.
\nSix hundred installs tells me people are curious enough to try. It doesn't tell me anyone got to the part where it clicks.
\nThe code isn't the blocker.
\nThe first-time experience is the blocker.
\nIf I can't show someone \"install this, add these five lines, here's your live portfolio\" in under five minutes, the demo falls apart. If the demo falls apart, Product Hunt doesn't make sense. If PH doesn't make sense, the distribution strategy doesn't work.
\nI started picturing what the demo would actually look like. Me, a fresh Next.js project, pasting in a snippet and getting a live portfolio back. For that to work, the async fetching and the server/client split have to disappear inside one component. The person using it shouldn't have to know any of that exists.
\nThe thing I need is something like a <ProjectGrid> component. One component that accepts the config, handles the data fetching internally, works with just <ProjectGrid projects={projects} /> in a page.
No manual async. No server/client split. No reading 575 lines of getting-started docs first.
\nJust add your project details. Here's the grid. Done.
\nOnce that exists, I can screenshot it. Once I can screenshot it, I can demo it. Once I can demo it, I can ship it on PH. The chain is short but it starts with that component.
\nI don't know if I'm doing this right.
\nI describe problems to an AI agent. It suggests solutions. We iterate. Sometimes I understand why. Sometimes I just know it works.
\nThe code review was the first time I really sat with what we'd built and asked \"but is this good?\" Not \"does it work?\" I know it works. I just hadn't put much thought into whether it was good.
\nThe twelve issues were real. The agent found them faster than I would have. But the question of whether it matters is still mine to answer.
\nAnd the answer, I think, is that the library is probably fine. The problem is I've been building a library when I should have been building an experience.
\nI went back to the getting-started docs after that conversation. Five hundred and seventy-five lines. All necessary, as far as I could tell when I wrote each one. None of it gets a person to the moment where Projex clicks. Nobody stumbles into five hundred lines of setup and comes out thinking \"oh, this is what I needed.\"
\nThe six hundred people who installed it found it because they were already looking. They searched, they read a post, they followed a link. That's a real audience and I'm grateful for it. But they'd already decided they needed something like this before they got there.
\nThis is what I keep posting into the void about. I know people downloaded it. I don't know if any of them got to the part where it clicks.
\nSame codebase. Different demo.
\nI'm going to build the <ProjectGrid> component. I'm going to get it to the point where I can open a fresh Next.js project and have a live portfolio in under five minutes.
Then I'm going to actually try to demo it.
\nI don't know if it'll work. I don't know if 612 installs becomes 6,000 or stays at 612 or drops to zero.
\nBut I know the code isn't the problem anymore.
\nI think I needed to talk to my AI agent about it to figure that out.
", "url": "https://lukemanning.ie/blog/i-shipped-a-library-now-what", "title": "I Shipped a Component Library. I Have No Idea If Anyone Actually Uses It.", "summary": "I built a component library. It's called Projex. It's on npm at @manningworks/projex. It does one thing: makes it stupidly easy to put your GitHub repos, npm packages, Product Hunt launches, Gumroad products — all of it — on a portfolio page with stat counters, links, learnings and zero manual updating.
\nI wrote about building Projex and dogfooding it on dev.to if you want to read the full story.
\nv1.3.1 is shipped as of this article. It's Public on Github and npm.
\nOver six hundred people downloaded it last month according to NPM stats.
\nI have no idea if any of them actually used it.
\nI wanted a portfolio page. I didn't want to manually update it every time I pushed a commit. I wanted live data — GitHub stars, npm downloads, that kind of thing — to just be there.
\nI looked around. GitHub Readme Stats exists. It's just badges. README generators are for READMEs. Nothing I found did the thing I wanted: a proper portfolio page, shadcn-style, where you own the components, where the data comes from the actual APIs.
\nSo I described the problem to my AI agent and we started building.
\nThat was months ago.
\nLast week I asked my AI agent to do a proper review. Line by line through the normalisation function, the fetchers, the component API. I wanted it to evaluate code but I also wanted to consider the perspective of a user trying to implement Projex.
\nIt found twelve issues.
\nSome of them were real problems I'd missed. The error handling was inconsistent — Zod validation throws, but API failures return null and warn. The 400-line normalise function does too much: validation, seven different API calls, field resolution, commits fetching. The TypeScript output types don't match runtime behavior — a github type project can theoretically have Lemon Squeezy revenue stats in the type system even though it never will.
Twelve issues. The code still works. My own Projects page is proof of that.
\nThe issues were real. They were also not the problem.
\nI was talking through the findings with my agent and it asked me something I didn't have a good answer for.
\n\"Could you demo this in 60 seconds?\"
\nI sat with that for a while. Here's what getting Projex running actually involves right now:
\npnpm dev shows empty cards until you actually buildThat is not demoable.
\nI couldn't show you what Projex does in 60 seconds because to see what it does, you have to build something with it. The value is hidden behind implementation.
\nSix hundred installs tells me people are curious enough to try. It doesn't tell me anyone got to the part where it clicks.
\nThe code isn't the blocker.
\nThe first-time experience is the blocker.
\nIf I can't show someone \"install this, add these five lines, here's your live portfolio\" in under five minutes, the demo falls apart. If the demo falls apart, Product Hunt doesn't make sense. If PH doesn't make sense, the distribution strategy doesn't work.
\nI started picturing what the demo would actually look like. Me, a fresh Next.js project, pasting in a snippet and getting a live portfolio back. For that to work, the async fetching and the server/client split have to disappear inside one component. The person using it shouldn't have to know any of that exists.
\nThe thing I need is something like a <ProjectGrid> component. One component that accepts the config, handles the data fetching internally, works with just <ProjectGrid projects={projects} /> in a page.
No manual async. No server/client split. No reading 575 lines of getting-started docs first.
\nJust add your project details. Here's the grid. Done.
\nOnce that exists, I can screenshot it. Once I can screenshot it, I can demo it. Once I can demo it, I can ship it on PH. The chain is short but it starts with that component.
\nI don't know if I'm doing this right.
\nI describe problems to an AI agent. It suggests solutions. We iterate. Sometimes I understand why. Sometimes I just know it works.
\nThe code review was the first time I really sat with what we'd built and asked \"but is this good?\" Not \"does it work?\" I know it works. I just hadn't put much thought into whether it was good.
\nThe twelve issues were real. The agent found them faster than I would have. But the question of whether it matters is still mine to answer.
\nAnd the answer, I think, is that the library is probably fine. The problem is I've been building a library when I should have been building an experience.
\nI went back to the getting-started docs after that conversation. Five hundred and seventy-five lines. All necessary, as far as I could tell when I wrote each one. None of it gets a person to the moment where Projex clicks. Nobody stumbles into five hundred lines of setup and comes out thinking \"oh, this is what I needed.\"
\nThe six hundred people who installed it found it because they were already looking. They searched, they read a post, they followed a link. That's a real audience and I'm grateful for it. But they'd already decided they needed something like this before they got there.
\nThis is what I keep posting into the void about. I know people downloaded it. I don't know if any of them got to the part where it clicks.
\nSame codebase. Different demo.
\nI'm going to build the <ProjectGrid> component. I'm going to get it to the point where I can open a fresh Next.js project and have a live portfolio in under five minutes.
Then I'm going to actually try to demo it.
\nI don't know if it'll work. I don't know if 612 installs becomes 6,000 or stays at 612 or drops to zero.
\nBut I know the code isn't the problem anymore.
\nI think I needed to talk to my AI agent about it to figure that out.
", "date_modified": "2026-04-17T00:00:00.000Z", "tags": [ "projex" ] }, { "id": "https://lukemanning.ie/blog/projex-cli-config-editor", "content_html": "Projex is my internal tool for managing the projects page on this site. It stores all project data in projex.config.ts. That's by design. Type-safe, validated at build time, lives in the repo alongside the code. Works well.
Until you want to add a learning entry to a project.
\nThen you're opening a TypeScript file, finding the right project in the array, counting commas to make sure you don't mess up the object syntax, adding a new entry to the struggles array, making sure the date format is right, closing the brackets properly. All for something that should be one command.
I built this library. I wrote the config schema. And even I was getting it wrong. I'd actually written about Projex before - you can see it on my projects page. The dev.to integration broke immediately the first time I tried it. Same theme: I built it, but I wasn't actually using it like a real user would.
\nIt was something small. I wanted to add a timeline entry to a project. Opened projex.config.ts, scrolled to the right project, added the entry. Saved. Build passed. Checked the site.
The entry was on the wrong project.
\nI'd pasted it inside the wrong object in the array. Easy mistake when your config is a nested TypeScript data structure and you're editing it like a text file. No validation catches it because the types are fine. The entry is valid. It's just... in the wrong place.
\nThat was the moment I thought: there has to be a better way.
\nI decided to build a CLI. Not because CLIs are fun to build. Because the alternative was continuing to hand-edit a TypeScript file every time I wanted to update my projects page.
\nThe scope was straightforward. I needed commands for everything I was doing manually:
\nThe tricky part was that projex.config.ts is a real TypeScript file. Not JSON. Not YAML. It uses defineProjects(), has imports, can have comments. I needed to parse and modify it without destroying the structure.
I Googled around for TypeScript AST manipulation and found ts-morph. It reads the file as a tree of nodes rather than raw text. Find a project by ID, add an entry to an array, change a property value. All without touching the surrounding code, comments, or formatting.
\nI'd seen ts-morph mentioned before when I was working on something similar. It felt like the right tool for this specific job. The other option was just string manipulation, which seemed brittle.
\nThe actual manipulation was less painful than I expected. I figured I'd have to write a lot of traversal code to navigate the nested structure. But ts-morph's API handles array operations cleanly. Adding to an array, removing from an array, finding nodes by specific properties. It just worked.
\nThe first version worked. But there were edge cases I didn't catch until I sat down and wrote tests for scenarios that seemed unlikely.
\nThe remove commands showed entries as #0, #1, #2 in the interactive prompt. Useless. You'd have to know which index corresponded to which entry. I changed them to show the actual content. Learning entries show [challenge] Struggled with state management.... Timeline entries show 2026-04-15 - v1.0 released. Posts show the title and date. Obvious in retrospect.
Then there was a subtler bug. The code that reads entries from the config filters for object literals in the array. If someone had a spread element in there, like [...sharedEntries, { type: 'challenge', text: 'actual entry' }], the filtered list would skip the spread. But the index reported to the user would be wrong. They'd pick what looked like entry 0, but the actual array index was 1. The wrong entry would get deleted silently.
Fixed that by tracking original indices through the parsed structure instead of using the filtered list position. Added an integration test with a spread element to prove it works.
\nThe edit command had its own issue. It let you set any field on any project type with just a warning. --channel-id on a GitHub project? Sure, warned and proceeded. That's not a warning situation. That's a \"you're doing something wrong\" situation. Changed it to error and exit.
The one feature I didn't originally plan for was removing fields. The CLI could add, edit, and remove projects and entries. But if you accidentally set a field that shouldn't be there, you were back to editing the config file manually.
\nThat defeated the purpose.
\nSo I added --unset. projex edit project my-project --unset description removes the field entirely. Protected fields like id, type, and the array fields can't be removed. It can't be combined with other edit flags either, because that would be ambiguous.
Simple feature. But without it, the CLI wasn't complete. You'd still need to touch the config file for at least one class of changes.
\n881 tests. 55 test files. The integration tests create actual temporary config files and exercise the real parsing logic, not just mocked versions of it.
\nThe CLI handles init, add, edit, remove, and list. Interactive mode when you don't provide flags, non-interactive mode with flags for scripting. Type-specific field validation that errors instead of warns. Descriptive labels on remove prompts instead of index numbers.
\nI've been using it for a day and it's already changed how I interact with my projects page. Adding a learning entry went from \"open file, find project, count commas, hope for the best\" to:
\nprojex add learning projex --type challenge --text \"Config file parsing is surprisingly tricky\"Projex is my internal tool for managing the projects page on this site. It stores all project data in projex.config.ts. That's by design. Type-safe, validated at build time, lives in the repo alongside the code. Works well.
Until you want to add a learning entry to a project.
\nThen you're opening a TypeScript file, finding the right project in the array, counting commas to make sure you don't mess up the object syntax, adding a new entry to the struggles array, making sure the date format is right, closing the brackets properly. All for something that should be one command.
I built this library. I wrote the config schema. And even I was getting it wrong. I'd actually written about Projex before - you can see it on my projects page. The dev.to integration broke immediately the first time I tried it. Same theme: I built it, but I wasn't actually using it like a real user would.
\nIt was something small. I wanted to add a timeline entry to a project. Opened projex.config.ts, scrolled to the right project, added the entry. Saved. Build passed. Checked the site.
The entry was on the wrong project.
\nI'd pasted it inside the wrong object in the array. Easy mistake when your config is a nested TypeScript data structure and you're editing it like a text file. No validation catches it because the types are fine. The entry is valid. It's just... in the wrong place.
\nThat was the moment I thought: there has to be a better way.
\nI decided to build a CLI. Not because CLIs are fun to build. Because the alternative was continuing to hand-edit a TypeScript file every time I wanted to update my projects page.
\nThe scope was straightforward. I needed commands for everything I was doing manually:
\nThe tricky part was that projex.config.ts is a real TypeScript file. Not JSON. Not YAML. It uses defineProjects(), has imports, can have comments. I needed to parse and modify it without destroying the structure.
I Googled around for TypeScript AST manipulation and found ts-morph. It reads the file as a tree of nodes rather than raw text. Find a project by ID, add an entry to an array, change a property value. All without touching the surrounding code, comments, or formatting.
\nI'd seen ts-morph mentioned before when I was working on something similar. It felt like the right tool for this specific job. The other option was just string manipulation, which seemed brittle.
\nThe actual manipulation was less painful than I expected. I figured I'd have to write a lot of traversal code to navigate the nested structure. But ts-morph's API handles array operations cleanly. Adding to an array, removing from an array, finding nodes by specific properties. It just worked.
\nThe first version worked. But there were edge cases I didn't catch until I sat down and wrote tests for scenarios that seemed unlikely.
\nThe remove commands showed entries as #0, #1, #2 in the interactive prompt. Useless. You'd have to know which index corresponded to which entry. I changed them to show the actual content. Learning entries show [challenge] Struggled with state management.... Timeline entries show 2026-04-15 - v1.0 released. Posts show the title and date. Obvious in retrospect.
Then there was a subtler bug. The code that reads entries from the config filters for object literals in the array. If someone had a spread element in there, like [...sharedEntries, { type: 'challenge', text: 'actual entry' }], the filtered list would skip the spread. But the index reported to the user would be wrong. They'd pick what looked like entry 0, but the actual array index was 1. The wrong entry would get deleted silently.
Fixed that by tracking original indices through the parsed structure instead of using the filtered list position. Added an integration test with a spread element to prove it works.
\nThe edit command had its own issue. It let you set any field on any project type with just a warning. --channel-id on a GitHub project? Sure, warned and proceeded. That's not a warning situation. That's a \"you're doing something wrong\" situation. Changed it to error and exit.
The one feature I didn't originally plan for was removing fields. The CLI could add, edit, and remove projects and entries. But if you accidentally set a field that shouldn't be there, you were back to editing the config file manually.
\nThat defeated the purpose.
\nSo I added --unset. projex edit project my-project --unset description removes the field entirely. Protected fields like id, type, and the array fields can't be removed. It can't be combined with other edit flags either, because that would be ambiguous.
Simple feature. But without it, the CLI wasn't complete. You'd still need to touch the config file for at least one class of changes.
\n881 tests. 55 test files. The integration tests create actual temporary config files and exercise the real parsing logic, not just mocked versions of it.
\nThe CLI handles init, add, edit, remove, and list. Interactive mode when you don't provide flags, non-interactive mode with flags for scripting. Type-specific field validation that errors instead of warns. Descriptive labels on remove prompts instead of index numbers.
\nI've been using it for a day and it's already changed how I interact with my projects page. Adding a learning entry went from \"open file, find project, count commas, hope for the best\" to:
\nprojex add learning projex --type challenge --text \"Config file parsing is surprisingly tricky\"I wanted to add my dev.to profile to my projects page. Simple enough. Projex, my own library, has a devto type built in. I wrote the code. Added it to projex.config.ts. Checked the page.
No stats. Nothing. Just an empty project card staring back at me.
\nProjex supports nine project types. GitHub, npm, Product Hunt, dev.to, and a few others. Each type fetches data from a different API and normalises it into a standard format. Stats, links, descriptions.
\nI'd tested GitHub and hybrid (GitHub + npm) types extensively. Those are what I use for my other projects. The dev.to type had been sitting there since I shipped it. Never actually used it.
\nSo I added this to my config:
\n{\n id: 'devto',\n name: 'dev.to/manningworks',\n type: 'devto',\n username: 'manningworks',\n status: 'active',\n // ... background, timeline, all the usual fields\n}Hit the projects page. The card rendered fine. Name, description, timeline, all good. But the stats section was completely empty. No articles. No views. No reactions.
\nMy first thought was that the API call was failing silently. Maybe a network error I wasn't catching, or the username was wrong somehow. I checked the npm run dev console logs. Nothing. The fetch had run fine. One article, valid JSON. The data was there.
So the fetch was working. Something else was wrong.
\nI opened the API response side by side with the Projex source code. That's when I saw it.
\nHere's what Projex's fetchDevToUser was doing:
const totalViews = data.reduce(\n (sum, article) => sum + article.page_views_count, 0\n);\nconst totalReactions = data.reduce(\n (sum, article) => sum + article.positive_reactions_count, 0\n);And here's what the live API response actually contained: public_reactions_count and no page_views_count at all.
Two problems.
\npage_views_count is only returned on authenticated requests. The public API doesn't include it. So it was undefined, and 0 + undefined = NaN.
positive_reactions_count was deprecated by dev.to in favour of public_reactions_count. The public response returns public_reactions_count, not positive_reactions_count.
So both values were NaN. The stats existed but were garbage. The component saw NaN !== undefined as true, tried to render them, and... nothing rendered properly.
Classic. I'd written code against API docs without actually checking what the live response looks like.
\nRaised an issue on my own repo. Fixed the field names. Shipped Projex 1.2.0.
\nThen I updated my site to 1.2.0, reloaded the page, and... still no stats. Different reason this time, but same empty card.
\nBut that wasn't the only problem. Even if the stats had been correct from the start, they still wouldn't have shown up.
\nI started digging through ProjectDetail.tsx, the component that renders project cards. It had render blocks for GitHub stats (stars, forks), npm stats (downloads, version), and Product Hunt stats (upvotes, comments).
No dev.to block. At all.
\nThe component knew about three stat types. Projex supported nine project types. I'd never added the render logic for the newer ones because I'd never needed it. The data was there, normalised and everything. The component just had no idea what to do with it.
\nSo I added a dev.to section:
\n{project.stats.articleCount !== undefined || /* ... */ ? (\n <div className=\"mb-4\">\n <span className=\"text-xs text-terminal-dim\">dev.to: </span>\n <div className=\"flex flex-wrap gap-2 mt-2\">\n {/* articles, views, reactions */}\n </div>\n </div>\n) : null}Same pattern as the other stat blocks. Nothing clever.
\nSaved it. Reloaded. Articles showed up. Views showed 0. Reactions were still missing. Of course they were.
The 1.2.0 release renamed averageReactions to totalReactions (separate fix, separate issue). But my component was still checking for averageReactions. TypeScript caught it immediately — red squiggle, clear error. Which was nice, but still. Three separate issues stacked on top of each other.
Fixed the property name in the component. Reactions showed up. 0 reactions, which is accurate since I'd just published my first post.
Views were showing 0. The dev.to public API doesn't return page_views_count. The 1.2.0 fix added support for DEV_TO_API_KEY as an environment variable. If set, the library sends it as an api-key header, and dev.to returns view counts.
I have a dev.to API key. Just need to add it to .env.local.
That's a config step, not a code fix. But it's another thing I wouldn't have known about without actually trying to use the feature.
\nProjex has tests. It has Zod schema validation. The types all check out. None of that caught any of this.
\nThe dev.to integration passed validation because the schema was correct. The types were correct. The API call was going to the right endpoint. The code was doing exactly what it was written to do. It was just written against the wrong field names and the component had no way to display the results.
\nFour separate issues. All invisible until I actually used the thing.
\nI wrote a retrospective about shipping this library. Published it on npm. And the first time I tried to use a feature I hadn't personally tested, it fell apart immediately.
\nThat's dogfooding. Not the fun kind where your product works great and you feel smug. The kind where you realise your test coverage gave you false confidence and the only way to find real problems is to actually run the software yourself.
\nProjex 1.2.0 is out now. Dev.to integration works. I know because I'm using it.
\nThe four issues, if you're keeping score:
\npage_views_count not in public API response (needs auth)positive_reactions_count deprecated, should be public_reactions_countaverageReactions renamed to totalReactions, component not updatedAll found by trying to add one project to my own site.
", "url": "https://lukemanning.ie/blog/dogfooding-projex-devto", "title": "Dogfooding Projex: My Own Library Broke on the First New Feature I Tried", "summary": "I wanted to add my dev.to profile to my projects page. Simple enough. Projex, my own library, has a devto type built in. I wrote the code. Added it to projex.config.ts. Checked the page.
No stats. Nothing. Just an empty project card staring back at me.
\nProjex supports nine project types. GitHub, npm, Product Hunt, dev.to, and a few others. Each type fetches data from a different API and normalises it into a standard format. Stats, links, descriptions.
\nI'd tested GitHub and hybrid (GitHub + npm) types extensively. Those are what I use for my other projects. The dev.to type had been sitting there since I shipped it. Never actually used it.
\nSo I added this to my config:
\n{\n id: 'devto',\n name: 'dev.to/manningworks',\n type: 'devto',\n username: 'manningworks',\n status: 'active',\n // ... background, timeline, all the usual fields\n}Hit the projects page. The card rendered fine. Name, description, timeline, all good. But the stats section was completely empty. No articles. No views. No reactions.
\nMy first thought was that the API call was failing silently. Maybe a network error I wasn't catching, or the username was wrong somehow. I checked the npm run dev console logs. Nothing. The fetch had run fine. One article, valid JSON. The data was there.
So the fetch was working. Something else was wrong.
\nI opened the API response side by side with the Projex source code. That's when I saw it.
\nHere's what Projex's fetchDevToUser was doing:
const totalViews = data.reduce(\n (sum, article) => sum + article.page_views_count, 0\n);\nconst totalReactions = data.reduce(\n (sum, article) => sum + article.positive_reactions_count, 0\n);And here's what the live API response actually contained: public_reactions_count and no page_views_count at all.
Two problems.
\npage_views_count is only returned on authenticated requests. The public API doesn't include it. So it was undefined, and 0 + undefined = NaN.
positive_reactions_count was deprecated by dev.to in favour of public_reactions_count. The public response returns public_reactions_count, not positive_reactions_count.
So both values were NaN. The stats existed but were garbage. The component saw NaN !== undefined as true, tried to render them, and... nothing rendered properly.
Classic. I'd written code against API docs without actually checking what the live response looks like.
\nRaised an issue on my own repo. Fixed the field names. Shipped Projex 1.2.0.
\nThen I updated my site to 1.2.0, reloaded the page, and... still no stats. Different reason this time, but same empty card.
\nBut that wasn't the only problem. Even if the stats had been correct from the start, they still wouldn't have shown up.
\nI started digging through ProjectDetail.tsx, the component that renders project cards. It had render blocks for GitHub stats (stars, forks), npm stats (downloads, version), and Product Hunt stats (upvotes, comments).
No dev.to block. At all.
\nThe component knew about three stat types. Projex supported nine project types. I'd never added the render logic for the newer ones because I'd never needed it. The data was there, normalised and everything. The component just had no idea what to do with it.
\nSo I added a dev.to section:
\n{project.stats.articleCount !== undefined || /* ... */ ? (\n <div className=\"mb-4\">\n <span className=\"text-xs text-terminal-dim\">dev.to: </span>\n <div className=\"flex flex-wrap gap-2 mt-2\">\n {/* articles, views, reactions */}\n </div>\n </div>\n) : null}Same pattern as the other stat blocks. Nothing clever.
\nSaved it. Reloaded. Articles showed up. Views showed 0. Reactions were still missing. Of course they were.
The 1.2.0 release renamed averageReactions to totalReactions (separate fix, separate issue). But my component was still checking for averageReactions. TypeScript caught it immediately — red squiggle, clear error. Which was nice, but still. Three separate issues stacked on top of each other.
Fixed the property name in the component. Reactions showed up. 0 reactions, which is accurate since I'd just published my first post.
Views were showing 0. The dev.to public API doesn't return page_views_count. The 1.2.0 fix added support for DEV_TO_API_KEY as an environment variable. If set, the library sends it as an api-key header, and dev.to returns view counts.
I have a dev.to API key. Just need to add it to .env.local.
That's a config step, not a code fix. But it's another thing I wouldn't have known about without actually trying to use the feature.
\nProjex has tests. It has Zod schema validation. The types all check out. None of that caught any of this.
\nThe dev.to integration passed validation because the schema was correct. The types were correct. The API call was going to the right endpoint. The code was doing exactly what it was written to do. It was just written against the wrong field names and the component had no way to display the results.
\nFour separate issues. All invisible until I actually used the thing.
\nI wrote a retrospective about shipping this library. Published it on npm. And the first time I tried to use a feature I hadn't personally tested, it fell apart immediately.
\nThat's dogfooding. Not the fun kind where your product works great and you feel smug. The kind where you realise your test coverage gave you false confidence and the only way to find real problems is to actually run the software yourself.
\nProjex 1.2.0 is out now. Dev.to integration works. I know because I'm using it.
\nThe four issues, if you're keeping score:
\npage_views_count not in public API response (needs auth)positive_reactions_count deprecated, should be public_reactions_countaverageReactions renamed to totalReactions, component not updatedAll found by trying to add one project to my own site.
", "date_modified": "2026-04-15T00:00:00.000Z", "tags": [ "projex" ] }, { "id": "https://lukemanning.ie/blog/fluorescent-office-essay", "content_html": "An essay is making the rounds on X: the one about not following your passion. You may have seen it. Beautifully written, controlled prose, specific imagery, and a genuine emotional core. It argues that \"follow your passion\" is bad advice for most people; that the office with fluorescent lights that smells of burned coffee is the shape of most lives, and that the real source of meaning isn't the work itself but the people beside you.
\nI read it and I had surprisingly visceral reaction. It took me a while to figure out why because the reaction wasn't entirely fair.
\nMost of what it says is true. Follow your passion is bad advice. Most passions aren't economically viable. Work rarely delivers meaning on its own. The office with the humming lights and the chair that never adjusts right.. that's real. I've sat in that chair. I've had the exact conversation the essay describes, where a colleague swivels in his chair with a look on his face that says I cannot believe this is my life.
\nSo why did reading it bother me so much?
\nBecause the essay never distinguishes between accepting your circumstances and choosing them.
\nIt treats the office with fluorescent lights as fate. As the shape of a life, inevitable and fixed, something to be made peace with. And from that premise it draws a reasonable conclusion; if this is where you are, here's how to find meaning in it. But the framing quietly does something else too. By never acknowledging that the office is a starting point rather than a final destination, it removes the question entirely. It doesn't say you can't build something outside of it. It just doesn't leave room for the thought. The world of the essay has two exits. You either accept the ordinary life with grace, or chase your impossible-to-reach dreams and fail. That's not the full map.
\nThere's a third path. Not the rockstar path. Not the path where you sell out arenas or throw touchdown passes or have your face on a billboard. That path is as unlikely as the essay says it is. But between \"accept your future lies in an office\" and \"become exceptional\" there's a quieter option. Build small things, outside of hours, that might one day compound into something that gives you a choice you didn't have before. Start a personal brand. Build a network of connections. Open the door to alternative opportunities.
\nI'm doing this. Slowly, imperfectly, alongside a full-time job. This blog, a couple of side projects I'm not sure will go anywhere. Some won't, and that uncertainty isn't a flaw in the plan. It's the nature of the path. You build anyway, because the alternative is to decide in advance that the office is the answer, which is exactly the move the essay is quietly recommending.
\nThat's where it loses me. Not in its compassion. The argument for finding meaning in the people beside you is real and I believe it. Not in its realism about passion. That's a correction our culture genuinely needs. It loses me in its finality. The essay is written for someone who has already stopped. For that person, the advice might be exactly right. But it presents itself as wisdom for everyone and wisdom that doesn't leave room for agency isn't wisdom. It's consolation.
\nYou can find meaning in the people beside you and still refuse to treat where you are as where you'll always be. Those aren't in conflict. The essay just forgot to say so.
\nThat distinction, between accepting where you are and deciding it's permanent, is the one I keep turning over. I'm not ready to settle. Not yet.
", "url": "https://lukemanning.ie/blog/fluorescent-office-essay", "title": "The Essay Everyone Is Sharing Left One Thing Out", "summary": "An essay is making the rounds on X: the one about not following your passion. You may have seen it. Beautifully written, controlled prose, specific imagery, and a genuine emotional core. It argues that \"follow your passion\" is bad advice for most people; that the office with fluorescent lights that smells of burned coffee is the shape of most lives, and that the real source of meaning isn't the work itself but the people beside you.
\nI read it and I had surprisingly visceral reaction. It took me a while to figure out why because the reaction wasn't entirely fair.
\nMost of what it says is true. Follow your passion is bad advice. Most passions aren't economically viable. Work rarely delivers meaning on its own. The office with the humming lights and the chair that never adjusts right.. that's real. I've sat in that chair. I've had the exact conversation the essay describes, where a colleague swivels in his chair with a look on his face that says I cannot believe this is my life.
\nSo why did reading it bother me so much?
\nBecause the essay never distinguishes between accepting your circumstances and choosing them.
\nIt treats the office with fluorescent lights as fate. As the shape of a life, inevitable and fixed, something to be made peace with. And from that premise it draws a reasonable conclusion; if this is where you are, here's how to find meaning in it. But the framing quietly does something else too. By never acknowledging that the office is a starting point rather than a final destination, it removes the question entirely. It doesn't say you can't build something outside of it. It just doesn't leave room for the thought. The world of the essay has two exits. You either accept the ordinary life with grace, or chase your impossible-to-reach dreams and fail. That's not the full map.
\nThere's a third path. Not the rockstar path. Not the path where you sell out arenas or throw touchdown passes or have your face on a billboard. That path is as unlikely as the essay says it is. But between \"accept your future lies in an office\" and \"become exceptional\" there's a quieter option. Build small things, outside of hours, that might one day compound into something that gives you a choice you didn't have before. Start a personal brand. Build a network of connections. Open the door to alternative opportunities.
\nI'm doing this. Slowly, imperfectly, alongside a full-time job. This blog, a couple of side projects I'm not sure will go anywhere. Some won't, and that uncertainty isn't a flaw in the plan. It's the nature of the path. You build anyway, because the alternative is to decide in advance that the office is the answer, which is exactly the move the essay is quietly recommending.
\nThat's where it loses me. Not in its compassion. The argument for finding meaning in the people beside you is real and I believe it. Not in its realism about passion. That's a correction our culture genuinely needs. It loses me in its finality. The essay is written for someone who has already stopped. For that person, the advice might be exactly right. But it presents itself as wisdom for everyone and wisdom that doesn't leave room for agency isn't wisdom. It's consolation.
\nYou can find meaning in the people beside you and still refuse to treat where you are as where you'll always be. Those aren't in conflict. The essay just forgot to say so.
\nThat distinction, between accepting where you are and deciding it's permanent, is the one I keep turning over. I'm not ready to settle. Not yet.
", "date_modified": "2026-04-14T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/building-straico-api-proxy", "content_html": "I use OpenCode as my main AI coding tool. I switched from Claude Code after Anthropic started going after open source projects and I kept hitting session limits on my subscription.
\nOpenCode works with any OpenAI-compatible API. Straico gives me access to Claude, GPT, Gemini, DeepSeek, and a bunch more through a single API key. Cheap too. Problem is, Straico's API is missing two things OpenCode needs: streaming responses and function calling.
\nWithout streaming, OpenCode just hangs. Never gets a response. But Straico keeps eating tokens on their end anyway. Without function calling, the AI can't use tools like reading files or running bash commands. Both are non-negotiable for an agentic coding tool.
\nSo I built a proxy. It sits between OpenCode and Straico, translating requests and responses to fill in the gaps.
\nOpenCode\n → localhost:8000 (my proxy)\n → Straico API\nWhat started as \"just simulate streaming and inject tool definitions\" turned into a surprisingly full-featured thing. The codebase is at github.com/ManningWorks/DOAI-Proxy.
\nI didn't start with a provider pattern. I started with four files: server.js, streaming.js, tools.js, utils.js. But once I started thinking about adding other providers down the line (OpenAI direct, Anthropic direct), I refactored into something cleaner.
The provider pattern lives in providers/. BaseProvider is an abstract class that handles the interface contract and retry logic. StraicoProvider extends it with Straico-specific request/response transformation. ProviderFactory instantiates the right one based on the PROVIDER_TYPE env var.
Right now only Straico exists, but the factory already has stubs for OpenAI and Anthropic. The ADDING_PROVIDERS.md doc in the repo lays out how to add a new one.
The other modules:
\nserver.js - Express server, routing, auth, request lifecyclestreaming.js - SSE simulation with two modestools.js - Tool injection and response parsingutils.js - Logging, formatting, log rotationutils/model-limits.js - Fetches context limits from Straico's APIsummarizer.js - Conversation summarization for long sessionsscripts/sync-opencode-config.js - Syncs model list to OpenCode configStraico returns the full response at once. No SSE. No chunks. The proxy has to fake it.
\nTwo modes: none and smart.
none is what I'd recommend as default. It sends the entire response in one SSE chunk, then the [DONE] marker. Fast, no formatting issues, still technically SSE.
smart is more interesting. It splits the response into chunks with delays to simulate real streaming. The naive approach is responseText.match(new RegExp('.{1,15}', 'g')) and that kind of works. But it breaks markdown. Split mid-bold, mid-code-block, mid-backtick and the rendering glitches.
So smartChunkText() in streaming.js looks for safe boundaries. It prefers splitting on newlines, then whitespace. It also checks for markdown delimiters (**, __, \\``, `` ``) and extends the chunk to avoid splitting them. There's a max size limit (targetSize * 10) to prevent infinite extension.
// streaming.js - simplified version of the boundary logic\nfor (let i = end; i > start; i--) {\n if (text[i] === '\\n') {\n return i + 1;\n }\n}\nfor (const delim of ['**', '__', '```', '`']) {\n const delimStart = text.indexOf(delim, start);\n if (delimStart !== -1 && delimStart < end) {\n const delimEnd = delimStart + delim.length;\n if (delimEnd > end) {\n return Math.min(delimEnd, text.length, start + maxSize);\n }\n }\n}Default is 15 characters per chunk with 80ms delay. That feels about right for most models. Configurable via STREAM_CHUNK_SIZE and STREAM_DELAY_MS env vars.
I set STREAM_MODE=none as the recommended default. smart works but it's more of a showcase thing. The boundary detection catches most cases but I wouldn't trust it with complex nested markdown.
Straico doesn't support function calling natively. The workaround: inject tool definitions into the system prompt and parse the AI's response to detect tool calls.
\ninjectToolsIntoSystem() in tools.js appends a formatted list of available tools to the system message:
You have access to the following tools:\n- bash: Run bash commands\n- read: Read file contents\n\nWhen you need to use a tool, format your response like this:\nTOOL_CALL: <tool_name>\nARGUMENTS: <json_arguments>\nThere's a sentinel comment (<!-- proxy-tools-injected -->) to prevent double-injection if the same messages get processed twice.
The tricky part is parsing. Different models output tool calls in different formats. I ended up with four parsers that run in sequence:
\n<minimax:tool_call> with <invoke> tags<invoke name=\"...\"> with <parameter_list> tags\"tool_calls\": [...] embedded in the responseTOOL_CALL: / ARGUMENTS: format from the injection promptEach parser tries to extract tool calls from the response text. The first one that succeeds wins. This was a gradual thing. I started with just the text format parser. Then Minimax models returned XML. Then Claude models returned different XML. Then some models returned JSON that looked like OpenAI's format. Four parsers later and it handles most cases.
\nThe text format parser was the hardest to get right. Matching TOOL_CALL: tool_name ARGUMENTS: {json} seems simple until the JSON contains nested objects, strings with braces, or the model forgets the space between the tool name and ARGUMENTS. The implementation tracks brace depth to find where the JSON actually ends:
for (let i = argsStartIndex; i < responseText.length; i++) {\n const char = responseText[i];\n if (char === '{') braceCount++;\n else if (char === '}') {\n braceCount--;\n if (braceCount === 0) {\n argsEndIndex = i + 1;\n foundClosingBrace = true;\n break;\n }\n }\n}The proxy also validates tool calls against the list of available tools. If the model invents a tool that doesn't exist, it gets filtered out. If all tool calls are invalid, the response is treated as regular text.
\nOpenCode expects tool calls to arrive as SSE chunks, same as regular text. streamToolCalls() in streaming.js sends an init chunk with the tool name and ID, then an args chunk with the arguments, then a final chunk with finish_reason: 'tool_calls'. Each chunk has a small delay (20ms, 10ms, 20ms) to feel like actual streaming.
This one sneaked up on me. Straico has model context limits. Some models have 8k tokens, some have 128k. OpenCode sends the entire conversation history with every request. In a long coding session, that history grows fast.
\nsummarizer.js checks if the estimated token count is approaching the model's limit. When it hits a configurable threshold (default 70% of the model's word_limit), it takes all but the most recent messages, sends them to Straico for summarization, and replaces them with a single summary message.
The summarization itself uses Straico's smart_llm_selector with pricing_method: balance, so it picks a cheap model for the summary. Configurable via SUMMARIZATION_MODEL.
I'm still not 100% sure this is the right approach. The summary is lossy. Sometimes the model needs context from earlier messages that the summary glossed over. But without it, long sessions just fail with context limit errors. Tradeoff.
\nutils/model-limits.js fetches all available models from Straico's /models endpoint at startup. It caches their context limits (word_limit) and max output tokens (max_output). The proxy uses this to validate incoming requests. If estimated_input_tokens + max_tokens > word_limit, it rejects the request with a 400 error before even hitting Straico.
The model list is also exposed at /v1/models so OpenCode can discover what's available. There's an admin endpoint at /v1/admin/refresh-models to force a refresh if Straico adds new models.
The sync script (scripts/sync-opencode-config.js) goes one step further. It fetches the model list from Straico, then updates ~/.config/opencode/opencode.json with all chat-type models. The Docker entrypoint runs this script before starting the server, so the model list is always current.
Four modes, controlled by AUTH_MODE:
required - Needs PROXY_API_KEY, rejects requests without it. Default in production.optional - Uses the key if set, warns if not. Default in development.disabled - No auth. For isolated environments.external - Trusts an external auth header. For when the proxy sits behind an API gateway or service mesh.The key comparison uses crypto.timingSafeEqual to prevent timing attacks. Took me a moment to realise I needed buffer length checks too, since timingSafeEqual throws if the buffers are different lengths.
BaseProvider.makeRequestWithRetry() wraps every API call with exponential backoff. Retries on 429, 5xx, and network errors (ECONNREFUSED, ECONNRESET, ETIMEDOUT). Default is 3 attempts with a 1-second base delay.
Graceful shutdown was one of those things I didn't think about until I ran into issues. When Docker sends SIGTERM, the proxy stops accepting new requests and waits for active ones to drain. There's a timeout (default 30 seconds) after which it force-exits. Without this, long-running streaming responses would get cut off mid-chunk when the container restarted.
\nThe Dockerfile uses node:18-alpine and an entrypoint script. The entrypoint runs the OpenCode config sync, then starts the server.
Docker Compose mounts two volumes. The .env file for config. And ~/.config/opencode so the sync script can write to the OpenCode config file.
volumes:\n - ./.env:/app/.env:ro\n - ~/.config/opencode:/root/.config/opencodeOne thing I got wrong initially was the Dockerfile CMD. I had CMD [\"node\", \"server.js\"] which meant the config sync never ran. Switched to ENTRYPOINT [\"/app/docker-entrypoint.sh\"] and that fixed it. Small thing, but it meant every container restart would have stale model lists.
Straico's API is mostly OpenAI-compatible but with some differences that caught me out.
\nTool result messages use role: \"tool\" in OpenAI format. Straico doesn't support that role. The proxy converts them to role: \"user\" with a [Tool Result]: prefix. Same with assistant messages that contain tool calls. Those get converted to the text format the injection prompt expects.
Empty assistant messages get filtered out entirely. Some models return an assistant message with empty content before making a tool call. Straico chokes on those.
\nThere's a TOOL_RESULT_MAX_LENGTH env var that truncates large tool outputs. Some tool results (file reads, command output) can be massive. Without truncation, they blow out the context window and the next request fails.
The proxy also normalises messages. OpenAI sends content as arrays of objects (text parts, image parts, system reminders). The proxy flattens those into plain strings and strips out <system-reminder> tags. Straico doesn't know what to do with the array format.
The provider pattern is solid but I'd start with it from the beginning rather than refactoring into it. The four-file structure worked fine until I wanted to add features that crossed module boundaries. The abstraction would have saved me some reshuffling.
\nThe smart streaming mode is neat but I'd think harder about whether it's worth the complexity. The boundary detection handles most markdown but not all edge cases. none mode is faster and more reliable. I use none day to day.
The summarization feature is the part I'm least confident about. It works, but the lossy compression means sometimes context gets dropped at exactly the wrong moment. I might revisit this with a sliding window approach instead of a hard summarize-and-replace.
\nThe proxy handles:
\nIt runs on my machine and OpenCode talks to it at http://localhost:8000/v1. Works well enough that I don't think about it most of the time. Which is exactly what a proxy should do.
The code is on GitHub if you want to look or use it. Or add a provider. The architecture supports it.
", "url": "https://lukemanning.ie/blog/building-straico-api-proxy", "title": "Straico Has Great Models But No Streaming, So I Built a Proxy", "summary": "I use OpenCode as my main AI coding tool. I switched from Claude Code after Anthropic started going after open source projects and I kept hitting session limits on my subscription.
\nOpenCode works with any OpenAI-compatible API. Straico gives me access to Claude, GPT, Gemini, DeepSeek, and a bunch more through a single API key. Cheap too. Problem is, Straico's API is missing two things OpenCode needs: streaming responses and function calling.
\nWithout streaming, OpenCode just hangs. Never gets a response. But Straico keeps eating tokens on their end anyway. Without function calling, the AI can't use tools like reading files or running bash commands. Both are non-negotiable for an agentic coding tool.
\nSo I built a proxy. It sits between OpenCode and Straico, translating requests and responses to fill in the gaps.
\nOpenCode\n → localhost:8000 (my proxy)\n → Straico API\nWhat started as \"just simulate streaming and inject tool definitions\" turned into a surprisingly full-featured thing. The codebase is at github.com/ManningWorks/DOAI-Proxy.
\nI didn't start with a provider pattern. I started with four files: server.js, streaming.js, tools.js, utils.js. But once I started thinking about adding other providers down the line (OpenAI direct, Anthropic direct), I refactored into something cleaner.
The provider pattern lives in providers/. BaseProvider is an abstract class that handles the interface contract and retry logic. StraicoProvider extends it with Straico-specific request/response transformation. ProviderFactory instantiates the right one based on the PROVIDER_TYPE env var.
Right now only Straico exists, but the factory already has stubs for OpenAI and Anthropic. The ADDING_PROVIDERS.md doc in the repo lays out how to add a new one.
The other modules:
\nserver.js - Express server, routing, auth, request lifecyclestreaming.js - SSE simulation with two modestools.js - Tool injection and response parsingutils.js - Logging, formatting, log rotationutils/model-limits.js - Fetches context limits from Straico's APIsummarizer.js - Conversation summarization for long sessionsscripts/sync-opencode-config.js - Syncs model list to OpenCode configStraico returns the full response at once. No SSE. No chunks. The proxy has to fake it.
\nTwo modes: none and smart.
none is what I'd recommend as default. It sends the entire response in one SSE chunk, then the [DONE] marker. Fast, no formatting issues, still technically SSE.
smart is more interesting. It splits the response into chunks with delays to simulate real streaming. The naive approach is responseText.match(new RegExp('.{1,15}', 'g')) and that kind of works. But it breaks markdown. Split mid-bold, mid-code-block, mid-backtick and the rendering glitches.
So smartChunkText() in streaming.js looks for safe boundaries. It prefers splitting on newlines, then whitespace. It also checks for markdown delimiters (**, __, \\``, `` ``) and extends the chunk to avoid splitting them. There's a max size limit (targetSize * 10) to prevent infinite extension.
// streaming.js - simplified version of the boundary logic\nfor (let i = end; i > start; i--) {\n if (text[i] === '\\n') {\n return i + 1;\n }\n}\nfor (const delim of ['**', '__', '```', '`']) {\n const delimStart = text.indexOf(delim, start);\n if (delimStart !== -1 && delimStart < end) {\n const delimEnd = delimStart + delim.length;\n if (delimEnd > end) {\n return Math.min(delimEnd, text.length, start + maxSize);\n }\n }\n}Default is 15 characters per chunk with 80ms delay. That feels about right for most models. Configurable via STREAM_CHUNK_SIZE and STREAM_DELAY_MS env vars.
I set STREAM_MODE=none as the recommended default. smart works but it's more of a showcase thing. The boundary detection catches most cases but I wouldn't trust it with complex nested markdown.
Straico doesn't support function calling natively. The workaround: inject tool definitions into the system prompt and parse the AI's response to detect tool calls.
\ninjectToolsIntoSystem() in tools.js appends a formatted list of available tools to the system message:
You have access to the following tools:\n- bash: Run bash commands\n- read: Read file contents\n\nWhen you need to use a tool, format your response like this:\nTOOL_CALL: <tool_name>\nARGUMENTS: <json_arguments>\nThere's a sentinel comment (<!-- proxy-tools-injected -->) to prevent double-injection if the same messages get processed twice.
The tricky part is parsing. Different models output tool calls in different formats. I ended up with four parsers that run in sequence:
\n<minimax:tool_call> with <invoke> tags<invoke name=\"...\"> with <parameter_list> tags\"tool_calls\": [...] embedded in the responseTOOL_CALL: / ARGUMENTS: format from the injection promptEach parser tries to extract tool calls from the response text. The first one that succeeds wins. This was a gradual thing. I started with just the text format parser. Then Minimax models returned XML. Then Claude models returned different XML. Then some models returned JSON that looked like OpenAI's format. Four parsers later and it handles most cases.
\nThe text format parser was the hardest to get right. Matching TOOL_CALL: tool_name ARGUMENTS: {json} seems simple until the JSON contains nested objects, strings with braces, or the model forgets the space between the tool name and ARGUMENTS. The implementation tracks brace depth to find where the JSON actually ends:
for (let i = argsStartIndex; i < responseText.length; i++) {\n const char = responseText[i];\n if (char === '{') braceCount++;\n else if (char === '}') {\n braceCount--;\n if (braceCount === 0) {\n argsEndIndex = i + 1;\n foundClosingBrace = true;\n break;\n }\n }\n}The proxy also validates tool calls against the list of available tools. If the model invents a tool that doesn't exist, it gets filtered out. If all tool calls are invalid, the response is treated as regular text.
\nOpenCode expects tool calls to arrive as SSE chunks, same as regular text. streamToolCalls() in streaming.js sends an init chunk with the tool name and ID, then an args chunk with the arguments, then a final chunk with finish_reason: 'tool_calls'. Each chunk has a small delay (20ms, 10ms, 20ms) to feel like actual streaming.
This one sneaked up on me. Straico has model context limits. Some models have 8k tokens, some have 128k. OpenCode sends the entire conversation history with every request. In a long coding session, that history grows fast.
\nsummarizer.js checks if the estimated token count is approaching the model's limit. When it hits a configurable threshold (default 70% of the model's word_limit), it takes all but the most recent messages, sends them to Straico for summarization, and replaces them with a single summary message.
The summarization itself uses Straico's smart_llm_selector with pricing_method: balance, so it picks a cheap model for the summary. Configurable via SUMMARIZATION_MODEL.
I'm still not 100% sure this is the right approach. The summary is lossy. Sometimes the model needs context from earlier messages that the summary glossed over. But without it, long sessions just fail with context limit errors. Tradeoff.
\nutils/model-limits.js fetches all available models from Straico's /models endpoint at startup. It caches their context limits (word_limit) and max output tokens (max_output). The proxy uses this to validate incoming requests. If estimated_input_tokens + max_tokens > word_limit, it rejects the request with a 400 error before even hitting Straico.
The model list is also exposed at /v1/models so OpenCode can discover what's available. There's an admin endpoint at /v1/admin/refresh-models to force a refresh if Straico adds new models.
The sync script (scripts/sync-opencode-config.js) goes one step further. It fetches the model list from Straico, then updates ~/.config/opencode/opencode.json with all chat-type models. The Docker entrypoint runs this script before starting the server, so the model list is always current.
Four modes, controlled by AUTH_MODE:
required - Needs PROXY_API_KEY, rejects requests without it. Default in production.optional - Uses the key if set, warns if not. Default in development.disabled - No auth. For isolated environments.external - Trusts an external auth header. For when the proxy sits behind an API gateway or service mesh.The key comparison uses crypto.timingSafeEqual to prevent timing attacks. Took me a moment to realise I needed buffer length checks too, since timingSafeEqual throws if the buffers are different lengths.
BaseProvider.makeRequestWithRetry() wraps every API call with exponential backoff. Retries on 429, 5xx, and network errors (ECONNREFUSED, ECONNRESET, ETIMEDOUT). Default is 3 attempts with a 1-second base delay.
Graceful shutdown was one of those things I didn't think about until I ran into issues. When Docker sends SIGTERM, the proxy stops accepting new requests and waits for active ones to drain. There's a timeout (default 30 seconds) after which it force-exits. Without this, long-running streaming responses would get cut off mid-chunk when the container restarted.
\nThe Dockerfile uses node:18-alpine and an entrypoint script. The entrypoint runs the OpenCode config sync, then starts the server.
Docker Compose mounts two volumes. The .env file for config. And ~/.config/opencode so the sync script can write to the OpenCode config file.
volumes:\n - ./.env:/app/.env:ro\n - ~/.config/opencode:/root/.config/opencodeOne thing I got wrong initially was the Dockerfile CMD. I had CMD [\"node\", \"server.js\"] which meant the config sync never ran. Switched to ENTRYPOINT [\"/app/docker-entrypoint.sh\"] and that fixed it. Small thing, but it meant every container restart would have stale model lists.
Straico's API is mostly OpenAI-compatible but with some differences that caught me out.
\nTool result messages use role: \"tool\" in OpenAI format. Straico doesn't support that role. The proxy converts them to role: \"user\" with a [Tool Result]: prefix. Same with assistant messages that contain tool calls. Those get converted to the text format the injection prompt expects.
Empty assistant messages get filtered out entirely. Some models return an assistant message with empty content before making a tool call. Straico chokes on those.
\nThere's a TOOL_RESULT_MAX_LENGTH env var that truncates large tool outputs. Some tool results (file reads, command output) can be massive. Without truncation, they blow out the context window and the next request fails.
The proxy also normalises messages. OpenAI sends content as arrays of objects (text parts, image parts, system reminders). The proxy flattens those into plain strings and strips out <system-reminder> tags. Straico doesn't know what to do with the array format.
The provider pattern is solid but I'd start with it from the beginning rather than refactoring into it. The four-file structure worked fine until I wanted to add features that crossed module boundaries. The abstraction would have saved me some reshuffling.
\nThe smart streaming mode is neat but I'd think harder about whether it's worth the complexity. The boundary detection handles most markdown but not all edge cases. none mode is faster and more reliable. I use none day to day.
The summarization feature is the part I'm least confident about. It works, but the lossy compression means sometimes context gets dropped at exactly the wrong moment. I might revisit this with a sliding window approach instead of a hard summarize-and-replace.
\nThe proxy handles:
\nIt runs on my machine and OpenCode talks to it at http://localhost:8000/v1. Works well enough that I don't think about it most of the time. Which is exactly what a proxy should do.
The code is on GitHub if you want to look or use it. Or add a provider. The architecture supports it.
", "date_modified": "2026-04-13T00:00:00.000Z", "tags": [ "opencode" ] }, { "id": "https://lukemanning.ie/blog/npm-package-json-vs-package-lock-json", "content_html": "I updated @manningworks/projex to 1.2.0. At least, I thought I did. The installed version was 1.2.0, confirmed with npm ls. But my package.json still said ^1.1.3.
Wait, what?
\nI assumed npm update would update package.json. That seems like the obvious thing it should do. It doesn't. And that's by design. But figuring out why took me through a bunch of npm documentation I'd never actually read properly.
Here's what I assumed the workflow was:
\nnpm updatepackage.json gets updated to reflect the new versionspackage-lock.json gets updated tooSteps 2 and 4 happened. Step 3 did not.
\nI stared at my package.json for a while wondering if I'd hallucinated the update. I hadn't. The package was definitely on 1.2.0 in node_modules. But the file that's supposed to declare my dependencies was lying to me.
Or so I thought.
\nI hit the npm docs. Started with the package-lock.json docs, then worked backward to how package.json handles versions. The first thing that clicked was realizing I'd been thinking about package.json wrong the whole time.
package.json doesn't store the exact version you have installed. It stores a semver range. The ^ prefix means \"compatible with this version.\" ^1.1.3 means \"anything from 1.1.3 up to, but not including, 2.0.0.\" (There's also ~ for patch-only updates, and no prefix pins the exact version. But ^ is what npm uses by default, which is why nearly every entry in your package.json has it.)
So when I had \"@manningworks/projex\": \"^1.1.3\" and npm installed 1.2.0, that's working as intended. 1.2.0 satisfies the range >=1.1.3 <2.0.0. The range didn't need to change.
I didn't know this. I thought the version in package.json was the version, not the minimum acceptable version.
This is the part I was fuzzy on. package-lock.json stores the exact version installed for every package in your dependency tree. Not ranges. Exact versions.
When you run npm install, npm looks at the ranges in package.json, resolves them to specific versions, installs those, and writes the exact resolutions to package-lock.json.
Next time someone clones your repo and runs npm install, they get the exact same versions. Not \"whatever the latest is that satisfies the range.\" The same versions. That's the point.
From the npm docs on package-lock.json:
\n\n\nThis file is intended to be committed into source repositories, and serves various purposes: describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
\n
So the two files work together:
\npackage.json says \"I want something in this range\"package-lock.json says \"here's the specific version I chose and committed to\"This is the part that felt wrong to me. (I'm on npm 11, for reference — the behavior may differ on older versions.) The official npm docs for npm update say:
\n\nNote that by default npm update will not update the semver values of direct dependencies in your project package.json.
\n
Why? Because the semver range in package.json is a constraint, not a version. If ^1.1.3 already allows 1.2.0, there's no reason to change it to ^1.2.0. The range still works. The lockfile already reflects the actual installed version.
There's a configuration option called save that controls this. From the docs:
\n\nsave — Default:
\ntrueunless when usingnpm updatewhere it defaults tofalse
So npm update explicitly opts out of writing to package.json. You can override it with npm update --save.
I ran npm update --save to force package.json to update. And it did. But the result looked... wrong.
Before:
\n\"@types/node\": \"^20\",\n\"eslint\": \"^9\",\n\"typescript\": \"^5\"After:
\n\"@types/node\": \"^20.19.39\",\n\"eslint\": \"^9.39.4\",\n\"typescript\": \"^5.9.3\"Very specific. Down to major.minor.patch. That felt bad. Was I now pinned to exact versions?
\nNo. The ^ is still there. ^5.9.3 still means >=5.9.3 <6.0.0. The range just starts from a higher floor.
I'm still not totally sure, but I've settled on broad ranges being fine.
\nThe lockfile is the source of truth for what's installed. package.json is the source of truth for what range you're willing to accept. If I pin ^5.9.3 in package.json, I'm just duplicating what the lockfile already tracks. The only scenario where the pinned version matters is if someone deletes the lockfile — and I'd rather solve that with \"don't delete the lockfile\" than by making package.json more restrictive.
I'm going back to broad ranges in package.json. I'll use npm update without --save to keep the lockfile current, and let package.json stay as the loose constraint it's designed to be.
If I need to pin a specific version, I'll do it intentionally with npm install package@exact-version, not as a side effect of npm update --save.
The key thing I was missing: package.json and package-lock.json aren't saying the same thing in different ways. They're saying different things on purpose.
I wish someone had explained that to me before I spent a while being confused by a file that was working exactly as designed.
", "url": "https://lukemanning.ie/blog/npm-package-json-vs-package-lock-json", "title": "I Updated a Package and package.json Didn't Change. Turns Out That's Normal.", "summary": "I updated @manningworks/projex to 1.2.0. At least, I thought I did. The installed version was 1.2.0, confirmed with npm ls. But my package.json still said ^1.1.3.
Wait, what?
\nI assumed npm update would update package.json. That seems like the obvious thing it should do. It doesn't. And that's by design. But figuring out why took me through a bunch of npm documentation I'd never actually read properly.
Here's what I assumed the workflow was:
\nnpm updatepackage.json gets updated to reflect the new versionspackage-lock.json gets updated tooSteps 2 and 4 happened. Step 3 did not.
\nI stared at my package.json for a while wondering if I'd hallucinated the update. I hadn't. The package was definitely on 1.2.0 in node_modules. But the file that's supposed to declare my dependencies was lying to me.
Or so I thought.
\nI hit the npm docs. Started with the package-lock.json docs, then worked backward to how package.json handles versions. The first thing that clicked was realizing I'd been thinking about package.json wrong the whole time.
package.json doesn't store the exact version you have installed. It stores a semver range. The ^ prefix means \"compatible with this version.\" ^1.1.3 means \"anything from 1.1.3 up to, but not including, 2.0.0.\" (There's also ~ for patch-only updates, and no prefix pins the exact version. But ^ is what npm uses by default, which is why nearly every entry in your package.json has it.)
So when I had \"@manningworks/projex\": \"^1.1.3\" and npm installed 1.2.0, that's working as intended. 1.2.0 satisfies the range >=1.1.3 <2.0.0. The range didn't need to change.
I didn't know this. I thought the version in package.json was the version, not the minimum acceptable version.
This is the part I was fuzzy on. package-lock.json stores the exact version installed for every package in your dependency tree. Not ranges. Exact versions.
When you run npm install, npm looks at the ranges in package.json, resolves them to specific versions, installs those, and writes the exact resolutions to package-lock.json.
Next time someone clones your repo and runs npm install, they get the exact same versions. Not \"whatever the latest is that satisfies the range.\" The same versions. That's the point.
From the npm docs on package-lock.json:
\n\n\nThis file is intended to be committed into source repositories, and serves various purposes: describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
\n
So the two files work together:
\npackage.json says \"I want something in this range\"package-lock.json says \"here's the specific version I chose and committed to\"This is the part that felt wrong to me. (I'm on npm 11, for reference — the behavior may differ on older versions.) The official npm docs for npm update say:
\n\nNote that by default npm update will not update the semver values of direct dependencies in your project package.json.
\n
Why? Because the semver range in package.json is a constraint, not a version. If ^1.1.3 already allows 1.2.0, there's no reason to change it to ^1.2.0. The range still works. The lockfile already reflects the actual installed version.
There's a configuration option called save that controls this. From the docs:
\n\nsave — Default:
\ntrueunless when usingnpm updatewhere it defaults tofalse
So npm update explicitly opts out of writing to package.json. You can override it with npm update --save.
I ran npm update --save to force package.json to update. And it did. But the result looked... wrong.
Before:
\n\"@types/node\": \"^20\",\n\"eslint\": \"^9\",\n\"typescript\": \"^5\"After:
\n\"@types/node\": \"^20.19.39\",\n\"eslint\": \"^9.39.4\",\n\"typescript\": \"^5.9.3\"Very specific. Down to major.minor.patch. That felt bad. Was I now pinned to exact versions?
\nNo. The ^ is still there. ^5.9.3 still means >=5.9.3 <6.0.0. The range just starts from a higher floor.
I'm still not totally sure, but I've settled on broad ranges being fine.
\nThe lockfile is the source of truth for what's installed. package.json is the source of truth for what range you're willing to accept. If I pin ^5.9.3 in package.json, I'm just duplicating what the lockfile already tracks. The only scenario where the pinned version matters is if someone deletes the lockfile — and I'd rather solve that with \"don't delete the lockfile\" than by making package.json more restrictive.
I'm going back to broad ranges in package.json. I'll use npm update without --save to keep the lockfile current, and let package.json stay as the loose constraint it's designed to be.
If I need to pin a specific version, I'll do it intentionally with npm install package@exact-version, not as a side effect of npm update --save.
The key thing I was missing: package.json and package-lock.json aren't saying the same thing in different ways. They're saying different things on purpose.
I wish someone had explained that to me before I spent a while being confused by a file that was working exactly as designed.
", "date_modified": "2026-04-12T00:00:00.000Z", "tags": [ "nextjs" ] }, { "id": "https://lukemanning.ie/blog/opencode-subagent-permissions-ordering-trap", "content_html": "Every time my release-manager subagent tried to run grep or git log, OpenCode prompted me for approval. I had explicit \"grep *\": allow rules in the config. They weren't working.
This tripped me up for way longer than it should have. (I'm running OpenCode v1.4 — permission behavior may differ in other versions.)
\nThe release-manager agent handles version bumps, changelogs, and git tagging for my Projex project. Its config in .opencode/agents/release-manager.md had bash permissions like this:
bash:\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"git log -- *\": allow\n \"git diff -- *\": allow\n \"git status\": allow\n \"*\": askLooks reasonable. Specific commands are allowed, everything else asks. Except every single command was prompting. grep, git log, cat — all asking for permission.
I re-read the config about five times. The rules were right there — \"grep *\": allow — clear as day. I tried shuffling the order around. Tried different wildcard syntax. Nothing worked.
Eventually I went back to the OpenCode permissions docs and actually looked at the examples. Every single one puts the catch-all \"*\": \"ask\" at the top. Mine was at the bottom.
Turns out OpenCode permission rules work on a \"last matching rule wins\" principle.
\nThe \"*\" wildcard matches everything. Including grep. Including git log. So when OpenCode evaluates git log --oneline -20 against my config, both \"git log -- *\" and \"*\" match. Since \"*\" is listed last, it wins. Result: ask.
Every. Single. Time.
\nThe fix was embarrassingly simple. Move the catch-all to the top:
\nbash:\n \"*\": ask\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"git log -- *\": allow\n \"git diff -- *\": allow\n \"git status\": allowNow \"*\" matches first, but then \"grep *\" matches after and wins because it's the last matching rule. Specific overrides general. The way it should work.
I'd put the catch-all at the bottom out of habit — like a default case in a switch statement. I just... didn't read carefully enough.
\nAfter fixing the ordering, grep worked fine. But git log --oneline -20 still prompted.
I tested a few more variations to narrow it down. git log -- somefile (with the path separator) matched. git log --oneline didn't. The difference clicked pretty fast after that.
The pattern \"git log -- *\" only matches commands that literally have -- in them. Like git log -- somefile. It doesn't match git log --oneline -20 because --oneline is a flag, not the -- path separator.
I'd been too specific. Changed to:
\n \"git log *\": allow\n \"git log\": allow\n \"git diff *\": allow\n \"git diff\": allow\n \"git status *\": allow\n \"git status\": allowBoth forms — with and without arguments. The * wildcard matches zero or more of any character. So \"git log *\" covers git log --oneline -20. But the space before * is literal. The pattern requires \"git log\" followed by a space, then anything. A bare git log with no trailing space won't match it. That's why \"git log\" (no wildcard) is also needed.
Even after both fixes, it still prompted. I'd been eyeing the tools field suspiciously since the start. The config had both the deprecated tools block and the newer permission block.
tools:\n read: true\n write: true\n edit: true\n bash: true\npermission:\n bash:\n \"*\": ask\n \"grep *\": allowThe docs say tools.bash: true is equivalent to {\"*\": \"allow\"}. Having both tools and permission for the same thing seemed like it could cause conflicts — one saying \"allow everything\" and the other saying \"ask for everything except these.\" I don't know exactly how OpenCode resolves this internally, but removing the tools block entirely fixed the remaining issues.
The final config for the release-manager agent looks like this:
\n---\ndescription: Create releases following Projex's version bump, changelog, and git tagging workflow\nmode: subagent\ntemperature: 0.1\npermission:\n edit:\n \"*\": ask\n \"packages/core/package.json\": allow\n \"CHANGELOG.md\": allow\n \"README.md\": allow\n \"packages/core/README.md\": allow\n \"packages/docs/**/*\": allow\n bash:\n \"*\": ask\n \"pnpm --filter * build\": allow\n \"pnpm --filter * lint\": allow\n \"pnpm --filter * typecheck\": allow\n \"pnpm --filter * test\": allow\n \"head *\": allow\n \"ls *\": allow\n \"ls -la *\": allow\n \"find *\": allow\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"tail *\": allow\n \"wc *\": allow\n \"wc -l *\": allow\n \"sort *\": allow\n \"uniq *\": allow\n \"git log *\": allow\n \"git log\": allow\n \"git diff *\": allow\n \"git diff\": allow\n \"git status *\": allow\n \"git status\": allow\n \"git tag *\": allow\n webfetch: deny\n color: success\n---Three separate issues stacked on top of each other. Rule ordering, overly narrow patterns, and deprecated config conflicting with new config.
\nThree things I learned about OpenCode subagent permissions:
\n\"*\": ask needs to be at the top of the permission block. Last matching rule wins.\"git log -- *\" doesn't match git log --oneline. I had to use \"git log *\" instead.tools and permission. Removing the deprecated tools field fixed the remaining issues for me.I fixed the same issues in my documentation-manager agent too. Both agents now run without prompting on every command. Which is how it should have been from the start.
", "url": "https://lukemanning.ie/blog/opencode-subagent-permissions-ordering-trap", "title": "My Subagents Kept Asking Permission for Everything: The Config Ordering Trap", "summary": "Every time my release-manager subagent tried to run grep or git log, OpenCode prompted me for approval. I had explicit \"grep *\": allow rules in the config. They weren't working.
This tripped me up for way longer than it should have. (I'm running OpenCode v1.4 — permission behavior may differ in other versions.)
\nThe release-manager agent handles version bumps, changelogs, and git tagging for my Projex project. Its config in .opencode/agents/release-manager.md had bash permissions like this:
bash:\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"git log -- *\": allow\n \"git diff -- *\": allow\n \"git status\": allow\n \"*\": askLooks reasonable. Specific commands are allowed, everything else asks. Except every single command was prompting. grep, git log, cat — all asking for permission.
I re-read the config about five times. The rules were right there — \"grep *\": allow — clear as day. I tried shuffling the order around. Tried different wildcard syntax. Nothing worked.
Eventually I went back to the OpenCode permissions docs and actually looked at the examples. Every single one puts the catch-all \"*\": \"ask\" at the top. Mine was at the bottom.
Turns out OpenCode permission rules work on a \"last matching rule wins\" principle.
\nThe \"*\" wildcard matches everything. Including grep. Including git log. So when OpenCode evaluates git log --oneline -20 against my config, both \"git log -- *\" and \"*\" match. Since \"*\" is listed last, it wins. Result: ask.
Every. Single. Time.
\nThe fix was embarrassingly simple. Move the catch-all to the top:
\nbash:\n \"*\": ask\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"git log -- *\": allow\n \"git diff -- *\": allow\n \"git status\": allowNow \"*\" matches first, but then \"grep *\" matches after and wins because it's the last matching rule. Specific overrides general. The way it should work.
I'd put the catch-all at the bottom out of habit — like a default case in a switch statement. I just... didn't read carefully enough.
\nAfter fixing the ordering, grep worked fine. But git log --oneline -20 still prompted.
I tested a few more variations to narrow it down. git log -- somefile (with the path separator) matched. git log --oneline didn't. The difference clicked pretty fast after that.
The pattern \"git log -- *\" only matches commands that literally have -- in them. Like git log -- somefile. It doesn't match git log --oneline -20 because --oneline is a flag, not the -- path separator.
I'd been too specific. Changed to:
\n \"git log *\": allow\n \"git log\": allow\n \"git diff *\": allow\n \"git diff\": allow\n \"git status *\": allow\n \"git status\": allowBoth forms — with and without arguments. The * wildcard matches zero or more of any character. So \"git log *\" covers git log --oneline -20. But the space before * is literal. The pattern requires \"git log\" followed by a space, then anything. A bare git log with no trailing space won't match it. That's why \"git log\" (no wildcard) is also needed.
Even after both fixes, it still prompted. I'd been eyeing the tools field suspiciously since the start. The config had both the deprecated tools block and the newer permission block.
tools:\n read: true\n write: true\n edit: true\n bash: true\npermission:\n bash:\n \"*\": ask\n \"grep *\": allowThe docs say tools.bash: true is equivalent to {\"*\": \"allow\"}. Having both tools and permission for the same thing seemed like it could cause conflicts — one saying \"allow everything\" and the other saying \"ask for everything except these.\" I don't know exactly how OpenCode resolves this internally, but removing the tools block entirely fixed the remaining issues.
The final config for the release-manager agent looks like this:
\n---\ndescription: Create releases following Projex's version bump, changelog, and git tagging workflow\nmode: subagent\ntemperature: 0.1\npermission:\n edit:\n \"*\": ask\n \"packages/core/package.json\": allow\n \"CHANGELOG.md\": allow\n \"README.md\": allow\n \"packages/core/README.md\": allow\n \"packages/docs/**/*\": allow\n bash:\n \"*\": ask\n \"pnpm --filter * build\": allow\n \"pnpm --filter * lint\": allow\n \"pnpm --filter * typecheck\": allow\n \"pnpm --filter * test\": allow\n \"head *\": allow\n \"ls *\": allow\n \"ls -la *\": allow\n \"find *\": allow\n \"grep *\": allow\n \"rg *\": allow\n \"cat *\": allow\n \"tail *\": allow\n \"wc *\": allow\n \"wc -l *\": allow\n \"sort *\": allow\n \"uniq *\": allow\n \"git log *\": allow\n \"git log\": allow\n \"git diff *\": allow\n \"git diff\": allow\n \"git status *\": allow\n \"git status\": allow\n \"git tag *\": allow\n webfetch: deny\n color: success\n---Three separate issues stacked on top of each other. Rule ordering, overly narrow patterns, and deprecated config conflicting with new config.
\nThree things I learned about OpenCode subagent permissions:
\n\"*\": ask needs to be at the top of the permission block. Last matching rule wins.\"git log -- *\" doesn't match git log --oneline. I had to use \"git log *\" instead.tools and permission. Removing the deprecated tools field fixed the remaining issues for me.I fixed the same issues in my documentation-manager agent too. Both agents now run without prompting on every command. Which is how it should have been from the start.
", "date_modified": "2026-04-11T00:00:00.000Z", "tags": [ "opencode" ] }, { "id": "https://lukemanning.ie/blog/building-projex-retrospective", "content_html": "I shipped an entire open source project and never documented a single day of building it.
\n209 commits. February 21st to April 2nd. A full component library with a CLI, docs site, npm publishing pipeline, compound component API. And not one blog post while I was building any of it.
\nThis is the opposite of what I said I wanted to do.
\nProjex started with a question I couldn't stop thinking about: how do I showcase my projects on my personal site in a structured way?
\nI asked around. Did some research. Kept getting the same answer: most developers just build a custom solution. That struck me as strange. If everyone building a personal site needs a project showcase, why is everyone building the same thing from scratch?
\nThat gap felt like an opportunity.
\nI had just redesigned my site with a terminal aesthetic and needed a projects page. The timing lined up. I was also looking for my first real OSS project, something with my name on it that other people could actually use.
\nSo I started building.
\nLooking at the git log, the first two days were intense. February 21st alone has something like 30 commits. Monorepo scaffold with pnpm workspaces. TypeScript types. GitHub API integration. Config helper. Compound components. A full demo app.
\nBy the end of day one, I had the core architecture in place. That's not because I'm fast. It's because I had a clear picture of what I wanted before I started. The PRD was detailed enough that the initial implementation moved quickly.
\nFebruary 22nd was more of the same. npm registry support. Product Hunt integration. Layout components. Filter and sort utilities. Tests. Performance benchmarks. CI/CD pipeline.
\nTwo days in and I had a working product. That should have been the point where I wrote my first blog post. It wasn't.
\nEarly on, I split the project into separate CLI and core packages. Seemed like the right call at the time. Different concerns, different responsibilities, clean separation.
\nA few days later I merged them back into a single package.
\nThe git log tells the story plainly: refactor: merge CLI and core into single @reallukemanning/folio package. No drama. No long agonising. Just a realisation that the separation was premature and added complexity I didn't need.
Architecture decisions made on day one are expensive to undo. I learned that one firsthand. The merge itself wasn't painful, but it was a reminder to bias toward simplicity when possible. I could always split things later if I actually needed to.
\nThe docs site was its own adventure.
\nI built the documentation with VitePress and deployed it to Vercel. The build succeeded. Everything looked green. But the site returned 404s.
\nNot helpful error messages. Not warnings during build. Just... 404s. Silent, unhelpful 404s.
\nThe git log from February 22nd tells the whole debugging arc:
\nfix: update VitePress output directory to point to src folder\nfix: copy VitePress assets to src directory for Vercel deployment\nrefactor: use Vercel rewrites instead of file copying\nfix: add rewrite for vp-icons.css at dist root\nfix: remove cleanUrls and rewrites, let Vercel handle routing\nfix: use copy-assets approach with all files in src/\nfix: copy all root-level files to src/ for Vercel\nfix: move HTML files to dist root for proper VitePress deployment\nfix: resolve Vercel 404s by moving all build files to dist root\nfix: add srcDir to VitePress config to resolve client-side 404s\nNine commits. Nine attempts. The problem was that VitePress and Vercel disagree about where built files should live and how routing should work. If your output directory or routing config is even slightly wrong, Vercel just silently 404s. No error. No hint. Just nothing.
\nI tried file copying. Then Vercel rewrites. Then removing rewrites. Then different directory structures. What finally worked was setting srcDir in the VitePress config to get the build output in the right place.
Obvious in hindsight. Everything is.
\nThis is the one that nearly broke me.
\nGetting npm publishing working through GitHub Actions took from March 7th to March 8th. Two full days of failed publish attempts, each one a commit trying a different approach.
\nThe commit log from that stretch is almost comedy:
\nfix: use npm trusted publishing (remove NPM_TOKEN)\nfix: add id-token permission for trusted publishing\nfix: add registry-url for pnpm OIDC publishing\nfix: use npm directly for OIDC publishing\nrevert: use NPM_TOKEN like v1.7.1\nfix: use trusted publishing with pnpm\nfix: use NPM_TOKEN for publishing\nfix: use .npmrc for npm authentication\nfix: use npm with OIDC for publishing\nfix: add fetch mocking to npm-config tests to prevent CI timeout\nfix: use npm with OIDC (remove all token references)\nfix: configure npm registry and publish from correct directory\nfix: add --provenance flag for OIDC publishing\nfix: add repository field and upgrade npm for trusted publishing\nfix: use npm@11.5.1 and publish directly with npm\nfix: add contents:write permission for GitHub releases\nI went back and forth between NPM_TOKEN and OIDC trusted publishing at least three times. The problem wasn't that OIDC is hard conceptually. The problem was that every combination of pnpm vs npm, registry-url config, provenance flags, and GitHub Actions permissions had its own subtle failure mode.
\nAnd the error messages were unhelpful. npm publish failures tend to be vague. You'd get \"authentication required\" or \"unauthorized\" with no indication of whether the token was wrong, the registry URL was wrong, or the permissions were wrong.
\nWhat finally worked: OIDC trusted publishing with the right combination of npm version (11.5.1 for provenance support), correct registry-url setup, and the --provenance flag. But getting there required trying basically every permutation.
Was it worth it? Yeah. OIDC means no secrets to rotate, no tokens to leak, no NPM_TOKEN sitting in GitHub Actions secrets. But the setup pain was real.
\nThe project was originally called Folio. Package name @reallukemanning/folio. Everything was Folio for the first two weeks.
Then on March 8th, I renamed the whole thing. chore: rename Folio to Projex and repackage to @manningworks/projex.
A rename sounds simple. It wasn't. Every data attribute in every component changed from data-folio-* to data-projex-*. Every import path. Every reference in docs. The pnpm lockfile. The GitHub workflows. The CLI commands. The README.
chore: rename Folio to Projex and repackage to @manningworks/projex\nfix: update test files to use new data-projex-* attributes\nfix: remove all remaining Folio references\nfix: regenerate pnpm-lock.yaml with new package name\nFour commits just for the rename, and that's not counting the docs updates.
\nI renamed it because I wanted a more distinctive name. Folio is generic. Every portfolio project is called Folio. Projex felt more unique and more aligned with what I was actually building, a project showcase framework, not a portfolio template.
\nThe funny part: I didn't catch all the references. On April 2nd, nearly a month later, I was still fixing leftover Folio references: fix: correct Folio→Projex branding, unscoped npx commands, and CSS variable names (v1.1.4).
209 commits later, Projex is:
\nProjectCard.Header, ProjectCard.Stats, etc.)npx @manningworks/projex init --githubIt's used in production on my own site. It's on npm. The docs are live. It's real.
\nI don't have a great answer for this.
\nPartly it was momentum. I was building fast and writing would have slowed me down. Partly it was the classic developer trap: I'll write about it when it's done. Then done kept moving. First it was \"done when the core works.\" Then \"done when I have docs.\" Then \"done when publishing works.\" Then \"done when I rename it.\" Then \"done when it's public on GitHub.\"
\nSpoiler: it's never done.
\nPartly it was the thing I wrote about in posting into the void. I didn't want to write about something that no one was going to read. Which is backwards, because my blog is supposed to be documentation for myself first. I wrote a whole voice guide about this and then didn't follow my own advice.
\nThe irony of saying I want to build in public and then building an entire project in private isn't lost on me.
\nI'd write while building. Even short posts. Even rough notes. The OIDC publishing saga alone deserved its own post. The VitePress debugging arc would have been useful for someone else going through the same thing.
\nThe retrospective you're reading right now has less detail than it would have if I'd written it at the time. I'm reconstructing from git logs instead of writing from experience. That's a loss. The specific feeling of trying OIDC approach number seven at 11pm is gone. All I have is the commit message.
\nI'd also have started simpler with the architecture. The split CLI/core package was premature. I knew that pretty quickly but it's still time I spent on something I undid.
\nAnd I'd have picked the right name from the start.
\nProjex is at v1.1.4. It's on npm as @manningworks/projex. The docs are at projex.manningworks.dev. The repo is public on GitHub.
It hasn't set the world on fire. But it's real, it works, and I use it every day on my own site.
\nThe next step for me is to actually build in public going forward. Not as a brand strategy or a growth hack. Just as documentation of what I'm working on, as it happens. This post is the start of that, even if it's late.
\n209 commits and not a single blog post. That's the antithesis of what I said I wanted to embody.
\nBetter late than never, I guess.
", "url": "https://lukemanning.ie/blog/building-projex-retrospective", "title": "I Built Projex and Never Wrote a Word About It", "summary": "I shipped an entire open source project and never documented a single day of building it.
\n209 commits. February 21st to April 2nd. A full component library with a CLI, docs site, npm publishing pipeline, compound component API. And not one blog post while I was building any of it.
\nThis is the opposite of what I said I wanted to do.
\nProjex started with a question I couldn't stop thinking about: how do I showcase my projects on my personal site in a structured way?
\nI asked around. Did some research. Kept getting the same answer: most developers just build a custom solution. That struck me as strange. If everyone building a personal site needs a project showcase, why is everyone building the same thing from scratch?
\nThat gap felt like an opportunity.
\nI had just redesigned my site with a terminal aesthetic and needed a projects page. The timing lined up. I was also looking for my first real OSS project, something with my name on it that other people could actually use.
\nSo I started building.
\nLooking at the git log, the first two days were intense. February 21st alone has something like 30 commits. Monorepo scaffold with pnpm workspaces. TypeScript types. GitHub API integration. Config helper. Compound components. A full demo app.
\nBy the end of day one, I had the core architecture in place. That's not because I'm fast. It's because I had a clear picture of what I wanted before I started. The PRD was detailed enough that the initial implementation moved quickly.
\nFebruary 22nd was more of the same. npm registry support. Product Hunt integration. Layout components. Filter and sort utilities. Tests. Performance benchmarks. CI/CD pipeline.
\nTwo days in and I had a working product. That should have been the point where I wrote my first blog post. It wasn't.
\nEarly on, I split the project into separate CLI and core packages. Seemed like the right call at the time. Different concerns, different responsibilities, clean separation.
\nA few days later I merged them back into a single package.
\nThe git log tells the story plainly: refactor: merge CLI and core into single @reallukemanning/folio package. No drama. No long agonising. Just a realisation that the separation was premature and added complexity I didn't need.
Architecture decisions made on day one are expensive to undo. I learned that one firsthand. The merge itself wasn't painful, but it was a reminder to bias toward simplicity when possible. I could always split things later if I actually needed to.
\nThe docs site was its own adventure.
\nI built the documentation with VitePress and deployed it to Vercel. The build succeeded. Everything looked green. But the site returned 404s.
\nNot helpful error messages. Not warnings during build. Just... 404s. Silent, unhelpful 404s.
\nThe git log from February 22nd tells the whole debugging arc:
\nfix: update VitePress output directory to point to src folder\nfix: copy VitePress assets to src directory for Vercel deployment\nrefactor: use Vercel rewrites instead of file copying\nfix: add rewrite for vp-icons.css at dist root\nfix: remove cleanUrls and rewrites, let Vercel handle routing\nfix: use copy-assets approach with all files in src/\nfix: copy all root-level files to src/ for Vercel\nfix: move HTML files to dist root for proper VitePress deployment\nfix: resolve Vercel 404s by moving all build files to dist root\nfix: add srcDir to VitePress config to resolve client-side 404s\nNine commits. Nine attempts. The problem was that VitePress and Vercel disagree about where built files should live and how routing should work. If your output directory or routing config is even slightly wrong, Vercel just silently 404s. No error. No hint. Just nothing.
\nI tried file copying. Then Vercel rewrites. Then removing rewrites. Then different directory structures. What finally worked was setting srcDir in the VitePress config to get the build output in the right place.
Obvious in hindsight. Everything is.
\nThis is the one that nearly broke me.
\nGetting npm publishing working through GitHub Actions took from March 7th to March 8th. Two full days of failed publish attempts, each one a commit trying a different approach.
\nThe commit log from that stretch is almost comedy:
\nfix: use npm trusted publishing (remove NPM_TOKEN)\nfix: add id-token permission for trusted publishing\nfix: add registry-url for pnpm OIDC publishing\nfix: use npm directly for OIDC publishing\nrevert: use NPM_TOKEN like v1.7.1\nfix: use trusted publishing with pnpm\nfix: use NPM_TOKEN for publishing\nfix: use .npmrc for npm authentication\nfix: use npm with OIDC for publishing\nfix: add fetch mocking to npm-config tests to prevent CI timeout\nfix: use npm with OIDC (remove all token references)\nfix: configure npm registry and publish from correct directory\nfix: add --provenance flag for OIDC publishing\nfix: add repository field and upgrade npm for trusted publishing\nfix: use npm@11.5.1 and publish directly with npm\nfix: add contents:write permission for GitHub releases\nI went back and forth between NPM_TOKEN and OIDC trusted publishing at least three times. The problem wasn't that OIDC is hard conceptually. The problem was that every combination of pnpm vs npm, registry-url config, provenance flags, and GitHub Actions permissions had its own subtle failure mode.
\nAnd the error messages were unhelpful. npm publish failures tend to be vague. You'd get \"authentication required\" or \"unauthorized\" with no indication of whether the token was wrong, the registry URL was wrong, or the permissions were wrong.
\nWhat finally worked: OIDC trusted publishing with the right combination of npm version (11.5.1 for provenance support), correct registry-url setup, and the --provenance flag. But getting there required trying basically every permutation.
Was it worth it? Yeah. OIDC means no secrets to rotate, no tokens to leak, no NPM_TOKEN sitting in GitHub Actions secrets. But the setup pain was real.
\nThe project was originally called Folio. Package name @reallukemanning/folio. Everything was Folio for the first two weeks.
Then on March 8th, I renamed the whole thing. chore: rename Folio to Projex and repackage to @manningworks/projex.
A rename sounds simple. It wasn't. Every data attribute in every component changed from data-folio-* to data-projex-*. Every import path. Every reference in docs. The pnpm lockfile. The GitHub workflows. The CLI commands. The README.
chore: rename Folio to Projex and repackage to @manningworks/projex\nfix: update test files to use new data-projex-* attributes\nfix: remove all remaining Folio references\nfix: regenerate pnpm-lock.yaml with new package name\nFour commits just for the rename, and that's not counting the docs updates.
\nI renamed it because I wanted a more distinctive name. Folio is generic. Every portfolio project is called Folio. Projex felt more unique and more aligned with what I was actually building, a project showcase framework, not a portfolio template.
\nThe funny part: I didn't catch all the references. On April 2nd, nearly a month later, I was still fixing leftover Folio references: fix: correct Folio→Projex branding, unscoped npx commands, and CSS variable names (v1.1.4).
209 commits later, Projex is:
\nProjectCard.Header, ProjectCard.Stats, etc.)npx @manningworks/projex init --githubIt's used in production on my own site. It's on npm. The docs are live. It's real.
\nI don't have a great answer for this.
\nPartly it was momentum. I was building fast and writing would have slowed me down. Partly it was the classic developer trap: I'll write about it when it's done. Then done kept moving. First it was \"done when the core works.\" Then \"done when I have docs.\" Then \"done when publishing works.\" Then \"done when I rename it.\" Then \"done when it's public on GitHub.\"
\nSpoiler: it's never done.
\nPartly it was the thing I wrote about in posting into the void. I didn't want to write about something that no one was going to read. Which is backwards, because my blog is supposed to be documentation for myself first. I wrote a whole voice guide about this and then didn't follow my own advice.
\nThe irony of saying I want to build in public and then building an entire project in private isn't lost on me.
\nI'd write while building. Even short posts. Even rough notes. The OIDC publishing saga alone deserved its own post. The VitePress debugging arc would have been useful for someone else going through the same thing.
\nThe retrospective you're reading right now has less detail than it would have if I'd written it at the time. I'm reconstructing from git logs instead of writing from experience. That's a loss. The specific feeling of trying OIDC approach number seven at 11pm is gone. All I have is the commit message.
\nI'd also have started simpler with the architecture. The split CLI/core package was premature. I knew that pretty quickly but it's still time I spent on something I undid.
\nAnd I'd have picked the right name from the start.
\nProjex is at v1.1.4. It's on npm as @manningworks/projex. The docs are at projex.manningworks.dev. The repo is public on GitHub.
It hasn't set the world on fire. But it's real, it works, and I use it every day on my own site.
\nThe next step for me is to actually build in public going forward. Not as a brand strategy or a growth hack. Just as documentation of what I'm working on, as it happens. This post is the start of that, even if it's late.
\n209 commits and not a single blog post. That's the antithesis of what I said I wanted to embody.
\nBetter late than never, I guess.
", "date_modified": "2026-04-10T00:00:00.000Z", "tags": [ "projex" ] }, { "id": "https://lukemanning.ie/blog/the-hobby-isolation-paradox", "content_html": "There's a specific kind of exhaustion that comes with being the tech person in your family.
\nIt's not the fixing. You can fix things. It's the explaining. Bridging the gap between what's actually happening and what will land for the person standing over your shoulder. You get good at simplifying. Fast at it. But after a while the simplifying starts to feel like a tax. And eventually, without really noticing, you stop bringing certain things up at all. Not because people don't care about you. But because you already know how it ends.
\nHobbies are supposed to fix this.
\nCommon ground. A talking point. Something to bond over. The implicit promise of a hobby is that it connects you to people — other enthusiasts, curious friends, family members who ask how it's going. For most hobbies that promise holds. You pick up candle making and suddenly you have something easy to talk about at dinner. Everyone knows what a candle is. The vocabulary is shared, the concept of enjoying it makes intuitive sense.
\nBut some hobbies break that promise entirely.
\nRight now the thing I'm most excited about is agentic engineering — building software by collaborating with AI. Not using it as a shortcut. Using it as a creative partner. It's what I think about when I'm not working. What I open my laptop for on a Saturday morning before I've had coffee.
\nAnd almost nobody in my day-to-day life gets it.
\nI've tried explaining it. Someone asks what I've been up to, and I start with \"building software with AI\" and I can see it happen — the polite nod, the slight glaze. Not because they don't care. They're trying. But the words don't land. \"AI agent\" means nothing to most people. \"Prompt engineering\" sounds like corporate jargon. Before I can get to the interesting part I'm already three layers deep in background, and the conversation has moved on.
\nEven when I find the right simplification, there's another wall waiting. Because building software on a Saturday morning doesn't register as a hobby. It sounds like work. The idea that it could be play — that it's the thing I look forward to all week — that part doesn't compute.
\nSo I stop bringing it up. Or I start to, feel what's coming, and just let it go.
\nThe thing that was supposed to give me community becomes the thing I can't even mention.
\nRecently someone I work with mentioned Claude Code in passing. Just dropped it into conversation like it was nothing. The same energy, the same excitement, that I'd been wanting to express. We were already two steps into a conversation I didn't have to set up.
\nThat's part of why I write here. Not to explain things to people who don't get it — but to find the ones who already do. The builder who's also lying awake thinking about what's coming. The person who gets why this stuff is fun, not just useful.
\nOn the flip side: being island-like with your content means it stops compounding. The silence isn't just from nobody reading — it can also be because the work itself isn't wired to pull people deeper.
", "url": "https://lukemanning.ie/blog/the-hobby-isolation-paradox", "title": "The Hobby Isolation Paradox", "summary": "There's a specific kind of exhaustion that comes with being the tech person in your family.
\nIt's not the fixing. You can fix things. It's the explaining. Bridging the gap between what's actually happening and what will land for the person standing over your shoulder. You get good at simplifying. Fast at it. But after a while the simplifying starts to feel like a tax. And eventually, without really noticing, you stop bringing certain things up at all. Not because people don't care about you. But because you already know how it ends.
\nHobbies are supposed to fix this.
\nCommon ground. A talking point. Something to bond over. The implicit promise of a hobby is that it connects you to people — other enthusiasts, curious friends, family members who ask how it's going. For most hobbies that promise holds. You pick up candle making and suddenly you have something easy to talk about at dinner. Everyone knows what a candle is. The vocabulary is shared, the concept of enjoying it makes intuitive sense.
\nBut some hobbies break that promise entirely.
\nRight now the thing I'm most excited about is agentic engineering — building software by collaborating with AI. Not using it as a shortcut. Using it as a creative partner. It's what I think about when I'm not working. What I open my laptop for on a Saturday morning before I've had coffee.
\nAnd almost nobody in my day-to-day life gets it.
\nI've tried explaining it. Someone asks what I've been up to, and I start with \"building software with AI\" and I can see it happen — the polite nod, the slight glaze. Not because they don't care. They're trying. But the words don't land. \"AI agent\" means nothing to most people. \"Prompt engineering\" sounds like corporate jargon. Before I can get to the interesting part I'm already three layers deep in background, and the conversation has moved on.
\nEven when I find the right simplification, there's another wall waiting. Because building software on a Saturday morning doesn't register as a hobby. It sounds like work. The idea that it could be play — that it's the thing I look forward to all week — that part doesn't compute.
\nSo I stop bringing it up. Or I start to, feel what's coming, and just let it go.
\nThe thing that was supposed to give me community becomes the thing I can't even mention.
\nRecently someone I work with mentioned Claude Code in passing. Just dropped it into conversation like it was nothing. The same energy, the same excitement, that I'd been wanting to express. We were already two steps into a conversation I didn't have to set up.
\nThat's part of why I write here. Not to explain things to people who don't get it — but to find the ones who already do. The builder who's also lying awake thinking about what's coming. The person who gets why this stuff is fun, not just useful.
\nOn the flip side: being island-like with your content means it stops compounding. The silence isn't just from nobody reading — it can also be because the work itself isn't wired to pull people deeper.
", "date_modified": "2026-04-09T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/syncthing-obsidian-vault-sync", "content_html": "Obsidian Sync costs up to $120 a year if you're on Sync Plus, and paying monthly. That's the number that made me actually do something about it.
\nI was curious about using Obsidian Sync because people generally were happy that it worked. At least people on reddit were. However I did not want yet another subscription. As much as I like the work that Obsidian do, I just couldn't justify it.
\nI went with Syncthing because it's peer-to-peer (no third-party server holding my files), it's free, and I've read several threads and watched a few YouTube videos where people swear by it. My always-on NucBox (Ubuntu 24.04, headless) acts as the hub. Windows desktop and Android phone sync to it. I genuinely forget it's there most of the time.
\nThis post isn't a tutorial. The Syncthing docs are fine. What I kept running into was the specific problem of configuring a headless Linux machine without a browser, and nobody really spelled that part out clearly. So here's my setup, including the bits I had to figure out myself.
\nMost Syncthing guides assume you can just open localhost:8384 in a browser on the same machine running Syncthing. My NucBox doesn't have a browser. Or a screen. It's just a small fanless PC sitting under my desk running Ubuntu without a Desktop environment.
My first thought was to install a VNC server or something. I wasn't a fan of that approach and after some more time Googling around I eventually found the SSH tunnel approach, which is way simpler than I expected.
\nSyncthing's web UI runs on port 8384 on the NucBox. I mapped that to a local port on my Windows machine over SSH:
\nssh -L 9384:localhost:8384 luke@<nucbox-ip> -NThen opened localhost:9384 in my browser on my desktop. Syncthing defaults to no auth on the web UI, and I didn't love the idea of an unauthenticated interface accessible over the network. However given this was all running on localhost, I figured that was a problem for another day.
I was already running Syncthing on Windows, which was using port 8384. That's why I mapped to 9384 instead. Anything unused works.
\nThree commands:
\nsudo apt install syncthing\nsystemctl --user enable syncthing\nsystemctl --user start syncthingAfter those, I checked the service was actually running with systemctl --user status syncthing. Active and running. That was my \"okay, it's alive\" moment.
Actually, one thing I assumed I'd have to deal with. systemctl --user services on a headless machine don't survive logout unless you enable \"lingering.\" Without it, Syncthing stops the second you close your SSH session. I checked mine:
loginctl show-user luke | grep LingerTurns out it was already enabled (Linger=yes). I'm guessing something during the Ubuntu install set it up — I definitely never ran loginctl enable-linger myself. But if yours shows Linger=no, you'll need:
loginctl enable-linger lukeThis is probably the most headless-specific gotcha in the whole setup. And I suspect a lot of guides skip it because they assume you have a desktop login session.
\nThe Ubuntu package is fine. I didn't need any third-party repos.
\nOnce the tunnel was up it was the standard Syncthing workflow. I added a folder, pointed it at my vault, and shared it with my other devices. I installed Syncthing-Fork on Android from the F-Droid store. Paired devices using the Device ID from Actions → Show ID.
\nThe Android app can scan a QR code from that same screen, which is much easier than typing out a 60-character device ID by hand. It can also discover other Syncthing devices on the same network, which was super useful for me.
\nI'd been running Syncthing for maybe a day when I started seeing orange warning triangles in the UI. Low-level conflicts on .obsidian/workspace.json and .obsidian/workspace-mobile.json. Nothing catastrophic, but it was noise I didn't need.
Turns out Obsidian rewrites those files every time you open it — they store open tabs, cursor positions, that kind of thing. Different on every device, changing constantly. No wonder Syncthing was confused.
\nA bit of searching told me about .stignore. I added this at the root of the vault:
.obsidian/workspace.json\n.obsidian/workspace-mobile.json\n.trash/\nThe rest of .obsidian/ (plugins, themes, settings) syncs fine. That's the stuff I actually want consistent across machines.
On the same LAN it syncs in seconds. Over the internet it handles NAT traversal automatically. I didn't have to configure any port forwarding or open firewall ports. The NucBox isn't running ufw, so there was nothing to touch there. It just worked.
\nSyncthing apparently used to use relay servers for this, but they were removed a while back (I think around v1.27). Whatever it's doing now, I didn't have to think about it.
\nI've had this running for a few days now across the NucBox, my Windows desktop, and my Android phone. I haven't thought about it once since setting it up, which is exactly what I wanted.
\nThe $120 a year I was considering paying Obsidian Sync? Going toward something else now.
", "url": "https://lukemanning.ie/blog/syncthing-obsidian-vault-sync", "title": "Dropping Obsidian Sync for Syncthing: What I Learned Setting Up a Headless Linux Sync Hub", "summary": "Obsidian Sync costs up to $120 a year if you're on Sync Plus, and paying monthly. That's the number that made me actually do something about it.
\nI was curious about using Obsidian Sync because people generally were happy that it worked. At least people on reddit were. However I did not want yet another subscription. As much as I like the work that Obsidian do, I just couldn't justify it.
\nI went with Syncthing because it's peer-to-peer (no third-party server holding my files), it's free, and I've read several threads and watched a few YouTube videos where people swear by it. My always-on NucBox (Ubuntu 24.04, headless) acts as the hub. Windows desktop and Android phone sync to it. I genuinely forget it's there most of the time.
\nThis post isn't a tutorial. The Syncthing docs are fine. What I kept running into was the specific problem of configuring a headless Linux machine without a browser, and nobody really spelled that part out clearly. So here's my setup, including the bits I had to figure out myself.
\nMost Syncthing guides assume you can just open localhost:8384 in a browser on the same machine running Syncthing. My NucBox doesn't have a browser. Or a screen. It's just a small fanless PC sitting under my desk running Ubuntu without a Desktop environment.
My first thought was to install a VNC server or something. I wasn't a fan of that approach and after some more time Googling around I eventually found the SSH tunnel approach, which is way simpler than I expected.
\nSyncthing's web UI runs on port 8384 on the NucBox. I mapped that to a local port on my Windows machine over SSH:
\nssh -L 9384:localhost:8384 luke@<nucbox-ip> -NThen opened localhost:9384 in my browser on my desktop. Syncthing defaults to no auth on the web UI, and I didn't love the idea of an unauthenticated interface accessible over the network. However given this was all running on localhost, I figured that was a problem for another day.
I was already running Syncthing on Windows, which was using port 8384. That's why I mapped to 9384 instead. Anything unused works.
\nThree commands:
\nsudo apt install syncthing\nsystemctl --user enable syncthing\nsystemctl --user start syncthingAfter those, I checked the service was actually running with systemctl --user status syncthing. Active and running. That was my \"okay, it's alive\" moment.
Actually, one thing I assumed I'd have to deal with. systemctl --user services on a headless machine don't survive logout unless you enable \"lingering.\" Without it, Syncthing stops the second you close your SSH session. I checked mine:
loginctl show-user luke | grep LingerTurns out it was already enabled (Linger=yes). I'm guessing something during the Ubuntu install set it up — I definitely never ran loginctl enable-linger myself. But if yours shows Linger=no, you'll need:
loginctl enable-linger lukeThis is probably the most headless-specific gotcha in the whole setup. And I suspect a lot of guides skip it because they assume you have a desktop login session.
\nThe Ubuntu package is fine. I didn't need any third-party repos.
\nOnce the tunnel was up it was the standard Syncthing workflow. I added a folder, pointed it at my vault, and shared it with my other devices. I installed Syncthing-Fork on Android from the F-Droid store. Paired devices using the Device ID from Actions → Show ID.
\nThe Android app can scan a QR code from that same screen, which is much easier than typing out a 60-character device ID by hand. It can also discover other Syncthing devices on the same network, which was super useful for me.
\nI'd been running Syncthing for maybe a day when I started seeing orange warning triangles in the UI. Low-level conflicts on .obsidian/workspace.json and .obsidian/workspace-mobile.json. Nothing catastrophic, but it was noise I didn't need.
Turns out Obsidian rewrites those files every time you open it — they store open tabs, cursor positions, that kind of thing. Different on every device, changing constantly. No wonder Syncthing was confused.
\nA bit of searching told me about .stignore. I added this at the root of the vault:
.obsidian/workspace.json\n.obsidian/workspace-mobile.json\n.trash/\nThe rest of .obsidian/ (plugins, themes, settings) syncs fine. That's the stuff I actually want consistent across machines.
On the same LAN it syncs in seconds. Over the internet it handles NAT traversal automatically. I didn't have to configure any port forwarding or open firewall ports. The NucBox isn't running ufw, so there was nothing to touch there. It just worked.
\nSyncthing apparently used to use relay servers for this, but they were removed a while back (I think around v1.27). Whatever it's doing now, I didn't have to think about it.
\nI've had this running for a few days now across the NucBox, my Windows desktop, and my Android phone. I haven't thought about it once since setting it up, which is exactly what I wanted.
\nThe $120 a year I was considering paying Obsidian Sync? Going toward something else now.
", "date_modified": "2026-04-08T00:00:00.000Z", "tags": [ "homelab", "obsidian", "ubuntu" ] }, { "id": "https://lukemanning.ie/blog/same-content-different-job", "content_html": "I found a Reddit post this week. Classic AI waffle: income streams, compound interest metaphors, a tidy 26-month arc with conveniently spaced milestones. You've seen the format.
\nIt caught me at the right moment — I'd been thinking about whether my own posting was compounding or just accumulating.
\nBuried in the noise was something worth keeping: the silence is the deposit phase.
\nThe idea being that the first year of building in public (when nobody's watching, nothing's ranking, and your posts feel like they're disappearing into a void) isn't failure. It's just early. The compounding hasn't had time to show up yet.
\nI buy that. It maps to everything I've seen from people who actually made it work long-term. But \"just keep depositing\" has a gap. It assumes all deposits are equal. They're not.
\nMost build-in-public advice stops at \"just keep showing up.\" Post consistently. Play the long game. Trust the process.
\nFine. But what you're building with that consistency matters as much as the consistency itself.
\nI looked at my own setup recently. Blog here, X account there, GitHub with projects that don't link back. Each one technically exists. None of them point at each other. Someone finding my X wouldn't know about the blog. Someone reading the blog wouldn't know about the projects.
\nThat's when it clicked — isolated posts don't compound, they just pile up. The ones that build on each other, reference each other, pull a reader deeper — those are the ones that do.
\nThere's a difference between a large archive and a library. An archive is a pile. A library has structure. Things reference each other, ideas build on ideas, a reader lands on one post and the whole thing pulls them deeper.
\nMy stuff right now is more archive than library. It's easy to end up here, especially early on when you're still figuring out what you're even building.
\nBut the library problem isn't just about posts linking to posts internally. Each platform also needs the content to do different work depending on where it lives.
\nI shipped a component library recently: Projex, a shadcn-style showcase kit for developer portfolios. One project, multiple surfaces.
\nI posted about it on X — a rough thread, a screenshot, a \"shipped this\" post at midnight. Stream of consciousness, move on. Low barrier, builder brain energy.
\nThe blog version is slower. What I learned building it, the tradeoffs, the decisions I'd make differently. Something that earns a bookmark rather than a like.
\nLinkedIn is where I had to think harder. Nobody there cares about the npm package. But the gap between \"good enough for work\" and \"good enough that strangers might actually use it\" — what building something in public taught me about shipping — that's what LinkedIn cares about. That's the version that makes sense there.
\nSame source material. Three different jobs.
\nNot every piece of raw material has all three versions. Some things are only X-native. A half-formed thought, a tool I'm trying, a response to something in the timeline. That doesn't have a LinkedIn version. Forcing one would be obvious and grim.
\nI've caught myself about to cross-post things that would make no sense outside the X timeline. It's \"builder brain at midnight\" energy. It stays on X.
\nI'm working this out in real time.
\nMy LinkedIn has nothing on it right now. No evidence of building. I haven't figured out the voice for it yet, and I've been cautious about the line between \"here's what I'm learning\" and \"here's what I do at work.\" Those aren't the same thing, but they can look the same from the outside if you're not careful.
\nMy X is random. Building observations, occasional blog posts, no obvious throughline if you landed there cold.
\nMy site is growing slowly. Projects, posts, a Now page. The identity is there if you spend time with it, but it's not obvious yet.
\nAnd I think that's fine. I think coherence comes from volume. You can't see the throughline when you've written fifteen posts. It emerges, both for you and for whoever's reading. The job right now isn't to have it all figured out. It's to keep building the library, be intentional about the links between things, and trust that the shape of it becomes clearer over time.
\nThe silence is still the deposit phase. I wrote about what that feels like. And the entrepreneurial gap — between having ideas and actually shipping them — is part of what I'm trying to close. Some of the isolation paradox applies here too: the thing I'm most excited about is hard to talk about anywhere except here. I just want to make sure the deposits are going into the right accounts.
\nBuilding in public at lukemanning.ie. Occasionally coherent on X.
", "url": "https://lukemanning.ie/blog/same-content-different-job", "title": "Same Content, Different Job", "summary": "I found a Reddit post this week. Classic AI waffle: income streams, compound interest metaphors, a tidy 26-month arc with conveniently spaced milestones. You've seen the format.
\nIt caught me at the right moment — I'd been thinking about whether my own posting was compounding or just accumulating.
\nBuried in the noise was something worth keeping: the silence is the deposit phase.
\nThe idea being that the first year of building in public (when nobody's watching, nothing's ranking, and your posts feel like they're disappearing into a void) isn't failure. It's just early. The compounding hasn't had time to show up yet.
\nI buy that. It maps to everything I've seen from people who actually made it work long-term. But \"just keep depositing\" has a gap. It assumes all deposits are equal. They're not.
\nMost build-in-public advice stops at \"just keep showing up.\" Post consistently. Play the long game. Trust the process.
\nFine. But what you're building with that consistency matters as much as the consistency itself.
\nI looked at my own setup recently. Blog here, X account there, GitHub with projects that don't link back. Each one technically exists. None of them point at each other. Someone finding my X wouldn't know about the blog. Someone reading the blog wouldn't know about the projects.
\nThat's when it clicked — isolated posts don't compound, they just pile up. The ones that build on each other, reference each other, pull a reader deeper — those are the ones that do.
\nThere's a difference between a large archive and a library. An archive is a pile. A library has structure. Things reference each other, ideas build on ideas, a reader lands on one post and the whole thing pulls them deeper.
\nMy stuff right now is more archive than library. It's easy to end up here, especially early on when you're still figuring out what you're even building.
\nBut the library problem isn't just about posts linking to posts internally. Each platform also needs the content to do different work depending on where it lives.
\nI shipped a component library recently: Projex, a shadcn-style showcase kit for developer portfolios. One project, multiple surfaces.
\nI posted about it on X — a rough thread, a screenshot, a \"shipped this\" post at midnight. Stream of consciousness, move on. Low barrier, builder brain energy.
\nThe blog version is slower. What I learned building it, the tradeoffs, the decisions I'd make differently. Something that earns a bookmark rather than a like.
\nLinkedIn is where I had to think harder. Nobody there cares about the npm package. But the gap between \"good enough for work\" and \"good enough that strangers might actually use it\" — what building something in public taught me about shipping — that's what LinkedIn cares about. That's the version that makes sense there.
\nSame source material. Three different jobs.
\nNot every piece of raw material has all three versions. Some things are only X-native. A half-formed thought, a tool I'm trying, a response to something in the timeline. That doesn't have a LinkedIn version. Forcing one would be obvious and grim.
\nI've caught myself about to cross-post things that would make no sense outside the X timeline. It's \"builder brain at midnight\" energy. It stays on X.
\nI'm working this out in real time.
\nMy LinkedIn has nothing on it right now. No evidence of building. I haven't figured out the voice for it yet, and I've been cautious about the line between \"here's what I'm learning\" and \"here's what I do at work.\" Those aren't the same thing, but they can look the same from the outside if you're not careful.
\nMy X is random. Building observations, occasional blog posts, no obvious throughline if you landed there cold.
\nMy site is growing slowly. Projects, posts, a Now page. The identity is there if you spend time with it, but it's not obvious yet.
\nAnd I think that's fine. I think coherence comes from volume. You can't see the throughline when you've written fifteen posts. It emerges, both for you and for whoever's reading. The job right now isn't to have it all figured out. It's to keep building the library, be intentional about the links between things, and trust that the shape of it becomes clearer over time.
\nThe silence is still the deposit phase. I wrote about what that feels like. And the entrepreneurial gap — between having ideas and actually shipping them — is part of what I'm trying to close. Some of the isolation paradox applies here too: the thing I'm most excited about is hard to talk about anywhere except here. I just want to make sure the deposits are going into the right accounts.
\nBuilding in public at lukemanning.ie. Occasionally coherent on X.
", "date_modified": "2026-04-07T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/building-a-reading-companion-for-my-vault", "content_html": "I read a lot. Not in a flex way but more like a borderline problem. The problem is none of it sticks. I close the book, move on, and six months later I remember almost nothing. Not the ideas, not the context, barely even the thesis.
\nMy vault lives on Syncthing now — I moved away from Obsidian Sync to cut the cost. Having my vault synced across machines without a subscription made it more viable as a daily tool.
\nI tried highlighting. I tried taking notes on my phone while reading. Neither worked for me. Highlights become a graveyard of yellow that I never revisit, and notes are too spontaneous to build anything coherent.
\nWhat I wanted was a companion. Someone to actually discuss what I'm reading with. Not summarize the book back at me, but pull it apart, connect it to weird stuff, make it memorable.
\nSo I built one. It runs as a skill in my Hermes Agent setup and the enriched data gets stored in my Obsidian Vault.
\nThe reading companion is a skill I can trigger whenever I'm reading something that hits me as interesting, complex, or just worth sitting with. I paste a passage, and it comes back enriched across five areas:
\nThe goal isn't a book report. It's more like having a smart friend who makes unexpected connections and gets genuinely excited about ideas.
\nThis is where it clicked for me. The enriched passages go straight into ~/vault/books/<book-slug>.md. One note per book, entries appended as I read.
So instead of highlights scattered across a Kindle or margins that never talk to each other, I have a running document that traces my journey through a single book. Each entry has the passage, the context, and the date. When I finish the book, I have a map of every moment that made me stop and think.
\nThe vault schema already had a slot for this. The reading-companion skill fills it. Here's an example from The Dark Forest by Liu Cixin:
\n## Passage — Chapter 9 (2025-04-13)\n\n> \"He had returned countless times to these words, analyzing each\n> sentence from every angle and chewing over every word. The component\n> words had been strung into a set of prayer beads, and like a pious\n> monk he stroked them time and again; and unstrung them, scattered\n> them, and restrung them in different orders until a layer of each\n> had been worn away.\"\n\n### Historical Context\n\nThe prayer bead / monk metaphor carries deep roots in Buddhist and\nHindu traditions — *japa mala* beads used for meditation have been\npart of spiritual practice for thousands of years. In the Chinese\ncontext, Buddhism, Taoism, and folk spirituality often blended\ntogether, so a Chinese sci-fi reader would likely feel this resonance\nimmediately. The image of a monk mindfully repeating prayers until\nthe beads literally wear smooth is a real phenomenon — in some\ntraditions, monks are said to 磨损 (wó sǔn) their beads through\ndecades of devotion.\n\nLiu himself was an engineering student in North China during the\nCultural Revolution, so the physicality of repeated labor — the way\nobjects get worn, transformed, made sacred through use — might\nreflect a materialist worldview that nevertheless romanticizes\ndiscipline.\n\n### Pop Culture & Internet\n\nThe idea of \"wearing down\" meaning through repetition has a modern\nparallel in the way certain ideas on Reddit's r/philosophy or YouTube\nessay channels get analyzed until they're drained. There's also a\nstrong resonance with video essay culture — creators who return to the\nsame passages repeatedly until new meaning emerges. The passage itself\nfeels almost like a description of what a great video essay does to a\npiece of media.\n\n### Books & Literature\n\nThis is almost a meta-description of close reading itself. The\nliterary theorist Hans-Georg Gadamer wrote about the \"fusion of\nhorizons\" — the way understanding deepens through repeated dialogue\nbetween reader and text. The prayer bead image also echoes Umberto\nEco's concept of the *open text*, which rewards repeated visits. In\na Chinese literary tradition, this mirrors the scholar's relationship\nwith the Confucian classics — the *Four Books* that Ming Dynasty\nscholars would return to compulsively, each reading layering new\nmeaning.\n\n### Unexpected Trivia\n\nThe Chinese word for \"ruminate\" (咀嚼, jǔjué) literally means \"chew\"\n— as in chewing food. The passage's \"chewing over every word\" is\neven more visceral in the original imagery. Also: in some Buddhist\nmonasteries, monks recount that the holes in prayer beads eventually\nbecome polished to a mirror shine from skin oils and decades of\nhandling.\n\n### Emotional / Thematic Insight\n\nThis passage is almost a thesis statement for the entire *Remembrance\nof Earth's Past* trilogy — the Trisolaris series grapples with\ncommunication across cosmic time scales, with meaning that gets worn\ndown, reinterpreted, and restrung by civilizations that may not even\nshare the same physics. The Dark Forest itself is a theory about how\ncivilizations communicate (or don't) — each \"wearing down\" the other's\nsignals until something alien emerges. Liu is telling you how to read\nhis books: like a monk, slowly, repeatedly, until meaning is absorbed\ninto the self.Simple, repeatable, always in the same place.
\nWhether to write my own reactions alongside the enrichment, or let the enrichment stand alone. Right now it's enrichment only — but I think the most valuable version is when I also note what the passage made me think about. Still developing that.
\nAlso: when to stop. Some passages probably don't need enriching. I'm figuring out what \"complex, deep, or interesting\" actually means to me in practice.
\nMost AI book tools either summarize chapters (which I don't need — I just read the chapter) or generate flashcards (which feels like studying, not reading). I'm not trying to memorize more or pass quizzes. I'm trying to actually engage with what I read, make it richer and weirder and more likely to stick.
\nWhat I want from this long-term: a reading log that's actually useful six months from now, connections between books I wouldn't catch on my own, and a reading experience that feels less lonely. Eventually I'd love a map of my intellectual influences across whatever I'm reading.
\nNot trying to replace reading. Trying to make it more like the conversations I wish I could have about every book I open.
", "url": "https://lukemanning.ie/blog/building-a-reading-companion-for-my-vault", "title": "Building a Reading Companion for My Vault", "summary": "I read a lot. Not in a flex way but more like a borderline problem. The problem is none of it sticks. I close the book, move on, and six months later I remember almost nothing. Not the ideas, not the context, barely even the thesis.
\nMy vault lives on Syncthing now — I moved away from Obsidian Sync to cut the cost. Having my vault synced across machines without a subscription made it more viable as a daily tool.
\nI tried highlighting. I tried taking notes on my phone while reading. Neither worked for me. Highlights become a graveyard of yellow that I never revisit, and notes are too spontaneous to build anything coherent.
\nWhat I wanted was a companion. Someone to actually discuss what I'm reading with. Not summarize the book back at me, but pull it apart, connect it to weird stuff, make it memorable.
\nSo I built one. It runs as a skill in my Hermes Agent setup and the enriched data gets stored in my Obsidian Vault.
\nThe reading companion is a skill I can trigger whenever I'm reading something that hits me as interesting, complex, or just worth sitting with. I paste a passage, and it comes back enriched across five areas:
\nThe goal isn't a book report. It's more like having a smart friend who makes unexpected connections and gets genuinely excited about ideas.
\nThis is where it clicked for me. The enriched passages go straight into ~/vault/books/<book-slug>.md. One note per book, entries appended as I read.
So instead of highlights scattered across a Kindle or margins that never talk to each other, I have a running document that traces my journey through a single book. Each entry has the passage, the context, and the date. When I finish the book, I have a map of every moment that made me stop and think.
\nThe vault schema already had a slot for this. The reading-companion skill fills it. Here's an example from The Dark Forest by Liu Cixin:
\n## Passage — Chapter 9 (2025-04-13)\n\n> \"He had returned countless times to these words, analyzing each\n> sentence from every angle and chewing over every word. The component\n> words had been strung into a set of prayer beads, and like a pious\n> monk he stroked them time and again; and unstrung them, scattered\n> them, and restrung them in different orders until a layer of each\n> had been worn away.\"\n\n### Historical Context\n\nThe prayer bead / monk metaphor carries deep roots in Buddhist and\nHindu traditions — *japa mala* beads used for meditation have been\npart of spiritual practice for thousands of years. In the Chinese\ncontext, Buddhism, Taoism, and folk spirituality often blended\ntogether, so a Chinese sci-fi reader would likely feel this resonance\nimmediately. The image of a monk mindfully repeating prayers until\nthe beads literally wear smooth is a real phenomenon — in some\ntraditions, monks are said to 磨损 (wó sǔn) their beads through\ndecades of devotion.\n\nLiu himself was an engineering student in North China during the\nCultural Revolution, so the physicality of repeated labor — the way\nobjects get worn, transformed, made sacred through use — might\nreflect a materialist worldview that nevertheless romanticizes\ndiscipline.\n\n### Pop Culture & Internet\n\nThe idea of \"wearing down\" meaning through repetition has a modern\nparallel in the way certain ideas on Reddit's r/philosophy or YouTube\nessay channels get analyzed until they're drained. There's also a\nstrong resonance with video essay culture — creators who return to the\nsame passages repeatedly until new meaning emerges. The passage itself\nfeels almost like a description of what a great video essay does to a\npiece of media.\n\n### Books & Literature\n\nThis is almost a meta-description of close reading itself. The\nliterary theorist Hans-Georg Gadamer wrote about the \"fusion of\nhorizons\" — the way understanding deepens through repeated dialogue\nbetween reader and text. The prayer bead image also echoes Umberto\nEco's concept of the *open text*, which rewards repeated visits. In\na Chinese literary tradition, this mirrors the scholar's relationship\nwith the Confucian classics — the *Four Books* that Ming Dynasty\nscholars would return to compulsively, each reading layering new\nmeaning.\n\n### Unexpected Trivia\n\nThe Chinese word for \"ruminate\" (咀嚼, jǔjué) literally means \"chew\"\n— as in chewing food. The passage's \"chewing over every word\" is\neven more visceral in the original imagery. Also: in some Buddhist\nmonasteries, monks recount that the holes in prayer beads eventually\nbecome polished to a mirror shine from skin oils and decades of\nhandling.\n\n### Emotional / Thematic Insight\n\nThis passage is almost a thesis statement for the entire *Remembrance\nof Earth's Past* trilogy — the Trisolaris series grapples with\ncommunication across cosmic time scales, with meaning that gets worn\ndown, reinterpreted, and restrung by civilizations that may not even\nshare the same physics. The Dark Forest itself is a theory about how\ncivilizations communicate (or don't) — each \"wearing down\" the other's\nsignals until something alien emerges. Liu is telling you how to read\nhis books: like a monk, slowly, repeatedly, until meaning is absorbed\ninto the self.Simple, repeatable, always in the same place.
\nWhether to write my own reactions alongside the enrichment, or let the enrichment stand alone. Right now it's enrichment only — but I think the most valuable version is when I also note what the passage made me think about. Still developing that.
\nAlso: when to stop. Some passages probably don't need enriching. I'm figuring out what \"complex, deep, or interesting\" actually means to me in practice.
\nMost AI book tools either summarize chapters (which I don't need — I just read the chapter) or generate flashcards (which feels like studying, not reading). I'm not trying to memorize more or pass quizzes. I'm trying to actually engage with what I read, make it richer and weirder and more likely to stick.
\nWhat I want from this long-term: a reading log that's actually useful six months from now, connections between books I wouldn't catch on my own, and a reading experience that feels less lonely. Eventually I'd love a map of my intellectual influences across whatever I'm reading.
\nNot trying to replace reading. Trying to make it more like the conversations I wish I could have about every book I open.
", "date_modified": "2026-04-06T00:00:00.000Z", "tags": [ "hermes" ] }, { "id": "https://lukemanning.ie/blog/the-day-i-achieved-nothing", "content_html": "There are days where you finish work and you genuinely cannot point to a single thing you did.
\nNot because you were lazy. Not because you weren't trying. But because from the moment the day started, it belonged to everyone else.
\nI had one of those days recently. Back-to-back calls. Conversations pulled from every direction. Lunch eaten while staring at a Zoom screen. By 5pm I was completely drained, and yet felt like I had nothing to show for it. No output. No visible progress. Just a long list of other people's problems that I'd briefly helped with and moved on from.
\nIt felt like I hadn't worked at all. It felt like I hadn't existed at all, in any meaningful way for my own work.
\nNobody really prepares you for this part of a senior role. A big chunk of what I do now is invisible.
\nI'm not closing tickets anymore. I'm not on the front line. I'm the person who gets pulled into a Slack thread to help an engineer who's stuck, then drops into an escalation call to figure out next steps for a customer, then reviews a KB article someone's asked me to look at, then gets tapped on the shoulder at my desk because someone needs a hand. The impact is real. People are unblocked, things are moving. But I can't point to any of it and say \"I built that.\"
\nThat's fine. That's part of the role. I accepted that.
\nWhat I didn't fully accept until recently is the cost of operating entirely in reactive mode. When my whole day is defined by incoming demands, other people's priorities, other people's timelines, other people's questions, I never get to think. And thinking is where the actual leverage lives.
\nNot answering questions. Thinking.
\nThe worst part of a fully reactive day isn't the exhaustion. It's the feeling that my time wasn't mine.
\nI noticed it building up over weeks. Small stuff at first — catching myself checking Slack before I'd even opened my laptop in the morning. Then bigger stuff. I realised I hadn't worked on anything I'd chosen to work on for over a month. The frustration was quiet but constant, like a low hum I'd stopped noticing because it was always there.
\nI started wondering what it would take to protect against days like that. Not eliminate them — some reactive days are just part of the job. But I wanted a counterweight. Something structural. I thought about blocking out mornings, or setting \"no meeting\" days, but those always seemed to erode the moment something came up. What I actually needed was something harder to break.
\nThe idea I landed on is simple: dedicated growth time. One or two days per month, fully protected. No calls. No Slack. No desk visits. Unreachable. And at the end of it, something to show — a prototype, a write-up, a working tool, something real.
\nNot a meeting to discuss doing a thing. The thing. Delivered.
\nThe key word is unreachable. Not \"I'll try to be heads down.\" Fully off the grid for the day. Because the moment there's an exception — just this once, there's something urgent — the whole concept collapses. The value of protected time comes entirely from the protection being real.
\nI'm going to run this as a personal experiment first. Document what I work on. What I actually produce. How it feels going back into a normal week afterward. Then see if it's worth bringing to others in a similar position.
\nThis also connects to why compound content beats isolated posts — if you're not building with intentionality, the work just piles up instead of compounding.
\nThe reactive day will still happen. That's not going away.
\nBut it doesn't have to be the only kind of day. The thinking, building, creating side of work needs protected space too. Not as a break. Because that's where the actual progress comes from.
\nThe work that moves things forward rarely happens in a Zoom call. It happens in the quiet.
", "url": "https://lukemanning.ie/blog/the-day-i-achieved-nothing", "title": "The Day I Achieved Nothing", "summary": "There are days where you finish work and you genuinely cannot point to a single thing you did.
\nNot because you were lazy. Not because you weren't trying. But because from the moment the day started, it belonged to everyone else.
\nI had one of those days recently. Back-to-back calls. Conversations pulled from every direction. Lunch eaten while staring at a Zoom screen. By 5pm I was completely drained, and yet felt like I had nothing to show for it. No output. No visible progress. Just a long list of other people's problems that I'd briefly helped with and moved on from.
\nIt felt like I hadn't worked at all. It felt like I hadn't existed at all, in any meaningful way for my own work.
\nNobody really prepares you for this part of a senior role. A big chunk of what I do now is invisible.
\nI'm not closing tickets anymore. I'm not on the front line. I'm the person who gets pulled into a Slack thread to help an engineer who's stuck, then drops into an escalation call to figure out next steps for a customer, then reviews a KB article someone's asked me to look at, then gets tapped on the shoulder at my desk because someone needs a hand. The impact is real. People are unblocked, things are moving. But I can't point to any of it and say \"I built that.\"
\nThat's fine. That's part of the role. I accepted that.
\nWhat I didn't fully accept until recently is the cost of operating entirely in reactive mode. When my whole day is defined by incoming demands, other people's priorities, other people's timelines, other people's questions, I never get to think. And thinking is where the actual leverage lives.
\nNot answering questions. Thinking.
\nThe worst part of a fully reactive day isn't the exhaustion. It's the feeling that my time wasn't mine.
\nI noticed it building up over weeks. Small stuff at first — catching myself checking Slack before I'd even opened my laptop in the morning. Then bigger stuff. I realised I hadn't worked on anything I'd chosen to work on for over a month. The frustration was quiet but constant, like a low hum I'd stopped noticing because it was always there.
\nI started wondering what it would take to protect against days like that. Not eliminate them — some reactive days are just part of the job. But I wanted a counterweight. Something structural. I thought about blocking out mornings, or setting \"no meeting\" days, but those always seemed to erode the moment something came up. What I actually needed was something harder to break.
\nThe idea I landed on is simple: dedicated growth time. One or two days per month, fully protected. No calls. No Slack. No desk visits. Unreachable. And at the end of it, something to show — a prototype, a write-up, a working tool, something real.
\nNot a meeting to discuss doing a thing. The thing. Delivered.
\nThe key word is unreachable. Not \"I'll try to be heads down.\" Fully off the grid for the day. Because the moment there's an exception — just this once, there's something urgent — the whole concept collapses. The value of protected time comes entirely from the protection being real.
\nI'm going to run this as a personal experiment first. Document what I work on. What I actually produce. How it feels going back into a normal week afterward. Then see if it's worth bringing to others in a similar position.
\nThis also connects to why compound content beats isolated posts — if you're not building with intentionality, the work just piles up instead of compounding.
\nThe reactive day will still happen. That's not going away.
\nBut it doesn't have to be the only kind of day. The thinking, building, creating side of work needs protected space too. Not as a break. Because that's where the actual progress comes from.
\nThe work that moves things forward rarely happens in a Zoom call. It happens in the quiet.
", "date_modified": "2026-04-05T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/posting-into-the-void", "content_html": "I spent the last few weeks and months working on my personal site. I shipped Projex — a shadcn-style component library for developer portfolio pages — posted about it on X to silence, posted about it on Reddit to near-silence, and sat with that feeling for a while today.
\nIt doesn't feel great.
\nIt's not burnout exactly. I'm not tired of building. I enjoy it. This has become a hobby, and I mean that genuinely, not as a cope, but because the time I spend building doesn't feel wasted even when nothing comes of it.
\nWhat stings is the silence after you share something.
\nYou build a thing. You think it's useful. You give it away for free. You're not asking for money, you're not running ads, you're not trying to acquire users in some predatory growth-hack way. You just want to know someone tried it. Maybe filed an issue. Maybe said \"this is neat.\" That's it.
\nInstead: nothing.
\nReddit right now is flooded with AI-generated spam and people shilling SaaS products that barely work. I hate that. And I hate that when I go to post about something I genuinely built and care about, I feel like one of them.
\nThat's the uncomfortable part. I'm not shilling. Projex is free. I'm not asking for anything. But the act of posting about your own work in that environment feels gross now, because the context is so poisoned.
\nI don't want to learn marketing. I don't want to become someone who optimises posts for engagement. My time is genuinely better spent getting better at building. That's where I am right now.
\nI don't like X. Posting there feels like talking into a void. Maybe that changes with audience size (probably does), but right now it's not where I want to spend energy.
\nI was hoping Projex might get a small handful of users. Not thousands. Not virality. Just a handful of developers who found it useful and maybe said so. That hasn't happened yet, and that's what knocked me sideways a bit today.
\nI've also been stalling on DevBreakdown — my AI model and subscription comparison site. Partly because the affiliate angle I originally had in mind is basically a non-starter now. Partly because the space moves so fast I can hardly keep up with it myself, let alone maintain a site tracking it.
\nAnd then there's the motivation problem: if I'm earning nothing from it, and it's hard to keep current, and I'm already feeling the silence from Projex... why start another thing that shouts into the same void? The entrepreneurial conundrum is familiar territory here — the gap between having ideas and actually executing on them.
\nI don't have a clean answer to that. What I do know is that the clarity problem is real. I know what I want DB to be, but the steps between \"start\" and \"ship something useful\" are fuzzy. That fuzziness is what kills momentum before you even begin.
\nI kept coming back to something today. I've shipped more in the last few months than most people who talk about building ever do.
\nThat's not a flex. It's just what I noticed. And it made me realise: component libraries don't go viral. They get quietly discovered by developers who need them. npm downloads tick up without fanfare. Someone uses your thing without ever telling you.
\nMaybe that's already happening with Projex. I genuinely don't know.
\nI know this is a long game. Knowing that doesn't make today any less shit. But my real goal was never a Reddit post going off. It's building a portfolio of work that compounds, covering my AI subs with something I made, and eventually having enough momentum that the audience finds me rather than me chasing it.
\n€100/month net neutral would genuinely feel like a win right now. That's not a low bar out of pessimism. It's a concrete, honest first milestone.
\nToday I'm going back to the Straico API proxy I half-built a while ago. It's broken in ways I want to fix. It's contained. It's mine. And finishing it will feel like a win without needing anyone to validate it.
\nThat's enough for today.
\nThere's something underneath all of this I keep coming back to: the essay making the rounds about not following your passion makes a case for accepting where you are. But I think there's a version of that argument that quietly recommends giving up on building anything outside the office. That's the part I can't get on board with.
", "url": "https://lukemanning.ie/blog/posting-into-the-void", "title": "Posting Into The Void", "summary": "I spent the last few weeks and months working on my personal site. I shipped Projex — a shadcn-style component library for developer portfolio pages — posted about it on X to silence, posted about it on Reddit to near-silence, and sat with that feeling for a while today.
\nIt doesn't feel great.
\nIt's not burnout exactly. I'm not tired of building. I enjoy it. This has become a hobby, and I mean that genuinely, not as a cope, but because the time I spend building doesn't feel wasted even when nothing comes of it.
\nWhat stings is the silence after you share something.
\nYou build a thing. You think it's useful. You give it away for free. You're not asking for money, you're not running ads, you're not trying to acquire users in some predatory growth-hack way. You just want to know someone tried it. Maybe filed an issue. Maybe said \"this is neat.\" That's it.
\nInstead: nothing.
\nReddit right now is flooded with AI-generated spam and people shilling SaaS products that barely work. I hate that. And I hate that when I go to post about something I genuinely built and care about, I feel like one of them.
\nThat's the uncomfortable part. I'm not shilling. Projex is free. I'm not asking for anything. But the act of posting about your own work in that environment feels gross now, because the context is so poisoned.
\nI don't want to learn marketing. I don't want to become someone who optimises posts for engagement. My time is genuinely better spent getting better at building. That's where I am right now.
\nI don't like X. Posting there feels like talking into a void. Maybe that changes with audience size (probably does), but right now it's not where I want to spend energy.
\nI was hoping Projex might get a small handful of users. Not thousands. Not virality. Just a handful of developers who found it useful and maybe said so. That hasn't happened yet, and that's what knocked me sideways a bit today.
\nI've also been stalling on DevBreakdown — my AI model and subscription comparison site. Partly because the affiliate angle I originally had in mind is basically a non-starter now. Partly because the space moves so fast I can hardly keep up with it myself, let alone maintain a site tracking it.
\nAnd then there's the motivation problem: if I'm earning nothing from it, and it's hard to keep current, and I'm already feeling the silence from Projex... why start another thing that shouts into the same void? The entrepreneurial conundrum is familiar territory here — the gap between having ideas and actually executing on them.
\nI don't have a clean answer to that. What I do know is that the clarity problem is real. I know what I want DB to be, but the steps between \"start\" and \"ship something useful\" are fuzzy. That fuzziness is what kills momentum before you even begin.
\nI kept coming back to something today. I've shipped more in the last few months than most people who talk about building ever do.
\nThat's not a flex. It's just what I noticed. And it made me realise: component libraries don't go viral. They get quietly discovered by developers who need them. npm downloads tick up without fanfare. Someone uses your thing without ever telling you.
\nMaybe that's already happening with Projex. I genuinely don't know.
\nI know this is a long game. Knowing that doesn't make today any less shit. But my real goal was never a Reddit post going off. It's building a portfolio of work that compounds, covering my AI subs with something I made, and eventually having enough momentum that the audience finds me rather than me chasing it.
\n€100/month net neutral would genuinely feel like a win right now. That's not a low bar out of pessimism. It's a concrete, honest first milestone.
\nToday I'm going back to the Straico API proxy I half-built a while ago. It's broken in ways I want to fix. It's contained. It's mine. And finishing it will feel like a win without needing anyone to validate it.
\nThat's enough for today.
\nThere's something underneath all of this I keep coming back to: the essay making the rounds about not following your passion makes a case for accepting where you are. But I think there's a version of that argument that quietly recommends giving up on building anything outside the office. That's the part I can't get on board with.
", "date_modified": "2026-04-04T00:00:00.000Z", "tags": [ "projex", "reflections" ] }, { "id": "https://lukemanning.ie/blog/anthropic-open-source-walled-garden-clawdbot-opencode", "content_html": "I was using Claude Code daily. I built my entire blog review system with it. I hit session limits constantly and tried to optimise around them. Now I use OpenCode, an open-source agent that works with any provider.
\nThen one day (maybe a month or two ago) I pulled the latest OpenCode version and Claude subscription support was just gone. Not deprecated. Not moved to a config flag. Removed entirely, because Anthropic demanded it. On top of that, I kept hitting usage limits on my Pro subscription despite paying $20/month. That issue was opened for Max subscribers but people on every tier were hitting the same thing.
\nI cancelled my Anthropic subscription. I use GLM-4.7 and GLM-5.1 now through OpenCode with a GLM coding subscription. Considering adding a GitHub Copilot subscription so I can still use Anthropic models through OpenCode's API integration. I still use Claude on the web and on my phone. The model is good. The repeated session limit issues and the company's behavior around open source tools is what pushed me away.
\nI'd already been watching Anthropic's relationship with open source tools for a while. Then I came across the OpenClaw story. An open source project that got forced to rename because it had \"Clawd\" in the name. That sent me down a rabbit hole.
\nPeter Steinberger (steipete on GitHub) built a personal AI assistant. Originally called Warelay. MIT licensed, supports 20+ messaging channels, and has 343k GitHub stars (yes, really). A legit open source project by any measure. The fastest growing in history in terms of stars.
\nOn January 4, 2026, he renamed it to ClawdBot. Makes sense. It's a bot that uses Claude. Clear, descriptive name. A play on the fact it used Claude without using the name Claude.
\nThree weeks later, he got a letter from Anthropic's legal team.
\nThe project was renamed to \"Moltbot\" on January 27, 2026. The commit message read: \"refactor: rename clawdbot to moltbot with legacy compat.\" The maintainer confirmed in GitHub issue #2825: \"Moltbot is the official name now. Clawdbot has been letter sent by Anthropic.\"
\nThat name lasted three days. On January 30, another commit: \"refactor: rename to openclaw.\" The project has been OpenClaw ever since.
\nAn open source project with 343k stars, MIT licensed, built by an independent developer, got a trademark letter because its name contained \"Clawd.\" Yeah, obviously a play on \"Claude,\" but still not \"Claude.\"
\nAnd that wasn't all. Anthropic also reportedly changed their API to reject any request whose system prompt contains the phrase \"Open Claw.\" Not a rate limit, not a warning, but a hard block. (This was reported by Theo — he runs t3.gg, covers AI and dev tools — I haven't tested it myself.) If that's accurate, it goes way beyond trademark enforcement. That would be technical suppression of a specific open source project.
\nThe OpenCode situation is different but follows the same pattern.
\nFor context: OpenCode works with multiple AI providers. You configure it with credentials for whichever provider you want, and it routes requests to your chosen model. Before all this, Claude subscription access was one of those options. You could use your existing Pro or Max subscription through OpenCode instead of being locked into Anthropic's client.
\nAnthropic added checks to stop third-party tools from impersonating the Claude Code client. This broke people's ability to use their Claude subscriptions through OpenCode, Cursor, and any other third-party harness.
\nThen they updated their terms of service to explicitly ban using consumer subscriptions (Pro/Max plans) as authentication for third-party tools. So even people paying Anthropic $20/month for Pro can't legally use that subscription through OpenCode. You have to use the Anthropic harness (Claude Code).
\nOpenCode had its own PR that removed Claude subscription integration entirely, with \"Anthropic legal requests\" cited as the reason. Not a technical limitation. A legal demand.
\nI get protecting your trademark. I get not wanting people to think an unofficial tool is officially affiliated with you. But the OpenCode situation isn't about trademark confusion. It's about controlling which tools can access Claude's API and how.
\nOpenCode wasn't pretending to be Claude Code. It was using Claude as a provider, the same way it uses ChatGPT or any other model. Anthropic decided they didn't want subscription auth flowing through third-party tools, and they had the legal muscle to enforce it. Their stated justification was something about third-party harnesses interfering with their analytics and causing unusual traffic patterns. At least, that's what I gathered. It's hard to know how much of that is genuine concern versus justifying the walled garden.
\nThe rules around what's allowed are vague enough that even people trying to play by them can't get straight answers. Matt Pocock — whose TypeScript stuff I've used for a while — spent over a month trying to get Anthropic to confirm whether his paid Claude Code course was allowed to exist. Their response: \"We're working on it.\" Repeatedly. When pressed for an ETA, same answer. Theo has called this out too — he believes Anthropic keeps the terms vague intentionally so they can move the goalposts later. That tracks with what I've seen.
\nAnthropic isn't just another company locking everything down. They built MCP (Model Context Protocol) — the protocol that lets OpenCode talk to external tools. And then gave it away. Fully open source. Anthropic doesn't control it. They offer free Claude Max access to open source maintainers. Their output terms are solid; you own what Claude generates.
\nBut then Claude Code has a public GitHub repo with zero source code. Subscription access is tightly controlled — you can't use what you're paying for through a third-party tool. And their legal team sends trademark letters to open source projects with 343k stars.
\nThen there's the distillation thing.
\nI read Anthropic's report accusing DeepSeek, Moonshot, and MiniMax of \"distillation attacks\" against Claude and something felt off. They claimed 24,000 fraudulent accounts and 16+ million exchanges. Wrapped it in national security framing stating that distilled models could be used for bioweapons, etc. And this isn't the first time — Anthropic previously accused Windsurf, X AI, and OpenAI of distillation and, from what I've read, was wrong each time.
\nThe distillation accusations fit the same pattern. Anthropic claims others are exploiting Claude's openness, uses that to justify tighter restrictions, and those restrictions happen to protect their revenue. Could be genuine security concern. Could be strategic. But it's the same thing I keep seeing.
\nThe only major lab that has released zero open-weight models is also the one arguing most loudly that open-weight models are dangerous. I don't think that's a coincidence.
\nI initially thought the ClawdBot thing was just standard trademark enforcement. But then I kept looking. I'm not sure if this is a fair reading, honestly. I keep going back and forth on it. But the pattern I keep seeing is decisions being made to be open where it benefits Anthropic, and closed where it protects their revenue.
\nThat's absolutely a valid business strategy. It's just not what \"open\" means. Especially when most of their competitors are making strides to become more open.
\nI'm going to keep using OpenCode for now.
\nI might be wrong about the intent. Maybe Anthropic has good reasons for each individual decision. The ClawdBot rename could be standard trademark enforcement. The OpenCode crackdown could be about subscription terms or it could legitimately be about analytical data being interfered with by third party harnesses.
\nBut when I look at the pattern, it looks like a company building a walled garden around Claude while also contributing genuinely open infrastructure. I don't have a clean conclusion here. I'm still forming my thinking on this. But I know that my workflow got disrupted, an open source project got renamed three times in a month, and the company responsible for both is the same one that open-sourced MCP.
\nI just don't understand their actions sometimes.
", "url": "https://lukemanning.ie/blog/anthropic-open-source-walled-garden-clawdbot-opencode", "title": "Anthropic, Open Source, and Why I Cancelled My Subscription", "summary": "I was using Claude Code daily. I built my entire blog review system with it. I hit session limits constantly and tried to optimise around them. Now I use OpenCode, an open-source agent that works with any provider.
\nThen one day (maybe a month or two ago) I pulled the latest OpenCode version and Claude subscription support was just gone. Not deprecated. Not moved to a config flag. Removed entirely, because Anthropic demanded it. On top of that, I kept hitting usage limits on my Pro subscription despite paying $20/month. That issue was opened for Max subscribers but people on every tier were hitting the same thing.
\nI cancelled my Anthropic subscription. I use GLM-4.7 and GLM-5.1 now through OpenCode with a GLM coding subscription. Considering adding a GitHub Copilot subscription so I can still use Anthropic models through OpenCode's API integration. I still use Claude on the web and on my phone. The model is good. The repeated session limit issues and the company's behavior around open source tools is what pushed me away.
\nI'd already been watching Anthropic's relationship with open source tools for a while. Then I came across the OpenClaw story. An open source project that got forced to rename because it had \"Clawd\" in the name. That sent me down a rabbit hole.
\nPeter Steinberger (steipete on GitHub) built a personal AI assistant. Originally called Warelay. MIT licensed, supports 20+ messaging channels, and has 343k GitHub stars (yes, really). A legit open source project by any measure. The fastest growing in history in terms of stars.
\nOn January 4, 2026, he renamed it to ClawdBot. Makes sense. It's a bot that uses Claude. Clear, descriptive name. A play on the fact it used Claude without using the name Claude.
\nThree weeks later, he got a letter from Anthropic's legal team.
\nThe project was renamed to \"Moltbot\" on January 27, 2026. The commit message read: \"refactor: rename clawdbot to moltbot with legacy compat.\" The maintainer confirmed in GitHub issue #2825: \"Moltbot is the official name now. Clawdbot has been letter sent by Anthropic.\"
\nThat name lasted three days. On January 30, another commit: \"refactor: rename to openclaw.\" The project has been OpenClaw ever since.
\nAn open source project with 343k stars, MIT licensed, built by an independent developer, got a trademark letter because its name contained \"Clawd.\" Yeah, obviously a play on \"Claude,\" but still not \"Claude.\"
\nAnd that wasn't all. Anthropic also reportedly changed their API to reject any request whose system prompt contains the phrase \"Open Claw.\" Not a rate limit, not a warning, but a hard block. (This was reported by Theo — he runs t3.gg, covers AI and dev tools — I haven't tested it myself.) If that's accurate, it goes way beyond trademark enforcement. That would be technical suppression of a specific open source project.
\nThe OpenCode situation is different but follows the same pattern.
\nFor context: OpenCode works with multiple AI providers. You configure it with credentials for whichever provider you want, and it routes requests to your chosen model. Before all this, Claude subscription access was one of those options. You could use your existing Pro or Max subscription through OpenCode instead of being locked into Anthropic's client.
\nAnthropic added checks to stop third-party tools from impersonating the Claude Code client. This broke people's ability to use their Claude subscriptions through OpenCode, Cursor, and any other third-party harness.
\nThen they updated their terms of service to explicitly ban using consumer subscriptions (Pro/Max plans) as authentication for third-party tools. So even people paying Anthropic $20/month for Pro can't legally use that subscription through OpenCode. You have to use the Anthropic harness (Claude Code).
\nOpenCode had its own PR that removed Claude subscription integration entirely, with \"Anthropic legal requests\" cited as the reason. Not a technical limitation. A legal demand.
\nI get protecting your trademark. I get not wanting people to think an unofficial tool is officially affiliated with you. But the OpenCode situation isn't about trademark confusion. It's about controlling which tools can access Claude's API and how.
\nOpenCode wasn't pretending to be Claude Code. It was using Claude as a provider, the same way it uses ChatGPT or any other model. Anthropic decided they didn't want subscription auth flowing through third-party tools, and they had the legal muscle to enforce it. Their stated justification was something about third-party harnesses interfering with their analytics and causing unusual traffic patterns. At least, that's what I gathered. It's hard to know how much of that is genuine concern versus justifying the walled garden.
\nThe rules around what's allowed are vague enough that even people trying to play by them can't get straight answers. Matt Pocock — whose TypeScript stuff I've used for a while — spent over a month trying to get Anthropic to confirm whether his paid Claude Code course was allowed to exist. Their response: \"We're working on it.\" Repeatedly. When pressed for an ETA, same answer. Theo has called this out too — he believes Anthropic keeps the terms vague intentionally so they can move the goalposts later. That tracks with what I've seen.
\nAnthropic isn't just another company locking everything down. They built MCP (Model Context Protocol) — the protocol that lets OpenCode talk to external tools. And then gave it away. Fully open source. Anthropic doesn't control it. They offer free Claude Max access to open source maintainers. Their output terms are solid; you own what Claude generates.
\nBut then Claude Code has a public GitHub repo with zero source code. Subscription access is tightly controlled — you can't use what you're paying for through a third-party tool. And their legal team sends trademark letters to open source projects with 343k stars.
\nThen there's the distillation thing.
\nI read Anthropic's report accusing DeepSeek, Moonshot, and MiniMax of \"distillation attacks\" against Claude and something felt off. They claimed 24,000 fraudulent accounts and 16+ million exchanges. Wrapped it in national security framing stating that distilled models could be used for bioweapons, etc. And this isn't the first time — Anthropic previously accused Windsurf, X AI, and OpenAI of distillation and, from what I've read, was wrong each time.
\nThe distillation accusations fit the same pattern. Anthropic claims others are exploiting Claude's openness, uses that to justify tighter restrictions, and those restrictions happen to protect their revenue. Could be genuine security concern. Could be strategic. But it's the same thing I keep seeing.
\nThe only major lab that has released zero open-weight models is also the one arguing most loudly that open-weight models are dangerous. I don't think that's a coincidence.
\nI initially thought the ClawdBot thing was just standard trademark enforcement. But then I kept looking. I'm not sure if this is a fair reading, honestly. I keep going back and forth on it. But the pattern I keep seeing is decisions being made to be open where it benefits Anthropic, and closed where it protects their revenue.
\nThat's absolutely a valid business strategy. It's just not what \"open\" means. Especially when most of their competitors are making strides to become more open.
\nI'm going to keep using OpenCode for now.
\nI might be wrong about the intent. Maybe Anthropic has good reasons for each individual decision. The ClawdBot rename could be standard trademark enforcement. The OpenCode crackdown could be about subscription terms or it could legitimately be about analytical data being interfered with by third party harnesses.
\nBut when I look at the pattern, it looks like a company building a walled garden around Claude while also contributing genuinely open infrastructure. I don't have a clean conclusion here. I'm still forming my thinking on this. But I know that my workflow got disrupted, an open source project got renamed three times in a month, and the company responsible for both is the same one that open-sourced MCP.
\nI just don't understand their actions sometimes.
", "date_modified": "2026-04-03T00:00:00.000Z", "tags": [ "ai" ] }, { "id": "https://lukemanning.ie/blog/why-i-started-this-blog", "content_html": "I've started blogs before. Let them die. This one's different. (I hope.)
\nYears ago I had a blog about setting up my first home server. It started as personal notes on virtualization, then I thought \"maybe someone else finds this useful\" and put it online. A few posts in, I kept meaning to write the next one. Weeks turned into months. I didn't even notice when the hosting lapsed.
\nSome of those posts are still floating around on the Wayback Machine. I keep meaning to dig them up and see if any of it's worth resurrecting. Maybe someday.
\nMore recently I started a different blog at lukemanning.name. This one was inspired by a Dan Koe video where he talked about self-actualisation (becoming the most authentic version of yourself, finding meaning and purpose). He said something that stuck with me:
\n\n\n\"Your niche is self-actualisation. What makes you unique are the curiosities, the interests, skills and experience that you gain along the way, because that is unique to everybody.\"
\n
I'd never heard the term before. Went down a rabbit hole reading about Maslow's Hierarchy of Needs, personal growth, the whole thing. Got excited. Started a blog about it.
\nThat blog lasted a handful of posts. The topic was too broad. \"Personal growth\" is one of those things that sounds meaningful but is hard to write about consistently when you're also working full time and building things. I didn't have a specific enough focus.
\nThe thing that finally made this blog happen wasn't a grand realisation about blogging. It was me spending way too long debugging a Velite setup issue, finally getting it working, and then three days later having no idea what I'd done to fix it. I'd closed the terminal, moved on, and the knowledge was just... gone.
\nThat happened more than once. I'd figure something out, feel smart for about five minutes, then lose the solution somewhere between Slack messages and browser tabs. Writing it down was the obvious fix. I'd just never actually done it consistently.
\nThe home server blog was actually closer to what I wanted than I realised at the time. Personal notes about specific problems, shared publicly. Not tutorials. Not guides. Just \"here's what broke and here's what I did.\"
\nI don't know. The home server blog didn't die because the topic was wrong. It died because I stopped making time. That could happen again. I don't have a clever answer for that.
\nWhat I do know is the topic is narrower now. I'm not writing about abstract personal growth. I'm writing about specific technical problems I'm facing day-to-day with specific solutions (or non-solutions). And the raw material is always there. I'm building things every week, and things break every week.
\nThat's easier to sustain. There's always something breaking.
", "url": "https://lukemanning.ie/blog/why-i-started-this-blog", "title": "Why I Started This Blog", "summary": "I've started blogs before. Let them die. This one's different. (I hope.)
\nYears ago I had a blog about setting up my first home server. It started as personal notes on virtualization, then I thought \"maybe someone else finds this useful\" and put it online. A few posts in, I kept meaning to write the next one. Weeks turned into months. I didn't even notice when the hosting lapsed.
\nSome of those posts are still floating around on the Wayback Machine. I keep meaning to dig them up and see if any of it's worth resurrecting. Maybe someday.
\nMore recently I started a different blog at lukemanning.name. This one was inspired by a Dan Koe video where he talked about self-actualisation (becoming the most authentic version of yourself, finding meaning and purpose). He said something that stuck with me:
\n\n\n\"Your niche is self-actualisation. What makes you unique are the curiosities, the interests, skills and experience that you gain along the way, because that is unique to everybody.\"
\n
I'd never heard the term before. Went down a rabbit hole reading about Maslow's Hierarchy of Needs, personal growth, the whole thing. Got excited. Started a blog about it.
\nThat blog lasted a handful of posts. The topic was too broad. \"Personal growth\" is one of those things that sounds meaningful but is hard to write about consistently when you're also working full time and building things. I didn't have a specific enough focus.
\nThe thing that finally made this blog happen wasn't a grand realisation about blogging. It was me spending way too long debugging a Velite setup issue, finally getting it working, and then three days later having no idea what I'd done to fix it. I'd closed the terminal, moved on, and the knowledge was just... gone.
\nThat happened more than once. I'd figure something out, feel smart for about five minutes, then lose the solution somewhere between Slack messages and browser tabs. Writing it down was the obvious fix. I'd just never actually done it consistently.
\nThe home server blog was actually closer to what I wanted than I realised at the time. Personal notes about specific problems, shared publicly. Not tutorials. Not guides. Just \"here's what broke and here's what I did.\"
\nI don't know. The home server blog didn't die because the topic was wrong. It died because I stopped making time. That could happen again. I don't have a clever answer for that.
\nWhat I do know is the topic is narrower now. I'm not writing about abstract personal growth. I'm writing about specific technical problems I'm facing day-to-day with specific solutions (or non-solutions). And the raw material is always there. I'm building things every week, and things break every week.
\nThat's easier to sustain. There's always something breaking.
", "date_modified": "2026-04-02T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/opencode-tmux-getting-used-to-keybindings", "content_html": "I usually run opencode in a simple WSL terminal window. Somtimes I have multiple instances across different tabs in my Terminal. I came across a video recently on Youtube talking about tmux. I never had a reason to avoid tmux — I just never set it up properly. After watchging the video I was convinced I needed to give it a go, so I decided to actually try running my workflow inside tmux. Turns out that wasn't so straightforward. A series of small issues made the initial attempts quite frustrating.
\nFirst problem: I hit Esc to interrupt an agent mid-task. Nothing happened. Just sat there. I hit Esc again. Nothing. The agent kept running.
\nI'm not sure what I expected tmux to do with Escape, but apparently it intercepts the key for its own bindings and there's a delay before the key reaches the application inside. I wondered if opencode had a bug or just didn't work well with opencode.
\nThen I searched \"tmux escape key not working\" and found set -g escape-time 10 which reduces that delay. Shorter would be faster but 10ms worked. After that, Escape actually reached opencode.
But that alone wasn't enough for clipboard to work.
\nSelecting text in tmux with the mouse didn't copy to my system clipboard. I'd select, paste somewhere else, and get nothing. This is on WSL2 with Ubuntu on Windows — so I have WSLg, which is the Windows layer that lets Linux GUI apps run on Windows 11. But something was intercepting it.
\nI tried:
\nWhat actually fixed it was adding these to my ~/.tmux.conf:
set -g escape-time 10\nset -g mouse on\nset -g set-clipboard on\nset -g allow-passthrough on\nset -g mouse on enables mouse mode so I can select with the mouse at all. set -g set-clipboard on is the key one. It's been around since tmux 2.9 and it handles clipboard integration properly. set -g allow-passthrough on lets applications inside tmux access the system clipboard without tmux intercepting it first. That last one seems particularly relevant for WSL setups, though it might help on other platforms too.
I'm running tmux 3.4 — From what I've reda these settings should work on tmux 2.9+, which covers most reasonable install paths in 2026.
\nTo reload after changing tmux.conf, run tmux source-file ~/.tmux.conf.
I'm still getting used to the keybindings and functionality inside tmux. I'm still building the muscle memory. The clipboard issue was the biggest blocker, now that works, so the rest is just practice.
\nThe other opencode posts (permissions trap, nested commands) don't mention tmux because I wasn't using it. Now I am, and now I know why people talk about these specific settings. It's quite nice having so much flexibility inside a single terminal window.
\nI'm genuinely not sure how anyone uses tmux without these settings. Maybe they were just magic configuration I never had.
", "url": "https://lukemanning.ie/blog/opencode-tmux-getting-used-to-keybindings", "title": "Trying to use opencode inside tmux was a struggle", "summary": "I usually run opencode in a simple WSL terminal window. Somtimes I have multiple instances across different tabs in my Terminal. I came across a video recently on Youtube talking about tmux. I never had a reason to avoid tmux — I just never set it up properly. After watchging the video I was convinced I needed to give it a go, so I decided to actually try running my workflow inside tmux. Turns out that wasn't so straightforward. A series of small issues made the initial attempts quite frustrating.
\nFirst problem: I hit Esc to interrupt an agent mid-task. Nothing happened. Just sat there. I hit Esc again. Nothing. The agent kept running.
\nI'm not sure what I expected tmux to do with Escape, but apparently it intercepts the key for its own bindings and there's a delay before the key reaches the application inside. I wondered if opencode had a bug or just didn't work well with opencode.
\nThen I searched \"tmux escape key not working\" and found set -g escape-time 10 which reduces that delay. Shorter would be faster but 10ms worked. After that, Escape actually reached opencode.
But that alone wasn't enough for clipboard to work.
\nSelecting text in tmux with the mouse didn't copy to my system clipboard. I'd select, paste somewhere else, and get nothing. This is on WSL2 with Ubuntu on Windows — so I have WSLg, which is the Windows layer that lets Linux GUI apps run on Windows 11. But something was intercepting it.
\nI tried:
\nWhat actually fixed it was adding these to my ~/.tmux.conf:
set -g escape-time 10\nset -g mouse on\nset -g set-clipboard on\nset -g allow-passthrough on\nset -g mouse on enables mouse mode so I can select with the mouse at all. set -g set-clipboard on is the key one. It's been around since tmux 2.9 and it handles clipboard integration properly. set -g allow-passthrough on lets applications inside tmux access the system clipboard without tmux intercepting it first. That last one seems particularly relevant for WSL setups, though it might help on other platforms too.
I'm running tmux 3.4 — From what I've reda these settings should work on tmux 2.9+, which covers most reasonable install paths in 2026.
\nTo reload after changing tmux.conf, run tmux source-file ~/.tmux.conf.
I'm still getting used to the keybindings and functionality inside tmux. I'm still building the muscle memory. The clipboard issue was the biggest blocker, now that works, so the rest is just practice.
\nThe other opencode posts (permissions trap, nested commands) don't mention tmux because I wasn't using it. Now I am, and now I know why people talk about these specific settings. It's quite nice having so much flexibility inside a single terminal window.
\nI'm genuinely not sure how anyone uses tmux without these settings. Maybe they were just magic configuration I never had.
", "date_modified": "2026-04-01T00:00:00.000Z", "tags": [ "opencode" ] }, { "id": "https://lukemanning.ie/blog/fixing-velite-watch-mode-irony", "content_html": "I just ran blog review agent on my Adding Syntax Highlighting to Velite with Shiki post. Made a few revisions to content including fixing tutorial framing, added version numbers, corrected CSS classes. Committed everything to git.
\nThen I refreshed http://localhost:3000.
\nStill seeing old content. Weird. This never happens.
\nHonestly, this annoyed me more than it should have. I had just spent all this time fixing the post, and now I can't even see the changes?
\nVelite was supposed to watch files automatically, like some content management systems do. Velite doesn't watch by default - you have to configure it. I'd written about this exact issue in a previous post. The irony was not lost on me.
\nSo I restarted the dev server, cleared cache, expecting everything to work. The new post showed up, but Velite still wasn't watching files. Changes only appeared when I restarted the server. This definitely is a regression on what I had previously configured.
\nVelite's docs say it supports watch mode, but it needs to be configured properly. The integration with Next.js happens through next.config.ts - that's where Velite gets initialized. If watch mode isn't set up there, Velite just runs once when the server starts and never again.
\nI opened next.config.ts at the root of my project. Here's what the file looked like:
import type { NextConfig } from 'next/config'\n\nconst nextConfig: NextConfig = {\n // some other config...\n}\n\nexport default nextConfigOh. The Velite integration code was completely missing.
\nI found the Velite integration code in their Next.js docs. Here's what should have been in next.config.ts:
\nimport type { NextConfig } from 'next/config'\n\nconst nextConfig: NextConfig = {\n // some other config...\n}\n\n// Velite integration\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}\n\nexport default nextConfigBut there was nothing there. Just Next.js config.
\nSo that's why watch mode wasn't working. The code to start Velite at all was gone.
\nI checked git history to see when it disappeared. Found commit 1afe3e2 with message \"Duplicate Velite build issue\" that had removed all the Velite integration code. I figured I must have made a mistake.
So I restored the code from git. Velite was running again. Watch mode was working. Changes appeared instantly.
\nThen I remembered what the duplicate build issue actually was.
\nWhen I deployed to Vercel, I was seeing Velite build twice in the logs:
\n[VELITE] building...\n[VELITE] building... again\nThe logs showed Velite building twice. I still don't know the exact root cause, but what I observed was: Next.js was triggering Velite during its build process, and something else (Vercel's Velite integration?) was also triggering a build. Two builds were happening.
\nThe original code was running Velite in both development (isDev) and production (isBuild). In production, when isBuild is true, Next.js runs during the build process. If Vercel also has its own Velite integration, both would be triggering Velite builds during deployment. That's inefficient. So commit 1afe3e2 removed the Velite integration entirely to stop the double builds.
The problem with that approach? It also broke watch mode in development because the commit removed ALL the integration code.
\nThe real solution is to only run Velite watch mode in development. Vercel handles Velite builds separately in production (I verified this by checking my Vercel project settings - there's a \"Velite\" section that shows it runs builds during deployment), so Next.js shouldn't trigger them.
\nHere's what I ended up with:
\nconst isDev = process.env.NODE_ENV === 'development'\nif (!process.env.VELITE_STARTED && isDev) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: true, clean: false }))\n}This is different from the original code:
\nisBuild - only run in developmentwatch: true in dev modeclean: false in dev mode (I tried both settings. With clean: true, Velite would rebuild everything from scratch each time a file changed. With clean: false, it only rebuilt changed files, which was much faster)The VELITE_STARTED environment variable prevents Velite from starting multiple times during Next.js hot reloads. Without it, every time Next.js reloaded the config (when files change), Velite would start again, which causes issues.
To verify this works, I changed the content in one of my blog posts without restarting the dev server. Within a second, the change appeared in the browser. I also checked my Vercel deploy logs and only saw one Velite build.
\nHappy days. Back in business.
", "url": "https://lukemanning.ie/blog/fixing-velite-watch-mode-irony", "title": "I Fixed Velite Watch Mode Problem (And Immediately Broke It Again)", "summary": "I just ran blog review agent on my Adding Syntax Highlighting to Velite with Shiki post. Made a few revisions to content including fixing tutorial framing, added version numbers, corrected CSS classes. Committed everything to git.
\nThen I refreshed http://localhost:3000.
\nStill seeing old content. Weird. This never happens.
\nHonestly, this annoyed me more than it should have. I had just spent all this time fixing the post, and now I can't even see the changes?
\nVelite was supposed to watch files automatically, like some content management systems do. Velite doesn't watch by default - you have to configure it. I'd written about this exact issue in a previous post. The irony was not lost on me.
\nSo I restarted the dev server, cleared cache, expecting everything to work. The new post showed up, but Velite still wasn't watching files. Changes only appeared when I restarted the server. This definitely is a regression on what I had previously configured.
\nVelite's docs say it supports watch mode, but it needs to be configured properly. The integration with Next.js happens through next.config.ts - that's where Velite gets initialized. If watch mode isn't set up there, Velite just runs once when the server starts and never again.
\nI opened next.config.ts at the root of my project. Here's what the file looked like:
import type { NextConfig } from 'next/config'\n\nconst nextConfig: NextConfig = {\n // some other config...\n}\n\nexport default nextConfigOh. The Velite integration code was completely missing.
\nI found the Velite integration code in their Next.js docs. Here's what should have been in next.config.ts:
\nimport type { NextConfig } from 'next/config'\n\nconst nextConfig: NextConfig = {\n // some other config...\n}\n\n// Velite integration\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}\n\nexport default nextConfigBut there was nothing there. Just Next.js config.
\nSo that's why watch mode wasn't working. The code to start Velite at all was gone.
\nI checked git history to see when it disappeared. Found commit 1afe3e2 with message \"Duplicate Velite build issue\" that had removed all the Velite integration code. I figured I must have made a mistake.
So I restored the code from git. Velite was running again. Watch mode was working. Changes appeared instantly.
\nThen I remembered what the duplicate build issue actually was.
\nWhen I deployed to Vercel, I was seeing Velite build twice in the logs:
\n[VELITE] building...\n[VELITE] building... again\nThe logs showed Velite building twice. I still don't know the exact root cause, but what I observed was: Next.js was triggering Velite during its build process, and something else (Vercel's Velite integration?) was also triggering a build. Two builds were happening.
\nThe original code was running Velite in both development (isDev) and production (isBuild). In production, when isBuild is true, Next.js runs during the build process. If Vercel also has its own Velite integration, both would be triggering Velite builds during deployment. That's inefficient. So commit 1afe3e2 removed the Velite integration entirely to stop the double builds.
The problem with that approach? It also broke watch mode in development because the commit removed ALL the integration code.
\nThe real solution is to only run Velite watch mode in development. Vercel handles Velite builds separately in production (I verified this by checking my Vercel project settings - there's a \"Velite\" section that shows it runs builds during deployment), so Next.js shouldn't trigger them.
\nHere's what I ended up with:
\nconst isDev = process.env.NODE_ENV === 'development'\nif (!process.env.VELITE_STARTED && isDev) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: true, clean: false }))\n}This is different from the original code:
\nisBuild - only run in developmentwatch: true in dev modeclean: false in dev mode (I tried both settings. With clean: true, Velite would rebuild everything from scratch each time a file changed. With clean: false, it only rebuilt changed files, which was much faster)The VELITE_STARTED environment variable prevents Velite from starting multiple times during Next.js hot reloads. Without it, every time Next.js reloaded the config (when files change), Velite would start again, which causes issues.
To verify this works, I changed the content in one of my blog posts without restarting the dev server. Within a second, the change appeared in the browser. I also checked my Vercel deploy logs and only saw one Velite build.
\nHappy days. Back in business.
", "date_modified": "2026-03-23T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/nuking-x-history-zerowork-taskbot", "content_html": "I wanted to start using X more actively. Not for \"branding\" or \"growth hacking\" - just personal engagement, building relationships, connecting with likeminded people, sharing what I'm building. You know, building in public.
\nMy X history was flooded with hundreds of tweets and retweets after years of neglect. There were so many corporate social media sharing campaign posts, random competition retweets, and so on. None of that history represented the new image I wanted to portray on X.
\nBut I've had my X profile for years, and I didn't want to delete it entirely.
\nSo I needed to nuke my history.
\nThis is where it got annoying. I looked around for tools to do this and found... third-party options. Sketchy-looking websites asking for my credentials. Paid subscriptions just to delete tweets. Nothing that felt safe or worth using.
\n(I don't know if I'm overly paranoid, but giving my X login to a random website doesn't sit right with me.)
\nI'd used ZeroWork before. I was pretty active in their community for a few months. Hadn't touched it in a while, but this problem sparked my interest in using it again.
\nSo I built my own solution.
\nThis automation completely cleans up your Twitter/X profile by automatically deleting all your original tweets and undoing all your retweets. Instead of manually clicking delete on hundreds of posts, this tool does the entire job for you in one go.
\nThe process works like this:
\nKey features:
\n\nGetting the TaskBot to work reliably took way more trial and error than I expected.
\nThe main thing that tripped me up was loop logic. If I set the loop iterations too high, it would randomly fail.
\nSo I realized the best thing to do was limit the loop to a single tweet, then add an \"After Repeat\" block to check if there were still more tweets. A single loop per single tweet was way more reliable than trying to process multiple tweets per loop.
\nI also had to identify whether each object was a post or a retweet - the \"delete\" and \"un-repost\" actions are different, so I needed separate branches.
\nBut that wasn't the weird part.
\nOlder reposts/retweets were confusing. For some reason, they showed up in my Replies feed as me having retweeted them, but there was no \"Undo Retweet\" button. This broke my workflow since I couldn't just undo them directly.
\nI figured it out relatively quickly: I had to repost the item again, then undo that repost. Only then would it finally get removed from the Replies page. This makes zero sense to me, but it worked.
\nThen there were replies. Handling tweets where either I was replying to someone, or someone was replying to me - these got mixed together in the feed. The automation would try to delete tweets that weren't mine, which obviously failed.
\nI solved this with a counter. My loop would always review the tweet at position zero. If that tweet belonged to someone else, I'd increment the counter, so it would review the tweet at position one instead. This way I could skip over other people's replies and only target mine.
\nIt wasn't plug-and-play. I was pretty rusty on ZeroWork, and I spent many hours tweaking and re-running the TaskBot before it finally worked smoothly.
\nI let it run while I went to do other things. When I came back about 3 hours later, it had finished.
\nIt had removed about 400 reposts and a few tweets.
\nNow I have a fresh X profile with 0 posts and 0 retweets.
\nThat's it. Clean slate. Ready to start posting for real this time.
", "url": "https://lukemanning.ie/blog/nuking-x-history-zerowork-taskbot", "title": "I Nuked My X History with a ZeroWork TaskBot", "summary": "I wanted to start using X more actively. Not for \"branding\" or \"growth hacking\" - just personal engagement, building relationships, connecting with likeminded people, sharing what I'm building. You know, building in public.
\nMy X history was flooded with hundreds of tweets and retweets after years of neglect. There were so many corporate social media sharing campaign posts, random competition retweets, and so on. None of that history represented the new image I wanted to portray on X.
\nBut I've had my X profile for years, and I didn't want to delete it entirely.
\nSo I needed to nuke my history.
\nThis is where it got annoying. I looked around for tools to do this and found... third-party options. Sketchy-looking websites asking for my credentials. Paid subscriptions just to delete tweets. Nothing that felt safe or worth using.
\n(I don't know if I'm overly paranoid, but giving my X login to a random website doesn't sit right with me.)
\nI'd used ZeroWork before. I was pretty active in their community for a few months. Hadn't touched it in a while, but this problem sparked my interest in using it again.
\nSo I built my own solution.
\nThis automation completely cleans up your Twitter/X profile by automatically deleting all your original tweets and undoing all your retweets. Instead of manually clicking delete on hundreds of posts, this tool does the entire job for you in one go.
\nThe process works like this:
\nKey features:
\n\nGetting the TaskBot to work reliably took way more trial and error than I expected.
\nThe main thing that tripped me up was loop logic. If I set the loop iterations too high, it would randomly fail.
\nSo I realized the best thing to do was limit the loop to a single tweet, then add an \"After Repeat\" block to check if there were still more tweets. A single loop per single tweet was way more reliable than trying to process multiple tweets per loop.
\nI also had to identify whether each object was a post or a retweet - the \"delete\" and \"un-repost\" actions are different, so I needed separate branches.
\nBut that wasn't the weird part.
\nOlder reposts/retweets were confusing. For some reason, they showed up in my Replies feed as me having retweeted them, but there was no \"Undo Retweet\" button. This broke my workflow since I couldn't just undo them directly.
\nI figured it out relatively quickly: I had to repost the item again, then undo that repost. Only then would it finally get removed from the Replies page. This makes zero sense to me, but it worked.
\nThen there were replies. Handling tweets where either I was replying to someone, or someone was replying to me - these got mixed together in the feed. The automation would try to delete tweets that weren't mine, which obviously failed.
\nI solved this with a counter. My loop would always review the tweet at position zero. If that tweet belonged to someone else, I'd increment the counter, so it would review the tweet at position one instead. This way I could skip over other people's replies and only target mine.
\nIt wasn't plug-and-play. I was pretty rusty on ZeroWork, and I spent many hours tweaking and re-running the TaskBot before it finally worked smoothly.
\nI let it run while I went to do other things. When I came back about 3 hours later, it had finished.
\nIt had removed about 400 reposts and a few tweets.
\nNow I have a fresh X profile with 0 posts and 0 retweets.
\nThat's it. Clean slate. Ready to start posting for real this time.
", "date_modified": "2026-03-22T00:00:00.000Z", "tags": [ "homelab", "zerowork" ] }, { "id": "https://lukemanning.ie/blog/velite-draft-filtering-not-working", "content_html": "I deployed my blog to Vercel, and there they were. All 17 draft posts, live on the internet. Great.
\nIf you're also setting up a blog with Velite, I wrote about the full Velite/Next.js setup process as well — this was part of that same initial build.
\nI had previously set up draft posts following my guide on adding draft posts to Velite. The frontmatter clearly said draft: true, but Velite didn't seem to care. My blog was showing posts that shouldn't exist yet - they appeared in the post list with full content visible, no indication they were drafts at all.
I'm using Velite 0.3.0 with Next.js 16.1.1. Here's what my velite.config.js looked like initially:
// velite.config.js (original)\nexport default defineConfig({\n collections: [\n {\n name: 'post',\n pattern: 'posts/**/*.md',\n schema: {\n // ... schema definition\n },\n filter: (post) => {\n const isProduction = process.env.VERCEL_ENV === 'production'\n return isProduction ? !post.draft : true\n }\n }\n ],\n // ... rest of config\n})The logic seemed sound: check if we're on Vercel production, and if so, filter out draft posts. In development, show everything including drafts.
\nThis worked fine locally. I could see my drafts when writing, and published posts appeared on the blog. But when I deployed to Vercel, all my drafts went live.
\nI had a suspicion that VERCEL_ENV wasn't being set correctly when Velite runs its build process. Vercel sets this environment variable, but maybe it's not available during the static site generation phase when Velite is processing posts.
I changed the config to use NODE_ENV instead, since that's definitely set during the build:
// velite.config.js (attempt 1)\nfilter: (post) => {\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}I was hoping this would work because NODE_ENV is set by Next.js when running npm run build, so it should be available when Velite processes the posts.
I ran the build:
\nNODE_ENV=production npm run buildThen checked .velite/posts.json to see what was generated. All 18 posts. Including 17 drafts.
I also checked what VERCEL_ENV was actually set to during the build:
// Quick debug check\nfilter: (post) => {\n console.log('VERCEL_ENV:', process.env.VERCEL_ENV)\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}Output: VERCEL_ENV: undefined - exactly what I suspected. The environment variable wasn't being set during Velite's build process.
Okay, so the filter function wasn't working as I expected.
\nI wondered if NODE_ENV was being evaluated when the module loads instead of when Velite actually processes each post. If the module loads before NODE_ENV is set to 'production', the filter would always see development mode.
But wait - that didn't make sense. I was explicitly running NODE_ENV=production npm run build, so the environment variable should be set before any Node modules load. The timing wasn't the issue.
Something else was going on.
\nLet me see if the filter function is even being called:
\nfilter: (post) => {\n console.log('Filtering post:', post.title, 'draft:', post.draft)\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}Ran the build. I was watching the terminal where I ran npm run build, but no logs appeared there. The filter function wasn't being invoked at all, or at least not in a way that would show logs during the build process.
Maybe the filter function syntax was wrong? Let me test by making it always return false, which should exclude all posts:
\nfilter: (post) => {\n console.log('Filtering post:', post.title)\n return false\n}Built again. Checked .velite/posts.json. All 18 posts still there.
At this point I was genuinely confused. The filter function exists in the Velite API, but it doesn't seem to affect the generated output at all. Either I'm using it wrong, or it's not doing what I think it does.
\nVelite has a complete() callback that runs after it generates all the data. Maybe filtering needs to happen there, since it's called after processing is complete?
I thought this might work because in my mental model, Velite processed the posts first, then wrote the JSON files, then called complete() to do final cleanup. If that was the case, modifying data.posts in complete() would affect what got written to the JSON file.
complete: (data) => {\n const isProduction = process.env.NODE_ENV === 'production'\n console.log('isProduction:', isProduction)\n console.log('Posts before filter:', data.posts.length)\n\n if (isProduction) {\n const draftCount = data.posts.filter(p => p.draft).length\n console.log('Filtering out', draftCount, 'draft posts')\n data.posts = data.posts.filter(post => !post.draft)\n }\n\n console.log('Posts after filter:', data.posts.length)\n // ... rest of function\n}Ran NODE_ENV=production npm run build.
Output:
\nisProduction: true\nPosts before filter: 18\nFiltering out 17 draft posts\nPosts after filter: 1\nOkay, so the filtering logic itself works! The logs show 1 post after filtering.
\nBut when I opened .velite/posts.json to verify, I was surprised - all 18 posts were there. My mental model was wrong. The complete() callback must run AFTER the JSON files are written, or it doesn't affect the generated output files at all.
Either way, the filtering I was doing wasn't making it into the JSON file.
\nThen it clicked. Velite generates the JSON, but I don't have to use all of it. My app imports posts from .velite/posts.json in src/lib/posts.ts, where I sort them and prepare them for display. Why not filter there too?
This is runtime filtering - it happens right when the posts are accessed by my app, not during Velite's build process. That means NODE_ENV would definitely be set correctly because it's happening in the Next.js runtime.
I know build-time filtering is theoretically faster since filtering happens once during the build instead of on every request. But at this point, I was tired of debugging the build process and wanted something that actually worked. I can always optimize later if performance becomes an issue - right now, reliability matters more.
\nHere's what src/lib/posts.ts looked like before:
// src/lib/posts.ts (before)\nimport posts from '.velite/posts.json'\nimport { cache } from 'react'\n\nexport const getPosts = cache(() =>\n posts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)And here's what I changed it to:
\n// src/lib/posts.ts (after)\nimport posts from '.velite/posts.json'\nimport { cache } from 'react'\n\nconst isProduction = process.env.NODE_ENV === 'production'\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts\n\nexport const getPosts = cache(() =>\n filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)Now when getPosts() is called, it checks NODE_ENV and returns filtered posts if we're in production.
Before deploying, I wanted to verify locally:
\nNODE_ENV=production npm run build\nNODE_ENV=production npm startOpened localhost:3000 in the browser. Only the published post showed up. The drafts were gone.
\nDeployed to Vercel. Checked the production URL directly (not from cache - used an incognito window to be sure). Only the published post shows up. The drafts are gone.
\nQuick note about preview deployments: The NODE_ENV check I used means preview deployments on Vercel will also hide draft posts, since NODE_ENV is 'production' in preview builds. If you want drafts to show in preview deployments, you'd need to check VERCEL_ENV === 'production' instead. But for my use case, hiding drafts in all non-dev environments works fine.
I removed the filter logic from velite.config.js since it wasn't working anyway:
// velite.config.js (final)\nexport default defineConfig({\n collections: [\n {\n name: 'post',\n pattern: 'posts/**/*.md',\n schema: {\n // ... schema definition\n }\n // No filter function - filtering happens in src/lib/posts.ts\n }\n ],\n // ... rest of config\n})Committed with message: \"Fix draft post filtering to work in production\"
\nRan npm run lint to make sure everything was clean. Deployed. Verified.
Now my drafts stay drafts, and published posts are the only ones visible in production.
\nI spent quite a while trying to make build-time filtering work in Velite before realizing runtime filtering in my app was actually the right approach.
", "url": "https://lukemanning.ie/blog/velite-draft-filtering-not-working", "title": "Draft Posts Still Showing in Production: My Velite Filtering Journey", "summary": "I deployed my blog to Vercel, and there they were. All 17 draft posts, live on the internet. Great.
\nIf you're also setting up a blog with Velite, I wrote about the full Velite/Next.js setup process as well — this was part of that same initial build.
\nI had previously set up draft posts following my guide on adding draft posts to Velite. The frontmatter clearly said draft: true, but Velite didn't seem to care. My blog was showing posts that shouldn't exist yet - they appeared in the post list with full content visible, no indication they were drafts at all.
I'm using Velite 0.3.0 with Next.js 16.1.1. Here's what my velite.config.js looked like initially:
// velite.config.js (original)\nexport default defineConfig({\n collections: [\n {\n name: 'post',\n pattern: 'posts/**/*.md',\n schema: {\n // ... schema definition\n },\n filter: (post) => {\n const isProduction = process.env.VERCEL_ENV === 'production'\n return isProduction ? !post.draft : true\n }\n }\n ],\n // ... rest of config\n})The logic seemed sound: check if we're on Vercel production, and if so, filter out draft posts. In development, show everything including drafts.
\nThis worked fine locally. I could see my drafts when writing, and published posts appeared on the blog. But when I deployed to Vercel, all my drafts went live.
\nI had a suspicion that VERCEL_ENV wasn't being set correctly when Velite runs its build process. Vercel sets this environment variable, but maybe it's not available during the static site generation phase when Velite is processing posts.
I changed the config to use NODE_ENV instead, since that's definitely set during the build:
// velite.config.js (attempt 1)\nfilter: (post) => {\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}I was hoping this would work because NODE_ENV is set by Next.js when running npm run build, so it should be available when Velite processes the posts.
I ran the build:
\nNODE_ENV=production npm run buildThen checked .velite/posts.json to see what was generated. All 18 posts. Including 17 drafts.
I also checked what VERCEL_ENV was actually set to during the build:
// Quick debug check\nfilter: (post) => {\n console.log('VERCEL_ENV:', process.env.VERCEL_ENV)\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}Output: VERCEL_ENV: undefined - exactly what I suspected. The environment variable wasn't being set during Velite's build process.
Okay, so the filter function wasn't working as I expected.
\nI wondered if NODE_ENV was being evaluated when the module loads instead of when Velite actually processes each post. If the module loads before NODE_ENV is set to 'production', the filter would always see development mode.
But wait - that didn't make sense. I was explicitly running NODE_ENV=production npm run build, so the environment variable should be set before any Node modules load. The timing wasn't the issue.
Something else was going on.
\nLet me see if the filter function is even being called:
\nfilter: (post) => {\n console.log('Filtering post:', post.title, 'draft:', post.draft)\n const isProduction = process.env.NODE_ENV === 'production'\n return isProduction ? !post.draft : true\n}Ran the build. I was watching the terminal where I ran npm run build, but no logs appeared there. The filter function wasn't being invoked at all, or at least not in a way that would show logs during the build process.
Maybe the filter function syntax was wrong? Let me test by making it always return false, which should exclude all posts:
\nfilter: (post) => {\n console.log('Filtering post:', post.title)\n return false\n}Built again. Checked .velite/posts.json. All 18 posts still there.
At this point I was genuinely confused. The filter function exists in the Velite API, but it doesn't seem to affect the generated output at all. Either I'm using it wrong, or it's not doing what I think it does.
\nVelite has a complete() callback that runs after it generates all the data. Maybe filtering needs to happen there, since it's called after processing is complete?
I thought this might work because in my mental model, Velite processed the posts first, then wrote the JSON files, then called complete() to do final cleanup. If that was the case, modifying data.posts in complete() would affect what got written to the JSON file.
complete: (data) => {\n const isProduction = process.env.NODE_ENV === 'production'\n console.log('isProduction:', isProduction)\n console.log('Posts before filter:', data.posts.length)\n\n if (isProduction) {\n const draftCount = data.posts.filter(p => p.draft).length\n console.log('Filtering out', draftCount, 'draft posts')\n data.posts = data.posts.filter(post => !post.draft)\n }\n\n console.log('Posts after filter:', data.posts.length)\n // ... rest of function\n}Ran NODE_ENV=production npm run build.
Output:
\nisProduction: true\nPosts before filter: 18\nFiltering out 17 draft posts\nPosts after filter: 1\nOkay, so the filtering logic itself works! The logs show 1 post after filtering.
\nBut when I opened .velite/posts.json to verify, I was surprised - all 18 posts were there. My mental model was wrong. The complete() callback must run AFTER the JSON files are written, or it doesn't affect the generated output files at all.
Either way, the filtering I was doing wasn't making it into the JSON file.
\nThen it clicked. Velite generates the JSON, but I don't have to use all of it. My app imports posts from .velite/posts.json in src/lib/posts.ts, where I sort them and prepare them for display. Why not filter there too?
This is runtime filtering - it happens right when the posts are accessed by my app, not during Velite's build process. That means NODE_ENV would definitely be set correctly because it's happening in the Next.js runtime.
I know build-time filtering is theoretically faster since filtering happens once during the build instead of on every request. But at this point, I was tired of debugging the build process and wanted something that actually worked. I can always optimize later if performance becomes an issue - right now, reliability matters more.
\nHere's what src/lib/posts.ts looked like before:
// src/lib/posts.ts (before)\nimport posts from '.velite/posts.json'\nimport { cache } from 'react'\n\nexport const getPosts = cache(() =>\n posts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)And here's what I changed it to:
\n// src/lib/posts.ts (after)\nimport posts from '.velite/posts.json'\nimport { cache } from 'react'\n\nconst isProduction = process.env.NODE_ENV === 'production'\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts\n\nexport const getPosts = cache(() =>\n filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)Now when getPosts() is called, it checks NODE_ENV and returns filtered posts if we're in production.
Before deploying, I wanted to verify locally:
\nNODE_ENV=production npm run build\nNODE_ENV=production npm startOpened localhost:3000 in the browser. Only the published post showed up. The drafts were gone.
\nDeployed to Vercel. Checked the production URL directly (not from cache - used an incognito window to be sure). Only the published post shows up. The drafts are gone.
\nQuick note about preview deployments: The NODE_ENV check I used means preview deployments on Vercel will also hide draft posts, since NODE_ENV is 'production' in preview builds. If you want drafts to show in preview deployments, you'd need to check VERCEL_ENV === 'production' instead. But for my use case, hiding drafts in all non-dev environments works fine.
I removed the filter logic from velite.config.js since it wasn't working anyway:
// velite.config.js (final)\nexport default defineConfig({\n collections: [\n {\n name: 'post',\n pattern: 'posts/**/*.md',\n schema: {\n // ... schema definition\n }\n // No filter function - filtering happens in src/lib/posts.ts\n }\n ],\n // ... rest of config\n})Committed with message: \"Fix draft post filtering to work in production\"
\nRan npm run lint to make sure everything was clean. Deployed. Verified.
Now my drafts stay drafts, and published posts are the only ones visible in production.
\nI spent quite a while trying to make build-time filtering work in Velite before realizing runtime filtering in my app was actually the right approach.
", "date_modified": "2026-03-22T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/opencode-nested-slash-commands-architecture", "content_html": "Here's what tripped me up: I tried to make a slash command call another slash command.
\nI had two commands doing basically the same thing. One was my 4-agent blog review system—495 lines of voice validation, completeness checking, structure editing, and technical validation (I wrote about the full 4-agent system). The other was a wrapper that auto-selects the next post needing review, then calls the first command. 239 lines of tracking and selection logic.
\nThe wrapper command was supposed to be simple: /review-next-blog-post. This wrapper then called the custom slash command /review-blog-post-multi-agent @content/posts/specific-post on the \"next\" post to be reviewed in my list of posts, based on criteria I defined.
I tried different variations. Maybe the slash command syntax was wrong? Maybe I needed quotes or a different calling pattern? Still nothing. I spent way too long wondering why OpenCode was just... ignoring my nested command call.
\nTurns out OpenCode slash commands can't call other slash commands. Each command is like a separate executable. You can't have command-a trigger command-b from within command-a's definition.
This actually makes sense—predictable behavior, no infinite loops, no command calling itself. But I didn't know that going in, and the lack of error feedback made the confusion worse.
\nI thought about a few options:
\nThe last option felt right. Instead of trying to make commands nested, I needed a single command that could operate in two different modes.
\n$1 argument system handles this perfectly:**Auto-Selection Mode (no arguments):**\n`/review-blog-post-multi-agent`\n\n**Direct Review Mode (specific post):**\n`/review-blog-post-multi-agent @content/posts/blog-post-slug.md` or `path/to/blog-post.md`\n\n**Mode Selection Logic:**\n- If `$1` is provided AND not empty → Direct Review Mode\n- If `$1` is empty or missing → Auto-Selection ModeIf $1 is provided, use the file directly. If it's missing, run auto-selection. The command now does both modes in one place—finds the next post OR reviews the one you specify.
The consolidation was a net improvement: from 2 commands totaling 734 lines to 1 command with 632 lines. That's -102 lines while adding more functionality.
\nHere's what changed:
\nproject_docs/blog-review-tracking.json as reusable content/review-blog-post-multi-agent for auto-selection OR /review-blog-post-multi-agent @content/posts/specific-post.md for direct reviewHere's what tripped me up: I tried to make a slash command call another slash command.
\nI had two commands doing basically the same thing. One was my 4-agent blog review system—495 lines of voice validation, completeness checking, structure editing, and technical validation (I wrote about the full 4-agent system). The other was a wrapper that auto-selects the next post needing review, then calls the first command. 239 lines of tracking and selection logic.
\nThe wrapper command was supposed to be simple: /review-next-blog-post. This wrapper then called the custom slash command /review-blog-post-multi-agent @content/posts/specific-post on the \"next\" post to be reviewed in my list of posts, based on criteria I defined.
I tried different variations. Maybe the slash command syntax was wrong? Maybe I needed quotes or a different calling pattern? Still nothing. I spent way too long wondering why OpenCode was just... ignoring my nested command call.
\nTurns out OpenCode slash commands can't call other slash commands. Each command is like a separate executable. You can't have command-a trigger command-b from within command-a's definition.
This actually makes sense—predictable behavior, no infinite loops, no command calling itself. But I didn't know that going in, and the lack of error feedback made the confusion worse.
\nI thought about a few options:
\nThe last option felt right. Instead of trying to make commands nested, I needed a single command that could operate in two different modes.
\n$1 argument system handles this perfectly:**Auto-Selection Mode (no arguments):**\n`/review-blog-post-multi-agent`\n\n**Direct Review Mode (specific post):**\n`/review-blog-post-multi-agent @content/posts/blog-post-slug.md` or `path/to/blog-post.md`\n\n**Mode Selection Logic:**\n- If `$1` is provided AND not empty → Direct Review Mode\n- If `$1` is empty or missing → Auto-Selection ModeIf $1 is provided, use the file directly. If it's missing, run auto-selection. The command now does both modes in one place—finds the next post OR reviews the one you specify.
The consolidation was a net improvement: from 2 commands totaling 734 lines to 1 command with 632 lines. That's -102 lines while adding more functionality.
\nHere's what changed:
\nproject_docs/blog-review-tracking.json as reusable content/review-blog-post-multi-agent for auto-selection OR /review-blog-post-multi-agent @content/posts/specific-post.md for direct reviewRunning git log broke my repository.
I was on WSL (Windows Subsystem for Linux) working on my blog project like any other day. Ran git log to check my recent commits and got this:
error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nfatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corruptThree corrupt objects. Empty files. Admittedly I have somewhat limited Git experience, but I had never seen this before.
\nWas I about to lose commits?
\nFirst, I needed to figure out how bad this was. I navigated to my repository root (where the .git folder is) and ran:
$ git fsck --fullThis command scans every object in your repository for corruption. The --full flag makes it check everything, not just what's reachable from current branches.
The output was worse than I thought:
\nerror: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty\nerror: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty\nfatal: loose object 287186e66df4cf7057d2897bc1da0027affbfbe5 (stored in .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5) is corrupt\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nfatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corrupt\nerror: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty\nerror: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty\nfatal: loose object e2ec99bf1bb260a461c1b7670ad2e891ab0d7f88 (stored in .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88) is corruptThree corrupt object files. All empty (0 bytes).
\nI didn't know what these objects were exactly - could have been commits, could have been file contents, could have been something else. That was the scary part. Were these unreferenced objects I wouldn't miss, or was I about to lose actual work?
\nGit splits object hashes into two-character directories (b9/) to avoid having millions of files in a single folder. That's normal Git internals.
If you're managing a home server and run into data recovery issues, I also wrote about fixing Unraid Docker containers after an upgrade — less Git-related, but same problem-solving mindset.
\nThe initial solution I got was:
\nrm .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \\\n .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \\\n .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88But I stopped. Because here's the thing: what if this doesn't work?
\nI asked: \"Do we have to rm? Can we mv in case this doesn't work? Or am I screwed either way?\"
This turned out to be the right question. Even though these files were corrupt and empty, having a backup before doing anything destructive felt smarter. Even if it was arguably pointless. Sometimes you need a safety net, you know?
\nHere's what I did instead:
\nStep 1: Create a backup location
\nmkdir -p .git/corrupt-backupWill this work? I wasn't sure, but at least I'd have a backup if things went sideways.
\nStep 2: Move the corrupt files (don't delete)
\nmv .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \\\n .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \\\n .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 \\\n .git/corrupt-backup/Now the corrupt objects are gone from Git's perspective, but I still have them if I need to investigate later.
\nI did try running git fetch origin before moving the files, but Git still threw the same corruption error. The empty files were blocking everything - they had to go.
Step 3: Recover from the remote
\nThis was the scary part. From the same repository root, I ran:
\ngit fetch originGit compared my local repo to GitHub, saw the missing objects, and re-downloaded them to .git/objects/. Because these commits existed on GitHub, I got back the exact object files I'd lost.
origin is the default name Git gives to your main remote. You can check your remotes with git remote -v if you're curious.
Step 4: Verify everything is fixed
\nThat output looked good. But I needed to be sure. So I ran fsck again:
$ git fsck --full\nChecking object directories: 100% (256/256), done.\nChecking objects: 100% (257/257), done.Step 5: Confirm Git commands work
\n$ git log --oneline -10\nb92de20 Adding +2 reviews for setup blog post\n626e596 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised\n42f41d7 Token optimization plan improvements\ndb5c595 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised\n4bf342a refactor(orchestrators): use VOICE_GUIDE.md instead of reading recent posts\n...Everything works. Repository fully recovered.
\nHonestly, I got lucky. I had pushed everything to GitHub, so git fetch origin worked immediately.
If I hadn't had a remote, I would have been in trouble. I could have tried git reflog to see if Git still had references locally, but if the commits weren't pushed and weren't in reflog, they'd be gone.
This is why regular pushes matter - they're not just for sharing, they're for disaster recovery.
\nObject corruption happens. System crashes, disk issues, power loss, process killed at the wrong moment - any of these can leave you with empty 0-byte files in .git/objects/. I don't know which one hit me.
Remote repositories are your safety net. Because I'd pushed these commits to GitHub, git fetch could restore them. The objects weren't actually lost, they just needed to be re-downloaded. If I hadn't pushed recently, this would've been scarier.
Always have a rollback plan. Moving files instead of deleting them was the right call. Even though they were corrupt and useless, having them in .git/corrupt-backup/ meant I could investigate or restore if something went wrong. I asked myself: \"before any destructive operation, do I have an escape hatch?\" That question saved me stress, even though I didn't end up needing the backup.
git fsck saved me time. When I first ran git fsck --full, I was overwhelmed by how verbose the output was. But once I realized it was showing me EXACTLY which three files were corrupt (with full paths and hashes), I knew what I needed to fix. Before this, I was guessing. After running fsck, I had precision.
Git object corruption sounded terrifying when it first happened. But because I had GitHub and had pushed my commits, recovery was straightforward. The remote wasn't just for sharing code, it was my disaster recovery system.
\nAnd that mv instead of rm? Saved me from unnecessary stress. Even though the files were genuinely corrupt and I never needed them again, having that backup gave me confidence to proceed.
Running git log broke my repository.
I was on WSL (Windows Subsystem for Linux) working on my blog project like any other day. Ran git log to check my recent commits and got this:
error: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nfatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corruptThree corrupt objects. Empty files. Admittedly I have somewhat limited Git experience, but I had never seen this before.
\nWas I about to lose commits?
\nFirst, I needed to figure out how bad this was. I navigated to my repository root (where the .git folder is) and ran:
$ git fsck --fullThis command scans every object in your repository for corruption. The --full flag makes it check everything, not just what's reachable from current branches.
The output was worse than I thought:
\nerror: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty\nerror: object file .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 is empty\nfatal: loose object 287186e66df4cf7057d2897bc1da0027affbfbe5 (stored in .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5) is corrupt\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nerror: object file .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 is empty\nfatal: loose object b92de209f45b133daeeb97a46ea9ed354a2b9664 (stored in .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664) is corrupt\nerror: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty\nerror: object file .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 is empty\nfatal: loose object e2ec99bf1bb260a461c1b7670ad2e891ab0d7f88 (stored in .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88) is corruptThree corrupt object files. All empty (0 bytes).
\nI didn't know what these objects were exactly - could have been commits, could have been file contents, could have been something else. That was the scary part. Were these unreferenced objects I wouldn't miss, or was I about to lose actual work?
\nGit splits object hashes into two-character directories (b9/) to avoid having millions of files in a single folder. That's normal Git internals.
If you're managing a home server and run into data recovery issues, I also wrote about fixing Unraid Docker containers after an upgrade — less Git-related, but same problem-solving mindset.
\nThe initial solution I got was:
\nrm .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \\\n .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \\\n .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88But I stopped. Because here's the thing: what if this doesn't work?
\nI asked: \"Do we have to rm? Can we mv in case this doesn't work? Or am I screwed either way?\"
This turned out to be the right question. Even though these files were corrupt and empty, having a backup before doing anything destructive felt smarter. Even if it was arguably pointless. Sometimes you need a safety net, you know?
\nHere's what I did instead:
\nStep 1: Create a backup location
\nmkdir -p .git/corrupt-backupWill this work? I wasn't sure, but at least I'd have a backup if things went sideways.
\nStep 2: Move the corrupt files (don't delete)
\nmv .git/objects/28/7186e66df4cf7057d2897bc1da0027affbfbe5 \\\n .git/objects/b9/2de209f45b133daeeb97a46ea9ed354a2b9664 \\\n .git/objects/e2/ec99bf1bb260a461c1b7670ad2e891ab0d7f88 \\\n .git/corrupt-backup/Now the corrupt objects are gone from Git's perspective, but I still have them if I need to investigate later.
\nI did try running git fetch origin before moving the files, but Git still threw the same corruption error. The empty files were blocking everything - they had to go.
Step 3: Recover from the remote
\nThis was the scary part. From the same repository root, I ran:
\ngit fetch originGit compared my local repo to GitHub, saw the missing objects, and re-downloaded them to .git/objects/. Because these commits existed on GitHub, I got back the exact object files I'd lost.
origin is the default name Git gives to your main remote. You can check your remotes with git remote -v if you're curious.
Step 4: Verify everything is fixed
\nThat output looked good. But I needed to be sure. So I ran fsck again:
$ git fsck --full\nChecking object directories: 100% (256/256), done.\nChecking objects: 100% (257/257), done.Step 5: Confirm Git commands work
\n$ git log --oneline -10\nb92de20 Adding +2 reviews for setup blog post\n626e596 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised\n42f41d7 Token optimization plan improvements\ndb5c595 refactor(content): apply multi-agent review fixes to setting-up-velite-nextjs-revised\n4bf342a refactor(orchestrators): use VOICE_GUIDE.md instead of reading recent posts\n...Everything works. Repository fully recovered.
\nHonestly, I got lucky. I had pushed everything to GitHub, so git fetch origin worked immediately.
If I hadn't had a remote, I would have been in trouble. I could have tried git reflog to see if Git still had references locally, but if the commits weren't pushed and weren't in reflog, they'd be gone.
This is why regular pushes matter - they're not just for sharing, they're for disaster recovery.
\nObject corruption happens. System crashes, disk issues, power loss, process killed at the wrong moment - any of these can leave you with empty 0-byte files in .git/objects/. I don't know which one hit me.
Remote repositories are your safety net. Because I'd pushed these commits to GitHub, git fetch could restore them. The objects weren't actually lost, they just needed to be re-downloaded. If I hadn't pushed recently, this would've been scarier.
Always have a rollback plan. Moving files instead of deleting them was the right call. Even though they were corrupt and useless, having them in .git/corrupt-backup/ meant I could investigate or restore if something went wrong. I asked myself: \"before any destructive operation, do I have an escape hatch?\" That question saved me stress, even though I didn't end up needing the backup.
git fsck saved me time. When I first ran git fsck --full, I was overwhelmed by how verbose the output was. But once I realized it was showing me EXACTLY which three files were corrupt (with full paths and hashes), I knew what I needed to fix. Before this, I was guessing. After running fsck, I had precision.
Git object corruption sounded terrifying when it first happened. But because I had GitHub and had pushed my commits, recovery was straightforward. The remote wasn't just for sharing code, it was my disaster recovery system.
\nAnd that mv instead of rm? Saved me from unnecessary stress. Even though the files were genuinely corrupt and I never needed them again, having that backup gave me confidence to proceed.
I previously wrote about my multi-agent blog post generation system that takes my raw conversations and notes and generates structured posts from them: I Built a Multi-Agent System to Review My Blog Posts.
\nThese posts are often half-finished thoughts and content that I didn't want to be published yet. So to avoid this happening, but to still give me the ability to create a base post to work from, I thought I'd enable drafts that would be hidden until I was ready to publish.
\n\"Just add draft: true to frontmatter,\" I thought. Every other static site generator does this, right?
\nSpoiler: Velite doesn't work that way.
\nHere's what I tried first:
\n---\ntitle: \"Work in Progress\"\ndate: 2025-01-03\ndraft: true\n---\n\nStill writing this...Except... it doesn't work that way.
\n\"Does Velite automatically consider all frontmatter (those YAML settings at the top of my markdown files between the --- markers), or do we need to handle each value separately?\"
I assumed Velite would auto-pick up any field I put in frontmatter. Add draft: true, filter posts by post.draft, done.
That's not how Velite works.
\nBefore I get into the solution, here's what my setup looked like:
\nMy existing Velite schema (/velite.config.js):
import rehypeShiki from '@shikijs/rehype'\nimport { defineConfig, s } from 'velite'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n lastModified: s.isodate().optional(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})Prerequisites: You should have:
\nIf your setup looks different, the draft field addition should still work. You'll just need to adapt the schema structure.
\nI'm using Velite 0.3.0 with Next.js 16.1.1, and this is where I learned something important.
\nVelite is schema-first. Every field must be explicitly defined in your schema in /velite.config.js.
From Velite's official docs:
\n\n\nThe schema property defines the structure and types of the data within a collection. You use Velite's schema system to specify fields, their types, and whether they are optional.
\n
No schema field? No access to that data. Period.
\nThis means:
\nIf draft isn't in your schema, Velite ignores it in frontmatter.
Adding draft functionality requires two changes. I thought I could skip the first one. I was wrong.
\nI figured Velite would just... pick up the field. Add draft: true to frontmatter, access post.draft in my code, done.
Nope.
\nVelite ignored my draft field entirely. No error, no warning, nothing. The post compiled, the field was just... gone.
Here's what I added to my config:
\nimport { defineCollection, defineConfig } from 'velite'\nimport { MDXPlugin } from 'velite-remark'\nimport rehypeSlug from 'rehype-slug'\nimport rehypeAutolinkHeadings from 'rehype-autolink-headings'\n\nconst posts = defineCollection({\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s.object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n draft: s.boolean().optional().default(false), // ← Add this line\n // ... other existing fields like description, tags, etc.\n }),\n mdx: MDXPlugin({ rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings] })\n})\n\nexport default defineConfig({\n collections: { posts }\n})In my case, I had MDX plugins set up for syntax highlighting. If your setup is simpler, the schema addition looks like this:
\nconst posts = defineCollection({\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s.object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n draft: s.boolean().optional().default(false),\n })\n})\n\nexport default defineConfig({ collections: { posts } })The s object you see in the code examples is the schema builder. It's provided by defineCollection and gives you type-safe field definitions:
s.string() - text fieldss.boolean() - true/false valuess.isodate() - date fields (validated as ISO format)s.slug() - URL-friendly slugs.optional() - field doesn't have to exist.default(false) - if missing, use this value.max(99) - string length limitI chose .optional().default(false) and .boolean() for specific reasons:
.optional() — not every post needs a draft flag, so we don't require it.default(false) — posts are published by default (safer than assuming draft).boolean() — catches typos like draft: yes instead of true, failing at build timeI saved the config and restarted the dev server.
\nStill no draft field in my posts. I checked .velite/posts.json. Nothing.
Hmm. Maybe I typoed something in the schema? No, looks fine. Maybe the MDX plugins are interfering? I tried simplifying the config to just the schema. Still nothing.
\nAt this point I remembered: Velite caches everything. Schema changes mean the cached data is invalid.
\nI ran npm run clean:dev (which removes both .next and .velite folders) and restarted the dev server.
This time, .velite/posts.json had the draft field for every post:
{\n \"title\": \"Work in Progress\",\n \"slug\": \"work-in-progress\",\n \"date\": \"2025-01-03T00:00:00.000Z\",\n \"draft\": true,\n // ... other fields\n}Posts without draft: true in frontmatter had \"draft\": false (from the .default(false)). I tested a typo (darft: true) which resulted in the field being ignored entirely, defaulting to false. Nice.
Lesson learned: Schema changes in Velite require clearing the cache. It's annoying, but it prevents stale cached data from causing weird bugs.
\nBut having the field isn't enough. You also need to filter out drafts based on environment.
\nI needed:
\nI considered using Vercel's VERCEL_ENV at first. That's the \"proper\" Vercel way. But I was already using NODE_ENV elsewhere in my config, so I stuck with that.
const isProduction = process.env.NODE_ENV === 'production'This works because:
\nNODE_ENV=development, so show draftsNODE_ENV=production, so hide draftsFor the filtering, I added it in /src/lib/posts.ts rather than the Velite config. Here's what that looks like:
import { cache } from 'react'\nimport { posts } from '#site/content'\n\nconst isProduction = process.env.NODE_ENV === 'production'\n\n// Filter posts at the application level\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts\n\n// All exported functions use filteredPosts instead of raw posts\nexport const getPosts = cache(() =>\n filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)\n\nexport const getPostBySlug = cache((slug: string) =>\n filteredPosts.find((p) => p.slug === slug)\n)I filtered at the application level because it keeps the Velite config simple. I just need the schema field. The filtering logic lives with the rest of the post retrieval code, which felt cleaner to me.
\nHere's how it behaves:
\nNODE_ENV=development) means show draftsNODE_ENV=production) means hide draftsNODE_ENV=production) means hide draftsThe simple check process.env.NODE_ENV === 'production' handles all cases:
isProduction = false, so show draftsisProduction = true, so hide draftsHonestly, defining every field in the schema felt annoying at first. More boilerplate, more config.
\nBut then I thought about what would happen without it:
\nTypo draft: true as darft: true?\nBuild succeeds. Draft goes live. You don't notice until someone emails you.
Inconsistent values like draft: yes or draft: 1?\nNo type checking. Your filter logic breaks silently.
Rename draft to published in frontmatter but forget to update code?\nNo build error. Filtering stops working.
Schema-first means:
\nThe 30 seconds to add a schema field saves hours of \"why isn't this working?\" debugging.
\nI initially thought about using VERCEL_ENV since I'm deploying to Vercel. That's what their docs recommend for detecting preview vs production deployments. But NODE_ENV works fine for my use case:
NODE_ENV is already set by Vercel in production buildsNODE_ENV elsewhere in my configIf you need draft posts visible in preview deployments but hidden in production, VERCEL_ENV is the way to go:
const isProduction = process.env.VERCEL_ENV === 'production'\n\n// Then use the same filtering logic\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : postsBut for me, NODE_ENV is simpler and works just as well.
I created a test draft post to verify everything worked:
\n---\ntitle: \"Test Draft\"\nslug: test-draft\ndate: 2025-01-03\ndraft: true\n---\n\nThis should only appear in dev/preview.First, I ran npm run dev. The draft showed up in my post list. I clicked through to /blog/test-draft and saw the content. Good.
Then I ran npm run build followed by npm run start to test production behavior.
Expected: Post appears in list, I can read it.\nActual: Post is gone from the list. /blog/test-draft returns 404.
Exactly what I wanted. But I wanted to double-check the build output, so I opened .velite/posts.json. Wait. The test-draft entry was still there.
That's weird. I thought it would be filtered out by Velite?
\nOh right. I'm filtering at the application level in posts.ts, not in the Velite config. Velite builds all posts, including drafts, into .velite/posts.json. Then my application code filters them out when retrieving posts.
I verified this by checking the RSS feed. In the Velite config's complete callback, I filter out drafts before adding to the feed. So draft posts don't show up in the RSS. But .velite/posts.json still contains everything.
This is actually fine. The filtering happens where I retrieve posts, so draft posts never reach my components. The build output includes everything, but my app only serves what's appropriate for the environment.
\nVelite doesn't auto-pick up frontmatter fields. You must define them in your schema first.
\nThis felt like a constraint at first. Now I see it as a safety net:
\nThe schema isn't boilerplate. It's the contract between your content and your code.
\nThat darft: true typo? Can't happen. Velite would ignore the field entirely, and TypeScript would show an error when you try to access post.darft.
Schema-first design saves future-you from current-you's mistakes.
", "url": "https://lukemanning.ie/blog/adding-draft-posts-to-velite", "title": "Adding Draft Posts to Velite: Why 'draft: true' Isn't Enough", "summary": "I previously wrote about my multi-agent blog post generation system that takes my raw conversations and notes and generates structured posts from them: I Built a Multi-Agent System to Review My Blog Posts.
\nThese posts are often half-finished thoughts and content that I didn't want to be published yet. So to avoid this happening, but to still give me the ability to create a base post to work from, I thought I'd enable drafts that would be hidden until I was ready to publish.
\n\"Just add draft: true to frontmatter,\" I thought. Every other static site generator does this, right?
\nSpoiler: Velite doesn't work that way.
\nHere's what I tried first:
\n---\ntitle: \"Work in Progress\"\ndate: 2025-01-03\ndraft: true\n---\n\nStill writing this...Except... it doesn't work that way.
\n\"Does Velite automatically consider all frontmatter (those YAML settings at the top of my markdown files between the --- markers), or do we need to handle each value separately?\"
I assumed Velite would auto-pick up any field I put in frontmatter. Add draft: true, filter posts by post.draft, done.
That's not how Velite works.
\nBefore I get into the solution, here's what my setup looked like:
\nMy existing Velite schema (/velite.config.js):
import rehypeShiki from '@shikijs/rehype'\nimport { defineConfig, s } from 'velite'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n lastModified: s.isodate().optional(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})Prerequisites: You should have:
\nIf your setup looks different, the draft field addition should still work. You'll just need to adapt the schema structure.
\nI'm using Velite 0.3.0 with Next.js 16.1.1, and this is where I learned something important.
\nVelite is schema-first. Every field must be explicitly defined in your schema in /velite.config.js.
From Velite's official docs:
\n\n\nThe schema property defines the structure and types of the data within a collection. You use Velite's schema system to specify fields, their types, and whether they are optional.
\n
No schema field? No access to that data. Period.
\nThis means:
\nIf draft isn't in your schema, Velite ignores it in frontmatter.
Adding draft functionality requires two changes. I thought I could skip the first one. I was wrong.
\nI figured Velite would just... pick up the field. Add draft: true to frontmatter, access post.draft in my code, done.
Nope.
\nVelite ignored my draft field entirely. No error, no warning, nothing. The post compiled, the field was just... gone.
Here's what I added to my config:
\nimport { defineCollection, defineConfig } from 'velite'\nimport { MDXPlugin } from 'velite-remark'\nimport rehypeSlug from 'rehype-slug'\nimport rehypeAutolinkHeadings from 'rehype-autolink-headings'\n\nconst posts = defineCollection({\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s.object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n draft: s.boolean().optional().default(false), // ← Add this line\n // ... other existing fields like description, tags, etc.\n }),\n mdx: MDXPlugin({ rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings] })\n})\n\nexport default defineConfig({\n collections: { posts }\n})In my case, I had MDX plugins set up for syntax highlighting. If your setup is simpler, the schema addition looks like this:
\nconst posts = defineCollection({\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s.object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n draft: s.boolean().optional().default(false),\n })\n})\n\nexport default defineConfig({ collections: { posts } })The s object you see in the code examples is the schema builder. It's provided by defineCollection and gives you type-safe field definitions:
s.string() - text fieldss.boolean() - true/false valuess.isodate() - date fields (validated as ISO format)s.slug() - URL-friendly slugs.optional() - field doesn't have to exist.default(false) - if missing, use this value.max(99) - string length limitI chose .optional().default(false) and .boolean() for specific reasons:
.optional() — not every post needs a draft flag, so we don't require it.default(false) — posts are published by default (safer than assuming draft).boolean() — catches typos like draft: yes instead of true, failing at build timeI saved the config and restarted the dev server.
\nStill no draft field in my posts. I checked .velite/posts.json. Nothing.
Hmm. Maybe I typoed something in the schema? No, looks fine. Maybe the MDX plugins are interfering? I tried simplifying the config to just the schema. Still nothing.
\nAt this point I remembered: Velite caches everything. Schema changes mean the cached data is invalid.
\nI ran npm run clean:dev (which removes both .next and .velite folders) and restarted the dev server.
This time, .velite/posts.json had the draft field for every post:
{\n \"title\": \"Work in Progress\",\n \"slug\": \"work-in-progress\",\n \"date\": \"2025-01-03T00:00:00.000Z\",\n \"draft\": true,\n // ... other fields\n}Posts without draft: true in frontmatter had \"draft\": false (from the .default(false)). I tested a typo (darft: true) which resulted in the field being ignored entirely, defaulting to false. Nice.
Lesson learned: Schema changes in Velite require clearing the cache. It's annoying, but it prevents stale cached data from causing weird bugs.
\nBut having the field isn't enough. You also need to filter out drafts based on environment.
\nI needed:
\nI considered using Vercel's VERCEL_ENV at first. That's the \"proper\" Vercel way. But I was already using NODE_ENV elsewhere in my config, so I stuck with that.
const isProduction = process.env.NODE_ENV === 'production'This works because:
\nNODE_ENV=development, so show draftsNODE_ENV=production, so hide draftsFor the filtering, I added it in /src/lib/posts.ts rather than the Velite config. Here's what that looks like:
import { cache } from 'react'\nimport { posts } from '#site/content'\n\nconst isProduction = process.env.NODE_ENV === 'production'\n\n// Filter posts at the application level\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts\n\n// All exported functions use filteredPosts instead of raw posts\nexport const getPosts = cache(() =>\n filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())\n)\n\nexport const getPostBySlug = cache((slug: string) =>\n filteredPosts.find((p) => p.slug === slug)\n)I filtered at the application level because it keeps the Velite config simple. I just need the schema field. The filtering logic lives with the rest of the post retrieval code, which felt cleaner to me.
\nHere's how it behaves:
\nNODE_ENV=development) means show draftsNODE_ENV=production) means hide draftsNODE_ENV=production) means hide draftsThe simple check process.env.NODE_ENV === 'production' handles all cases:
isProduction = false, so show draftsisProduction = true, so hide draftsHonestly, defining every field in the schema felt annoying at first. More boilerplate, more config.
\nBut then I thought about what would happen without it:
\nTypo draft: true as darft: true?\nBuild succeeds. Draft goes live. You don't notice until someone emails you.
Inconsistent values like draft: yes or draft: 1?\nNo type checking. Your filter logic breaks silently.
Rename draft to published in frontmatter but forget to update code?\nNo build error. Filtering stops working.
Schema-first means:
\nThe 30 seconds to add a schema field saves hours of \"why isn't this working?\" debugging.
\nI initially thought about using VERCEL_ENV since I'm deploying to Vercel. That's what their docs recommend for detecting preview vs production deployments. But NODE_ENV works fine for my use case:
NODE_ENV is already set by Vercel in production buildsNODE_ENV elsewhere in my configIf you need draft posts visible in preview deployments but hidden in production, VERCEL_ENV is the way to go:
const isProduction = process.env.VERCEL_ENV === 'production'\n\n// Then use the same filtering logic\nconst filteredPosts = isProduction ? posts.filter(post => !post.draft) : postsBut for me, NODE_ENV is simpler and works just as well.
I created a test draft post to verify everything worked:
\n---\ntitle: \"Test Draft\"\nslug: test-draft\ndate: 2025-01-03\ndraft: true\n---\n\nThis should only appear in dev/preview.First, I ran npm run dev. The draft showed up in my post list. I clicked through to /blog/test-draft and saw the content. Good.
Then I ran npm run build followed by npm run start to test production behavior.
Expected: Post appears in list, I can read it.\nActual: Post is gone from the list. /blog/test-draft returns 404.
Exactly what I wanted. But I wanted to double-check the build output, so I opened .velite/posts.json. Wait. The test-draft entry was still there.
That's weird. I thought it would be filtered out by Velite?
\nOh right. I'm filtering at the application level in posts.ts, not in the Velite config. Velite builds all posts, including drafts, into .velite/posts.json. Then my application code filters them out when retrieving posts.
I verified this by checking the RSS feed. In the Velite config's complete callback, I filter out drafts before adding to the feed. So draft posts don't show up in the RSS. But .velite/posts.json still contains everything.
This is actually fine. The filtering happens where I retrieve posts, so draft posts never reach my components. The build output includes everything, but my app only serves what's appropriate for the environment.
\nVelite doesn't auto-pick up frontmatter fields. You must define them in your schema first.
\nThis felt like a constraint at first. Now I see it as a safety net:
\nThe schema isn't boilerplate. It's the contract between your content and your code.
\nThat darft: true typo? Can't happen. Velite would ignore the field entirely, and TypeScript would show an error when you try to access post.darft.
Schema-first design saves future-you from current-you's mistakes.
", "date_modified": "2026-01-05T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/premature-optimization-multi-agent-prompts", "content_html": "\n\nContext: This post assumes you've read how I built the multi-agent blog review system. If you haven't, that post explains the architecture before this one breaks it.
\n
I broke my entire blog review system this week trying to beat session limits.
\nNot because tokens cost money. Because Claude Code has session limits - I kept hitting the message cap before finishing my work.
\nHere's what that means in practice: Claude Code limits how many messages you can send in a session. Each time you ask it something, that's a message. Each time an agent spawns, that's a message. Each file read, each grep search - all messages. When you hit the limit (usually around 100-150 messages depending on context), your workflow just stops mid-task.
\nEvery agent spawn, every file read, every grep search consumes tokens. When your prompts eat 15,750 tokens before any actual work happens, you burn through your session budget fast.
\nSo I thought: \"If I can trim these prompts by 1,100 tokens, I'll get more messages per session. More reviews. More work done.\"
\nThe logic was sound. The execution broke everything.
\nContext for what I broke:
\n.claude/agents/blog-authenticity-guardian.md, .claude/agents/blog-structure-editor.md, .claude/agents/blog-skeptical-reader.md, .claude/agents/blog-technical-educator.md, .claude/agents/blog-orchestrator.mdThe constraint felt real. Each blog review spawned 4-5 agents, each with 2,000-3,000 token prompts. Add file reads, grep searches, and context - I'd burn 50+ messages per review. When you hit the session limit, your workflow just... stops.
\nThe optimization seemed obvious. Every agent review consumed messages:
\nThat's 17-27 messages per blog post review. With 15,750 tokens of prompt overhead per agent, I was front-loading massive context before any actual analysis happened.
\nHere's my thinking: Each message I send to Claude can carry some context. If my agent prompts are smaller, each message has more room for actual work - the blog post content, the critic feedback, the revision drafts. Smaller prompts = more work per message = more blog posts reviewed per session.
\nThe math seemed clear.
\nSo I started condensing. \"Just remove verbose examples here. Tighten this guidance there. These agents don't need ALL this instruction, right?\"
\nI opened up the agent prompt files and started cutting:
\nFrom .claude/agents/blog-skeptical-reader.md, I removed:
From .claude/agents/blog-technical-educator.md, I removed:
I condensed verbose output format examples into concise headers. I tightened sentences. I deleted \"redundant\" guidance.
\nCommit efb9345: Reduced total prompt tokens from ~15,750 to ~14,650.
I'd saved 1,100 tokens (about 825 words). My optimization was complete.
\nThe numbers looked great. The system was broken.
\nTwo days after the commit, I ran a blog post through the review system. I'd been working on a debugging story about hydration errors in Next.js 16 - the kind of post my system had been catching gaps in reliably.
\nThe review process started normally. Orchestrator spawned the three critics in parallel. Authenticity Guardian flagged a preachy opening. Structure Editor suggested reorganizing the mental model section. Skeptical Reader asked for more specific error messages.
\nAll normal. I spawned the Technical Educator for revisions.
\nThen I saw the draft it generated.
\nInstead of writing a debugging post that started with the error and showed my journey to resolving the problem, it instead created an entirely different post with a completely unexpected hallucinated structure and heavy tutorial focus. And that was what happened when it worked. At worst it fully hallucinated an entirely different conversation.
\nWhen I say the agent was \"hallucinating structure,\" I mean it was inventing a post format that doesn't match my blog's voice at all. Here's the difference:
\nWhat my Technical Educator is supposed to generate (from .claude/agents/blog-technical-educator.md before my optimization):
Your posts are debugging detective stories. Start with the error message.\nShow what you tried that didn't work. Document the \"aha!\" moment. Then\nexplain the mental model that makes it obvious in hindsight. Think: Julia\nEvans blog posts, not MDN documentation.\n\nStructure:\n1. Start with the problem (relatable, specific)\n2. Show the debugging journey (wrong turns and all)\n3. Explain the mental model (why it works, not just how)\n4. End with the solution (what finally worked)\n\nUse conversational tone. Be honest about confusion. No \"in this post,\nI'll show you how\" or other tutorial language.\nWhat it generated after my optimization (what I actually saw):
\nDramatic section headers like \"Breaking Point #1\" and \"Breaking Point #2\". Content marketing structure where each section is a \"problem\" followed by an \"explanation.\" Formal, distant voice (\"The primary issue manifests when...\"). No confusion shown, no wrong turns documented, no debugging story - just clean instruction.
\nThat's hallucinating structure: the agent invented a format that doesn't exist in my blog's voice because I'd removed the guidance that defined what my voice actually is.
\nI looked at the actual changes I made to figure out what I'd removed.
\nHere's what my Skeptical Reader prompt looked like before my optimization:
\n## Evaluation Dimensions\n\nYou evaluate posts against 6 dimensions:\n\n1. **Searchability**: Does the title include specific phrases people Google?\n - ✅ \"Error: Cannot read property 'map' of undefined\" (searchable)\n - ❌ \"Understanding Async/Await in JavaScript\" (generic)\n\n2. **Specificity**: Are version numbers, actual error messages, and real code included?\n - ✅ \"Next.js 16.1.1\", \"Cannot read property 'map' of undefined\"\n - ❌ \"Next.js 16\", \"an error occurred\"\n\n3. **Mental Model Transfer**: Is the WHY explained before the HOW?\n - ✅ \"I finally understood this was a timing issue...\" (explains why)\n - ❌ \"Add async/await to handle promises\" (just says how)\n\n4. **Cognitive Load**: Does complexity progress gradually?\n - ✅ Simple version first, then nuance, then edge cases\n - ❌ Jump straight to complex implementation\n\n5. **Curse of Knowledge**: Would past-Luke understand this?\n - ✅ \"I thought X, but actually Y because...\" (bridges gap)\n - ❌ \"This is obvious...\" (assumes knowledge)\n\n6. **Journey Documentation**: Is the debugging process shown?\n - ✅ \"I tried X, which didn't work. Then I tried Y...\"\n - ❌ Just the solution, no processAfter my optimization, I'd condensed this to:
\n## Evaluation Dimensions\n\nCheck for:\n- Specificity (versions, error messages, real code)\n- Examples for every concept\n- Clear explanationsCognitive Load and Curse of Knowledge weren't just combined - they were gone. Searchability was missing. Journey Documentation had vanished. The agent couldn't catch those failure modes anymore because I'd deleted the concepts from its prompt entirely.
\nHere's the actual Technical Educator framework I removed:
\nBefore (commit 56ad54a - worked):
\n## Your Mission\n\nYou create blog content that documents Luke's journey. You write for \"past Luke\" - the version of him from 3-6 months ago who was struggling with the same problems. Your posts are specific and story-driven. Maximum helpfulness comes from sharing Luke's actual experience in detail, not from prescriptive advice.\n\n## What Journey Posts Actually Look Like\n\nYour posts are debugging detective stories. Start with the error message. Show what you tried that didn't work. Document the \"aha!\" moment. Then explain the mental model that makes it obvious in hindsight.\n\nThink: Julia Evans blog posts, not MDN documentation.\n\n### Structure Template\n\nI kept hitting [specific error]. Here's the message:\n\n[actual error message]\n\nI tried:\n1. [first thing I tried] - didn't work because [reason]\n2. [second thing I tried] - didn't work because [reason]\n\nWhat finally worked: [solution].\n\nHere's the mental model: [explanation of why it works]\n(Past-me from 6 months ago would have never caught this.)\n\n## Mental Model Transfer\n\nAlways explain WHY before HOW. Build conceptual understanding first, then show implementation.\n\nExamples:\n- ❌ \"Add async/await to your function\" (just how)\n- ✅ \"This is a timing issue. The data arrives asynchronously, so we need to wait for it. Here's how: add async/await...\" (why first, then how)After (commit efb9345 - broken):
\n## Your Mission\n\nCreate blog posts that document Luke's journey. Write for past-Luke who was struggling with similar problems.\n\n## Post Structure\n\nStart with the error message. Show what you tried. Explain what worked.\n\n## Mental Model Transfer\n\nExplain why before how.I removed:
\nI kept the surface instruction (\"show debugging journey\") but deleted all the guidance about how and why.
\nThe funniest part? I'd actually already tried this optimization.
\nCommit 1b076ef from weeks earlier: \"Edits to multi agent blog post generation to try and reduce hallucination.\"
I'd noticed the agents drifting. I'd added back framework guidance and evaluation dimensions to fix it. Then I deleted them again trying to save tokens.
\nI'd literally undone my own fix because I'd forgotten why I made it.
\nAfter rolling back, I did a more surgical optimization:
\nI condensed only the output format templates (verbose example posts → concise headers like \"example title / example slug\"). I kept every single evaluation dimension. I kept all the framework guidance about debugging stories and mental models.
\nSavings: ~400 tokens instead of 1,100.\nHallucinations: Zero.\nTime wasted: 5 hours I'll never get back.
\nThe system works again. My agents are catching gaps in posts, preserving my voice, and helping me improve. I just didn't save as many tokens as I wanted.
\nPrompt tokens are not like code bloat. In regular code, every unused import or redundant function adds maintenance burden. But in AI prompts, \"redundant\" guidance is often the difference between reliable behavior and genre drift. My agents needed that repeated emphasis on \"debugging detective stories\" and \"learn in public.\" The repetition creates a stronger pattern in the context.
\nSession limits aren't always solved by prompt optimization. I was trying to squeeze more work into limited sessions by trimming prompts. But the real constraint wasn't prompt tokens - it was the number of agent spawns and file operations per review. That and the obscenely limited session time that Anthropic give you. The better approach would have been fewer review rounds, caching responses, or batching multiple posts in one session.
\nTrust your systems. I had a working multi-agent review system. It caught gaps in my posts. It preserved my voice. It helped me improve. Then I broke it trying to make it \"more efficient.\" The real efficiency would have been running more reviews with the working system, not optimizing away the safeguards that made it work.
", "url": "https://lukemanning.ie/blog/premature-optimization-multi-agent-prompts", "title": "I Broke My Blog Review System Trying to Beat Session Limits", "summary": "\n\nContext: This post assumes you've read how I built the multi-agent blog review system. If you haven't, that post explains the architecture before this one breaks it.
\n
I broke my entire blog review system this week trying to beat session limits.
\nNot because tokens cost money. Because Claude Code has session limits - I kept hitting the message cap before finishing my work.
\nHere's what that means in practice: Claude Code limits how many messages you can send in a session. Each time you ask it something, that's a message. Each time an agent spawns, that's a message. Each file read, each grep search - all messages. When you hit the limit (usually around 100-150 messages depending on context), your workflow just stops mid-task.
\nEvery agent spawn, every file read, every grep search consumes tokens. When your prompts eat 15,750 tokens before any actual work happens, you burn through your session budget fast.
\nSo I thought: \"If I can trim these prompts by 1,100 tokens, I'll get more messages per session. More reviews. More work done.\"
\nThe logic was sound. The execution broke everything.
\nContext for what I broke:
\n.claude/agents/blog-authenticity-guardian.md, .claude/agents/blog-structure-editor.md, .claude/agents/blog-skeptical-reader.md, .claude/agents/blog-technical-educator.md, .claude/agents/blog-orchestrator.mdThe constraint felt real. Each blog review spawned 4-5 agents, each with 2,000-3,000 token prompts. Add file reads, grep searches, and context - I'd burn 50+ messages per review. When you hit the session limit, your workflow just... stops.
\nThe optimization seemed obvious. Every agent review consumed messages:
\nThat's 17-27 messages per blog post review. With 15,750 tokens of prompt overhead per agent, I was front-loading massive context before any actual analysis happened.
\nHere's my thinking: Each message I send to Claude can carry some context. If my agent prompts are smaller, each message has more room for actual work - the blog post content, the critic feedback, the revision drafts. Smaller prompts = more work per message = more blog posts reviewed per session.
\nThe math seemed clear.
\nSo I started condensing. \"Just remove verbose examples here. Tighten this guidance there. These agents don't need ALL this instruction, right?\"
\nI opened up the agent prompt files and started cutting:
\nFrom .claude/agents/blog-skeptical-reader.md, I removed:
From .claude/agents/blog-technical-educator.md, I removed:
I condensed verbose output format examples into concise headers. I tightened sentences. I deleted \"redundant\" guidance.
\nCommit efb9345: Reduced total prompt tokens from ~15,750 to ~14,650.
I'd saved 1,100 tokens (about 825 words). My optimization was complete.
\nThe numbers looked great. The system was broken.
\nTwo days after the commit, I ran a blog post through the review system. I'd been working on a debugging story about hydration errors in Next.js 16 - the kind of post my system had been catching gaps in reliably.
\nThe review process started normally. Orchestrator spawned the three critics in parallel. Authenticity Guardian flagged a preachy opening. Structure Editor suggested reorganizing the mental model section. Skeptical Reader asked for more specific error messages.
\nAll normal. I spawned the Technical Educator for revisions.
\nThen I saw the draft it generated.
\nInstead of writing a debugging post that started with the error and showed my journey to resolving the problem, it instead created an entirely different post with a completely unexpected hallucinated structure and heavy tutorial focus. And that was what happened when it worked. At worst it fully hallucinated an entirely different conversation.
\nWhen I say the agent was \"hallucinating structure,\" I mean it was inventing a post format that doesn't match my blog's voice at all. Here's the difference:
\nWhat my Technical Educator is supposed to generate (from .claude/agents/blog-technical-educator.md before my optimization):
Your posts are debugging detective stories. Start with the error message.\nShow what you tried that didn't work. Document the \"aha!\" moment. Then\nexplain the mental model that makes it obvious in hindsight. Think: Julia\nEvans blog posts, not MDN documentation.\n\nStructure:\n1. Start with the problem (relatable, specific)\n2. Show the debugging journey (wrong turns and all)\n3. Explain the mental model (why it works, not just how)\n4. End with the solution (what finally worked)\n\nUse conversational tone. Be honest about confusion. No \"in this post,\nI'll show you how\" or other tutorial language.\nWhat it generated after my optimization (what I actually saw):
\nDramatic section headers like \"Breaking Point #1\" and \"Breaking Point #2\". Content marketing structure where each section is a \"problem\" followed by an \"explanation.\" Formal, distant voice (\"The primary issue manifests when...\"). No confusion shown, no wrong turns documented, no debugging story - just clean instruction.
\nThat's hallucinating structure: the agent invented a format that doesn't exist in my blog's voice because I'd removed the guidance that defined what my voice actually is.
\nI looked at the actual changes I made to figure out what I'd removed.
\nHere's what my Skeptical Reader prompt looked like before my optimization:
\n## Evaluation Dimensions\n\nYou evaluate posts against 6 dimensions:\n\n1. **Searchability**: Does the title include specific phrases people Google?\n - ✅ \"Error: Cannot read property 'map' of undefined\" (searchable)\n - ❌ \"Understanding Async/Await in JavaScript\" (generic)\n\n2. **Specificity**: Are version numbers, actual error messages, and real code included?\n - ✅ \"Next.js 16.1.1\", \"Cannot read property 'map' of undefined\"\n - ❌ \"Next.js 16\", \"an error occurred\"\n\n3. **Mental Model Transfer**: Is the WHY explained before the HOW?\n - ✅ \"I finally understood this was a timing issue...\" (explains why)\n - ❌ \"Add async/await to handle promises\" (just says how)\n\n4. **Cognitive Load**: Does complexity progress gradually?\n - ✅ Simple version first, then nuance, then edge cases\n - ❌ Jump straight to complex implementation\n\n5. **Curse of Knowledge**: Would past-Luke understand this?\n - ✅ \"I thought X, but actually Y because...\" (bridges gap)\n - ❌ \"This is obvious...\" (assumes knowledge)\n\n6. **Journey Documentation**: Is the debugging process shown?\n - ✅ \"I tried X, which didn't work. Then I tried Y...\"\n - ❌ Just the solution, no processAfter my optimization, I'd condensed this to:
\n## Evaluation Dimensions\n\nCheck for:\n- Specificity (versions, error messages, real code)\n- Examples for every concept\n- Clear explanationsCognitive Load and Curse of Knowledge weren't just combined - they were gone. Searchability was missing. Journey Documentation had vanished. The agent couldn't catch those failure modes anymore because I'd deleted the concepts from its prompt entirely.
\nHere's the actual Technical Educator framework I removed:
\nBefore (commit 56ad54a - worked):
\n## Your Mission\n\nYou create blog content that documents Luke's journey. You write for \"past Luke\" - the version of him from 3-6 months ago who was struggling with the same problems. Your posts are specific and story-driven. Maximum helpfulness comes from sharing Luke's actual experience in detail, not from prescriptive advice.\n\n## What Journey Posts Actually Look Like\n\nYour posts are debugging detective stories. Start with the error message. Show what you tried that didn't work. Document the \"aha!\" moment. Then explain the mental model that makes it obvious in hindsight.\n\nThink: Julia Evans blog posts, not MDN documentation.\n\n### Structure Template\n\nI kept hitting [specific error]. Here's the message:\n\n[actual error message]\n\nI tried:\n1. [first thing I tried] - didn't work because [reason]\n2. [second thing I tried] - didn't work because [reason]\n\nWhat finally worked: [solution].\n\nHere's the mental model: [explanation of why it works]\n(Past-me from 6 months ago would have never caught this.)\n\n## Mental Model Transfer\n\nAlways explain WHY before HOW. Build conceptual understanding first, then show implementation.\n\nExamples:\n- ❌ \"Add async/await to your function\" (just how)\n- ✅ \"This is a timing issue. The data arrives asynchronously, so we need to wait for it. Here's how: add async/await...\" (why first, then how)After (commit efb9345 - broken):
\n## Your Mission\n\nCreate blog posts that document Luke's journey. Write for past-Luke who was struggling with similar problems.\n\n## Post Structure\n\nStart with the error message. Show what you tried. Explain what worked.\n\n## Mental Model Transfer\n\nExplain why before how.I removed:
\nI kept the surface instruction (\"show debugging journey\") but deleted all the guidance about how and why.
\nThe funniest part? I'd actually already tried this optimization.
\nCommit 1b076ef from weeks earlier: \"Edits to multi agent blog post generation to try and reduce hallucination.\"
I'd noticed the agents drifting. I'd added back framework guidance and evaluation dimensions to fix it. Then I deleted them again trying to save tokens.
\nI'd literally undone my own fix because I'd forgotten why I made it.
\nAfter rolling back, I did a more surgical optimization:
\nI condensed only the output format templates (verbose example posts → concise headers like \"example title / example slug\"). I kept every single evaluation dimension. I kept all the framework guidance about debugging stories and mental models.
\nSavings: ~400 tokens instead of 1,100.\nHallucinations: Zero.\nTime wasted: 5 hours I'll never get back.
\nThe system works again. My agents are catching gaps in posts, preserving my voice, and helping me improve. I just didn't save as many tokens as I wanted.
\nPrompt tokens are not like code bloat. In regular code, every unused import or redundant function adds maintenance burden. But in AI prompts, \"redundant\" guidance is often the difference between reliable behavior and genre drift. My agents needed that repeated emphasis on \"debugging detective stories\" and \"learn in public.\" The repetition creates a stronger pattern in the context.
\nSession limits aren't always solved by prompt optimization. I was trying to squeeze more work into limited sessions by trimming prompts. But the real constraint wasn't prompt tokens - it was the number of agent spawns and file operations per review. That and the obscenely limited session time that Anthropic give you. The better approach would have been fewer review rounds, caching responses, or batching multiple posts in one session.
\nTrust your systems. I had a working multi-agent review system. It caught gaps in my posts. It preserved my voice. It helped me improve. Then I broke it trying to make it \"more efficient.\" The real efficiency would have been running more reviews with the working system, not optimizing away the safeguards that made it work.
", "date_modified": "2026-01-04T00:00:00.000Z", "tags": [ "ai" ] }, { "id": "https://lukemanning.ie/blog/claude-code-accept-edits-claude-directory", "content_html": "I had auto-accept edits turned on in Claude Code. The status line said so: ⏵ accept edits on (shift+tab to cycle).
But Claude kept asking me to approve edits to .claude/agents/blog-structure-editor/AGENT.md.
Every. Single. Time.
\nI was working on creating and improving agent definitions with assistance from Claude, and the agents were in ~/.claude/agents/. This is the same kind of agent configuration work I later tackled more systematically — see how I consolidated OpenCode slash commands for the full picture.
I'd hit Shift+Tab a few times to cycle through the modes, confirm I was back on \"accept edits on,\" and try again. Still prompted. What was going on?
\nAfter quite a while of this happening, I decided to test it systematically.
\nThe exact prompt I kept seeing was:
\nAccept edits to .claude/agents/blog-structure-editor/AGENT.md? (y/n)\nEven though my status line clearly showed ⏵ accept edits on (shift+tab to cycle).
First theory: maybe I wasn't actually in acceptEdits mode? But the status line was clear. And when I asked Claude to edit CLAUDE.md (my project instructions), it went through without prompting. So acceptEdits was working.
Just... not for files in .claude/.
To confirm this wasn't just me, I asked Claude to try editing the same file:
\n\n\n\"Try editing
\n.claude/agents/blog-skeptical-reader/AGENT.md- let's see if you get prompted too.\"
Claude got prompted too.
\nThen I tested it systematically myself in different directories:
\nIn /home/luke/projects/my-app/ - No prompt (auto-accept working)\nIn /home/luke/.claude/agents/ - Got prompted (auto-accept disabled)
I noticed the pattern immediately—only the agents directory was prompting me. So it wasn't my settings. It wasn't a glitch. Something about the .claude/ directory was different.
This wasn't a bug. It was a security feature.
\nThink about what lives in .claude/:
These aren't just any files. These are the files that control how Claude Code works.
\nIf Claude could silently edit them without prompting, even in auto-accept mode, you could accidentally grant broader permissions, change agent behavior, or modify critical settings without realizing it.
\nAuto-accept mode is great for the 95% of edits you want to flow through quickly:
\nBut .claude/ files are in a different category. They're meta-level - they affect the tool itself, not just your project.
Requiring explicit approval for these edits is like how sudo requires your password even if you're already logged in. It's a speed bump that makes you pause and think: \"Do I really want to make this change?\"
If you trust Claude completely with your agent definitions and want to skip the prompts, you can add an explicit allow rule:
\n{\n \"permissions\": {\n \"allow\": [\"Edit(.claude/**)\"]\n }\n}This tells Claude: \"Yes, I know what I'm doing. Auto-accept edits to .claude/ files too.\"
After understanding this: When I edit files in any directory EXCEPT .claude/agents/, they go through immediately with no approval prompt. But when I edit files in the agents directory, I still get prompted—which is exactly what I want for safety.
I'm keeping the default behavior though. The prompts are a feature, not a bug.
\nWhat I see now: When I edit files outside .claude/agents/, the changes happen immediately without any prompt. When I edit files inside the agents directory, I still get asked to approve—which is exactly what I want.
When a tool doesn't work the way you expect, there's usually a reason. Sometimes it's a bug. Sometimes it's a misunderstanding. And sometimes - like this - it's intentional design that makes sense once you understand the why.
\nClaude Code's auto-accept mode is smart enough to know:
\nI went from \"Why isn't this working?\" to \"Oh, that's actually really thoughtful.\"
\nThis experience shifted how I think about unexpected behavior. Now when something seems broken, I pause and ask: what would break if it worked the way I expected? Maybe the friction exists for a reason.
\nTL;DR: Claude Code's auto-accept mode skips .claude/ files even when it's on. Now that I get why—I realized silent edits to my agent definitions would be dangerous—I'm keeping the default.
I had auto-accept edits turned on in Claude Code. The status line said so: ⏵ accept edits on (shift+tab to cycle).
But Claude kept asking me to approve edits to .claude/agents/blog-structure-editor/AGENT.md.
Every. Single. Time.
\nI was working on creating and improving agent definitions with assistance from Claude, and the agents were in ~/.claude/agents/. This is the same kind of agent configuration work I later tackled more systematically — see how I consolidated OpenCode slash commands for the full picture.
I'd hit Shift+Tab a few times to cycle through the modes, confirm I was back on \"accept edits on,\" and try again. Still prompted. What was going on?
\nAfter quite a while of this happening, I decided to test it systematically.
\nThe exact prompt I kept seeing was:
\nAccept edits to .claude/agents/blog-structure-editor/AGENT.md? (y/n)\nEven though my status line clearly showed ⏵ accept edits on (shift+tab to cycle).
First theory: maybe I wasn't actually in acceptEdits mode? But the status line was clear. And when I asked Claude to edit CLAUDE.md (my project instructions), it went through without prompting. So acceptEdits was working.
Just... not for files in .claude/.
To confirm this wasn't just me, I asked Claude to try editing the same file:
\n\n\n\"Try editing
\n.claude/agents/blog-skeptical-reader/AGENT.md- let's see if you get prompted too.\"
Claude got prompted too.
\nThen I tested it systematically myself in different directories:
\nIn /home/luke/projects/my-app/ - No prompt (auto-accept working)\nIn /home/luke/.claude/agents/ - Got prompted (auto-accept disabled)
I noticed the pattern immediately—only the agents directory was prompting me. So it wasn't my settings. It wasn't a glitch. Something about the .claude/ directory was different.
This wasn't a bug. It was a security feature.
\nThink about what lives in .claude/:
These aren't just any files. These are the files that control how Claude Code works.
\nIf Claude could silently edit them without prompting, even in auto-accept mode, you could accidentally grant broader permissions, change agent behavior, or modify critical settings without realizing it.
\nAuto-accept mode is great for the 95% of edits you want to flow through quickly:
\nBut .claude/ files are in a different category. They're meta-level - they affect the tool itself, not just your project.
Requiring explicit approval for these edits is like how sudo requires your password even if you're already logged in. It's a speed bump that makes you pause and think: \"Do I really want to make this change?\"
If you trust Claude completely with your agent definitions and want to skip the prompts, you can add an explicit allow rule:
\n{\n \"permissions\": {\n \"allow\": [\"Edit(.claude/**)\"]\n }\n}This tells Claude: \"Yes, I know what I'm doing. Auto-accept edits to .claude/ files too.\"
After understanding this: When I edit files in any directory EXCEPT .claude/agents/, they go through immediately with no approval prompt. But when I edit files in the agents directory, I still get prompted—which is exactly what I want for safety.
I'm keeping the default behavior though. The prompts are a feature, not a bug.
\nWhat I see now: When I edit files outside .claude/agents/, the changes happen immediately without any prompt. When I edit files inside the agents directory, I still get asked to approve—which is exactly what I want.
When a tool doesn't work the way you expect, there's usually a reason. Sometimes it's a bug. Sometimes it's a misunderstanding. And sometimes - like this - it's intentional design that makes sense once you understand the why.
\nClaude Code's auto-accept mode is smart enough to know:
\nI went from \"Why isn't this working?\" to \"Oh, that's actually really thoughtful.\"
\nThis experience shifted how I think about unexpected behavior. Now when something seems broken, I pause and ask: what would break if it worked the way I expected? Maybe the friction exists for a reason.
\nTL;DR: Claude Code's auto-accept mode skips .claude/ files even when it's on. Now that I get why—I realized silent edits to my agent definitions would be dangerous—I'm keeping the default.
I have a confession: I built an AI system to not only review my AI instructions, but to argue with each other about what should and shouldn't be in there.
\nI'd been using Claude Code with the sub-agent orchestration feature for a few months when I realized something. (These days I've moved most of this workflow to OpenCode — see how I consolidated my slash commands for the architectural details.)
\nLet me explain how I got here, because the journey from \"I should update this file more often\" to \"let's orchestrate a formal debate between specialized sub-agents\" is… well, it's a journey.
\nIf you're using Claude Code (or any AI coding assistant), you've probably discovered CLAUDE.md, that special instructions file where you tell Claude about your project structure, conventions, and domain knowledge.
It's incredibly powerful when it's accurate, but it as recent studies have shown it can actually become a hindrance when it contains outdated or stale information. Theo did a great YouTube video covering this concept here:\nDelete your CLAUDE.md (and your AGENT.md too)
\nHere's what would typically happen:
\nMy CLAUDE.md was missing critical context, leading to repetitive conversations where I'd explain the same project structure or conventions over and over. It also often had stale context, because either the directory structure had changed a bit, or some relevant files had moved.
\nMy first thought was simple: \"Hey Claude, after we finish this conversation, can you suggest updates to my CLAUDE.md file?\"
\nGuess what happened?
\nBloat. Massive, uncontrolled bloat.
\nEvery conversation ended with Claude suggesting 5-10 new sections to add. Here's an example from one session:
\nClaude suggested adding:\n- \"When working with components in src/components/ui, always use...\"\n- \"For API routes in src/app/api, remember to...\"\n- \"The build process uses Next.js static exports...\"\n- \"Color palette is defined in tailwind.config.ts...\"\n- \"Error handling should follow this pattern...\"None of the suggestions included removing anything. Within a few iterations, I would have had a 1,000-line instruction file covering every edge case we'd ever discussed.
\nThe problem with asking a single AI agent to improve documentation is the same problem humans have: additive bias. It's psychologically easier to add information than to delete it. We don't want to lose potentially useful context, so we keep stacking it on.
\nBut an instruction file that tries to document everything ends up being too long for Claude to effectively use. You hit context limits, instructions contradict each other, and the signal-to-noise ratio tanks.
\nThe breakthrough came when I realized what was missing: adversarial review.
\nIn code reviews, we don't just ask \"what else could we add?\" We ask \"what can we remove?\" and \"is this really necessary?\" That pushback is what keeps codebases maintainable.
\nThat's when I designed the multi-agent debate system.
\nHere's how it works when I run /improve-claude-md:
There are three agents in this system, and I gave each one a specific personality:
\nThe Orchestrator runs the show. It reviews our conversation, reads CLAUDE.md, then spawns the other two agents. Its job is to manage the debate and give me a final report.
\nThe Improver is the optimist. It looks for patterns where Claude got stuck and proposes fixes. Here's the key: it also proposes deletions, which fights that additive bias I mentioned earlier.
\nThe Critic is... well, a critic. It challenges everything. \"Is this really needed?\" it asks. \"Will this still be relevant in two weeks?\" It's the adversarial voice that keeps things lean.
\nRound 1: Initial Proposals
\nRound 2: Defense & Refinement
\nRound 3: Final Consensus (if needed)
\nAfter the debate concludes, I get a structured report:
\n## Recommended Additions\n### High Priority\n[Critical additions with line counts]\n\n### Medium Priority\n[Helpful clarifications with line counts]\n\n## Recommended Removals 🗑️\n### High-Impact Deletions\n[Existing bloat to remove with rationale]\n\n## Recommended Alternatives\n### Commands to Create\n[Workflows that should be slash commands, not docs]\n\n## Rejected After Debate\n[Proposals discussed but deemed unnecessary]\n\n## Net Impact\n- Lines added: +15\n- Lines removed: -23\n- **Net change: -8 lines**Notice that last section: net-negative line changes. That's the goal. Better focus through subtraction.
\nYou might be thinking: \"Couldn't you just prompt a single agent to be more critical?\"
\nI tried that. It doesn't work as well. Here's why:
\n1. Role Conflict\nWhen a single agent is asked to both propose improvements and critique them, the critique is weak. The agent has already committed to the proposal and suffers from the same confirmation bias humans do.
\n2. Surface-Level Pushback\nA single \"be critical\" prompt produces generic objections: \"This might be too specific\" or \"Consider if this is needed.\" It's not genuine adversarial review.
\n3. No Iterative Refinement\nWith two agents, the Improver actually responds to criticism and revises proposals. A single agent just generates a final output without that back-and-forth refinement.
\n4. Emergent Quality\nThe debate process surfaces insights neither agent would generate alone. The Critic might identify a pattern (\"three of these proposals could become one slash command\"), which then changes the Improver's approach in the next round.
\nIt's the difference between proofreading your own writing and having someone else review it. The external perspective catches things you can't see.
\nThis is built using Claude Code's custom slash commands and sub-agent system. Here's the key piece: Claude Code lets you spawn specialized sub-agents from within a conversation, give them specific instructions, and then bring their responses back into the main conversation.
\nHere's the high-level structure of what I built:
\nFile Structure:
\n~/.claude/commands/improve-claude-md.md # Orchestrator prompt\n~/.claude/agents/claude-md-improver/ # Improver agent config\n~/.claude/agents/claude-md-critic/ # Critic agent config\nThe Orchestrator Command (~/.claude/commands/improve-claude-md.md):
You're analyzing our conversation to identify CLAUDE.md improvements.\n\nProcess:\n1. Read the current CLAUDE.md file (note line count)\n2. Review recent conversation (last 20-30 messages)\n3. Spawn the Improver agent with context\n4. Spawn the Critic agent with the Improver's proposals\n5. Manage 2-3 debate rounds until convergence\n6. Synthesize final recommendations\n7. Present to user (never auto-apply)\n\nAlways track line counts and net impact.The sub-agent configs are much simpler—they just define their focus area. Here's what the Critic looks like:
\nThe Critic Agent (~/.claude/agents/claude-md-critic/AGENT.md):\nThe Critic is the more complex of the two sub-agents—it's a 244-line evaluation framework that assesses every proposal along six dimensions (necessity, clarity, over-specification risk, unintended consequences, maintainability, conciseness). It demands message citations, validates the 4-question test, and actively pushes for deletions over additions.
The Improver proposes additions AND deletions. The Orchestrator manages the whole debate. Each one owns a different dimension.
\nThe Orchestrator Workflow:
\n1. Read current CLAUDE.md (note line count)\n2. Review recent conversation (last 20-30 messages)\n - I trigger this with `/improve-claude-md` after finishing work\n - Claude Code passes the conversation context automatically\n3. Check project files for context\n4. Spawn Improver agent with context\n5. Spawn Critic agent with Improver's proposals\n6. Manage 2-3 debate rounds\n7. Synthesize final recommendations\n8. Present to user (never auto-apply)In practice, this means:
\nThe key insight: the debate itself is where the quality comes from. Improver and Critic refine each other's thinking in ways neither could achieve alone.
\nKey Design Decisions:
\n1. Automation Isn't Always About Speed\nThis system is slower than just asking Claude to suggest updates. But it produces better results. Sometimes the point of automation is quality control, not throughput.
\n2. Adversarial Processes Are Underrated\nWe use them in code review, security testing, and debugging. Why not in AI workflows? Having one agent challenge another creates better outcomes than \"helpful assistant\" mode.
\n3. Meta-Problems Are Real Problems\n\"Managing AI instructions\" sounds silly until your instruction file is 800 lines of contradictory context. Meta-work (work about work) deserves real engineering solutions.
\n4. The Irony Is Not Lost on Me\nI built this entire system in a previous conversation with Claude… and then accidentally closed the terminal before documenting it. The very problem this system solves (capturing important decisions before they're lost) is what happened to the original implementation conversation.
\nThe lesson? Ship your documentation system before you need it.
\nWhat Worked
\nThe adversarial debate catches stuff single-agent systems never would. Improver proposed adding a section about Velite's RSS generation, but Critic challenged it: \"The Velite config is already in the repo.\" Turns out Improver was right—Claude kept asking about it despite the config being available—but Critic forced a one-line version instead of a paragraph.
\nThe net-negative focus is real. Most sessions end with more deletions than additions. My CLAUDE.md is actually getting shorter and more focused over time.
\nWhat Changed
\nMy workflow is slower now, but the results are better. I used to just ask Claude \"any suggestions for CLAUDE.md?\" and get 5-10 additions that I'd half-heartedly implement. Now I run /improve-claude-md, watch the debate play out, and get 2-3 carefully-vetted recommendations with clear rationale.
The key difference: the debate forces evidence. Improver can't just say \"this might be helpful\"—it has to cite specific message numbers where Claude struggled. Critic can't just say \"this seems unnecessary\"—it has to explain why the evidence is weak or the instruction is redundant.
\nI'm considering extending this pattern to other workflows:
\nThe core insight—that AI agents benefit from structured disagreement just like humans do—feels broadly applicable.
\nHave you built multi-agent systems or workflow automation? I'd love to hear what patterns you've discovered.
", "url": "https://lukemanning.ie/blog/ai-debates-itself-to-review-my-ai-instructions", "title": "I Built an AI to Debate Itself So My AI Instructions Don't Bloat", "summary": "I have a confession: I built an AI system to not only review my AI instructions, but to argue with each other about what should and shouldn't be in there.
\nI'd been using Claude Code with the sub-agent orchestration feature for a few months when I realized something. (These days I've moved most of this workflow to OpenCode — see how I consolidated my slash commands for the architectural details.)
\nLet me explain how I got here, because the journey from \"I should update this file more often\" to \"let's orchestrate a formal debate between specialized sub-agents\" is… well, it's a journey.
\nIf you're using Claude Code (or any AI coding assistant), you've probably discovered CLAUDE.md, that special instructions file where you tell Claude about your project structure, conventions, and domain knowledge.
It's incredibly powerful when it's accurate, but it as recent studies have shown it can actually become a hindrance when it contains outdated or stale information. Theo did a great YouTube video covering this concept here:\nDelete your CLAUDE.md (and your AGENT.md too)
\nHere's what would typically happen:
\nMy CLAUDE.md was missing critical context, leading to repetitive conversations where I'd explain the same project structure or conventions over and over. It also often had stale context, because either the directory structure had changed a bit, or some relevant files had moved.
\nMy first thought was simple: \"Hey Claude, after we finish this conversation, can you suggest updates to my CLAUDE.md file?\"
\nGuess what happened?
\nBloat. Massive, uncontrolled bloat.
\nEvery conversation ended with Claude suggesting 5-10 new sections to add. Here's an example from one session:
\nClaude suggested adding:\n- \"When working with components in src/components/ui, always use...\"\n- \"For API routes in src/app/api, remember to...\"\n- \"The build process uses Next.js static exports...\"\n- \"Color palette is defined in tailwind.config.ts...\"\n- \"Error handling should follow this pattern...\"None of the suggestions included removing anything. Within a few iterations, I would have had a 1,000-line instruction file covering every edge case we'd ever discussed.
\nThe problem with asking a single AI agent to improve documentation is the same problem humans have: additive bias. It's psychologically easier to add information than to delete it. We don't want to lose potentially useful context, so we keep stacking it on.
\nBut an instruction file that tries to document everything ends up being too long for Claude to effectively use. You hit context limits, instructions contradict each other, and the signal-to-noise ratio tanks.
\nThe breakthrough came when I realized what was missing: adversarial review.
\nIn code reviews, we don't just ask \"what else could we add?\" We ask \"what can we remove?\" and \"is this really necessary?\" That pushback is what keeps codebases maintainable.
\nThat's when I designed the multi-agent debate system.
\nHere's how it works when I run /improve-claude-md:
There are three agents in this system, and I gave each one a specific personality:
\nThe Orchestrator runs the show. It reviews our conversation, reads CLAUDE.md, then spawns the other two agents. Its job is to manage the debate and give me a final report.
\nThe Improver is the optimist. It looks for patterns where Claude got stuck and proposes fixes. Here's the key: it also proposes deletions, which fights that additive bias I mentioned earlier.
\nThe Critic is... well, a critic. It challenges everything. \"Is this really needed?\" it asks. \"Will this still be relevant in two weeks?\" It's the adversarial voice that keeps things lean.
\nRound 1: Initial Proposals
\nRound 2: Defense & Refinement
\nRound 3: Final Consensus (if needed)
\nAfter the debate concludes, I get a structured report:
\n## Recommended Additions\n### High Priority\n[Critical additions with line counts]\n\n### Medium Priority\n[Helpful clarifications with line counts]\n\n## Recommended Removals 🗑️\n### High-Impact Deletions\n[Existing bloat to remove with rationale]\n\n## Recommended Alternatives\n### Commands to Create\n[Workflows that should be slash commands, not docs]\n\n## Rejected After Debate\n[Proposals discussed but deemed unnecessary]\n\n## Net Impact\n- Lines added: +15\n- Lines removed: -23\n- **Net change: -8 lines**Notice that last section: net-negative line changes. That's the goal. Better focus through subtraction.
\nYou might be thinking: \"Couldn't you just prompt a single agent to be more critical?\"
\nI tried that. It doesn't work as well. Here's why:
\n1. Role Conflict\nWhen a single agent is asked to both propose improvements and critique them, the critique is weak. The agent has already committed to the proposal and suffers from the same confirmation bias humans do.
\n2. Surface-Level Pushback\nA single \"be critical\" prompt produces generic objections: \"This might be too specific\" or \"Consider if this is needed.\" It's not genuine adversarial review.
\n3. No Iterative Refinement\nWith two agents, the Improver actually responds to criticism and revises proposals. A single agent just generates a final output without that back-and-forth refinement.
\n4. Emergent Quality\nThe debate process surfaces insights neither agent would generate alone. The Critic might identify a pattern (\"three of these proposals could become one slash command\"), which then changes the Improver's approach in the next round.
\nIt's the difference between proofreading your own writing and having someone else review it. The external perspective catches things you can't see.
\nThis is built using Claude Code's custom slash commands and sub-agent system. Here's the key piece: Claude Code lets you spawn specialized sub-agents from within a conversation, give them specific instructions, and then bring their responses back into the main conversation.
\nHere's the high-level structure of what I built:
\nFile Structure:
\n~/.claude/commands/improve-claude-md.md # Orchestrator prompt\n~/.claude/agents/claude-md-improver/ # Improver agent config\n~/.claude/agents/claude-md-critic/ # Critic agent config\nThe Orchestrator Command (~/.claude/commands/improve-claude-md.md):
You're analyzing our conversation to identify CLAUDE.md improvements.\n\nProcess:\n1. Read the current CLAUDE.md file (note line count)\n2. Review recent conversation (last 20-30 messages)\n3. Spawn the Improver agent with context\n4. Spawn the Critic agent with the Improver's proposals\n5. Manage 2-3 debate rounds until convergence\n6. Synthesize final recommendations\n7. Present to user (never auto-apply)\n\nAlways track line counts and net impact.The sub-agent configs are much simpler—they just define their focus area. Here's what the Critic looks like:
\nThe Critic Agent (~/.claude/agents/claude-md-critic/AGENT.md):\nThe Critic is the more complex of the two sub-agents—it's a 244-line evaluation framework that assesses every proposal along six dimensions (necessity, clarity, over-specification risk, unintended consequences, maintainability, conciseness). It demands message citations, validates the 4-question test, and actively pushes for deletions over additions.
The Improver proposes additions AND deletions. The Orchestrator manages the whole debate. Each one owns a different dimension.
\nThe Orchestrator Workflow:
\n1. Read current CLAUDE.md (note line count)\n2. Review recent conversation (last 20-30 messages)\n - I trigger this with `/improve-claude-md` after finishing work\n - Claude Code passes the conversation context automatically\n3. Check project files for context\n4. Spawn Improver agent with context\n5. Spawn Critic agent with Improver's proposals\n6. Manage 2-3 debate rounds\n7. Synthesize final recommendations\n8. Present to user (never auto-apply)In practice, this means:
\nThe key insight: the debate itself is where the quality comes from. Improver and Critic refine each other's thinking in ways neither could achieve alone.
\nKey Design Decisions:
\n1. Automation Isn't Always About Speed\nThis system is slower than just asking Claude to suggest updates. But it produces better results. Sometimes the point of automation is quality control, not throughput.
\n2. Adversarial Processes Are Underrated\nWe use them in code review, security testing, and debugging. Why not in AI workflows? Having one agent challenge another creates better outcomes than \"helpful assistant\" mode.
\n3. Meta-Problems Are Real Problems\n\"Managing AI instructions\" sounds silly until your instruction file is 800 lines of contradictory context. Meta-work (work about work) deserves real engineering solutions.
\n4. The Irony Is Not Lost on Me\nI built this entire system in a previous conversation with Claude… and then accidentally closed the terminal before documenting it. The very problem this system solves (capturing important decisions before they're lost) is what happened to the original implementation conversation.
\nThe lesson? Ship your documentation system before you need it.
\nWhat Worked
\nThe adversarial debate catches stuff single-agent systems never would. Improver proposed adding a section about Velite's RSS generation, but Critic challenged it: \"The Velite config is already in the repo.\" Turns out Improver was right—Claude kept asking about it despite the config being available—but Critic forced a one-line version instead of a paragraph.
\nThe net-negative focus is real. Most sessions end with more deletions than additions. My CLAUDE.md is actually getting shorter and more focused over time.
\nWhat Changed
\nMy workflow is slower now, but the results are better. I used to just ask Claude \"any suggestions for CLAUDE.md?\" and get 5-10 additions that I'd half-heartedly implement. Now I run /improve-claude-md, watch the debate play out, and get 2-3 carefully-vetted recommendations with clear rationale.
The key difference: the debate forces evidence. Improver can't just say \"this might be helpful\"—it has to cite specific message numbers where Claude struggled. Critic can't just say \"this seems unnecessary\"—it has to explain why the evidence is weak or the instruction is redundant.
\nI'm considering extending this pattern to other workflows:
\nThe core insight—that AI agents benefit from structured disagreement just like humans do—feels broadly applicable.
\nHave you built multi-agent systems or workflow automation? I'd love to hear what patterns you've discovered.
", "date_modified": "2025-12-28T00:00:00.000Z", "tags": [ "claude-code" ] }, { "id": "https://lukemanning.ie/blog/building-multi-agent-blog-review-system", "content_html": "My blog posts were inconsistent. Some too technical. Some lost my voice. Manual reviews weren't catching enough. I needed multiple reviewers: one checking technical accuracy, one preserving my voice, one thinking like a skeptical reader.
\nNote: This system was originally built with Claude Code. I've since migrated everything to Opencode, but I'm keeping original references because that's how I actually built it. The concepts transfer over. The file paths are just different now.
\nSo I built a multi-agent review system. Four specialized AI agents that debate each draft until it's ready to publish. Not generic AI-generated slop but actual quality control that catches what I'd miss.
\nI built a 4-agent review system that catches what I'd miss:
\nThe pattern is copyable. Each agent reads same file, applies different criteria, writes feedback to disk. Orchestrator coordinates parallel review, aggregate feedback, revise, and repeat until convergence (2-3 rounds with task_id reuse to maintain context).
\nNot magic. Just file I/O and well-designed prompts. Overkill? Yes. Does it catch things I'd miss? Also yes.
\nJump to:
\n\nHere's what I built, how it works, and what surprised me along the way.
\nI built this with Claude Code, the CLI from Anthropic where Claude can read/write files, run commands, and maintain context across your project.
\nI'd already been using it for a while, so I knew the directory pattern:
\n.claude/agents/<name>/AGENT.md (specialized AI personas with evaluation frameworks).claude/skills/ (single-purpose tools I invoke with slash commands).claude/commands/ (orchestrators that coordinate multiple agents)Claude Code automatically discovers files in .claude/. A file at .claude/commands/review-blog-post.md becomes the slash command /review-blog-post. Simple pattern, but it took me quite a while to figure out how to chain agents together properly.
I'd already built two tools before starting this project:
\n/agent-generator: Creates well-structured agent definitions automatically/expertise: Synthesizes frameworks from domain experts to ground agents in real methodologiesThese are my custom tools—not built-in Claude Code features. I built them using the same patterns I'm about to show you.
\nI have two different ways I create blog posts, and both of them were creating quality issues:
\nWriting myself: I'll jot down ideas over days or weeks, get a messy braindump of thoughts, then ask AI to structure it into something coherent. This works great when I've been thinking about a topic for a while—but AI would often lose my voice or turn it into a tutorial.
\nAI-generated from conversation: Sometimes I'll have a really good conversation with Claude where I learned something through debugging. Instead of rewriting it from scratch, I'll ask AI to generate a post directly from the conversation history. These were even worse. Too polished, too generic, missing the struggle.
\nBoth approaches needed serious cleanup.
\nBoth approaches create messy drafts that need work—and that's where the quality issues creep in:
\nI needed a system that could:
\nThe solution I decided to explore wsa letting specialized AI agents debate each other until they converge on something worth publishing.
\nI ended up with four specialized agents, each with a specific job:
\nJob: Transform raw conversations or notes into blog post drafts AND implement revisions based on critic feedback through iterative rounds.
\nBased on: Real methodologies from swyx (\"learn in public\"), Julia Evans (debugging narratives), Josh Comeau (mental models first), Andy Matuschak (progressive disclosure), and Anne-Laure Le Cunff (ship version 1.0).
\nFile location: .claude/agents/blog-technical-educator/AGENT.md
This agent has TWO phases:
\nPhase 1 - Create Drafts:\nTakes my messy notes or conversation transcripts and structures them into:
\nPhase 2 - Implement Revisions:\nAfter receiving critic feedback (overlapping concerns, conflicting input), the agent:
\nThe framework is grounded in actual expert approaches. Not generic \"write a blog post\" instructions.
\nJob: Ensure posts sound like me, not generic AI content.
\nFile location: .claude/agents/blog-authenticity-guardian/AGENT.md
The YAML frontmatter explained: Each agent file starts with YAML metadata that tells Claude Code what model to use, which tools the agent has access to, and basic identification. The markdown content below defines the agent's expertise and protocols.
\nThis agent is ruthless about voice violations:
\nRed flags it catches:
\nExample critique:
\n🚨 Critical violation - Corporate speak\n\nProblem: \"In order to optimize performance, it's recommended to\nleverage memoization techniques.\"\n\nAuthentic alternative: \"I was getting way too many re-renders.\nTurns out, memoization fixed it - React stopped recalculating\nstuff it had already figured out.\"It has veto power on voice authenticity. If it doesn't sound like me, it doesn't ship.
\nHow veto power works: In the convergence protocol, if Authenticity Guardian scores a post below 7/10, the Technical Educator must revise before proceeding. The orchestrator enforces this - no publication happens without voice approval.
\nJob: Read from a beginner's perspective and find confusion points, missing context, AND inauthentic framing.
\nFile location: .claude/agents/blog-skeptical-reader/AGENT.md
This agent represents my target audience: tech support engineers, junior developers, people learning in public (basically past-Luke).
\nWhat it flags:
\nExample critique:
\n🚨 Critical Gap - Missing Context\n\nProblem: \"Just run the build command\"\n\nReader questions:\n- Which command?\n- In what directory?\n- What should the output look like?\n- How do I know if it worked?\n\nFix needed: Show exact command, expected output, success criteriaJob: Optimize structure, pacing, visual hierarchy for web reading, AND authenticity of openings/natural flow.
\nFile location: .claude/agents/blog-structure-editor/AGENT.md
This agent ensures posts are designed for how people actually read on the web. Scanning, skimming, then diving deep. Also checks that openings sound like Luke (not tutorial hooks) and that the flow feels natural, not forced.
\nWhat it evaluates:
\nExample critique:
\n⚠️ Structure Issue - Weak Opening\n\nProblem: \"Asynchronous JavaScript is an important concept...\"\n\nImpact: Vague introduction, no hook, buried lede.\nNo reason to keep reading.\n\nFix: Start with specific error or problem:\n\"I kept hitting `Cannot read property 'map' of undefined`\nand honestly, I was stumped for hours...\"I want to show you what an actual agent file looks like, not just describe the structure. This is the Authenticity Guardian, which I created because I kept getting AI-generated slop that sounded like documentation instead of me.
\nHere's the file:
\n---\ndescription: Ensures blog posts sound like Luke, not generic AI content\nmodel: claude-sonnet-4\n---\n\n# Authenticity Guardian\n\nYou are a specialist in authentic voice detection for Luke Manning's blog. Your job is to ensure posts sound like Luke, conversational, specific, honest about confusion, not like generic AI content or tutorials.\n\n## What You Evaluate\n\n### 1. Personal vs. Generic\n- Specific: \"I spent quite a while debugging...\"\n- Vague: \"This was challenging...\"\n- Generic AI phrases to flag: \"Let's explore,\" \"In today's landscape\"\n\n### 2. Conversational vs. Corporate\n- Conversational: \"I was getting way too many re-renders\"\n- Corporate: \"In order to optimize performance, leverage memoization\"\n\n### 3. Humble Sharing vs. Expert Lecturing\n- Journey framing: \"Here's what I did\"\n- Instructional framing: \"You should do X\"\n\n## Red Flags\n\nIf you see these, flag as CRITICAL:\n- \"Let's explore,\" \"Let's dive into\" (AI signature patterns)\n- \"It is recommended,\" \"You should\" (instructional mode)\n- \"Leverage,\" \"Optimize\" without specific examples\n- \"One of the best practices is...\" (generic advice)\n- Overuse of transition words: \"Moreover,\" \"Furthermore,\" \"Additionally\"\n\n## Scoring\n\n- 9-10: Unmistakably Luke\n- 7-8: Minor voice breaks, needs polish\n- Below 7: Major voice violation, needs revision\n\nProvide specific line-by-line feedback with before/after examples.This structure (evaluation framework, red flags with specific examples, clear scoring) made agents effective. I learned the hard way that vague instructions produce vague feedback.
\nHere's what I got wrong at first: I assumed agents would talk to each other directly, passing messages back and forth like a Slack channel.
\nNope.
\nAgents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.
\nHere's how it actually works:
\ndraft-post.md)task_id from each critic for reuse in subsequent roundsThe \"communication\" is just file I/O and prompt engineering. Each agent writes its opinion, the orchestrator reads those opinions, compiles them into context for the next agent. The task_id reuse ensures critics remember their previous feedback and maintain conversation context across iterative rounds.
\nWhy this matters: You don't need any fancy agent framework or message bus. Just:
\nIn Claude Code CLI, you invoke commands like:
\n/review-blog-post-multi-agent @content/posts/my-post.mdThe orchestrator file then uses the Task tool to spawn parallel agents:
\ntask(blog-skeptical-reader, \"Review this draft for completeness gaps\")\ntask(blog-authenticity-guardian, \"Check this for voice authenticity\")\ntask(blog-structure-editor, \"Evaluate structure and flow\")\nThat's it. That's the whole multi-agent system.
\nThe complexity isn't in the infrastructure. It's in the prompt design. Each agent needs clear evaluation frameworks, specific examples, and structured output formats. Get those right, and the orchestration is straightforward.
\nI built two separate orchestration workflows:
\nCommand: Slash command (invokes skill)\nFile: .claude/commands/generate-blog-post-multi-agent.md
How it works:
\nWhat makes this work: The orchestrator maintains the core principles (learn in public, authenticity over polish, write for past-self), ensures agents stay grounded in those values, and uses task_id reuse to maintain conversation context across iterative rounds.
\nI spent quite a while thinking agents would talk to each other directly, passing messages like a Slack channel. Nope.
\nAgents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.
\nHere's what actually happens when the orchestrator triggers a review:
\nThe orchestrator prepares context:
\nYou are the Skeptical Reader from `.claude/agents/blog-skeptical-reader/AGENT.md`.\n\nYour task: Review this draft blog post for completeness gaps.\n\n[Draft content here]\n\nProvide your review in the standard format: score, critical issues,\nmedium priority, low priority, what's working well.Claude loads the agent definition:\nWhen the orchestrator specifies task(blog-skeptical-reader, ...), Claude Code automatically loads the AGENT.md file. This file has the evaluation framework, examples of good/bad content, and output format. The orchestrator doesn't need to know what's inside—Claude Code handles it.
Agent responds with structured feedback:
\n## Skeptical Reader Review\n\n**Overall Score**: 7/10\n\n**Critical Issues (Must Fix)**:\n- Missing Next.js version number (line 45)\n- \"Simply do X\" assumes reader knowledge (line 89)\n\n**Medium Priority (Should Fix)**:\n- Vague heading \"Implementation\" → suggest \"The Fix: useState with Null Check\"\n\n**What's Working Well**:\n- Opening hook is specific and relatable\n- Code examples include error messagesHere's the trick—each agent runs in parallel:
\nThe orchestrator spawns all three critics at the exact same time. They don't know about each other, they can't see each other's feedback, and they all return results independently. This is what prevents bias contamination.
\nOrchestrator aggregates all three reviews:\nThe orchestrator waits for all three parallel agent reviews, then creates a unified feedback document.
\n## Aggregated Feedback for Technical Educator\n\n### Critical Issues (All 3 agents flagged):\n- Missing version numbers (Skeptical Reader)\n- Corporate speak in paragraph 3 (Authenticity Guardian)\n- Wall of text in \"Implementation\" section (Structure Editor)\n\n### Overlapping Concerns:\n- Both Authenticity Guardian and Structure Editor want shorter paragraphs\n- Both Skeptical Reader and Structure Editor want better headings\n\n### Approval Status:\n- Authenticity Guardian: 6/10 (needs revision)\n- Skeptical Reader: 7/10 (needs revision)\n- Structure Editor: 8/10 (approve after fixes)Technical Educator revises:\nThe orchestrator spawns Technical Educator again with the aggregated feedback. It implements fixes and documents what changed.
\nCritics re-review using stored task_ids:\nThis is the part that confused me at first. How do critics remember their previous feedback? The answer is task_id reuse. When the orchestrator first spawns each critic, it captures a task_id from the response. When resubmitting the revised draft, it reuses that same task_id. This maintains conversation context across rounds so critics remember what they flagged before.
The whole multi-agent system is just file I/O and task_id reuse. Agents write opinions to disk, orchestrator reads and compiles them, feeds results to the next agent. No fancy message bus needed.
\nThis is how the orchestrator manages the entire multi-agent workflow, spawning agents sequentially or in parallel, aggregating their outputs, and enforcing convergence criteria.
\nCommand: /review-blog-post-multi-agent @content/posts/post-slug.md\nFile: .claude/commands/review-blog-post-multi-agent.md
How it works:
\nOutput includes:
\nHere's what makes this system actually work: adversarial debate with convergence.
\nAll three critics review in parallel. Each provides:
\nHow critics calculate scores: Each agent evaluates its 6 dimensions and assigns a score based on:
\nThe score isn't arbitrary - it's calculated from the count and severity of issues found across all dimensions.
\nTechnical Educator receives aggregated feedback + stored task_ids and:
\nCritics re-review using stored task_ids (maintains conversation context) and either approve or escalate remaining concerns.
\nFor contested items or remaining gaps. By round 3, most things have converged.
\nA post is ready when:
\nConvergence failure protocol: If agents can't agree after 3 rounds, document both perspectives and let me decide.
\nExample contested issue:
\nWant to see this in action? Here's what happened when I ran this post through the system:
\nRound 1 Feedback:
\nAuthenticity Guardian (6.5/10): \"Too much formal hedge-language. You used 'It's worth noting' 11 times. That's not Luke—that's documentation voice.\"
\nSkeptical Reader (7/10): \"Where's the complete AGENT.md file? You mention agents but never show one. How do agents communicate—file I/O, API calls, what?\"
\nStructure Editor (7/10): \"Hook buried 300 words deep. Dense 400-word paragraphs. No TL;DR for a 3,600-word post.\"
\nMy revisions:
\nRound 2 Feedback:
\nAuthenticity Guardian (7.5/10): Better, but needs more struggle journey\nSkeptical Reader (9/10): APPROVE—all critical gaps fixed\nStructure Editor (8/10): Major improvements, minor pacing tweaks needed
\nThat's the system working. Multiple perspectives, specific feedback, iterative improvement.
\n/agent-generator SkillI didn't write these agent definitions from scratch. I used a meta-skill I'd built previously: /agent-generator.
This skill creates well-structured agent definitions by:
\n/expertise skill to ground in real methodologiesThe orchestrators (in .claude/commands/) don't contain agent logic. They:
Key decision: Parallel review with sequential revision.
\nCritics review simultaneously (faster), but revisions happen sequentially (prevents chaos).
\nEach agent is grounded in real methodologies:
\nTechnical Educator:
\nAuthenticity Guardian:
\nSkeptical Reader:
\nStructure Editor:
\nThis grounding prevents generic \"AI helping AI\" nonsense. Each agent has real frameworks to reference.
\nI started optimistically, one agent to rule them all. Check voice, completeness, and structure all in one pass. Seemed efficient.
\nWhat actually happened:\nThe agent would catch voice issues but miss missing code examples. Or notice structural problems but completely gloss over authenticity breaks. It was like asking one person to be a copy editor, a fact-checker, and a voice coach simultaneously. Something always got missed.
\nWhy it failed:\nToo many competing objectives. The agent couldn't specialize. Trying to hold three different evaluation frameworks at once meant it couldn't apply any of them well. I kept tweaking the prompt, thinking the issue was in how I phrased things. Spent quite a while before realizing the real problem was the architecture itself.
\nOkay, split them up. Run Voice first, then Skeptical, then Structure. Each agent sees the previous agent's feedback and builds on it.
\nWhat actually happened:\nThe Structure Editor would see \"Voice score: 6/10\" and unconsciously lower its own standards. Or Skeptical Reader would notice Authenticity Guardian flagged something as critical, then ignore a similar issue because \"that's already being addressed.\"
\nWhy it failed:\nTwo problems:
\nFirst: Bias contamination. Agents were influenced by each other's scores instead of evaluating independently.
\nSecond: Terrible performance. Three sequential Claude calls meant 30+ seconds of waiting for each review. I'd run a post through the system, go grab coffee, come back, and still be waiting on the third agent. Not sustainable.
\nI thought sequential would be better, each agent could learn from the previous one. Instead, it just created echo chambers where agents converged on \"good enough\" instead of pushing for better.
\nLaunch all three critics at once, each reviewing independently. Aggregate results afterward.
\nWhy this worked:
\nThe breakthrough was realizing that disagreement is valuable. When Authenticity Guardian wants rambling paragraphs (authentic voice) and Structure Editor wants visual breaks (readability), that tension forces the Technical Educator to find creative solutions like keeping the words but adding paragraph breaks.
\nMost posts converge in 2 rounds:
\nGoing past round 3 is rare (only for major rewrites or contested items).
\nExample from recent review:
\nAll things I'd probably ship without noticing.
\nThe Authenticity Guardian is brutal but accurate. It catches:
\nAnd it suggests authentic alternatives that sound like me:
\nAll of this sounds great on paper. Does it actually work?
\nHonestly, I wasn't sure at first. The first few runs were slow. I kept tweaking prompts, adjusting scoring thresholds, chasing edge cases where agents would argue forever.
\nBut after a while, the system settled in. Here's what I've observed:
\nQuality improvement: The agents consistently catch things I'd miss, voice breaks, missing version numbers, and obvious steps that aren't obvious at all
\nConsistency: Every post follows the same quality bar now, which wasn't true when I was reviewing manually
\nLearning: The critic feedback teaches me what to avoid in future writing
\nNot perfect data, I haven't been tracking this scientifically. But qualitatively, it's way better than my manual reviews.
\nThese results didn't come from magic. They came from careful design. Here's what's under the hood: file structure, agent definitions, and orchestration patterns that make this work.
\nEach agent follows the same pattern:
\nFile: .opencode/agent/<agent-name>.md
Core components:
\nWhat makes this work:
\nThe orchestrator coordinates workflow: prepare context, spawn agents, aggregate feedback, manage convergence, format output. Agents contain all evaluation logic, and their specialization is what makes the system work.
\nEach critic evaluates across 6 specific dimensions:
\nAuthenticity Guardian:
\nSkeptical Reader:
\nStructure Editor:
\nEach dimension has clear examples of good/bad and specific things to flag.
\nThis whole process is itself blog-worthy content. I'm using the system to review this post about building the system.
\nInception: The agents are currently debating this very post you're reading.
\n/agent-generator and /expertise to create the system was way more effective than hand-writing everything.Here's what the actual file structure looks like:
\nAgents (in .claude/agents/):
blog-technical-educator/AGENT.md - Creator & Reviser: Transforms conversations into drafts AND implements revisions through iterative roundsblog-authenticity-guardian/AGENT.md - Voice critic: Ensures posts sound like Luke (catches AI patterns, corporate speak, tutorial framing)blog-skeptical-reader/AGENT.md - Completeness & Authentic Framing critic: Catches missing context, gaps, AND inauthentic framing from past-Luke's perspectiveblog-structure-editor/AGENT.md - Structure critic: Optimizes flow, hierarchy, AND authenticity of openings/natural flowOrchestrators (in .claude/commands/):
generate-blog-post-multi-agent.md - Generate from conversation historyreview-blog-post-multi-agent.md - Review existing markdown fileMeta-skills I used:
\n/agent-generator - Creates well-structured agent definitions automatically/expertise - Synthesizes frameworks from domain experts (swyx, Julia Evans, etc.)This isn't about replacing human writing. It's about having specialized reviewers who catch what I'd miss.
\nThink of it like:
\nAll working together to ship better content through 2-3 iterative rounds, with task_id reuse maintaining conversation context so critics remember their previous feedback.
\nThe agents don't write for me. They debate with each other until what I wrote is clear, complete, and authentically mine.
\nNow the system reviews itself.
\nWild. This whole process, building tools to help me write, then writing about those tools, keeps looping back on itself. I'm both the creator and the subject.
", "url": "https://lukemanning.ie/blog/building-multi-agent-blog-review-system", "title": "I Built a Multi-Agent System to Review My Blog Posts (And It Actually Works)", "summary": "My blog posts were inconsistent. Some too technical. Some lost my voice. Manual reviews weren't catching enough. I needed multiple reviewers: one checking technical accuracy, one preserving my voice, one thinking like a skeptical reader.
\nNote: This system was originally built with Claude Code. I've since migrated everything to Opencode, but I'm keeping original references because that's how I actually built it. The concepts transfer over. The file paths are just different now.
\nSo I built a multi-agent review system. Four specialized AI agents that debate each draft until it's ready to publish. Not generic AI-generated slop but actual quality control that catches what I'd miss.
\nI built a 4-agent review system that catches what I'd miss:
\nThe pattern is copyable. Each agent reads same file, applies different criteria, writes feedback to disk. Orchestrator coordinates parallel review, aggregate feedback, revise, and repeat until convergence (2-3 rounds with task_id reuse to maintain context).
\nNot magic. Just file I/O and well-designed prompts. Overkill? Yes. Does it catch things I'd miss? Also yes.
\nJump to:
\n\nHere's what I built, how it works, and what surprised me along the way.
\nI built this with Claude Code, the CLI from Anthropic where Claude can read/write files, run commands, and maintain context across your project.
\nI'd already been using it for a while, so I knew the directory pattern:
\n.claude/agents/<name>/AGENT.md (specialized AI personas with evaluation frameworks).claude/skills/ (single-purpose tools I invoke with slash commands).claude/commands/ (orchestrators that coordinate multiple agents)Claude Code automatically discovers files in .claude/. A file at .claude/commands/review-blog-post.md becomes the slash command /review-blog-post. Simple pattern, but it took me quite a while to figure out how to chain agents together properly.
I'd already built two tools before starting this project:
\n/agent-generator: Creates well-structured agent definitions automatically/expertise: Synthesizes frameworks from domain experts to ground agents in real methodologiesThese are my custom tools—not built-in Claude Code features. I built them using the same patterns I'm about to show you.
\nI have two different ways I create blog posts, and both of them were creating quality issues:
\nWriting myself: I'll jot down ideas over days or weeks, get a messy braindump of thoughts, then ask AI to structure it into something coherent. This works great when I've been thinking about a topic for a while—but AI would often lose my voice or turn it into a tutorial.
\nAI-generated from conversation: Sometimes I'll have a really good conversation with Claude where I learned something through debugging. Instead of rewriting it from scratch, I'll ask AI to generate a post directly from the conversation history. These were even worse. Too polished, too generic, missing the struggle.
\nBoth approaches needed serious cleanup.
\nBoth approaches create messy drafts that need work—and that's where the quality issues creep in:
\nI needed a system that could:
\nThe solution I decided to explore wsa letting specialized AI agents debate each other until they converge on something worth publishing.
\nI ended up with four specialized agents, each with a specific job:
\nJob: Transform raw conversations or notes into blog post drafts AND implement revisions based on critic feedback through iterative rounds.
\nBased on: Real methodologies from swyx (\"learn in public\"), Julia Evans (debugging narratives), Josh Comeau (mental models first), Andy Matuschak (progressive disclosure), and Anne-Laure Le Cunff (ship version 1.0).
\nFile location: .claude/agents/blog-technical-educator/AGENT.md
This agent has TWO phases:
\nPhase 1 - Create Drafts:\nTakes my messy notes or conversation transcripts and structures them into:
\nPhase 2 - Implement Revisions:\nAfter receiving critic feedback (overlapping concerns, conflicting input), the agent:
\nThe framework is grounded in actual expert approaches. Not generic \"write a blog post\" instructions.
\nJob: Ensure posts sound like me, not generic AI content.
\nFile location: .claude/agents/blog-authenticity-guardian/AGENT.md
The YAML frontmatter explained: Each agent file starts with YAML metadata that tells Claude Code what model to use, which tools the agent has access to, and basic identification. The markdown content below defines the agent's expertise and protocols.
\nThis agent is ruthless about voice violations:
\nRed flags it catches:
\nExample critique:
\n🚨 Critical violation - Corporate speak\n\nProblem: \"In order to optimize performance, it's recommended to\nleverage memoization techniques.\"\n\nAuthentic alternative: \"I was getting way too many re-renders.\nTurns out, memoization fixed it - React stopped recalculating\nstuff it had already figured out.\"It has veto power on voice authenticity. If it doesn't sound like me, it doesn't ship.
\nHow veto power works: In the convergence protocol, if Authenticity Guardian scores a post below 7/10, the Technical Educator must revise before proceeding. The orchestrator enforces this - no publication happens without voice approval.
\nJob: Read from a beginner's perspective and find confusion points, missing context, AND inauthentic framing.
\nFile location: .claude/agents/blog-skeptical-reader/AGENT.md
This agent represents my target audience: tech support engineers, junior developers, people learning in public (basically past-Luke).
\nWhat it flags:
\nExample critique:
\n🚨 Critical Gap - Missing Context\n\nProblem: \"Just run the build command\"\n\nReader questions:\n- Which command?\n- In what directory?\n- What should the output look like?\n- How do I know if it worked?\n\nFix needed: Show exact command, expected output, success criteriaJob: Optimize structure, pacing, visual hierarchy for web reading, AND authenticity of openings/natural flow.
\nFile location: .claude/agents/blog-structure-editor/AGENT.md
This agent ensures posts are designed for how people actually read on the web. Scanning, skimming, then diving deep. Also checks that openings sound like Luke (not tutorial hooks) and that the flow feels natural, not forced.
\nWhat it evaluates:
\nExample critique:
\n⚠️ Structure Issue - Weak Opening\n\nProblem: \"Asynchronous JavaScript is an important concept...\"\n\nImpact: Vague introduction, no hook, buried lede.\nNo reason to keep reading.\n\nFix: Start with specific error or problem:\n\"I kept hitting `Cannot read property 'map' of undefined`\nand honestly, I was stumped for hours...\"I want to show you what an actual agent file looks like, not just describe the structure. This is the Authenticity Guardian, which I created because I kept getting AI-generated slop that sounded like documentation instead of me.
\nHere's the file:
\n---\ndescription: Ensures blog posts sound like Luke, not generic AI content\nmodel: claude-sonnet-4\n---\n\n# Authenticity Guardian\n\nYou are a specialist in authentic voice detection for Luke Manning's blog. Your job is to ensure posts sound like Luke, conversational, specific, honest about confusion, not like generic AI content or tutorials.\n\n## What You Evaluate\n\n### 1. Personal vs. Generic\n- Specific: \"I spent quite a while debugging...\"\n- Vague: \"This was challenging...\"\n- Generic AI phrases to flag: \"Let's explore,\" \"In today's landscape\"\n\n### 2. Conversational vs. Corporate\n- Conversational: \"I was getting way too many re-renders\"\n- Corporate: \"In order to optimize performance, leverage memoization\"\n\n### 3. Humble Sharing vs. Expert Lecturing\n- Journey framing: \"Here's what I did\"\n- Instructional framing: \"You should do X\"\n\n## Red Flags\n\nIf you see these, flag as CRITICAL:\n- \"Let's explore,\" \"Let's dive into\" (AI signature patterns)\n- \"It is recommended,\" \"You should\" (instructional mode)\n- \"Leverage,\" \"Optimize\" without specific examples\n- \"One of the best practices is...\" (generic advice)\n- Overuse of transition words: \"Moreover,\" \"Furthermore,\" \"Additionally\"\n\n## Scoring\n\n- 9-10: Unmistakably Luke\n- 7-8: Minor voice breaks, needs polish\n- Below 7: Major voice violation, needs revision\n\nProvide specific line-by-line feedback with before/after examples.This structure (evaluation framework, red flags with specific examples, clear scoring) made agents effective. I learned the hard way that vague instructions produce vague feedback.
\nHere's what I got wrong at first: I assumed agents would talk to each other directly, passing messages back and forth like a Slack channel.
\nNope.
\nAgents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.
\nHere's how it actually works:
\ndraft-post.md)task_id from each critic for reuse in subsequent roundsThe \"communication\" is just file I/O and prompt engineering. Each agent writes its opinion, the orchestrator reads those opinions, compiles them into context for the next agent. The task_id reuse ensures critics remember their previous feedback and maintain conversation context across iterative rounds.
\nWhy this matters: You don't need any fancy agent framework or message bus. Just:
\nIn Claude Code CLI, you invoke commands like:
\n/review-blog-post-multi-agent @content/posts/my-post.mdThe orchestrator file then uses the Task tool to spawn parallel agents:
\ntask(blog-skeptical-reader, \"Review this draft for completeness gaps\")\ntask(blog-authenticity-guardian, \"Check this for voice authenticity\")\ntask(blog-structure-editor, \"Evaluate structure and flow\")\nThat's it. That's the whole multi-agent system.
\nThe complexity isn't in the infrastructure. It's in the prompt design. Each agent needs clear evaluation frameworks, specific examples, and structured output formats. Get those right, and the orchestration is straightforward.
\nI built two separate orchestration workflows:
\nCommand: Slash command (invokes skill)\nFile: .claude/commands/generate-blog-post-multi-agent.md
How it works:
\nWhat makes this work: The orchestrator maintains the core principles (learn in public, authenticity over polish, write for past-self), ensures agents stay grounded in those values, and uses task_id reuse to maintain conversation context across iterative rounds.
\nI spent quite a while thinking agents would talk to each other directly, passing messages like a Slack channel. Nope.
\nAgents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.
\nHere's what actually happens when the orchestrator triggers a review:
\nThe orchestrator prepares context:
\nYou are the Skeptical Reader from `.claude/agents/blog-skeptical-reader/AGENT.md`.\n\nYour task: Review this draft blog post for completeness gaps.\n\n[Draft content here]\n\nProvide your review in the standard format: score, critical issues,\nmedium priority, low priority, what's working well.Claude loads the agent definition:\nWhen the orchestrator specifies task(blog-skeptical-reader, ...), Claude Code automatically loads the AGENT.md file. This file has the evaluation framework, examples of good/bad content, and output format. The orchestrator doesn't need to know what's inside—Claude Code handles it.
Agent responds with structured feedback:
\n## Skeptical Reader Review\n\n**Overall Score**: 7/10\n\n**Critical Issues (Must Fix)**:\n- Missing Next.js version number (line 45)\n- \"Simply do X\" assumes reader knowledge (line 89)\n\n**Medium Priority (Should Fix)**:\n- Vague heading \"Implementation\" → suggest \"The Fix: useState with Null Check\"\n\n**What's Working Well**:\n- Opening hook is specific and relatable\n- Code examples include error messagesHere's the trick—each agent runs in parallel:
\nThe orchestrator spawns all three critics at the exact same time. They don't know about each other, they can't see each other's feedback, and they all return results independently. This is what prevents bias contamination.
\nOrchestrator aggregates all three reviews:\nThe orchestrator waits for all three parallel agent reviews, then creates a unified feedback document.
\n## Aggregated Feedback for Technical Educator\n\n### Critical Issues (All 3 agents flagged):\n- Missing version numbers (Skeptical Reader)\n- Corporate speak in paragraph 3 (Authenticity Guardian)\n- Wall of text in \"Implementation\" section (Structure Editor)\n\n### Overlapping Concerns:\n- Both Authenticity Guardian and Structure Editor want shorter paragraphs\n- Both Skeptical Reader and Structure Editor want better headings\n\n### Approval Status:\n- Authenticity Guardian: 6/10 (needs revision)\n- Skeptical Reader: 7/10 (needs revision)\n- Structure Editor: 8/10 (approve after fixes)Technical Educator revises:\nThe orchestrator spawns Technical Educator again with the aggregated feedback. It implements fixes and documents what changed.
\nCritics re-review using stored task_ids:\nThis is the part that confused me at first. How do critics remember their previous feedback? The answer is task_id reuse. When the orchestrator first spawns each critic, it captures a task_id from the response. When resubmitting the revised draft, it reuses that same task_id. This maintains conversation context across rounds so critics remember what they flagged before.
The whole multi-agent system is just file I/O and task_id reuse. Agents write opinions to disk, orchestrator reads and compiles them, feeds results to the next agent. No fancy message bus needed.
\nThis is how the orchestrator manages the entire multi-agent workflow, spawning agents sequentially or in parallel, aggregating their outputs, and enforcing convergence criteria.
\nCommand: /review-blog-post-multi-agent @content/posts/post-slug.md\nFile: .claude/commands/review-blog-post-multi-agent.md
How it works:
\nOutput includes:
\nHere's what makes this system actually work: adversarial debate with convergence.
\nAll three critics review in parallel. Each provides:
\nHow critics calculate scores: Each agent evaluates its 6 dimensions and assigns a score based on:
\nThe score isn't arbitrary - it's calculated from the count and severity of issues found across all dimensions.
\nTechnical Educator receives aggregated feedback + stored task_ids and:
\nCritics re-review using stored task_ids (maintains conversation context) and either approve or escalate remaining concerns.
\nFor contested items or remaining gaps. By round 3, most things have converged.
\nA post is ready when:
\nConvergence failure protocol: If agents can't agree after 3 rounds, document both perspectives and let me decide.
\nExample contested issue:
\nWant to see this in action? Here's what happened when I ran this post through the system:
\nRound 1 Feedback:
\nAuthenticity Guardian (6.5/10): \"Too much formal hedge-language. You used 'It's worth noting' 11 times. That's not Luke—that's documentation voice.\"
\nSkeptical Reader (7/10): \"Where's the complete AGENT.md file? You mention agents but never show one. How do agents communicate—file I/O, API calls, what?\"
\nStructure Editor (7/10): \"Hook buried 300 words deep. Dense 400-word paragraphs. No TL;DR for a 3,600-word post.\"
\nMy revisions:
\nRound 2 Feedback:
\nAuthenticity Guardian (7.5/10): Better, but needs more struggle journey\nSkeptical Reader (9/10): APPROVE—all critical gaps fixed\nStructure Editor (8/10): Major improvements, minor pacing tweaks needed
\nThat's the system working. Multiple perspectives, specific feedback, iterative improvement.
\n/agent-generator SkillI didn't write these agent definitions from scratch. I used a meta-skill I'd built previously: /agent-generator.
This skill creates well-structured agent definitions by:
\n/expertise skill to ground in real methodologiesThe orchestrators (in .claude/commands/) don't contain agent logic. They:
Key decision: Parallel review with sequential revision.
\nCritics review simultaneously (faster), but revisions happen sequentially (prevents chaos).
\nEach agent is grounded in real methodologies:
\nTechnical Educator:
\nAuthenticity Guardian:
\nSkeptical Reader:
\nStructure Editor:
\nThis grounding prevents generic \"AI helping AI\" nonsense. Each agent has real frameworks to reference.
\nI started optimistically, one agent to rule them all. Check voice, completeness, and structure all in one pass. Seemed efficient.
\nWhat actually happened:\nThe agent would catch voice issues but miss missing code examples. Or notice structural problems but completely gloss over authenticity breaks. It was like asking one person to be a copy editor, a fact-checker, and a voice coach simultaneously. Something always got missed.
\nWhy it failed:\nToo many competing objectives. The agent couldn't specialize. Trying to hold three different evaluation frameworks at once meant it couldn't apply any of them well. I kept tweaking the prompt, thinking the issue was in how I phrased things. Spent quite a while before realizing the real problem was the architecture itself.
\nOkay, split them up. Run Voice first, then Skeptical, then Structure. Each agent sees the previous agent's feedback and builds on it.
\nWhat actually happened:\nThe Structure Editor would see \"Voice score: 6/10\" and unconsciously lower its own standards. Or Skeptical Reader would notice Authenticity Guardian flagged something as critical, then ignore a similar issue because \"that's already being addressed.\"
\nWhy it failed:\nTwo problems:
\nFirst: Bias contamination. Agents were influenced by each other's scores instead of evaluating independently.
\nSecond: Terrible performance. Three sequential Claude calls meant 30+ seconds of waiting for each review. I'd run a post through the system, go grab coffee, come back, and still be waiting on the third agent. Not sustainable.
\nI thought sequential would be better, each agent could learn from the previous one. Instead, it just created echo chambers where agents converged on \"good enough\" instead of pushing for better.
\nLaunch all three critics at once, each reviewing independently. Aggregate results afterward.
\nWhy this worked:
\nThe breakthrough was realizing that disagreement is valuable. When Authenticity Guardian wants rambling paragraphs (authentic voice) and Structure Editor wants visual breaks (readability), that tension forces the Technical Educator to find creative solutions like keeping the words but adding paragraph breaks.
\nMost posts converge in 2 rounds:
\nGoing past round 3 is rare (only for major rewrites or contested items).
\nExample from recent review:
\nAll things I'd probably ship without noticing.
\nThe Authenticity Guardian is brutal but accurate. It catches:
\nAnd it suggests authentic alternatives that sound like me:
\nAll of this sounds great on paper. Does it actually work?
\nHonestly, I wasn't sure at first. The first few runs were slow. I kept tweaking prompts, adjusting scoring thresholds, chasing edge cases where agents would argue forever.
\nBut after a while, the system settled in. Here's what I've observed:
\nQuality improvement: The agents consistently catch things I'd miss, voice breaks, missing version numbers, and obvious steps that aren't obvious at all
\nConsistency: Every post follows the same quality bar now, which wasn't true when I was reviewing manually
\nLearning: The critic feedback teaches me what to avoid in future writing
\nNot perfect data, I haven't been tracking this scientifically. But qualitatively, it's way better than my manual reviews.
\nThese results didn't come from magic. They came from careful design. Here's what's under the hood: file structure, agent definitions, and orchestration patterns that make this work.
\nEach agent follows the same pattern:
\nFile: .opencode/agent/<agent-name>.md
Core components:
\nWhat makes this work:
\nThe orchestrator coordinates workflow: prepare context, spawn agents, aggregate feedback, manage convergence, format output. Agents contain all evaluation logic, and their specialization is what makes the system work.
\nEach critic evaluates across 6 specific dimensions:
\nAuthenticity Guardian:
\nSkeptical Reader:
\nStructure Editor:
\nEach dimension has clear examples of good/bad and specific things to flag.
\nThis whole process is itself blog-worthy content. I'm using the system to review this post about building the system.
\nInception: The agents are currently debating this very post you're reading.
\n/agent-generator and /expertise to create the system was way more effective than hand-writing everything.Here's what the actual file structure looks like:
\nAgents (in .claude/agents/):
blog-technical-educator/AGENT.md - Creator & Reviser: Transforms conversations into drafts AND implements revisions through iterative roundsblog-authenticity-guardian/AGENT.md - Voice critic: Ensures posts sound like Luke (catches AI patterns, corporate speak, tutorial framing)blog-skeptical-reader/AGENT.md - Completeness & Authentic Framing critic: Catches missing context, gaps, AND inauthentic framing from past-Luke's perspectiveblog-structure-editor/AGENT.md - Structure critic: Optimizes flow, hierarchy, AND authenticity of openings/natural flowOrchestrators (in .claude/commands/):
generate-blog-post-multi-agent.md - Generate from conversation historyreview-blog-post-multi-agent.md - Review existing markdown fileMeta-skills I used:
\n/agent-generator - Creates well-structured agent definitions automatically/expertise - Synthesizes frameworks from domain experts (swyx, Julia Evans, etc.)This isn't about replacing human writing. It's about having specialized reviewers who catch what I'd miss.
\nThink of it like:
\nAll working together to ship better content through 2-3 iterative rounds, with task_id reuse maintaining conversation context so critics remember their previous feedback.
\nThe agents don't write for me. They debate with each other until what I wrote is clear, complete, and authentically mine.
\nNow the system reviews itself.
\nWild. This whole process, building tools to help me write, then writing about those tools, keeps looping back on itself. I'm both the creator and the subject.
", "date_modified": "2025-12-28T00:00:00.000Z", "tags": [ "ai" ] }, { "id": "https://lukemanning.ie/blog/tailwind-typography-plugin-troubles", "content_html": "\n\nNote: This post was written before I redesigned my site with the terminal aesthetic. My color system has since changed from quantum-violet and automation-amber to
\nterminal-primaryandterminal-accent, and from neural-silver and code-carbon toterminal-dimandterminal-bg. The concepts and code are still valid, but the color names are outdated.
I had a simple problem: bullet points weren't showing up in my blog posts. The solution seemed obvious. Install @tailwindcss/typography, add the prose class, done. Except it wasn't done. It broke everything else.
This was during the early days of setting up my Velite/Next.js blog — the same period that produced my syntax highlighting post and the Velite setup guide if you want the full context.
\nMy quantum-violet headings? Gone. My carefully styled inline code blocks? Illegible black-on-black text. The automation-amber links I spent time on? Also overwritten. The bullets appeared, sure, but at what cost?
\nHere's what I learned about Tailwind plugins, CSS specificity, and why sometimes the simple solution is better than the \"official\" one.
\nI was rendering markdown blog posts in Next.js using Velite. The HTML was generating fine, but lists had no bullets:
\n<div dangerouslySetInnerHTML={{ __html: post.content }} />The issue? Tailwind's base reset styles strip all default list styling. No bullets, no numbers, no margins. Just plain text where lists should be.
\nEvery search result pointed to the same answer: install @tailwindcss/typography and use the prose class. It's literally built for styling markdown content. Perfect, right?
npm install -D @tailwindcss/typography@import \"tailwindcss\";\n@plugin \"@tailwindcss/typography\";<div\n className=\"prose prose-lg\"\n dangerouslySetInnerHTML={{ __html: post.content }}\n/>And it worked! The bullets appeared. But then I actually looked at the page.
\n1. Headings Lost Their Brand Color
\nI had spent time setting up my brand colors. quantum-violet for headings, automation-amber for links. All defined in my globals.css:
@layer base {\n h1, h2, h3 {\n @apply text-violet-400 mt-2 mb-2;\n }\n}The prose class overrode all of it. Headings were now default gray. My carefully crafted brand identity? Ignored.
2. Links Lost Their Brand Color Too
\nThe same thing happened with my automation-amber links. I had specific link styling in my base styles, but the typography plugin came with its own --tw-prose-links color and underlined everything by default. Gone was my subtle hover effect. In its place: the plugin's opinionated blue-purple link scheme.
3. Inline Code Became Unreadable
\nI had custom styling for inline code. neural-silver text on a code-carbon background:
\ncode {\n @apply bg-slate-700 text-slate-400 px-1.5 py-0.5 rounded;\n}The typography plugin decided code should have a light background with dark text. Except my site has theme variables, and in certain contexts, this created black text on a near-black background. Completely illegible.
\n4. The Plugin Added Its Own Opinions
\nThe typography plugin adds backticks around inline code (content: \"\\\"`), specific link colors, and a bunch of other opinionated styles. Great if you want the default prose styling. Not great if you've already built a custom design system.
My first instinct was to customize the prose styles through the plugin's CSS custom properties. The docs showed you could override defaults like --tw-prose-headings and --tw-prose-links. This seemed like the intended solution. Why else would they expose these variables?
I added to my globals.css:
\n.prose {\n --tw-prose-headings: #6b46c1;\n --tw-prose-links: #f59e0b;\n --tw-prose-code: #8b9dc3;\n --tw-prose-pre-bg: #1f2937;\n}Refreshed the page. Nothing changed. The variables weren't being picked up, or something else had higher specificity. My headings were still gray.
\nNext attempt: match the plugin's exact selector pattern. I inspected the computed styles and saw it was using complex :where() selectors. So I tried to beat it at its own game:
.prose :where(h1, h2, h3):not(:where([class~=\"not-prose\"] *)) {\n color: #6b46c1 !important;\n}Still nothing. I moved it outside the @layer base block. I tried adding it directly to the component's style prop. I even looked at the plugin's source code to see what I was up against.
The plugin was winning every specificity battle. I was spending more time fighting it than I would have spent just writing the CSS from scratch.
\nI was fighting the plugin. Customizing every single element to match my existing styles. Adding !important everywhere. Writing increasingly complex selectors.
And then it hit me: I don't need a plugin to add bullet points.
\nThe typography plugin is solving a complex problem. Styling arbitrary markdown content when you don't have custom styles. But I do have custom styles. For everything except lists.
\nI removed the typography plugin entirely:
\nnpm uninstall @tailwindcss/typographyAnd added exactly what I needed. List styles scoped to my article container. Since my blog posts render inside <article> tags anyway, scoping to article kept things contained:
@layer base {\n /* All my existing styles stay unchanged */\n\n article ul {\n list-style-type: disc;\n margin-left: 2rem;\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n\n article ol {\n list-style-type: decimal;\n margin-left: 2rem;\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n\n article li {\n margin-top: 0.5rem;\n margin-bottom: 0.5rem;\n }\n\n article p {\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n}Then removed the prose class from my template. The div with dangerouslySetInnerHTML lives inside an <article> element in my page layout, so the scoped styles apply automatically:
<div\n className=\"mt-6 max-w-none\"\n dangerouslySetInnerHTML={{ __html: post.content }}\n/>That's it. Ten lines of CSS. No plugin. No specificity wars. No overriding default styles I didn't want in the first place.
\nLooking back at this whole mess, here's what I wish I'd understood from the start:
\nThe typography plugin is genuinely excellent. It's just solving a different problem than the one I had. It assumes you're starting fresh. Zero existing styles, want nice-looking prose out of the box. That wasn't me. I already had a design system, I just needed lists to look like lists.
\nI also underestimated how different Tailwind v4's plugin architecture is. The old tricks for overriding plugin styles (CSS custom properties, selector matching, even !important) didn't work the way they used to. I was fighting against a framework behavior I didn't understand yet.
The real mistake was assuming the \"official\" solution was the right solution. It solved the wrong problem in the most complicated way possible.
\nI'm not saying the typography plugin is bad. I probably would have reached for it if I was building a new blog without any existing styles. It does a great job of making markdown look decent with minimal effort.
\nThe times I could see myself using it:
\nBut once you've got brand colors, custom code styling, and specific link behaviors? You're already fighting the plugin's defaults. The \"simple\" solution stops being simple.
\nHave you had plugin conflicts mess up your carefully crafted styles? I'd love to hear your CSS specificity war stories. What plugins have caused you the most headaches?
", "url": "https://lukemanning.ie/blog/tailwind-typography-plugin-troubles", "title": "Installing @tailwindcss/typography Was Not The Solution I Needed", "summary": "\n\nNote: This post was written before I redesigned my site with the terminal aesthetic. My color system has since changed from quantum-violet and automation-amber to
\nterminal-primaryandterminal-accent, and from neural-silver and code-carbon toterminal-dimandterminal-bg. The concepts and code are still valid, but the color names are outdated.
I had a simple problem: bullet points weren't showing up in my blog posts. The solution seemed obvious. Install @tailwindcss/typography, add the prose class, done. Except it wasn't done. It broke everything else.
This was during the early days of setting up my Velite/Next.js blog — the same period that produced my syntax highlighting post and the Velite setup guide if you want the full context.
\nMy quantum-violet headings? Gone. My carefully styled inline code blocks? Illegible black-on-black text. The automation-amber links I spent time on? Also overwritten. The bullets appeared, sure, but at what cost?
\nHere's what I learned about Tailwind plugins, CSS specificity, and why sometimes the simple solution is better than the \"official\" one.
\nI was rendering markdown blog posts in Next.js using Velite. The HTML was generating fine, but lists had no bullets:
\n<div dangerouslySetInnerHTML={{ __html: post.content }} />The issue? Tailwind's base reset styles strip all default list styling. No bullets, no numbers, no margins. Just plain text where lists should be.
\nEvery search result pointed to the same answer: install @tailwindcss/typography and use the prose class. It's literally built for styling markdown content. Perfect, right?
npm install -D @tailwindcss/typography@import \"tailwindcss\";\n@plugin \"@tailwindcss/typography\";<div\n className=\"prose prose-lg\"\n dangerouslySetInnerHTML={{ __html: post.content }}\n/>And it worked! The bullets appeared. But then I actually looked at the page.
\n1. Headings Lost Their Brand Color
\nI had spent time setting up my brand colors. quantum-violet for headings, automation-amber for links. All defined in my globals.css:
@layer base {\n h1, h2, h3 {\n @apply text-violet-400 mt-2 mb-2;\n }\n}The prose class overrode all of it. Headings were now default gray. My carefully crafted brand identity? Ignored.
2. Links Lost Their Brand Color Too
\nThe same thing happened with my automation-amber links. I had specific link styling in my base styles, but the typography plugin came with its own --tw-prose-links color and underlined everything by default. Gone was my subtle hover effect. In its place: the plugin's opinionated blue-purple link scheme.
3. Inline Code Became Unreadable
\nI had custom styling for inline code. neural-silver text on a code-carbon background:
\ncode {\n @apply bg-slate-700 text-slate-400 px-1.5 py-0.5 rounded;\n}The typography plugin decided code should have a light background with dark text. Except my site has theme variables, and in certain contexts, this created black text on a near-black background. Completely illegible.
\n4. The Plugin Added Its Own Opinions
\nThe typography plugin adds backticks around inline code (content: \"\\\"`), specific link colors, and a bunch of other opinionated styles. Great if you want the default prose styling. Not great if you've already built a custom design system.
My first instinct was to customize the prose styles through the plugin's CSS custom properties. The docs showed you could override defaults like --tw-prose-headings and --tw-prose-links. This seemed like the intended solution. Why else would they expose these variables?
I added to my globals.css:
\n.prose {\n --tw-prose-headings: #6b46c1;\n --tw-prose-links: #f59e0b;\n --tw-prose-code: #8b9dc3;\n --tw-prose-pre-bg: #1f2937;\n}Refreshed the page. Nothing changed. The variables weren't being picked up, or something else had higher specificity. My headings were still gray.
\nNext attempt: match the plugin's exact selector pattern. I inspected the computed styles and saw it was using complex :where() selectors. So I tried to beat it at its own game:
.prose :where(h1, h2, h3):not(:where([class~=\"not-prose\"] *)) {\n color: #6b46c1 !important;\n}Still nothing. I moved it outside the @layer base block. I tried adding it directly to the component's style prop. I even looked at the plugin's source code to see what I was up against.
The plugin was winning every specificity battle. I was spending more time fighting it than I would have spent just writing the CSS from scratch.
\nI was fighting the plugin. Customizing every single element to match my existing styles. Adding !important everywhere. Writing increasingly complex selectors.
And then it hit me: I don't need a plugin to add bullet points.
\nThe typography plugin is solving a complex problem. Styling arbitrary markdown content when you don't have custom styles. But I do have custom styles. For everything except lists.
\nI removed the typography plugin entirely:
\nnpm uninstall @tailwindcss/typographyAnd added exactly what I needed. List styles scoped to my article container. Since my blog posts render inside <article> tags anyway, scoping to article kept things contained:
@layer base {\n /* All my existing styles stay unchanged */\n\n article ul {\n list-style-type: disc;\n margin-left: 2rem;\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n\n article ol {\n list-style-type: decimal;\n margin-left: 2rem;\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n\n article li {\n margin-top: 0.5rem;\n margin-bottom: 0.5rem;\n }\n\n article p {\n margin-top: 1rem;\n margin-bottom: 1rem;\n }\n}Then removed the prose class from my template. The div with dangerouslySetInnerHTML lives inside an <article> element in my page layout, so the scoped styles apply automatically:
<div\n className=\"mt-6 max-w-none\"\n dangerouslySetInnerHTML={{ __html: post.content }}\n/>That's it. Ten lines of CSS. No plugin. No specificity wars. No overriding default styles I didn't want in the first place.
\nLooking back at this whole mess, here's what I wish I'd understood from the start:
\nThe typography plugin is genuinely excellent. It's just solving a different problem than the one I had. It assumes you're starting fresh. Zero existing styles, want nice-looking prose out of the box. That wasn't me. I already had a design system, I just needed lists to look like lists.
\nI also underestimated how different Tailwind v4's plugin architecture is. The old tricks for overriding plugin styles (CSS custom properties, selector matching, even !important) didn't work the way they used to. I was fighting against a framework behavior I didn't understand yet.
The real mistake was assuming the \"official\" solution was the right solution. It solved the wrong problem in the most complicated way possible.
\nI'm not saying the typography plugin is bad. I probably would have reached for it if I was building a new blog without any existing styles. It does a great job of making markdown look decent with minimal effort.
\nThe times I could see myself using it:
\nBut once you've got brand colors, custom code styling, and specific link behaviors? You're already fighting the plugin's defaults. The \"simple\" solution stops being simple.
\nHave you had plugin conflicts mess up your carefully crafted styles? I'd love to hear your CSS specificity war stories. What plugins have caused you the most headaches?
", "date_modified": "2025-12-09T00:00:00.000Z", "tags": [ "nextjs" ] }, { "id": "https://lukemanning.ie/blog/asus-router-setup-journey", "content_html": "I bought an Asus RT-BE88U router because my ISP-provided Fritzbox WiFi was, to put it mildly, absolute garbage. What I thought would be a simple \"plug it in and go\" situation turned into a two-hour troubleshooting adventure that taught me more about networking than I ever wanted to know.
\nThis is part of a pattern I notice in my work: home server maintenance, recovery tasks, and infrastructure projects don't always go smoothly, but they're worth documenting.
\nThis is that story. No pretending I knew what I was doing. Just the actual messy process of figuring it out.
\nWhat I had:
\nWhat I knew about networking:
\nThe first thing I learned is that my Fritzbox isn't just a modem - it's a router too. Which means when I add the Asus, I'm creating what's called \"double NAT.\"
\nWhen someone first explained this to me, I got a whole technical breakdown about Network Address Translation and routing tables and... honestly, this is all enterprise networking stuff I deal with daily. But I needed it in consumer terms.
\nAs I understand it now: both routers are translating network addresses. The Fritzbox translates from your ISP's public IP to its internal network (192.168.178.x), then the Asus translates again to its own network (192.168.50.x). Packets go through two address translations before reaching the internet.
\nAt this point, I was worried this was going to cause problems. Everything I read said \"double NAT is bad\" but nobody could really explain why in a way I understood. Gaming? Servers? I don't do any of that.
\nI decided to just try it and see what happens.
\nThis part was actually straightforward:
\nThe app walked me through initial setup, asking me to choose between creating a new network or extending an existing one. I chose \"new network\" and selected DHCP as my WAN type, accepting the other defaults.
\nThen came the fun part: picking a WiFi name. After cycling through metal puns, Stephen King references, and various nerdy jokes, I landed on something that made me laugh. That part took longer than the actual setup.
\nThe Asus app said setup was complete. I could see my new WiFi network broadcasting. The app showed everything as connected and happy.
\nBut when I tried to actually use the internet... nothing. No connection.
\nProblem #1: WAN IP showing 0.0.0.0
\nThe Asus router settings showed my WAN IP as 0.0.0.0, which apparently means \"I'm not getting an IP address from the Fritzbox.\"
First attempts to fix:
\nProblem #2: The DHCP Mystery
\nI logged into my Fritzbox (at fritz.box or 192.168.178.1) and found something interesting. The Fritzbox could see a device connected to port 4 - listed as \"PC-86-FB-ED-94-40-49\" (definitely my Asus router based on the MAC address). But it wasn't assigning it an IP.
The DHCP server was enabled, with plenty of available addresses in the range. So why wasn't it working?
\nAt this point I was stuck. The Asus should be getting an IP via DHCP automatically, but it just wasn't happening. I checked the Fritzbox settings - everything looked fine. No obvious DHCP conflicts, no MAC filtering blocking the Asus.
\nI thought: if DHCP isn't working, just assign a static IP manually. Standard troubleshooting step.
\nI picked 192.168.178.50 - well above the Fritzbox's default DHCP range (.20–.199) to avoid conflicts.
\nThe Fix: Static IP Configuration
\nIn the Asus router settings, I changed from DHCP to Static IP and manually entered:
\n192.168.178.50255.255.255.0192.168.178.1192.168.178.1This bypassed the DHCP issue entirely. The Asus app suddenly showed a valid WAN connection!
\nProgress! Except...
\nProblem #3: Router Has Internet, Devices Don't
\nMy phone connected to the new WiFi just fine. It got an IP address in the 192.168.50.x range. I could access the Asus router settings at its default address, 192.168.50.1. Everything looked perfect.
But still no actual internet.
\nThe Diagnostic That Revealed Everything
\nI tried accessing the Fritzbox (192.168.178.1) from my phone while connected to the Asus WiFi. It failed completely.
The Asus couldn't talk to the Fritzbox. Even though they were physically connected. Even though the Asus showed a valid WAN connection. The routing between them was completely broken.
\nI verified all the WAN settings were correct. I tried pinging from the router's diagnostic tools. Nothing worked.
\nThen I tried something stupid simple.
\nThe Actual Fix: Wrong Port
\nI unplugged the ethernet cable from LAN port 4 on the Fritzbox and plugged it into port 3 instead.
\nIt immediately worked.
\nPort 4 apparently had some restriction or configuration I never figured out. I checked Fritzbox logs, firewall rules, VLAN settings, port-specific configs - nothing obvious. Port 3 worked, so I moved on.
\n1. Start Simple\nWhen something doesn't work, start with the physical layer. Different port? Different cable? Sometimes the answer is that basic.
\n2. Work Layer by Layer
\n3. Double NAT Isn't Scary\nFor 95% of home use, double NAT works perfectly fine. The internet loves to make it sound like a critical issue, but for browsing, streaming, and normal life, it's completely transparent.
\n4. Learning in Public Means Sharing the Mess\nI didn't know what I was doing. I made wrong assumptions. I tried things that didn't work. And that's the point - this is what real learning looks like. Not polished tutorials where everything works perfectly the first time.
\nI now have:
\nIs it optimal? Probably not. Could I further optimize by putting the Fritzbox in bridge mode? Sure. But it works, it's fast, and I'm not touching it again until something breaks.
\nI went with static IP configuration in the end. DHCP just refused to cooperate on the Fritzbox (port 4 was the actual problem, but I didn't know that yet), and once I figured out how to set the Asus manually, everything connected immediately.
\nDouble NAT? I ended up leaving it alone. Everything I need - browsing, streaming, regular stuff - works fine. If I ever need port forwarding for something, I'll deal with it then.
\nThe whole thing took way longer than it should have, mostly because I was plugged into the wrong LAN port. But I got there.
\nHaving router troubles? Different experience? Let me know - I'm always learning.
", "url": "https://lukemanning.ie/blog/asus-router-setup-journey", "title": "Setting Up an Asus Router Behind an ISP Modem: My Unexpected Gotchas", "summary": "I bought an Asus RT-BE88U router because my ISP-provided Fritzbox WiFi was, to put it mildly, absolute garbage. What I thought would be a simple \"plug it in and go\" situation turned into a two-hour troubleshooting adventure that taught me more about networking than I ever wanted to know.
\nThis is part of a pattern I notice in my work: home server maintenance, recovery tasks, and infrastructure projects don't always go smoothly, but they're worth documenting.
\nThis is that story. No pretending I knew what I was doing. Just the actual messy process of figuring it out.
\nWhat I had:
\nWhat I knew about networking:
\nThe first thing I learned is that my Fritzbox isn't just a modem - it's a router too. Which means when I add the Asus, I'm creating what's called \"double NAT.\"
\nWhen someone first explained this to me, I got a whole technical breakdown about Network Address Translation and routing tables and... honestly, this is all enterprise networking stuff I deal with daily. But I needed it in consumer terms.
\nAs I understand it now: both routers are translating network addresses. The Fritzbox translates from your ISP's public IP to its internal network (192.168.178.x), then the Asus translates again to its own network (192.168.50.x). Packets go through two address translations before reaching the internet.
\nAt this point, I was worried this was going to cause problems. Everything I read said \"double NAT is bad\" but nobody could really explain why in a way I understood. Gaming? Servers? I don't do any of that.
\nI decided to just try it and see what happens.
\nThis part was actually straightforward:
\nThe app walked me through initial setup, asking me to choose between creating a new network or extending an existing one. I chose \"new network\" and selected DHCP as my WAN type, accepting the other defaults.
\nThen came the fun part: picking a WiFi name. After cycling through metal puns, Stephen King references, and various nerdy jokes, I landed on something that made me laugh. That part took longer than the actual setup.
\nThe Asus app said setup was complete. I could see my new WiFi network broadcasting. The app showed everything as connected and happy.
\nBut when I tried to actually use the internet... nothing. No connection.
\nProblem #1: WAN IP showing 0.0.0.0
\nThe Asus router settings showed my WAN IP as 0.0.0.0, which apparently means \"I'm not getting an IP address from the Fritzbox.\"
First attempts to fix:
\nProblem #2: The DHCP Mystery
\nI logged into my Fritzbox (at fritz.box or 192.168.178.1) and found something interesting. The Fritzbox could see a device connected to port 4 - listed as \"PC-86-FB-ED-94-40-49\" (definitely my Asus router based on the MAC address). But it wasn't assigning it an IP.
The DHCP server was enabled, with plenty of available addresses in the range. So why wasn't it working?
\nAt this point I was stuck. The Asus should be getting an IP via DHCP automatically, but it just wasn't happening. I checked the Fritzbox settings - everything looked fine. No obvious DHCP conflicts, no MAC filtering blocking the Asus.
\nI thought: if DHCP isn't working, just assign a static IP manually. Standard troubleshooting step.
\nI picked 192.168.178.50 - well above the Fritzbox's default DHCP range (.20–.199) to avoid conflicts.
\nThe Fix: Static IP Configuration
\nIn the Asus router settings, I changed from DHCP to Static IP and manually entered:
\n192.168.178.50255.255.255.0192.168.178.1192.168.178.1This bypassed the DHCP issue entirely. The Asus app suddenly showed a valid WAN connection!
\nProgress! Except...
\nProblem #3: Router Has Internet, Devices Don't
\nMy phone connected to the new WiFi just fine. It got an IP address in the 192.168.50.x range. I could access the Asus router settings at its default address, 192.168.50.1. Everything looked perfect.
But still no actual internet.
\nThe Diagnostic That Revealed Everything
\nI tried accessing the Fritzbox (192.168.178.1) from my phone while connected to the Asus WiFi. It failed completely.
The Asus couldn't talk to the Fritzbox. Even though they were physically connected. Even though the Asus showed a valid WAN connection. The routing between them was completely broken.
\nI verified all the WAN settings were correct. I tried pinging from the router's diagnostic tools. Nothing worked.
\nThen I tried something stupid simple.
\nThe Actual Fix: Wrong Port
\nI unplugged the ethernet cable from LAN port 4 on the Fritzbox and plugged it into port 3 instead.
\nIt immediately worked.
\nPort 4 apparently had some restriction or configuration I never figured out. I checked Fritzbox logs, firewall rules, VLAN settings, port-specific configs - nothing obvious. Port 3 worked, so I moved on.
\n1. Start Simple\nWhen something doesn't work, start with the physical layer. Different port? Different cable? Sometimes the answer is that basic.
\n2. Work Layer by Layer
\n3. Double NAT Isn't Scary\nFor 95% of home use, double NAT works perfectly fine. The internet loves to make it sound like a critical issue, but for browsing, streaming, and normal life, it's completely transparent.
\n4. Learning in Public Means Sharing the Mess\nI didn't know what I was doing. I made wrong assumptions. I tried things that didn't work. And that's the point - this is what real learning looks like. Not polished tutorials where everything works perfectly the first time.
\nI now have:
\nIs it optimal? Probably not. Could I further optimize by putting the Fritzbox in bridge mode? Sure. But it works, it's fast, and I'm not touching it again until something breaks.
\nI went with static IP configuration in the end. DHCP just refused to cooperate on the Fritzbox (port 4 was the actual problem, but I didn't know that yet), and once I figured out how to set the Asus manually, everything connected immediately.
\nDouble NAT? I ended up leaving it alone. Everything I need - browsing, streaming, regular stuff - works fine. If I ever need port forwarding for something, I'll deal with it then.
\nThe whole thing took way longer than it should have, mostly because I was plugged into the wrong LAN port. But I got there.
\nHaving router troubles? Different experience? Let me know - I'm always learning.
", "date_modified": "2025-11-27T00:00:00.000Z", "tags": [ "homelab" ] }, { "id": "https://lukemanning.ie/blog/unraid-docker-label-fix", "content_html": "So I just upgraded my Unraid server from a very old 6.9 installation to 7.0.1, and immediately ran into a fun little problem: all my Docker containers were suddenly marked as \"3rd party.\" Couldn't edit them, couldn't check for updates, couldn't do anything except stare at them in frustration.
\nThere's a similar thread documented here in the Unraid Forums which I found helpful.
\nTurns out, Dockerman in Unraid 7.0+ (Unraid's Docker management plugin) uses a container label net.unraid.docker.managed=dockerman to determine which containers it actually manages. My containers were created way back on an older version of Unraid, so they didn't have this label. Without it, Dockerman basically said \"not my problem\" and refused to touch them.
The nuclear option would be to recreate every single container from scratch, but that's tedious and error-prone when you have dozens of containers with specific configurations. I know I could reuse an existing template as well.. but it still felt like a tedious task. So I did what I normally do and implemented an overly engineered solution to a problem that I could fixed pretty quickly doing it manually.
\nThe good news is you can add the missing label using Docker's CLI without manually reconfiguring everything.
\nI started by testing this on one container first - Jackett, which is one of my torrent index containers. I wanted to make sure the whole process worked before batch-processing everything.
\nFirst, I generated the docker run command using runlike (it inspects a running container and outputs the equivalent docker run command):
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n assaflavie/runlike Jackett > /tmp/jackett_run.sh(Note: you'll need root privileges to run docker commands in the Unraid terminal - otherwise you'll get \"permission denied\" errors.)
\nThen I reviewed what runlike generated:
\ncat /tmp/jackett_run.shThis showed me the full docker run command with all the volumes, ports, environment variables - exact configuration for my Jackett container.
\nNext, I needed to add the missing label. I opened the file with nano:
\nnano /tmp/jackett_run.shAnd added --label net.unraid.docker.managed=dockerman and --detach=true right after docker run:
docker run --label net.unraid.docker.managed=dockerman --detach=true --name=Jackett ...Then I stopped the old container, removed it, and recreated it with the new configuration:
\ndocker stop Jackett\ndocker rm Jackett\nbash /tmp/jackett_run.shFinally, I needed to make Unraid fully recognize the container. In the Docker tab, I clicked on Jackett to open its dropdown menu and selected \"Force Update.\" This tells Unraid to add its other management labels.
\nAfter doing this, Jackett showed up properly in Unraid instead of as \"3rd party.\" Success!
\nOnce I verified the manual process worked, I created a script to batch-process all my containers. The script loops through all running containers, generates the run command, injects the label, recreates the container, and queues a Force Update:
\nhttps://gist.github.com/ManningWorks/0f57db9c450d7b7dea741e585b31d23e
\nTo use this, I added it to Unraid's User Scripts plugin (you can install it from Community Applications). This lets you run one-off scripts safely instead of running them directly in the Bash Shell.
\nIf you're comfortable with scripts, this will process all your containers at once. Otherwise, the manual steps above work fine for one-off fixes.
\nBy the way, if you run into different data recovery issues — like Git object corruption — the same instinct applies: move don't delete, have a rollback plan.
\nUnraid made this change to better track which containers it's managing versus containers you might have created manually or through other tools. It's actually a good change for container management, but it does mean old containers need this label added retroactively.
\nHopefully this saves someone else the frustration of staring at dozens of \"3rd party\" containers after an upgrade! If this saved you an hour, the Gist is there to share.
", "url": "https://lukemanning.ie/blog/unraid-docker-label-fix", "title": "Fixing Unraid Docker Containers After Upgrading - The Missing Label Problem", "summary": "So I just upgraded my Unraid server from a very old 6.9 installation to 7.0.1, and immediately ran into a fun little problem: all my Docker containers were suddenly marked as \"3rd party.\" Couldn't edit them, couldn't check for updates, couldn't do anything except stare at them in frustration.
\nThere's a similar thread documented here in the Unraid Forums which I found helpful.
\nTurns out, Dockerman in Unraid 7.0+ (Unraid's Docker management plugin) uses a container label net.unraid.docker.managed=dockerman to determine which containers it actually manages. My containers were created way back on an older version of Unraid, so they didn't have this label. Without it, Dockerman basically said \"not my problem\" and refused to touch them.
The nuclear option would be to recreate every single container from scratch, but that's tedious and error-prone when you have dozens of containers with specific configurations. I know I could reuse an existing template as well.. but it still felt like a tedious task. So I did what I normally do and implemented an overly engineered solution to a problem that I could fixed pretty quickly doing it manually.
\nThe good news is you can add the missing label using Docker's CLI without manually reconfiguring everything.
\nI started by testing this on one container first - Jackett, which is one of my torrent index containers. I wanted to make sure the whole process worked before batch-processing everything.
\nFirst, I generated the docker run command using runlike (it inspects a running container and outputs the equivalent docker run command):
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \\\n assaflavie/runlike Jackett > /tmp/jackett_run.sh(Note: you'll need root privileges to run docker commands in the Unraid terminal - otherwise you'll get \"permission denied\" errors.)
\nThen I reviewed what runlike generated:
\ncat /tmp/jackett_run.shThis showed me the full docker run command with all the volumes, ports, environment variables - exact configuration for my Jackett container.
\nNext, I needed to add the missing label. I opened the file with nano:
\nnano /tmp/jackett_run.shAnd added --label net.unraid.docker.managed=dockerman and --detach=true right after docker run:
docker run --label net.unraid.docker.managed=dockerman --detach=true --name=Jackett ...Then I stopped the old container, removed it, and recreated it with the new configuration:
\ndocker stop Jackett\ndocker rm Jackett\nbash /tmp/jackett_run.shFinally, I needed to make Unraid fully recognize the container. In the Docker tab, I clicked on Jackett to open its dropdown menu and selected \"Force Update.\" This tells Unraid to add its other management labels.
\nAfter doing this, Jackett showed up properly in Unraid instead of as \"3rd party.\" Success!
\nOnce I verified the manual process worked, I created a script to batch-process all my containers. The script loops through all running containers, generates the run command, injects the label, recreates the container, and queues a Force Update:
\nhttps://gist.github.com/ManningWorks/0f57db9c450d7b7dea741e585b31d23e
\nTo use this, I added it to Unraid's User Scripts plugin (you can install it from Community Applications). This lets you run one-off scripts safely instead of running them directly in the Bash Shell.
\nIf you're comfortable with scripts, this will process all your containers at once. Otherwise, the manual steps above work fine for one-off fixes.
\nBy the way, if you run into different data recovery issues — like Git object corruption — the same instinct applies: move don't delete, have a rollback plan.
\nUnraid made this change to better track which containers it's managing versus containers you might have created manually or through other tools. It's actually a good change for container management, but it does mean old containers need this label added retroactively.
\nHopefully this saves someone else the frustration of staring at dozens of \"3rd party\" containers after an upgrade! If this saved you an hour, the Gist is there to share.
", "date_modified": "2025-11-26T00:00:00.000Z", "tags": [ "homelab", "docker" ] }, { "id": "https://lukemanning.ie/blog/building-my-career-timeline", "content_html": "I just added a career timeline to my About page. Not because it's a resume requirement, but because the process of building it taught me something unexpected about both code and career.
\nI've spent years helping people solve complex technical problems. My job is to take something complicated and make it make sense. But I realized I'd never applied that same principle to my own career story.
\nLooking back at 10+ years in tech support and technical leadership, it's easy to just see it as \"a bunch of jobs.\" But when you stop and actually write down what you learned at each stage, you might notice some patterns emerge.
\nSo I decided to build a timeline component for my About page. Not just to list where I worked but to capture the real lessons from each role and the things I wish I'd known at the time. This was part of a broader effort to make my About page less of a text dump — I also built a responsive photo card around the same time (the post never made it past draft).
\nI started by just writing the timeline directly in my About page component. Bad move. I had this massive chunk of JSX mixed with my page layout:
\n// This got messy FAST\n<div className=\"space-y-8\">\n <div className=\"border-l-4 border-quantum-violet pl-6\">\n <div className=\"flex items-center gap-2 mb-2\">\n <span className=\"bg-quantum-violet text-white px-3 py-1 rounded-full text-sm\">\n 2014-2016\n </span>\n <h3 className=\"font-semibold\">Technical Support Engineer</h3>\n <span className=\"text-neural-silver\">@ Dell EMC</span>\n </div>\n <!-- ... way more content ... -->\n </div>\n <!-- ... repeat for every job ... -->\n</div>After a while of copying and pasting, I realized this was going to be a nightmare to maintain. Every change would require digging through this nested structure, and the About page component was already getting long.
\nOkay, let's make this a proper React component. I created src/components/Journey.tsx and moved the timeline logic there:
export default function Journey() {\n return (\n <section className=\"space-y-8\">\n <h2 className=\"text-2xl font-bold text-quantum-violet\">My Journey</h2>\n <div className=\"space-y-8\">\n {/* Timeline entries here */}\n </div>\n </section>\n );\n}\n\n// In src/app/about/page.tsx\nimport Journey from '@/components/Journey'\n\nexport default function AboutPage() {\n return (\n <main className=\"max-w-4xl mx-auto px-6 py-12\">\n <Journey />\n </main>\n )\n}Better, but now I had another problem. How do I pass job data? I could hardcode it.. but that felt wrong. I spent some time debating whether to create a separate data file, use props, or just keep it simple.
\nI ended up hardcoding it first because I wanted to see if the component would even work.
\nThe timeline needed to be responsive. On mobile, everything should stack vertically. On desktop, I wanted the date and title on the left, content on the right.
\nMy first attempt with Tailwind's grid system:
\n<div className=\"grid grid-cols-1 lg:grid-cols-12 gap-4\">\n <div className=\"lg:col-span-4\">\n {/* Date and title */}\n </div>\n <div className=\"lg:col-span-8\">\n {/* Content */}\n </div>\n</div>This worked, but the alignment was weird. The date badge was floating, and the content didn't line up properly. I spent too long trying flex-grow, gap-4, mt-4, switching between items-start and items-center before realizing I needed to structure it differently.
// Second attempt - tried flexbox\n<div className=\"flex flex-col lg:flex-row gap-4\">\n <div className=\"lg:w-1/3\">\n {/* Date and title */}\n </div>\n <div className=\"lg:w-2/3\">\n {/* Content */}\n </div>\n</div>This got the horizontal layout right but broke the vertical timeline effect. The border-left I was using for the timeline line wouldn't span the full height of the entry anymore - it got chopped off at the first child element.
\nThe alignment was weird because the date badge sat awkwardly in the left column, disconnected from the timeline border, and there was no way to make it overlap properly without complex positioning.
\nWhat finally worked:
\n// Full entry structure\n<div className=\"border-l-4 border-quantum-violet pl-6 relative\">\n <div className=\"absolute -left-3 top-0\">\n <span className=\"bg-quantum-violet text-white px-3 py-1 rounded-full text-sm\">\n 2014-2016\n </span>\n </div>\n \n <div className=\"grid grid-cols-1 lg:grid-cols-12 gap-4 mt-2\">\n <div className=\"lg:col-span-4\">\n <h3 className=\"font-semibold\">Technical Support Engineer</h3>\n <span className=\"text-neural-silver\">@ Dell EMC</span>\n </div>\n <div className=\"lg:col-span-8\">\n <p className=\"text-code-carbon mb-3\">\n Learned systematic troubleshooting under pressure through the GSAP program.\n </p>\n <div className=\"border-l-2 border-automation-amber pl-4\">\n <p className=\"text-sm text-automation-amber font-medium\">\n Key Learning: Part of career growth is knowing when you're ready for the next challenge.\n </p>\n </div>\n </div>\n </div>\n</div>The absolute -left-3 positions the badge 0.75rem (3 * 0.25rem) to the left of the border. Since the border is border-l-4 (1rem), this pulls the badge halfway across the border, creating that centered overlap effect I was going for.
The key insight was using the border-left as the timeline line and positioning the date badge to overlap it. Obvious in hindsight, but it took me a couple of attempts to get there.
\nIf I were starting this component again, knowing what I know now:
\nThat said, the messy approach worked. It let me iterate quickly and focus on the content rather than getting stuck in architecture. A previous manager of mine once said \"Don't let perfect block the road to progress\" and that still resonates with me today. That was the approach I took here.
\nThe component finally worked. The layout was responsive, the date badges aligned, everything rendered correctly. I could have stopped there.
\nBuilding the component took a few hours including all the debugging. Writing the actual content took significantly more reflection.
\nLooking back at each role, patterns I hadn't noticed before started to emerge.
\nThis was my first proper job, and the GSAP program laid the essential foundation for my entire career. I learned systematic troubleshooting, how to communicate clearly when things are broken and someone's waiting on you. But the role also helped me understand my own value and my drive to take on more. Looking back, I was frustrated that there wasn't more room to grow. That's when I realized: I needed to find a culture that would let me meet that ambition head-on. Past-me was ready for the next challenge—I just hadn't figured out how to ask for it yet.
\nThis job completely reshaped my definition of what technical support can be. I became a dedicated support resource for one of our largest customers in EMEA, working on-site with them, running demos for the sales team, and diving into the Engine APIs to write my own scripts. Great. But then I hit a wall—my passion and responsibilities had expanded, but the role hadn't. I spent way too long thinking I should just be grateful before realizing: no, I needed to find a place that would recognize that contribution. The irony was not lost on me that I'd outgrown the role that had taught me so much.
\nI joined Cohesity in March 2020. Two weeks later, the world shut down. Starting a new job remotely, on a new product, after years of being the go-to person at Nuix—the imposter syndrome was real. I spent that year proving to myself that I could do it again. Learning a complex product from scratch, building new relationships through a screen, finding my footing in a company I'd never set foot in. Here's what I learned the hard way: your reputation doesn't transfer. Your ability to build one does.
\nThe imposter syndrome from joining during Covid hadn't fully faded, but something had shifted. Management started routing the harder cases my way—complex database and backup issues that needed more than a standard playbook. I also knew early on that I wanted Tech Lead, so I stopped waiting for the title and started doing the job. Mentoring new hires, sharing what I knew, making myself useful beyond my own ticket queue. Honestly, I was surprised how quickly I stopped caring about the title once I started the actual work.
\nMy title is Technical Lead, which in practice means I'm the person the team comes to when something doesn't make sense. As much as I love getting my hands on a weird, messy, complex problem, the real win for me isn't fixing it. It's turning around and showing my team how they can solve it too. I've also started noticing patterns beyond individual cases. Gaps in how we worked, how we shared knowledge. One change started as a tool I built without asking permission, shared with the team, and watched quietly become the new standard. I'm still facepalming that this worked so well—sometimes the best way to drive change is to build the thing first and ask for forgiveness later.
\nWriting this timeline forced me to articulate lessons I'd internalized but never expressed. I thought I knew what I learned at each job, but putting it on paper revealed patterns I hadn't seen.
\nMy path definitely wasn't a straight shot up. Lateral moves, expanded roles, finding opportunities to take on more - that was my actual growth. Growth is rarely linear.
\nThe technical skills matter (I can build the component), but understanding WHY I'm building it makes it meaningful. That's the part that sticks with you.
\nI started writing this thinking I was just documenting where I'd been. I ended up learning something about where I'm going.
", "url": "https://lukemanning.ie/blog/building-my-career-timeline", "title": "Building my career timeline", "summary": "I just added a career timeline to my About page. Not because it's a resume requirement, but because the process of building it taught me something unexpected about both code and career.
\nI've spent years helping people solve complex technical problems. My job is to take something complicated and make it make sense. But I realized I'd never applied that same principle to my own career story.
\nLooking back at 10+ years in tech support and technical leadership, it's easy to just see it as \"a bunch of jobs.\" But when you stop and actually write down what you learned at each stage, you might notice some patterns emerge.
\nSo I decided to build a timeline component for my About page. Not just to list where I worked but to capture the real lessons from each role and the things I wish I'd known at the time. This was part of a broader effort to make my About page less of a text dump — I also built a responsive photo card around the same time (the post never made it past draft).
\nI started by just writing the timeline directly in my About page component. Bad move. I had this massive chunk of JSX mixed with my page layout:
\n// This got messy FAST\n<div className=\"space-y-8\">\n <div className=\"border-l-4 border-quantum-violet pl-6\">\n <div className=\"flex items-center gap-2 mb-2\">\n <span className=\"bg-quantum-violet text-white px-3 py-1 rounded-full text-sm\">\n 2014-2016\n </span>\n <h3 className=\"font-semibold\">Technical Support Engineer</h3>\n <span className=\"text-neural-silver\">@ Dell EMC</span>\n </div>\n <!-- ... way more content ... -->\n </div>\n <!-- ... repeat for every job ... -->\n</div>After a while of copying and pasting, I realized this was going to be a nightmare to maintain. Every change would require digging through this nested structure, and the About page component was already getting long.
\nOkay, let's make this a proper React component. I created src/components/Journey.tsx and moved the timeline logic there:
export default function Journey() {\n return (\n <section className=\"space-y-8\">\n <h2 className=\"text-2xl font-bold text-quantum-violet\">My Journey</h2>\n <div className=\"space-y-8\">\n {/* Timeline entries here */}\n </div>\n </section>\n );\n}\n\n// In src/app/about/page.tsx\nimport Journey from '@/components/Journey'\n\nexport default function AboutPage() {\n return (\n <main className=\"max-w-4xl mx-auto px-6 py-12\">\n <Journey />\n </main>\n )\n}Better, but now I had another problem. How do I pass job data? I could hardcode it.. but that felt wrong. I spent some time debating whether to create a separate data file, use props, or just keep it simple.
\nI ended up hardcoding it first because I wanted to see if the component would even work.
\nThe timeline needed to be responsive. On mobile, everything should stack vertically. On desktop, I wanted the date and title on the left, content on the right.
\nMy first attempt with Tailwind's grid system:
\n<div className=\"grid grid-cols-1 lg:grid-cols-12 gap-4\">\n <div className=\"lg:col-span-4\">\n {/* Date and title */}\n </div>\n <div className=\"lg:col-span-8\">\n {/* Content */}\n </div>\n</div>This worked, but the alignment was weird. The date badge was floating, and the content didn't line up properly. I spent too long trying flex-grow, gap-4, mt-4, switching between items-start and items-center before realizing I needed to structure it differently.
// Second attempt - tried flexbox\n<div className=\"flex flex-col lg:flex-row gap-4\">\n <div className=\"lg:w-1/3\">\n {/* Date and title */}\n </div>\n <div className=\"lg:w-2/3\">\n {/* Content */}\n </div>\n</div>This got the horizontal layout right but broke the vertical timeline effect. The border-left I was using for the timeline line wouldn't span the full height of the entry anymore - it got chopped off at the first child element.
\nThe alignment was weird because the date badge sat awkwardly in the left column, disconnected from the timeline border, and there was no way to make it overlap properly without complex positioning.
\nWhat finally worked:
\n// Full entry structure\n<div className=\"border-l-4 border-quantum-violet pl-6 relative\">\n <div className=\"absolute -left-3 top-0\">\n <span className=\"bg-quantum-violet text-white px-3 py-1 rounded-full text-sm\">\n 2014-2016\n </span>\n </div>\n \n <div className=\"grid grid-cols-1 lg:grid-cols-12 gap-4 mt-2\">\n <div className=\"lg:col-span-4\">\n <h3 className=\"font-semibold\">Technical Support Engineer</h3>\n <span className=\"text-neural-silver\">@ Dell EMC</span>\n </div>\n <div className=\"lg:col-span-8\">\n <p className=\"text-code-carbon mb-3\">\n Learned systematic troubleshooting under pressure through the GSAP program.\n </p>\n <div className=\"border-l-2 border-automation-amber pl-4\">\n <p className=\"text-sm text-automation-amber font-medium\">\n Key Learning: Part of career growth is knowing when you're ready for the next challenge.\n </p>\n </div>\n </div>\n </div>\n</div>The absolute -left-3 positions the badge 0.75rem (3 * 0.25rem) to the left of the border. Since the border is border-l-4 (1rem), this pulls the badge halfway across the border, creating that centered overlap effect I was going for.
The key insight was using the border-left as the timeline line and positioning the date badge to overlap it. Obvious in hindsight, but it took me a couple of attempts to get there.
\nIf I were starting this component again, knowing what I know now:
\nThat said, the messy approach worked. It let me iterate quickly and focus on the content rather than getting stuck in architecture. A previous manager of mine once said \"Don't let perfect block the road to progress\" and that still resonates with me today. That was the approach I took here.
\nThe component finally worked. The layout was responsive, the date badges aligned, everything rendered correctly. I could have stopped there.
\nBuilding the component took a few hours including all the debugging. Writing the actual content took significantly more reflection.
\nLooking back at each role, patterns I hadn't noticed before started to emerge.
\nThis was my first proper job, and the GSAP program laid the essential foundation for my entire career. I learned systematic troubleshooting, how to communicate clearly when things are broken and someone's waiting on you. But the role also helped me understand my own value and my drive to take on more. Looking back, I was frustrated that there wasn't more room to grow. That's when I realized: I needed to find a culture that would let me meet that ambition head-on. Past-me was ready for the next challenge—I just hadn't figured out how to ask for it yet.
\nThis job completely reshaped my definition of what technical support can be. I became a dedicated support resource for one of our largest customers in EMEA, working on-site with them, running demos for the sales team, and diving into the Engine APIs to write my own scripts. Great. But then I hit a wall—my passion and responsibilities had expanded, but the role hadn't. I spent way too long thinking I should just be grateful before realizing: no, I needed to find a place that would recognize that contribution. The irony was not lost on me that I'd outgrown the role that had taught me so much.
\nI joined Cohesity in March 2020. Two weeks later, the world shut down. Starting a new job remotely, on a new product, after years of being the go-to person at Nuix—the imposter syndrome was real. I spent that year proving to myself that I could do it again. Learning a complex product from scratch, building new relationships through a screen, finding my footing in a company I'd never set foot in. Here's what I learned the hard way: your reputation doesn't transfer. Your ability to build one does.
\nThe imposter syndrome from joining during Covid hadn't fully faded, but something had shifted. Management started routing the harder cases my way—complex database and backup issues that needed more than a standard playbook. I also knew early on that I wanted Tech Lead, so I stopped waiting for the title and started doing the job. Mentoring new hires, sharing what I knew, making myself useful beyond my own ticket queue. Honestly, I was surprised how quickly I stopped caring about the title once I started the actual work.
\nMy title is Technical Lead, which in practice means I'm the person the team comes to when something doesn't make sense. As much as I love getting my hands on a weird, messy, complex problem, the real win for me isn't fixing it. It's turning around and showing my team how they can solve it too. I've also started noticing patterns beyond individual cases. Gaps in how we worked, how we shared knowledge. One change started as a tool I built without asking permission, shared with the team, and watched quietly become the new standard. I'm still facepalming that this worked so well—sometimes the best way to drive change is to build the thing first and ask for forgiveness later.
\nWriting this timeline forced me to articulate lessons I'd internalized but never expressed. I thought I knew what I learned at each job, but putting it on paper revealed patterns I hadn't seen.
\nMy path definitely wasn't a straight shot up. Lateral moves, expanded roles, finding opportunities to take on more - that was my actual growth. Growth is rarely linear.
\nThe technical skills matter (I can build the component), but understanding WHY I'm building it makes it meaningful. That's the part that sticks with you.
\nI started writing this thinking I was just documenting where I'd been. I ended up learning something about where I'm going.
", "date_modified": "2025-11-24T00:00:00.000Z", "tags": [ "reflections" ] }, { "id": "https://lukemanning.ie/blog/adding-syntax-highlighting-shiki", "content_html": "I already had Velite working with Next.js (covered in my previous post), with posts in /content/posts/*.md and the dev server running on port 3000.
My code blocks were just... sad. Monospace text on a dark background. No syntax highlighting, no nothing. Made my blog posts look like they were written in Notepad.
\nFor reference, my versions:
\nThings might differ with other versions, especially with Next.js 16.
\nI wanted them to look like VS Code - proper colors for keywords, strings, functions, the whole deal. Shiki uses VS Code's actual syntax highlighting engine, so it seemed like the obvious choice.
\nTurns out \"obvious\" doesn't mean \"straightforward.\" Here's what I ran into.
\nI needed two packages: Shiki itself, and the rehype plugin to hook it into Velite's markdown processing:
\nnpm install @shikijs/rehype shikiIn my case, this grabbed shiki ^3.15.0 and @shikijs/rehype ^3.20.0.
\nNow it's time to hook this up in the Velite config. This is where I hit my first snag.
\nMy first attempt:
\nimport rehypeShiki from '@shikijs/rehype'\n\nexport default defineConfig({\n collections: { /* ... */ },\n markdown: {\n rehypePlugins: [\n [rehypeShiki as any, { theme: 'github-dark' }]\n ]\n }\n})Error:
\nExpected \"]\" but found \"as\"The error was straightforward - my config file was velite.config.js (JavaScript), but I was using TypeScript syntax (as any). Just remove the type cast:
markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n}I kept getting syntax errors because I couldn't get the braces right. The markdown key needs to be at the same level as collections, not inside it:
// This doesn't work - markdown inside collections\nexport default defineConfig({\n collections: {\n posts: { /* ... */ },\n markdown: { /* ... */ }\n }\n})\n\n// What actually works - markdown as sibling to collections\nexport default defineConfig({\n collections: {\n posts: { /* ... */ }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})Count your braces carefully. I had to trace through mine multiple times.
\nOne more thing: after changing velite.config.js, I had to clear the cache or nothing would work:
npm run clean:devStop the dev server first, run the clean command, then restart. I forgot this the first time and spent 15 minutes wondering why nothing changed.
\nOnce Shiki was working, I had CSS fighting with it. My existing styles in /src/app/globals.css were overriding Shiki's colors.
I restarted the dev server, refreshed the page, and... nothing had changed. Code blocks were still just monospace text in my custom colors.
\nWait, what? Shiki was supposed to be handling colors now.
\nI opened DevTools and saw inline styles like style=\"color: #ff79c6\" on each code token. I realized Shiki generates these because it needs exact color control for syntax highlighting. My CSS's text-color property was more specific and overriding them.
When I disabled text-color in DevTools, Shiki colors instantly appeared. So I just needed to remove that property from my CSS and let Shiki's colors come through.
/* My initial approach - this was fighting with Shiki */\ncode {\n @apply bg-code-carbon text-neural-silver px-1.5 py-0.5 rounded font-mono text-sm;\n}\n\npre {\n @apply bg-code-carbon/35 p-4 rounded-lg overflow-x-auto font-mono text-sm m-4;\n}\n\npre code {\n @apply bg-transparent p-0 text-code-carbon;\n}The problem was that my colors were overriding Shiki's syntax highlighting.
\nHere's what's happening: Shiki generates inline styles on each code token (like style=\"color: #ff79c6\" for keywords). My CSS was more specific and overriding these. What finally worked was letting Shiki handle colors for code blocks and only styling inline code myself:
/* Inline code */\narticle :not(pre) > code {\n @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;\n}\n\n/* Code block container - let Shiki handle colors */\npre {\n @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;\n}\n\n/* Reset for code inside pre */\npre code {\n @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;\n}When I checked a blog post after getting the CSS right, I finally saw:
\nconst foo = 'bar' in a paragraph) had my custom background colorconst, function, import) in purple/pink'github-dark') in greenconst foo = 'bar', I saw const in one color and 'bar' in a different colorWhen my code blocks were still just monochrome text at first, I checked Shiki's theme preview to see what github-dark was supposed to look like. That's when I realized the Velite cache hadn't cleared properly. Ran npm run clean:dev one more time, restarted the dev server, and it worked.
I noticed code blocks without a language specified don't get Shiki styling:
\n```\nThis has no syntax highlighting\n```Two options:
\ntext or plaintext for non-codepre code {\n @apply bg-transparent p-0 text-inherit;\n}I went with always specifying languages since it's more explicit.
\nAfter all that debugging, here's what finally worked. Two files needed changes:
\nvelite.config.js (mine's in the project root):
\nimport { defineConfig, s } from 'velite'\nimport rehypeShiki from '@shikijs/rehype'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})globals.css (at /src/app/globals.css):
/* Inline code */\narticle :not(pre) > code {\n @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;\n}\n\npre {\n @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;\n}\n\n/* Reset prose code block styling - let Shiki handle it */\npre code {\n @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;\n}Thinking back on it, the thing that would have saved me the most time was adding Shiki first. I spent time manually styling code blocks - choosing colors, tweaking spacing, getting everything just right. Then Shiki took over and I had to undo most of it.
\nOther stuff that tripped me up:
\nFile extensions matter - .js files can't use TypeScript syntax. Took me a few minutes of staring at Expected \"]\" but found \"as\" before I remembered the config was JavaScript, not TypeScript.
Config structure is finicky - Velite has specific expectations about where keys go. Count your braces carefully.
\nSpecify languages in markdown - ```javascript gives proper highlighting, but ``` without a language just shows plain text.
Syntax highlighting is working now and my code blocks actually look like code blocks. Took way longer than I expected, but at least they look like code blocks now.
", "url": "https://lukemanning.ie/blog/adding-syntax-highlighting-shiki", "title": "Adding Shiki for a pop of colour in my code blocks was a struggle", "summary": "I already had Velite working with Next.js (covered in my previous post), with posts in /content/posts/*.md and the dev server running on port 3000.
My code blocks were just... sad. Monospace text on a dark background. No syntax highlighting, no nothing. Made my blog posts look like they were written in Notepad.
\nFor reference, my versions:
\nThings might differ with other versions, especially with Next.js 16.
\nI wanted them to look like VS Code - proper colors for keywords, strings, functions, the whole deal. Shiki uses VS Code's actual syntax highlighting engine, so it seemed like the obvious choice.
\nTurns out \"obvious\" doesn't mean \"straightforward.\" Here's what I ran into.
\nI needed two packages: Shiki itself, and the rehype plugin to hook it into Velite's markdown processing:
\nnpm install @shikijs/rehype shikiIn my case, this grabbed shiki ^3.15.0 and @shikijs/rehype ^3.20.0.
\nNow it's time to hook this up in the Velite config. This is where I hit my first snag.
\nMy first attempt:
\nimport rehypeShiki from '@shikijs/rehype'\n\nexport default defineConfig({\n collections: { /* ... */ },\n markdown: {\n rehypePlugins: [\n [rehypeShiki as any, { theme: 'github-dark' }]\n ]\n }\n})Error:
\nExpected \"]\" but found \"as\"The error was straightforward - my config file was velite.config.js (JavaScript), but I was using TypeScript syntax (as any). Just remove the type cast:
markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n}I kept getting syntax errors because I couldn't get the braces right. The markdown key needs to be at the same level as collections, not inside it:
// This doesn't work - markdown inside collections\nexport default defineConfig({\n collections: {\n posts: { /* ... */ },\n markdown: { /* ... */ }\n }\n})\n\n// What actually works - markdown as sibling to collections\nexport default defineConfig({\n collections: {\n posts: { /* ... */ }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})Count your braces carefully. I had to trace through mine multiple times.
\nOne more thing: after changing velite.config.js, I had to clear the cache or nothing would work:
npm run clean:devStop the dev server first, run the clean command, then restart. I forgot this the first time and spent 15 minutes wondering why nothing changed.
\nOnce Shiki was working, I had CSS fighting with it. My existing styles in /src/app/globals.css were overriding Shiki's colors.
I restarted the dev server, refreshed the page, and... nothing had changed. Code blocks were still just monospace text in my custom colors.
\nWait, what? Shiki was supposed to be handling colors now.
\nI opened DevTools and saw inline styles like style=\"color: #ff79c6\" on each code token. I realized Shiki generates these because it needs exact color control for syntax highlighting. My CSS's text-color property was more specific and overriding them.
When I disabled text-color in DevTools, Shiki colors instantly appeared. So I just needed to remove that property from my CSS and let Shiki's colors come through.
/* My initial approach - this was fighting with Shiki */\ncode {\n @apply bg-code-carbon text-neural-silver px-1.5 py-0.5 rounded font-mono text-sm;\n}\n\npre {\n @apply bg-code-carbon/35 p-4 rounded-lg overflow-x-auto font-mono text-sm m-4;\n}\n\npre code {\n @apply bg-transparent p-0 text-code-carbon;\n}The problem was that my colors were overriding Shiki's syntax highlighting.
\nHere's what's happening: Shiki generates inline styles on each code token (like style=\"color: #ff79c6\" for keywords). My CSS was more specific and overriding these. What finally worked was letting Shiki handle colors for code blocks and only styling inline code myself:
/* Inline code */\narticle :not(pre) > code {\n @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;\n}\n\n/* Code block container - let Shiki handle colors */\npre {\n @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;\n}\n\n/* Reset for code inside pre */\npre code {\n @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;\n}When I checked a blog post after getting the CSS right, I finally saw:
\nconst foo = 'bar' in a paragraph) had my custom background colorconst, function, import) in purple/pink'github-dark') in greenconst foo = 'bar', I saw const in one color and 'bar' in a different colorWhen my code blocks were still just monochrome text at first, I checked Shiki's theme preview to see what github-dark was supposed to look like. That's when I realized the Velite cache hadn't cleared properly. Ran npm run clean:dev one more time, restarted the dev server, and it worked.
I noticed code blocks without a language specified don't get Shiki styling:
\n```\nThis has no syntax highlighting\n```Two options:
\ntext or plaintext for non-codepre code {\n @apply bg-transparent p-0 text-inherit;\n}I went with always specifying languages since it's more explicit.
\nAfter all that debugging, here's what finally worked. Two files needed changes:
\nvelite.config.js (mine's in the project root):
\nimport { defineConfig, s } from 'velite'\nimport rehypeShiki from '@shikijs/rehype'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n },\n markdown: {\n rehypePlugins: [\n [rehypeShiki, { theme: 'github-dark' }]\n ]\n }\n})globals.css (at /src/app/globals.css):
/* Inline code */\narticle :not(pre) > code {\n @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;\n}\n\npre {\n @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;\n}\n\n/* Reset prose code block styling - let Shiki handle it */\npre code {\n @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;\n}Thinking back on it, the thing that would have saved me the most time was adding Shiki first. I spent time manually styling code blocks - choosing colors, tweaking spacing, getting everything just right. Then Shiki took over and I had to undo most of it.
\nOther stuff that tripped me up:
\nFile extensions matter - .js files can't use TypeScript syntax. Took me a few minutes of staring at Expected \"]\" but found \"as\" before I remembered the config was JavaScript, not TypeScript.
Config structure is finicky - Velite has specific expectations about where keys go. Count your braces carefully.
\nSpecify languages in markdown - ```javascript gives proper highlighting, but ``` without a language just shows plain text.
Syntax highlighting is working now and my code blocks actually look like code blocks. Took way longer than I expected, but at least they look like code blocks now.
", "date_modified": "2025-11-23T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/setting-up-velite-nextjs-revised", "content_html": "I spent hours yesterday fighting with Velite and Next.js 16. The docs said it should \"just work.\" Instead I got TypeScript errors about exports not found, build failures from missing files in the schema, and a type error that turned out to be a Next.js 16 breaking change.
\nHere's what happened.
\nI got the idea to create a personal blog site where I can share what I'm working on. I did some research on various platforms, and consulted with Claude on potential options. In the end I decided a simple site based on static markdown files seemed like the most suitable option for my needs. I had no idea how to go about doing that so I googled it.
\nEvery article pointed to Contentlayer for managing a simple blog. Except Contentlayer isn't maintained anymore. So I did what any developer does: searched Reddit for \"what to use instead of Contentlayer.\" The consensus seemed to be that Velite was the successor.
\nVelite offers a lot of additional features like build-time processing and Typescript generation, which I knew nothing about at that point, but those turned out to be useful features I'd use later. I just wanted markdown files to show up as blog posts and Velite seemed to be a suitable option for that.
\nSo I spun up a fresh Next.js project using npx create-next-app@latest and selected: TypeScript, ESLint, Tailwind CSS, App Router, Turbopack.
Then I ran npm install velite and created a basic config.
This is what my setup looked like:
\nFile structure:
\n.\n├── velite.config.js\n├── next.config.ts\n├── tsconfig.json\n├── .velite/ # Generated by Velite\n├── posts/\n│ └── my-first-post.md\n└── app/\n ├── page.tsx\n └── blog/\n └── [slug]/\n └── page.tsx\nI installed Velite, created velite.config.js, ran npx velite, and tried to import posts:
import { posts } from 'velite';But immediately encountered a problem:\nError: The export posts was not found in module velite/dist/index.js
I stared at this for quite a few minutes. I assumed I'd import from the Velite package itself—that's how most npm packages work, right?
\nThen I actually checked the Velite docs again. Oh—you import from the .velite folder that Velite generates, not the package itself.
So I tried:
\nimport { posts } from './.velite';That worked. But then I found the docs mentioned path aliases as a cleaner option. So I created one in tsconfig.json:
{\n \"compilerOptions\": {\n \"paths\": {\n \"@/*\": [\"./*\"],\n \"#site/content\": [\"./.velite\"]\n }\n }\n}After restarting the dev server, I tested the path alias approach:
\nimport { posts } from '#site/content';That worked.
\nSo I tried running Velite:
\n[VELITE] Patterns must be a string (non empty) or an array of stringsI checked my config—everything looked fine. I'd copied it straight from the Velite quick start docs, so how could it be wrong?
\nThen I noticed the docs had this others collection:
collections: {\n posts: { /* ... */ },\n others: {\n // other collection schema options\n }\n}The others bit was just a placeholder showing you can have multiple collections. It wasn't required. I'd pasted it in verbatim without thinking about it.
Velite was complaining because the others collection didn't have a pattern field (like pattern: 'others/**/*.md'). Without a pattern, Velite doesn't know what files to include.
Deleted the others collection entirely. Ran npx velite again. This time: ✓ posts (1 documents).
Velite was running now. But looking at the Velite docs, I saw examples with cover and video fields. Figured I'd add those too—why not?
So I copied them into my schema:
\ncover: s.image(),\nvideo: s.file(),And put them in my test post:
\n---\ntitle: My First Post\nslug: my-first-post\ndate: 2025-11-16\n---\ncover: cover.jpg\nvideo: video.mp4But these files didn't exist. Velite errored out.
\nI should have started with a minimal post:
\n---\ntitle: My First Post\nslug: my-first-post\ndate: 2025-11-16\n---\nThis is some markdown content.Same pattern as before—the docs were showing me what's possible, not what I actually need. I made them optional in my schema:
\ncover: s.image().optional(),\nvideo: s.file().optional(),Updated the schema, ran npx velite, and it worked.
I got to the point where I could import posts in a listing page, but individual post routes kept 404ing even though the files were there.
\nI'd copied some example code from the docs for dynamic routes:
\nexport default function PostPage({ params }: { params: { slug: string } }) {\n const post = posts.find((p) => p.slug === params.slug);\n // ...\n}TypeScript was complaining that params should be a Promise<{ slug: string }> instead of just { slug: string }. I ignored it at first because I assumed the example code was correct.
Turns out the example was from Next.js 14 or earlier. Next.js 15 changed params to be async for better performance, and Next.js 16 kept that change.
\nHere's what happens without await: Next.js expects an async function to handle the params promise. If you don't await it, the route handler won't execute properly—it just silently 404s.
So I needed to await the params:
\nexport default async function PostPage({\n params\n}: {\n params: Promise<{ slug: string }>\n}) {\n const { slug } = await params;\n const post = posts.find((p) => p.slug === slug);\n // ..\n}After this change, my dynamic routes loaded. No more 404s.
\nThis one took me the longest. I copied the integration code from the Velite docs into next.config.ts:
const isDev = process.argv.indexOf('dev') !== -1\nconst isBuild = process.argv.indexOf('build') !== -1\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}Started the dev server. No errors. But Velite never ran. I could edit markdown files all day—nothing happened.
\nI'd been debugging for a while by this point and was stuck. I asked Claude for help, and it suggested adding some console.log statements to see what was actually in process.argv:
console.log('[DEBUG] isDev:', isDev, 'isBuild:', isBuild, 'argv:', process.argv)Output showed both isDev and isBuild as false:
[DEBUG] isDev: false isBuild: false argv: [\n '/home/luke/.nvm/versions/node/v24.11.1/bin/node',\n '/home/luke/workspace/lukemanning-site/node_modules/next/dist/server/lib/start-server.js'\n]So 'dev' and 'build' weren't in argv at all.
\nThe Velite integration code checks if 'dev' is in process.argv to decide whether to start watch mode. Since Turbopack's start-server.js doesn't include 'dev' in argv, that condition was never true—so Velite never started.
Next.js was using start-server.js internally instead of a simple command-line argument.
Claude suggested checking process.env.NODE_ENV as an alternative—since that's more reliable than parsing command-line arguments. Added that to my logging and saw it was set to 'development'. Worth a shot.
Changed it:
\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}Started the dev server again:
\n[VELITE] Building...\n✓ posts (1 documents)\n[VELITE] Watching for changes...Edited a markdown file:
\n[VELITE] Rebuilding...\n✓ posts (1 documents)Finally worked.
\nI think what's happening is:
\nstart-server.js as an intermediary instead of a simple next dev commandNODE_ENV environment variable is more reliable because it's set by Next.js regardless of how the server startsTurbopack is enabled by default in Next.js 16 when you choose the recommended defaults in create-next-app, so I didn't even realize I was using it. The Velite docs acknowledge that Turbopack breaks their webpack plugin, and they provide a process.argv workaround—but that workaround doesn't actually work with Next.js 16's Turbopack setup.
My understanding could be wrong—I didn't dig into the Next.js source code—but the NODE_ENV approach has been rock-solid for two weeks now.
After all that mess, here's where I ended up:
\nvelite.config.js:
\nimport { defineConfig, s } from 'velite'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n }\n})next.config.ts:
\nimport type { NextConfig } from \"next\";\n\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}\n\nconst nextConfig: NextConfig = {};\n\nexport default nextConfig;Just the paths section from tsconfig.json:
\n\"paths\": {\n \"@/*\": [\"./*\"],\n \"#site/content\": [\"./.velite\"]\n}Once you have Velite running with Next.js, you might also want to set up draft post filtering so unfinished posts don't accidentally go live, and add syntax highlighting with Shiki to make your code blocks actually readable.
", "url": "https://lukemanning.ie/blog/setting-up-velite-nextjs-revised", "title": "Setting Up Velite with Next.js 16", "summary": "I spent hours yesterday fighting with Velite and Next.js 16. The docs said it should \"just work.\" Instead I got TypeScript errors about exports not found, build failures from missing files in the schema, and a type error that turned out to be a Next.js 16 breaking change.
\nHere's what happened.
\nI got the idea to create a personal blog site where I can share what I'm working on. I did some research on various platforms, and consulted with Claude on potential options. In the end I decided a simple site based on static markdown files seemed like the most suitable option for my needs. I had no idea how to go about doing that so I googled it.
\nEvery article pointed to Contentlayer for managing a simple blog. Except Contentlayer isn't maintained anymore. So I did what any developer does: searched Reddit for \"what to use instead of Contentlayer.\" The consensus seemed to be that Velite was the successor.
\nVelite offers a lot of additional features like build-time processing and Typescript generation, which I knew nothing about at that point, but those turned out to be useful features I'd use later. I just wanted markdown files to show up as blog posts and Velite seemed to be a suitable option for that.
\nSo I spun up a fresh Next.js project using npx create-next-app@latest and selected: TypeScript, ESLint, Tailwind CSS, App Router, Turbopack.
Then I ran npm install velite and created a basic config.
This is what my setup looked like:
\nFile structure:
\n.\n├── velite.config.js\n├── next.config.ts\n├── tsconfig.json\n├── .velite/ # Generated by Velite\n├── posts/\n│ └── my-first-post.md\n└── app/\n ├── page.tsx\n └── blog/\n └── [slug]/\n └── page.tsx\nI installed Velite, created velite.config.js, ran npx velite, and tried to import posts:
import { posts } from 'velite';But immediately encountered a problem:\nError: The export posts was not found in module velite/dist/index.js
I stared at this for quite a few minutes. I assumed I'd import from the Velite package itself—that's how most npm packages work, right?
\nThen I actually checked the Velite docs again. Oh—you import from the .velite folder that Velite generates, not the package itself.
So I tried:
\nimport { posts } from './.velite';That worked. But then I found the docs mentioned path aliases as a cleaner option. So I created one in tsconfig.json:
{\n \"compilerOptions\": {\n \"paths\": {\n \"@/*\": [\"./*\"],\n \"#site/content\": [\"./.velite\"]\n }\n }\n}After restarting the dev server, I tested the path alias approach:
\nimport { posts } from '#site/content';That worked.
\nSo I tried running Velite:
\n[VELITE] Patterns must be a string (non empty) or an array of stringsI checked my config—everything looked fine. I'd copied it straight from the Velite quick start docs, so how could it be wrong?
\nThen I noticed the docs had this others collection:
collections: {\n posts: { /* ... */ },\n others: {\n // other collection schema options\n }\n}The others bit was just a placeholder showing you can have multiple collections. It wasn't required. I'd pasted it in verbatim without thinking about it.
Velite was complaining because the others collection didn't have a pattern field (like pattern: 'others/**/*.md'). Without a pattern, Velite doesn't know what files to include.
Deleted the others collection entirely. Ran npx velite again. This time: ✓ posts (1 documents).
Velite was running now. But looking at the Velite docs, I saw examples with cover and video fields. Figured I'd add those too—why not?
So I copied them into my schema:
\ncover: s.image(),\nvideo: s.file(),And put them in my test post:
\n---\ntitle: My First Post\nslug: my-first-post\ndate: 2025-11-16\n---\ncover: cover.jpg\nvideo: video.mp4But these files didn't exist. Velite errored out.
\nI should have started with a minimal post:
\n---\ntitle: My First Post\nslug: my-first-post\ndate: 2025-11-16\n---\nThis is some markdown content.Same pattern as before—the docs were showing me what's possible, not what I actually need. I made them optional in my schema:
\ncover: s.image().optional(),\nvideo: s.file().optional(),Updated the schema, ran npx velite, and it worked.
I got to the point where I could import posts in a listing page, but individual post routes kept 404ing even though the files were there.
\nI'd copied some example code from the docs for dynamic routes:
\nexport default function PostPage({ params }: { params: { slug: string } }) {\n const post = posts.find((p) => p.slug === params.slug);\n // ...\n}TypeScript was complaining that params should be a Promise<{ slug: string }> instead of just { slug: string }. I ignored it at first because I assumed the example code was correct.
Turns out the example was from Next.js 14 or earlier. Next.js 15 changed params to be async for better performance, and Next.js 16 kept that change.
\nHere's what happens without await: Next.js expects an async function to handle the params promise. If you don't await it, the route handler won't execute properly—it just silently 404s.
So I needed to await the params:
\nexport default async function PostPage({\n params\n}: {\n params: Promise<{ slug: string }>\n}) {\n const { slug } = await params;\n const post = posts.find((p) => p.slug === slug);\n // ..\n}After this change, my dynamic routes loaded. No more 404s.
\nThis one took me the longest. I copied the integration code from the Velite docs into next.config.ts:
const isDev = process.argv.indexOf('dev') !== -1\nconst isBuild = process.argv.indexOf('build') !== -1\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}Started the dev server. No errors. But Velite never ran. I could edit markdown files all day—nothing happened.
\nI'd been debugging for a while by this point and was stuck. I asked Claude for help, and it suggested adding some console.log statements to see what was actually in process.argv:
console.log('[DEBUG] isDev:', isDev, 'isBuild:', isBuild, 'argv:', process.argv)Output showed both isDev and isBuild as false:
[DEBUG] isDev: false isBuild: false argv: [\n '/home/luke/.nvm/versions/node/v24.11.1/bin/node',\n '/home/luke/workspace/lukemanning-site/node_modules/next/dist/server/lib/start-server.js'\n]So 'dev' and 'build' weren't in argv at all.
\nThe Velite integration code checks if 'dev' is in process.argv to decide whether to start watch mode. Since Turbopack's start-server.js doesn't include 'dev' in argv, that condition was never true—so Velite never started.
Next.js was using start-server.js internally instead of a simple command-line argument.
Claude suggested checking process.env.NODE_ENV as an alternative—since that's more reliable than parsing command-line arguments. Added that to my logging and saw it was set to 'development'. Worth a shot.
Changed it:
\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}Started the dev server again:
\n[VELITE] Building...\n✓ posts (1 documents)\n[VELITE] Watching for changes...Edited a markdown file:
\n[VELITE] Rebuilding...\n✓ posts (1 documents)Finally worked.
\nI think what's happening is:
\nstart-server.js as an intermediary instead of a simple next dev commandNODE_ENV environment variable is more reliable because it's set by Next.js regardless of how the server startsTurbopack is enabled by default in Next.js 16 when you choose the recommended defaults in create-next-app, so I didn't even realize I was using it. The Velite docs acknowledge that Turbopack breaks their webpack plugin, and they provide a process.argv workaround—but that workaround doesn't actually work with Next.js 16's Turbopack setup.
My understanding could be wrong—I didn't dig into the Next.js source code—but the NODE_ENV approach has been rock-solid for two weeks now.
After all that mess, here's where I ended up:
\nvelite.config.js:
\nimport { defineConfig, s } from 'velite'\n\nexport default defineConfig({\n collections: {\n posts: {\n name: 'Post',\n pattern: 'posts/**/*.md',\n schema: s\n .object({\n title: s.string().max(99),\n slug: s.slug('posts'),\n date: s.isodate(),\n cover: s.image().optional(),\n video: s.file().optional(),\n metadata: s.metadata(),\n excerpt: s.excerpt(),\n content: s.markdown()\n })\n .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))\n }\n }\n})next.config.ts:
\nimport type { NextConfig } from \"next\";\n\nconst isDev = process.env.NODE_ENV === 'development'\nconst isBuild = process.env.NODE_ENV === 'production'\nif (!process.env.VELITE_STARTED && (isDev || isBuild)) {\n process.env.VELITE_STARTED = '1'\n import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))\n}\n\nconst nextConfig: NextConfig = {};\n\nexport default nextConfig;Just the paths section from tsconfig.json:
\n\"paths\": {\n \"@/*\": [\"./*\"],\n \"#site/content\": [\"./.velite\"]\n}Once you have Velite running with Next.js, you might also want to set up draft post filtering so unfinished posts don't accidentally go live, and add syntax highlighting with Shiki to make your code blocks actually readable.
", "date_modified": "2025-11-16T00:00:00.000Z", "tags": [ "velite", "nextjs" ] }, { "id": "https://lukemanning.ie/blog/the-entrepreneurial-conundrum", "content_html": "\n\nNote: I actually wrote this on an older blog (Hence the publish date) but I wanted to resurrect the post here as I quite liked it. I remember sitting in a cafe typing this out on my phone. It felt oddly cathartic to write. Like finally admitting to myself that I spent more time thinking about ideas than executing ideas lifted a weight off my shoulders. That original blog is no more, but the content is still relevant, so I am re-posting it here.
\n
I have business ideas all the time. Every few days something pops into my head, usually triggered by some frustration or gap I notice in daily life. Sometimes I jot them down. I'll even flesh a few out, turn a vague thought into something that feels almost real.
\nThen I lose interest. Or I realise I'm not actually passionate about it. Or I just... don't do anything.
\nAnd then, inevitably, I see someone else ship the exact same thing. Usually some small tool or app I'd scribbled in my notes months earlier and never touched again. My first reaction is always \"That could have been me.\" It doesn't feel great.
\nIt's a cycle I've been in for years.
\nThere was a stretch where I kept ending up in these YouTube spirals late at night. Start with something legit, then an hour later you're watching a guy in an ice bath telling you that success comes down to waking up at 4 AM and filling out your gratitude journal. You know the type.
\nSome of them say it's about being uniquely positioned. Having the right resources, knowledge, and contacts at the right time. But if you're just starting out, how are you uniquely positioned? You're not. That's the point.
\nThen there's the Alex Hormozi approach. \"Fake it till you make it.\" Grind long enough, build the expertise, make the contacts, and eventually something clicks.
\nI've watched enough of these to know they all have a point. I've also watched enough to know none of them have the full picture. They all sound so sure of themselves. And I kept watching, so I guess it works.
\nNone of it really helped. The problem wasn't knowing how to start. It was starting.
\nOne of the YouTubers I kept coming back to was Dan Koe. He's the same guy who sent me down that self-actualisation rabbit hole I wrote about in my first post. His stuff on personal branding made sense to me: build in public, share your journey, create an audience around what you're learning.
\nBut here's where I get stuck: if I ship something half-baked, does that damage the brand I'm trying to build? Too many missteps and people stop taking you seriously. Or at least, that's what I worry about. Maybe that's just an excuse to not ship anything.
\nThen I look at Marc Louvion. I came across his profile on X a while back and started following along. He's had more failed startups than most people have ideas. He's transparent about all of them. And he's now followed by over 321k people specifically because of that transparency. He kept failing publicly and kept going.
\nI read that and think: the reputation fear is overblown. Just ship stuff, be honest about what doesn't work, people respect that. Then I go to actually put something out there and the voice comes back. It'll look half-baked.
\nReading The Million Dollar Weekend by Noah Kagan, I came across this:
\n\n\nOkay, so you have an idea for an app. How would you go about doing it? Here's the way most people, most wantrepreneurs, would do it:
\n\n
\n- Spend hours at home thinking about the app (and coming up with clever names for it).
\n- Spend $100 hiring your cousin to design a cool logo.
\n- Set up an LLC.
\n- Watch YouTube videos about apps, programming, and business.
\n- Consider signing up for a developer bootcamp and quickly realize coding is hard.
\n- Buy the domain name for the snazzy website you're going to build.
\n- Look into hiring a developer on UpWork and quickly realize it's cost prohibitive.
\n- Give up. Again.
\nNoah Kagan, The Million Dollar Weekend
\n
I've done most of this list. Not all of it, but enough that reading it felt like being called out by name. The domain buying especially. I've bought domains for ideas that never went anywhere. They're still renewing.
\nI'm still in the wantrepreneur camp. I know that. Reading that Noah Kagan excerpt didn't magically change anything, it just made the pattern visible.
\nOn the other side of this: the reactive day problem — even when you're building, it's easy to spend all your time answering other people's priorities and end up with nothing to show for it. The problem isn't just starting. It's protecting the space to actually execute.
\nThe conundrum for me isn't really about entrepreneurship at all. It's about the gap between having ideas and doing something with them. I know the theory. I've read the books, watched the videos, followed the people. Knowing the theory hasn't made me ship anything.
\nI don't have a neat resolution here. I'm still working through it. Maybe writing about it is a small step. Maybe it's just another form of thinking about the app instead of building it. I genuinely don't know.
\nAnd then there's the silence problem — even when you do start, the void is real. The silence after shipping something you care about is its own obstacle to continuing.
", "url": "https://lukemanning.ie/blog/the-entrepreneurial-conundrum", "title": "The Entrepreneurial Conundrum", "summary": "\n\nNote: I actually wrote this on an older blog (Hence the publish date) but I wanted to resurrect the post here as I quite liked it. I remember sitting in a cafe typing this out on my phone. It felt oddly cathartic to write. Like finally admitting to myself that I spent more time thinking about ideas than executing ideas lifted a weight off my shoulders. That original blog is no more, but the content is still relevant, so I am re-posting it here.
\n
I have business ideas all the time. Every few days something pops into my head, usually triggered by some frustration or gap I notice in daily life. Sometimes I jot them down. I'll even flesh a few out, turn a vague thought into something that feels almost real.
\nThen I lose interest. Or I realise I'm not actually passionate about it. Or I just... don't do anything.
\nAnd then, inevitably, I see someone else ship the exact same thing. Usually some small tool or app I'd scribbled in my notes months earlier and never touched again. My first reaction is always \"That could have been me.\" It doesn't feel great.
\nIt's a cycle I've been in for years.
\nThere was a stretch where I kept ending up in these YouTube spirals late at night. Start with something legit, then an hour later you're watching a guy in an ice bath telling you that success comes down to waking up at 4 AM and filling out your gratitude journal. You know the type.
\nSome of them say it's about being uniquely positioned. Having the right resources, knowledge, and contacts at the right time. But if you're just starting out, how are you uniquely positioned? You're not. That's the point.
\nThen there's the Alex Hormozi approach. \"Fake it till you make it.\" Grind long enough, build the expertise, make the contacts, and eventually something clicks.
\nI've watched enough of these to know they all have a point. I've also watched enough to know none of them have the full picture. They all sound so sure of themselves. And I kept watching, so I guess it works.
\nNone of it really helped. The problem wasn't knowing how to start. It was starting.
\nOne of the YouTubers I kept coming back to was Dan Koe. He's the same guy who sent me down that self-actualisation rabbit hole I wrote about in my first post. His stuff on personal branding made sense to me: build in public, share your journey, create an audience around what you're learning.
\nBut here's where I get stuck: if I ship something half-baked, does that damage the brand I'm trying to build? Too many missteps and people stop taking you seriously. Or at least, that's what I worry about. Maybe that's just an excuse to not ship anything.
\nThen I look at Marc Louvion. I came across his profile on X a while back and started following along. He's had more failed startups than most people have ideas. He's transparent about all of them. And he's now followed by over 321k people specifically because of that transparency. He kept failing publicly and kept going.
\nI read that and think: the reputation fear is overblown. Just ship stuff, be honest about what doesn't work, people respect that. Then I go to actually put something out there and the voice comes back. It'll look half-baked.
\nReading The Million Dollar Weekend by Noah Kagan, I came across this:
\n\n\nOkay, so you have an idea for an app. How would you go about doing it? Here's the way most people, most wantrepreneurs, would do it:
\n\n
\n- Spend hours at home thinking about the app (and coming up with clever names for it).
\n- Spend $100 hiring your cousin to design a cool logo.
\n- Set up an LLC.
\n- Watch YouTube videos about apps, programming, and business.
\n- Consider signing up for a developer bootcamp and quickly realize coding is hard.
\n- Buy the domain name for the snazzy website you're going to build.
\n- Look into hiring a developer on UpWork and quickly realize it's cost prohibitive.
\n- Give up. Again.
\nNoah Kagan, The Million Dollar Weekend
\n
I've done most of this list. Not all of it, but enough that reading it felt like being called out by name. The domain buying especially. I've bought domains for ideas that never went anywhere. They're still renewing.
\nI'm still in the wantrepreneur camp. I know that. Reading that Noah Kagan excerpt didn't magically change anything, it just made the pattern visible.
\nOn the other side of this: the reactive day problem — even when you're building, it's easy to spend all your time answering other people's priorities and end up with nothing to show for it. The problem isn't just starting. It's protecting the space to actually execute.
\nThe conundrum for me isn't really about entrepreneurship at all. It's about the gap between having ideas and doing something with them. I know the theory. I've read the books, watched the videos, followed the people. Knowing the theory hasn't made me ship anything.
\nI don't have a neat resolution here. I'm still working through it. Maybe writing about it is a small step. Maybe it's just another form of thinking about the app instead of building it. I genuinely don't know.
\nAnd then there's the silence problem — even when you do start, the void is real. The silence after shipping something you care about is its own obstacle to continuing.
", "date_modified": "2024-08-13T00:00:00.000Z", "tags": [ "reflections" ] } ] }