![\"Meet](\"https://kobi.kadosh.me/media/link-cards/latch-grok-bot.png\")
▸x.ai/bot↗
Latch by Kobi
Drives a real Mac safely for Grok Bot: mouse-first UI automation, Accessibility without lockouts, and a hard hand-back when you need the machine. For anyone who wants Mac UI playbooks other bots can hand off to.
When I first wrote about Latch, the problem was interaction.
\nAn agent could be perfectly capable of reasoning about what needed to happen next and still get stuck because the next action lived on my Mac. There was a button to click, a dialog to inspect, something in Terminal or Chrome, or some other piece of graphical state that did not have a useful API.
\nLatch became the small layer that gave the agent hands.
\nThe second version exposes a different problem: giving the agent hands is not enough if the path to those hands can disappear.
\nAnd, once you accept that the Mac UI itself is a legitimate bounded interface, another slightly strange thing follows: sometimes the application Latch needs to operate is Grok Bot itself.
\nSo Latch v2 has two additions that look different on the surface but are really extensions of the same boundary:
\nI think this makes the role of Latch clearer.
\nLatch is becoming the Mac-side reliability and interaction layer beneath the agent — not another agent inside the harness.
\nLatch v1 gave the agent hands. V2 makes the path to those hands more recoverable.
\nThe first new capability came from a fairly quiet failure.
\nThe Mac was awake.
\nThe network was there.
\nApplications were still running.
\nBut Grok Bot no longer had its local-exec connection to the machine.
\nListMachines reported the Mac as disconnected, which meant commands against that machine were effectively finished until the connection returned.
This is different from the laptop sleeping or losing Wi-Fi. The machine can be healthy while the local bridge is not.
\nThe obvious fix is also obvious to a human:
\nclose Grok Bot, reopen it, wait for the machine to reconnect.
\nThe problem is that the agent cannot necessarily do that.
\nOnce local-exec is gone, asking the same agent to run a command on the Mac to restore local-exec is circular.
\nIt is roughly:
\nCloud agent\n |\n | local-exec\n v\nGrok Bot.app\n |\n v\nMacIf the middle link disappears, anything above it can understand the failure but cannot use that path to repair the failure.
\nThis is not really a prompting problem.
\nIt is a supervision problem.
\nAnd the recovery mechanism has to sit outside the failure domain it is responsible for repairing.
\nOn macOS, there is already a boring and well-understood place for this kind of responsibility: launchd.
\nSo Latch v2 adds a LaunchAgent that runs independently of the Grok Bot session and checks whether the local-exec side still looks healthy.
\nThe important distinction is not that Latch has a shell script now.
\nThe important distinction is that the script does not need the agent connection in order to run.
\nAt a high level, the installation looks like this:
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Piece | Responsibility |
|---|---|
~/Library/Application Support/Latch/bin/grok-bot-local-exec-heal.sh | Detect the unhealthy local state and perform recovery |
~/Library/LaunchAgents/com.latch.grok-bot-local-exec-heal.plist | Run the watchdog periodically and at login |
~/Library/Logs/GrokBotLocalExecHeal.log | Human-readable recovery log |
~/Library/Logs/GrokBotLocalExecHeal-last.json | Small machine-readable recovery receipt |
~/Library/Application Support/Latch/grok-bot-local-exec-heal.disable | Explicit soft-off switch |
~/Library/Application Support/Latch/grok-bot-local-exec-heal.request | One-shot “relaunch now” from anyone who can still reach the Mac |
The self-heal kit is open source, and its README carries the install details and knobs. I don’t think the interesting part of the design is whether a heartbeat timeout is 150 or 180 seconds.
\nThe interesting part is the contract.
\nLatch treats the bridge as unhealthy when one of a small set of local signals says it is no longer viable: the expected process is gone, the heartbeat has gone stale or stopped moving, or startup reached a non-ready outcome. Someone who can still reach the Mac can also ask for a relaunch by leaving the request file.
\nThe LaunchAgent checks periodically. When it decides recovery is warranted, it tries to relaunch Grok Bot gently rather than immediately killing it.
\nThe sequence is deliberately uninteresting:
\ndetect unhealthy state\n |\n v\nrequest normal quit\n |\n v\nwait\n |\n v\nreopen Grok Bot in the background\n |\n v\nwait for local readiness\n |\n v\nrecord healed, or say why not\n |\n v\ncool down before another recoveryThere is a fallback if the process refuses to exit, but the normal case is intended to be uneventful.
\nThe readiness step matters more than it looks. A process that exists is not a connection that works. The kit records healed only when Grok Bot is running again and its heartbeat is fresh, or its startup reports ready, within a bounded wait. Otherwise the receipt says heal_incomplete or heal_failed, with a hint about what to escalate.
Relaunched is not the same as recovered.
\nThat is what I want from this layer.
\nRecovery infrastructure should be less clever than the system it supervises.
\nIt is important to keep the boundary honest.
\nThe watchdog does not wake a sleeping Mac.
\nIt does not open a closed lid.
\nIt does not restore a dead network connection.
\nIt does not sign the operator back into an account.
\nIt does not bypass macOS security boundaries.
\nIt handles a narrower local case: the Mac is available, but the expected Grok Bot process is gone or the heartbeat is stale. A configured beacon also lets an outside box ask the Mac for the same relaunch.
\nOutside of that, Latch fails closed.
\nI would rather have an explicit edge where the human has to return than describe every unavailable capability as something automation should somehow solve.
\nThere is another tradeoff worth saying directly.
\nIf I intentionally press Cmd+Q, the watchdog cannot read my mind and know whether I meant “quit forever” or “the app died.”
\nUnless the disable file is present, Grok Bot can therefore come back roughly a minute later.
\nThat is the cost of choosing unattended recovery.
\nThe fix is not another heuristic. The fix is a visible off switch.
\nPredictable automation is better than automation that tries too hard to guess intent.
\nOne failure sits awkwardly between what the watchdog fixes and what it leaves alone.
\nGrok Bot’s cloud side knows whether a machine is connected. ListMachines reports it as connected. The Mac never gets that flag. Nothing on disk and nothing on localhost mirrors it in a way a LaunchAgent could use.
So the cloud can decide the Mac is disconnected while, on the Mac, the process is alive and the heartbeat keeps moving. To the watchdog, that machine looks healthy. By every signal it has, it is.
\nThe receipt is honest about this. GrokBotLocalExecHeal-last.json carries a field called cloudConnectObservable, and it is always false.
It would be easy to “fix” this by tightening the thresholds until the watchdog relaunches more often. That would only turn a missing signal into guesswork, and a relaunch on a guess is just a new way to interrupt the person using the machine.
\nThe signal has to come from the side that can see it.
\nSo the kit has an optional worker-beacon/ mode.
The agent that actually sees the disconnect can POST a heal_request to a small Cloudflare Worker the operator deploys. The Worker is a heal-only inbox. It accepts one kind of request in one strict shape. Requests are short-lived and single-use, and the Worker rate-limits them per machine.
The Mac polls that inbox on its normal tick. Nothing calls in to the Mac. When a request is waiting, the LaunchAgent runs the same quit-and-open heal it runs for a local request file, records reason=beacon_request, and skips the normal cooldown. The readiness gate still applies.
agent sees connected=false\n |\n | POST heal_request\n v\noperator's Worker (heal-only inbox)\n ^\n | outbound poll, once per tick\n |\nLaunchAgent on the Mac\n |\n v\nsame quit, reopen, and readiness gateThe Worker applies the limits. The Mac still owns the recovery.
\nA few boundaries hold it together:
\nKit 1.4.2 also makes the installer keep an operator’s beacon settings across a reinstall, so updating the kit does not quietly switch the outside signal off.
\nOn October 5, at about 11:23 AM PT, the live end-to-end test of that path passed. The kit’s notes call it Prove C. The request came from a remote box, and nothing touched the request file on the Mac. Grok Bot relaunched, the pid changed, and the receipt came back healed and ready.
The negative cases passed too: a malformed request, an expired one, a replay, and a second request inside the rate limit were all refused.
\nA separate live check covered the off switch. With the disable file present, the heal was skipped and the pid did not change. With the file removed, the agent went back to its normal checks.
\nThat proves the outside signal can reach the existing heal path.
\nIt does not prove that Latch can detect every outage by itself.
\nOn October 7, Prove D confirmed that gap: the cloud-connection helper exited while the main app and heartbeat still looked healthy, so kit 1.4.2 kept reporting healthy.
\nKit 1.5.0, now released, detects and logs that silent cloud drop in observe-only mode; it does not heal it.
\nAnd the limits from before do not move. Latch still cannot wake a sleeping Mac, open a lid, restore a lost network connection, or infer ListMachines.connected locally. With 1.4.2, an agent that can see the disconnect still has to send the request.
Putting a watchdog on the Mac only solves half of the problem.
\nThe agents using the machine also need to know what a disconnection means.
\nWithout that shared behavior, it is easy to turn one dead connection into a pile of retries.
\nThe Latch-side protocol is intentionally small:
\nListMachines\n |\n | connected=false\n v\nsoft-park Mac-dependent work\n |\n v\nwait for the local watchdog, then re-poll\n |\n | still connected=false\n v\nsend one heal_request, if a beacon is set up\n |\n v\nre-poll ListMachines\n |\n | connected=true\n v\nread GrokBotLocalExecHeal-last.json\n |\n v\nresume from verified stateIf the machine does not come back after the recovery window, then ask the human.
\nDo not invent a remote wake capability.
\nDo not keep throwing commands at a transport that has already told you it is unavailable.
\nDo not send another heal request because the first one did not work. One per outage, then escalate.
\nDo not assume that a reconnect proves what happened. Read the receipt.
\nThis distinction between the skill and the supervisor has become useful to me.
\nA skill can describe what an agent should do around a failure.
\nThe LaunchAgent can actually remain present when the agent path disappears.
\nOne describes behavior.
\nThe other enforces a piece of local reality.
\nThat fits closely with how I have been thinking about harness-driven development. The harness is not only the model or the prompt. It includes the operational pieces that make the model’s actions dependable.
\nLong-running agents make this much easier to see.
\nThe second half of Latch v2 sounds more recursive than it really is.
\nLatch can now drive Grok Bot.app.
\nSo, yes, there are situations where Grok Bot can effectively use Latch to operate Grok Bot.
\nThat is a funny sentence.
\nBut I don’t think the recursion is the interesting idea.
\nThe interesting part is what happens when the structured interfaces run out.
\nMost agent systems have some hierarchy of preferred interaction:
\nAPI / structured tool\n ↓\nCLI / shell\n ↓\napplication-specific automation\n ↓\ncomputer UII would nearly always prefer the top of that list.
\nStructured tools are easier to reason about, easier to verify, and much less ambiguous than moving a cursor across a screen.
\nBut the existence of a better interface does not mean every action has one.
\nThere are still product surfaces where the last useful move is graphical.
\nGrok Bot itself contains some of them.
\nAn Allow card may need a click.
\nAn Assist flow may need to be advanced.
\nA draft may need its Send action.
\nA share or publish surface may need to be opened.
\nA setting may exist only in the desktop interface.
\nThese are not all the same kind of action, and Latch should not pretend they are.
\nBut they share something important: the interface is the UI.
\nWhen that happens, the UI can become another bounded tool surface.
\nThis is where I think agent-first development becomes relevant.
\nDesigning for agents does not mean eliminating graphical interfaces or pretending an API exists for everything.
\nIt means being explicit about what capabilities an agent has, how it can discover them, and where the boundaries are.
\nLatch treats computer use the same way.
\nGrok-Bot-on-Grok-Bot does not mean:
\nthe agent is allowed to click whatever gets in its way.
\nIt means a registered Mac can expose a constrained interaction capability with rules around it.
\nThose rules remain intentionally strict:
\nThose rules came from Latch v1 and I do not want v2 to weaken them just because the UI happens to belong to Grok Bot.
\nThere is a major difference between performing a gesture and making a judgment.
\nComputer Use can click an Allow card when the authorization to do so is already part of the task.
\nThat does not imply that Latch should manufacture authorization where none was given.
\nIt can advance an Assist form whose intended values are already known.
\nThat does not mean it should invent missing information.
\nIt can move through a mechanical share flow.
\nThat does not turn every consequential confirmation into something an agent should silently approve.
\nThe UI is another interface.
\nThe human boundary still exists above it.
\nThere is a temptation, once you have local computer access, to turn the Mac into a general input-injection surface.
\nLatch deliberately does not do that.
\nFor graphical work, the mouse is easier to constrain and easier to observe.
\nFor text, the preferred path remains clipboard-based rather than pretending to be an invisible hardware keyboard.
\nThat is partly a safety decision, but it also makes the automation easier to reason about.
\nIf Latch puts text on the clipboard and a human paste action completes it, the transition is explicit.
\nIf an agent can synthesize arbitrary keyboard events at arbitrary moments, the boundary between application automation and control of the entire user session gets much fuzzier.
\nI already learned in the first version of Latch that macOS Accessibility deserves respect.
\nV2 does not reinterpret that lesson.
\nIt builds on it.
\nSelf-heal and Grok-Bot-on-Grok-Bot look like two unrelated release notes.
\nOne is a LaunchAgent.
\nOne is computer use.
\nBut both exist because the agent itself should not own every layer it depends on.
\nThe self-heal path says:
\nIf the agent loses its path to the Mac, something below that path must be able to attempt a bounded relaunch when it has a reliable signal.
\nThe UI path says:
\nIf the agent reaches the end of its structured interfaces, something below the reasoning layer can provide a bounded physical interaction surface.
\nIn both cases, Latch sits closer to the machine than the agent does.
\nThat gives the architecture a clearer shape:
\n┌──────────────────────────────────────┐\n│ Agent / Harness │\n│ reasoning, planning, skills, tools │\n└──────────────────┬───────────────────┘\n │\n │ structured intent\n ▼\n┌──────────────────────────────────────┐\n│ Latch │\n│ │\n│ reliability interaction │\n│ ─────────── ──────────── │\n│ self-heal mouse/UI │\n│ receipts clipboard │\n│ outside signal lease control │\n│ │\n└──────────────────┬───────────────────┘\n │\n ▼\n┌──────────────────────────────────────┐\n│ macOS │\n│ Grok Bot · Chrome · Terminal · UI │\n└──────────────────────────────────────┘That is a more useful mental model for Latch than “a bot that can click things.”
\nIt is the local reliability and interaction layer underneath the agent.
\nThis is Latch v2: relaunch proven on self-heal kit 1.4.2, with 1.5.0 now detecting and logging silent cloud drops without healing them.
\nThe version includes:
\nworker-beacon/, for the disconnects the Mac cannot see;The exact timers, plist, health checks, install flow, and operational details belong in the kit’s README rather than turning this post into a deployment guide.
\nLatch itself is public as a Grok Bot template:
\nDrives a real Mac safely for Grok Bot: mouse-first UI automation, Accessibility without lockouts, and a hard hand-back when you need the machine. For anyone who wants Mac UI playbooks other bots can hand off to.
There is also an observable product gap underneath the watchdog.
\nIdeally, Grok Bot’s own local-exec lifecycle becomes reliable enough that an external watchdog is unnecessary. And if Grok Bot wrote its own connection state somewhere on the Mac, no bot would have to declare the machine down. If you hit the same class of failure, the useful long-term thing to do is also send it upstream through Help → Send Feedback.
\nI do not particularly want Latch to own process resurrection forever.
\nThat would be missing the point.
\nOne thing I increasingly like about building around fast-moving agent systems is that some infrastructure is allowed to be temporary.
\nThere is a tendency in software to treat deletion as evidence that the original work was wasted.
\nI think the opposite can be true here.
\nIf Grok Bot eventually absorbs reliable local-exec recovery, the self-heal LaunchAgent should disappear.
\nIf the Mac can ever read its own connection state, the beacon should go first.
\nIf richer structured interfaces replace one of the UI interactions, Latch should stop clicking that UI.
\nIf macOS or the agent harness grows a safer primitive, use the safer primitive.
\nThe goal is not to preserve Latch’s implementation.
\nThe goal is to preserve the operating capability.
\nThat is also why I would rather ship a small watchdog now than turn “the agent sometimes disconnects” into a permanent ritual where a human checks the Dock every few hours.
\nThe current primitive is appropriate for the current gap.
\nWhen the gap moves, the primitive can move with it.
\nLatch v1 started with a fairly practical question: how do I let an agent safely operate the Mac when APIs stop?
\nV2 adds another one: what can attempt to restore that capability when the agent itself cannot reach it?
\nThe answer, at least for now, is to put a deliberately boring layer underneath the clever one.
\nAnd once that layer exists, even Grok Bot’s own UI becomes just another bounded surface it can mediate.
\nThat is the practice I care about more than the slogan:
\nput reliability below the thing that can fail, keep interaction narrower than authority, and delete the workaround when the platform finally makes it unnecessary.
", "date_published": "2026-10-08T00:00:00.000Z", "tags": [ "Agents", "AI Tools", "Grok Bot", "Latch" ] }, { "id": "https://kobi.kadosh.me/blog/2026-10-02-latch-giving-grok-bot-hands-on-my-mac/", "url": "https://kobi.kadosh.me/blog/2026-10-02-latch-giving-grok-bot-hands-on-my-mac/", "title": "Latch: Giving Grok Bot Hands on My Mac", "summary": "The bot had a computer. The next step needed to happen on mine. Latch is a specialist Grok Bot for the small, authorized desktop interactions that stall larger workflows: mouse first, clipboard over keystrokes, screenshot receipts, and a hard hand-back. This is the story of building it, including the keyboard lockout that wrote most of its rules.", "content_html": "Update, Oct 5: Latch’s self-heal kit can now take a heal request from outside the Mac. Read the update.
\nSometimes the thing blocking an agent is not a hard problem.
\nIt is a button.
\nThe agent understands the task. It knows what should happen next. There may be other bots working on other parts of the process, making progress on their own. But somewhere along the way an application needs a small interaction, and the application is running on my computer — not on the computer the bot is using.
\nNow the process is waiting for me.
\nThe frustrating part is that the interaction takes a few seconds. The delay comes from when I am available to perform it. I might be away from my desk, or deep in something else, or standing in the kitchen with my phone. A five-second action becomes a thirty-minute interruption to a workflow, not because the action is complicated, but because I am the only available way to perform it.
\nAt that point I am not directing the work. I am the missing connection between the bot and the computer where the work needs to happen.
\nThat is where Latch started.
\nNot as “can we make another bot that clicks things?” Something narrower: can I give a bot a useful, explicitly authorized way to handle those interactions on my Mac, without me becoming its remote mouse — and without handing it unrestricted control of the machine I actually work on?
\nThe one-line description on the bot’s public card says what it became:
\n\n\nDrives a real Mac safely for Grok Bot: mouse-first UI automation, Accessibility without lockouts, and a hard hand-back when you need the machine. For anyone who wants Mac UI playbooks other bots can hand off to.
\n
Every clause in that sentence was earned the hard way. The second half of this post is the story of how, told partly in Latch’s own words. The first half is why I wanted it at all.
\nGrok Bot’s working environment is a persistent cloud computer: a browser, a filesystem, a terminal, all of it running whether or not my laptop is open. That is most of the appeal. I can close the lid and the work continues.
\nBut there is a difference between talking to a bot from my Mac and having that bot operate my Mac.
\nThe application I need might already be open locally. The relevant files might sit in a local workflow. The next step might depend on the state of a desktop application that simply does not exist in the bot’s environment, or on a browser session that is signed in on my machine and nowhere else. Recreating that entire environment somewhere in the cloud is not the problem I want to solve.
\nSometimes I just need the next action to happen where the work already is.
\nI want to be precise about what exists here, because it would be easy to overclaim. Grok Bot already has a documented, permission-gated path for running commands on your local computer. The docs describe it as a setting, Execution on Local Computer, with three policies: ask every time, always allow, never allow. It defaults to asking, and the documentation recommends “never allow” unless a bot has a specific reason to work on your local files.
\nSo local execution is not what we invented.
\nWhat was missing was everything around it: a working practice for driving a real Mac’s interface. Which permissions to grant and which to refuse. How to click without typing. What to do when the keyboard stops responding. How to prove the action happened. How to give the machine back.
\nThat practice is Latch. The cloud computer does not go away. My Mac becomes one more place where a specifically delegated part of a task can happen, under rules we wrote down after breaking things.
\nMy goal is not to make clicking the universal interface to software.
\nWhere a suitable API, connector, or command-line interface exists, I would much rather use it. Grok Bot’s own docs say the same thing: prefer a connector when one is available, and use the browser for services without one or for visual workflows a connector does not expose. That is the right order of preference, and Latch does not change it.
\nBut a task does not become less real because the application lacks an automation interface.
\nConsider a desktop app whose export lives only behind a menu item. A confirmation dialog that appears halfway through a long local job and blocks everything behind it until someone presses a button. A System Settings toggle. A native application that needs a predictable sequence of clicks before the next part of a process can continue. None of these are difficult. All of them are the kind of thing that stalls an otherwise automated workflow at the edge of the interfaces we already have.
\nComputer use is valuable to me as a way to fill those gaps. Not as a reason to ignore better interfaces.
\nThe experience I am aiming for has a simple test.
\nI am not at my desk. I have my phone. A workflow needs a small action on my Mac.
\nDo I walk back, find the right window, remember what the bot was doing, perform the action, and tell it to continue? Or can I give a bounded instruction from where I am?
\nSomething like:
\n\n\nFinish the export in the app we were using and save it to the folder we agreed on. Stop if that means overwriting an existing file or granting a new permission.
\n
That is an illustrative instruction, not a transcript. But it has the shape I care about: an outcome and a boundary, rather than me steering every movement of the pointer.
\nTalking to a bot from my phone is nothing new. What changed is where the requested desktop action can happen. The phone is where I talk. The Mac is where this part of the task lives. Latch connects the two.
\nIt does not need to look spectacular. It needs to be useful.
\nI also do not see Latch owning entire workflows.
\nIts role is narrow: handle an authorized local interaction, establish whether it succeeded, hand the result back. That matters when there is more than one bot in the picture. I do not want the research bot, the planning bot, and every other specialist to become general-purpose desktop operators. I want one clear owner for that responsibility that the rest of the workflow can hand off to when appropriate.
\nThis is the same instinct behind Buzzcut, and behind the Unix philosophy for agents and skills: give a bot one constrained responsibility and be extremely explicit about what it should and should not do. Independent work continues elsewhere. Work that depends on the local result waits until that result is actually confirmed.
\nFor me the value is not the number of clicks we automate. It is the amount of unnecessary human coordination we remove. There is a difference between being involved because a decision needs my judgment and being involved because a window needs attention. I want to keep the former and shrink the latter.
\nOne boundary is worth stating plainly, because a well-named specialist can create a false sense of separation. Grok Bot’s docs are explicit that all of your bots share one cloud computer, and that files, browser sessions, and command-line credentials on it are available across your roster. In their words: do not use separate bots as a security boundary. Giving one bot a narrow name and a narrow job is a design decision. It is not technical isolation. A well-defined role is useful. Enforced permissions are a separate concern, and on the Mac side they live in System Settings, not in the bot’s description.
\nThere is a mistake hiding in the phrase “unblocking the bot.”
\nSome blocks are accidental friction. Others exist because the system needs a human decision. Those are not the same thing, and a bot that treats every confirmation, permission prompt, or credential wall as an obstacle to click through is not a specialist. It is a liability with a nice name.
\nI want help with mechanical steps I have authorized. I do not want a bot deciding, on my behalf, that a single sign-on page or a payment form or a “grant access” dialog is just another button.
\nSo the operating boundaries had to be as clear as the capabilities: what Latch may act on, what requires a fresh decision, when it stops, and how access is withdrawn. The distinction I care about is simple.
\nI want to delegate the interaction, not accidentally delegate every decision behind it.
\nThat principle turned out to be load-bearing in a way I did not expect. Most of Latch’s rules came from a moment when the machine, not the bot, needed to be protected.
\nWhat follows is the build record. Once the design stabilized, I asked Latch to write up its own account of how it was built, and the rest of this section draws on that account and on the skill it now carries. I have stripped names, paths, and anything specific to my environment, and I have left its voice alone where it says things better than I would. Where it is quoted, that is the bot talking.
\nWe started with a narrow brief, on purpose.
\n\n\nOwn the Mac-automation playbooks. Speak short and procedural. Fail closed when the ask is unclear or destructive. Prove work with screenshots, not vibes. Always hand the machine back.
\n
And a name that describes the contract: something that catches onto the UI, holds briefly, then releases.
\nThe first four rules survived intact. The fifth became the whole story.
\nThe obvious path is the one every Mac automation tutorial teaches. Synthesize keyboard events, fill the fields, press Return.
\n\n\nIt worked — until it didn’t. After a hung keystroke path, the Mac’s keyboard felt frozen. Mouse still moved. Keys did nothing useful for seconds at a time. The shared machine was no longer shared.
\n
I want to separate what we observed from how we explained it, because those are different kinds of claims.
\nWhat we observed: after a run that mixed synthetic keystrokes with mouse automation, each keypress stalled the pointer for a few seconds, or the keys went dead altogether. The mouse still worked. Typing did not.
\nThe explanation we settled on, and later supported by fixing it: the helper that Grok Bot’s Computer Use registers under macOS Accessibility had left an event tap armed. On my machine at the time that helper showed up as a process called CUGrokBotService; treat the name as a detail of my setup and version, not a spec. The event tap is the part that matters. Synthetic keyboard injection through Accessibility is not a casual tool on a Mac that a human also uses. It is a lockout vector.
When input wedged, the instinct was to fix permissions. Reset the privacy database, toggle everything, hope.
\nWe refused the nuclear option.
\n\n\nNever reset Accessibility to paper over a bad driver. Diagnose the tap. Document the unlock. Prefer narrower permissions over wider ones.
\n
Running tccutil reset on Accessibility is opaque, it punishes every other application that had been granted access, and it teaches exactly the wrong habit: treat the operating system as something you reboot when your automation is sloppy. That rule is now permanent and written into Latch’s instructions. It does not reset the Transparency, Consent, and Control database, ever.
The fix that actually worked was mundane. In System Settings, under Privacy & Security, turn Grok Bot off in Accessibility, and in Input Monitoring if it is listed there. That cleared the stuck tap.
\nWe nearly declared victory too early.
\n\n\nTeardown is delayed. Turning the switch off does not mean the tap is gone in three seconds. Helpers need time to unregister. We learned to wait — tens of seconds, up to about a minute — and to run an active unlock script that kills stuck helpers and lifts stuck mouse buttons and modifiers, without sending new keyDown events.
\n
That last clause is the subtle part. The unlock script is allowed to release things: mouse up, modifier keys up, hung automation processes killed. It is not allowed to press anything, because pressing is what got us here. The procedure that came out of it is a schedule, not a hope: toggle off, run the unlock, try typing at ten seconds, at thirty, at sixty. Still wedged after a minute, log out of the Mac session.
\n\n\nOFF is not instant. Measure teardown. Script the unlock. Don’t gaslight the human with “try again now” while the tap is still dying.
\n
I keep that sentence around because it names a failure mode that has nothing to do with capability. A bot that says “fixed, try again” three seconds after flipping a switch is not lying. It is confusing an action it took with an outcome it has not observed. The person at the keyboard experiences the difference.
\nAfter the lockout, we rebuilt the default path from scratch.
\nCGEvent or System Events keystrokes, for typing: never.It felt slower. It was also the first design that respected a shared Mac.
\n\n\nThe innovative part is not “the bot can type.” It’s “the bot knows when typing through the OS is the wrong abstraction.”
\n
I argued in The Magic Prompt that when automation stops, orchestration should continue, and that the human should stay inside the execution graph rather than being ejected from it. This is that principle applied to a single keystroke. Latch navigates to the field, puts the right text on the clipboard, tells me exactly what to paste and where, and waits. The step is still one step. It just has two participants.
\nThe last piece is the one that gave the bot its name.
\n\n\nEvery Mac drive now ends with an explicit release-the-lease step: kill hung click and keystroke processes, mouse up, clear stuck modifiers, hand focus back. If a lockout still happens, the bot stops driving until a human says it’s okay again.
\n
Two things are packed in there. The first is a routine: every run, successful or not, ends by releasing whatever it held. The second is a policy: the moment the lockout signature appears, Latch stops. It does not retry, it does not “try one more thing,” and it does not resume until I say so. Re-enabling is deliberate too. Grant Accessibility again, then run a mouse-only smoke probe before anything heavier.
\nI would not call that a guarantee. It is a contract with a specific trigger, a specific set of actions, and a specific stop condition, and it is the mechanism behind the “hard hand-back” on the card. If you clone this pattern, test the hand-back on your own machine before you trust the phrase.
\n\n\nAutomation without a hand-back contract is just a fancy way to steal the keyboard.
\n
One more rule came from a different kind of failure.
\nEarly on, Latch shipped visual “proof” that did not survive a second look. The screenshots existed. They did not show the thing I had asked for. A command had returned, a capture had been taken, and the bot reported success on the strength of both.
\nSo we added a rule that reads like a tautology and is not one: DONE ≠ PASS. A screenshot that does not show the ask is not evidence. The bot inspects its own receipts before it reports, and if the receipt does not match the request, the run is not finished, whatever the exit code said.
\nThis is the same discipline I keep coming back to in the feedback loop series: the agent needs objective verification of its own output, and “the command succeeded” is not that. On a Mac it is even less than that, because the interface can change state without any process reporting anything at all.
\nCondensed, for anyone cloning the pattern. This is the public version of the skill Latch carries.
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n| Do | Don’t |
|---|---|
| Drive the user’s own Mac through the tools the bot is authorized for: shell, AppleScript, a click helper | Pretend the bot’s cloud computer is the user’s Mac |
| Prefer mouse, clipboard, and a human paste | Inject HID keyboard events “to go faster” |
| End every run with a lease release | Leave hung osascript or click helpers running |
| Treat Accessibility teardown as delayed | Declare the keyboard fixed at three seconds |
| Fail closed on unclear or destructive asks | Guess through single sign-on, payments, or credential walls |
| Prove with inspected screenshots | Claim PASS from a probe you did not look at |
| Leave the privacy database alone | Reset it to hide a bad driver |
And the decision tree the skill opens with, which is short enough to memorize:
\nLockout signature? → Grok Bot Accessibility OFF + unlock script + wait up to 60s → log out if needed\nNeed typing? → clipboard + human paste (never synthetic keys)\nNeed mouse drive? → only with a greenlight; end with lease releaseThe ordering is deliberate. The failure case comes first, because the failure case is the one you will meet at the worst moment.
\nWe kept the root-cause analysis of the keyboard lockout inside the playbook, not in a separate postmortem nobody will open.
\n\n\nPublic bots usually hide their scars. Latch’s value is the scar tissue: other builders shouldn’t relearn that a Computer Use helper can leave an Accessibility tap armed after synthetic keyboard use.
\n
I think this is the most transferable idea in the whole project. A polished demo shows that something happened once. The explanation of what it depended on, what broke, and why each constraint exists is what lets someone else decide whether the same approach makes sense for them. If you read the playbook without the story, the rules look overcautious. Read with it, every rule has a date and a reason.
\nIt is also the most direct example I have of what I meant by harness-driven development. The skill file, the unlock procedure, the do-and-don’t table, the chronicle: none of that is source code, and all of it is the software. Delete it and the bot still exists. It would just relearn the lockout on your machine instead of mine.
\nTurning an experiment built around one person’s environment into something shareable was its own piece of work, and most of it was not about deleting names.
\nGrok Bot lets you share a bot as a template, as a public link or team-only. A template carries the bot’s shared configuration: identity, description, skills, routines. It does not copy conversation history, learned memory, or chat attachments. Adding it creates a copy on the recipient’s account. It does not give them your computer, your logins, or your history.
\nThat makes the template itself the review surface, not just the blog post. A sanitized profile does not mean the skills underneath it are sanitized, and the skills are where the specifics of one desk tend to hide.
\nGeneralizing is also different from redacting. Wherever the implementation depended on a specific path, application, or account, the public version needed either an explicit setup input or a documented prerequisite. Otherwise I would be hiding a dependency rather than removing it. What survives is the part a stranger can act on: the mouse-first playbook, the lease release, the delayed teardown, and the fail-closed defaults. Some things remain yours to supply: the Accessibility grant on your Mac, your own unlock script, the applications you actually want driven, and the smoke probe you run before trusting any of it.
\nThree caveats I want on the record, because the card is short and cards invite over-reading.
\nThe scope is macOS. Windows and Linux are possible directions, not demonstrated compatibility, and I am not going to claim them without the implementation and the tests.
\nA public bot template is not an open source release. It is shared configuration. The playbook is reusable; the platform underneath it is not yours to fork.
\nAnd a public link is public. Anyone who has it can open it. That is a property of the sharing model, not something a bot’s description can narrow.
\nStrip the Mac details away and Latch is an existence proof for a few things I care about.
\nThe interesting product claim is not that an agent clicked a button. It is that we found a stable contract for automation on a machine that a human also uses.
\nThat is the contract, in three words.
\nA task that used to require me to walk back to my desk is now a bounded delegation: do this specific thing, on this specific machine, within these limits, and tell me what actually happened. Not what you did. What happened.
\nIf you want to try it, the practical chapter is short. Add the template. Grant Accessibility deliberately, and only to what needs it. Run a mouse-only smoke probe before anything else. And write your own lease-release habit into every Mac-facing skill you publish, because the first time your keyboard goes quiet you will want to have already decided what the bot does next.
\nSometimes the next useful capability is not a smarter answer.
\nSometimes it is a way to complete the missing action.
\nSince this post went up, Latch has picked up a second job: watching the path to my Mac and relaunching it when the signals it can see fail.
\nEverything above runs over Grok Bot’s local-exec link to the Mac, the path behind Execution on Local Computer. When that link drops, an agent on the other side cannot run a command on the Mac to bring it back, so the repair has to live on the Mac. Latch’s self-heal kit is a LaunchAgent that runs there, outside any agent session, and relaunches Grok Bot when the local side stops looking healthy.
\nVersion 1.3.0 of the kit covered the Mac-local signals it can see. If Grok Bot dies, its heartbeat goes stale or freezes, or an operator leaves a local .request file, the LaunchAgent can quit and reopen it, and it only calls the run healed once local readiness comes back.
There was still one gap.
\nThe Mac does not see the cloud’s view of the connection by itself. Grok Bot’s ListMachines reports whether a machine is connected, and nothing on the Mac mirrors that flag. If the cloud thinks the machine is disconnected while the local process and heartbeat still look healthy, there is no honest local signal for the watchdog to act on. Lowering the thresholds would only turn a missing signal into guesswork.
Version 1.4.0 added an optional worker-beacon/ mode for that case. The agent that actually sees the disconnect can POST a heal_request to a Cloudflare Worker the operator deploys. The Mac polls that heal-only inbox and runs the same quit-and-open heal as a local .request, records reason=beacon_request, and bypasses the normal cooldown. The Worker applies rate limits; the Mac still owns the actual recovery. Version 1.4.2, a tagged release, makes the installer keep an operator’s BEACON_* settings across a reinstall and retry loading the LaunchAgent.
At about 11:23 AM PT on October 5, the live test of that path, Prove C, passed end to end. The request came from a remote box, and nothing touched the .request file on the Mac. Grok Bot relaunched, the pid changed, and the local result came back healed and ready. The negative cases passed too: a malformed request, an expired one, a replay, and a second request inside the rate limit were all refused.
The off switch still wins. While the kit’s .disable file is present, the heal is skipped; remove the file, and the agent recovers normally.
That proves the outside signal can reach the existing heal path.
\nIt does not prove that Latch can detect every outage by itself.
\nIt still cannot wake a sleeping Mac, open a lid, restore a lost network connection, or infer ListMachines.connected locally. When the cloud says the Mac is gone while everything on the Mac looks fine, an agent that can see that disconnect still has to send the request.
On October 7, Prove D confirmed the observability gap: the cloud-connection helper exited while the main app and heartbeat still looked healthy, so 1.4.2 kept reporting healthy instead of relaunching. Kit 1.5.0, now released, detects and logs that silent cloud drop in observe-only mode; it does not heal it.
\nSame rule as DONE ≠ PASS: the claim stops where the evidence does.
\nLatch is public as a Grok Bot template. It is opinionated about what it will not do, which is most of why I trust it with what it will.
\nDrives a real Mac safely for Grok Bot: mouse-first UI automation, Accessibility without lockouts, and a hard hand-back when you need the machine. For anyone who wants Mac UI playbooks other bots can hand off to.
Anyone who built software through the early 2010s remembers the moment mobile stopped being the version you squeezed down at the end.
\nFor years the order was fixed. You designed for the desktop, where there was room for everything — navigation, secondary actions, three competing calls to action — and then somebody had to figure out how to fit all of it onto a screen the size of a hand. The results were exactly what you would expect from a design that was never meant to live there.
\nMobile-first flipped the order, and the argument was never simply that phones were important. It was that starting with the most constrained interface forced you to understand what mattered. Luke Wroblewski’s original case put it plainly: mobile forces a team to focus on the most important data and actions, because there is no room for anything else. The practice that grew out of it was to start there and then expand into environments with more space.
\nI think we are approaching a similar shift, and the constraint is different enough that it changes what “interface” even means.
\nWhat happens when the user doesn’t need to visit your application?
\nNot because they stopped needing what it does. Not because a model somehow replaced the service. But because the assistant they already have can discover it, understand its capabilities, and use it on their behalf.
\nThe application still exists. Its capabilities still matter. Its reliability probably matters more than before. But its dedicated user interface is no longer necessarily the front door.
\nThat is the idea I want to poke at: agent-first development.
\nThe phrase is already overloaded — I have used it myself to describe development tools built around agents rather than an editor — so let me separate this from a few adjacent ideas first.
\nI am not talking about using an agent to write your application. That is about the development process, and I have written about it at length; harness-driven development is my name for it. This post is about the way the resulting software is designed to be used.
\nI am also not talking about putting a chat window inside an existing product. That can be useful, but it usually preserves the exact assumption I want to question: the user must come to your application, learn its boundaries, and talk to your assistant inside them.
\nThe more interesting question is almost the opposite. How does your product become useful to the assistant the user already has?
\nMy working definition:
\n\n\nAgent-first development means designing a product’s core capabilities so that an agent, acting on human intent, can discover, evaluate, use, and verify them without depending on the product’s dedicated graphical interface.
\n
The human remains the person being served. The agent becomes the operator.
\nNotice that this does not require the product to contain a model at all. A deterministic service that performs one narrow task reliably can be an excellent agent-first product. A product stuffed with AI features can be nearly impossible for any external agent to use. The distinction isn’t how much AI is inside the application. It is whether the application can participate in an agent-mediated workflow.
\nInstead of beginning with “what screens do we need?”, we begin with “what can someone accomplish through this service, and what must an agent understand to accomplish it correctly?”
\nThe screens become one possible expression of the product. They stop being its definition.
\nAt first the mobile-first analogy looks backward.
\nMobile-first starts with less space. An agent appears to offer much more: describe an intent, combine capabilities, coordinate several services, and produce an outcome that would otherwise require a person to navigate five applications. There is no obvious limit to the workflows you can imagine, and that is precisely where the thinking goes wrong.
\nAn imaginable workflow is not an executable one.
\nThe agent still needs usable tools, sufficient context, appropriate permissions, and feedback it can interpret. Anthropic’s guidance on writing tools for agents is blunt about this: good tools need deliberate descriptions, useful responses, and evaluation against real agent behavior — not merely more operations exposed. Everything your backend happens to do is not a capability surface. It is a pile. The important capabilities have to be understandable, bounded, and composable.
\nMeanwhile, the human-facing side of the interaction may be more constrained than anything we designed for on mobile.
\nPerhaps the assistant lives in a messaging app. Perhaps the interaction starts with a voice note. Perhaps the user only ever sees a short notification asking them to approve an action. We have gained a potentially unbounded capability space while giving up control over almost all of the presentation.
\nThat is the tension worth sitting with. In mobile design we asked how much would fit inside a known viewport. In agent-first design we have to ask what the host, meaning the app the assistant lives in, lets us communicate, and what the agent can reliably understand.
\nCan the host show a useful comparison, or only prose? Can the user approve a specific action, or only reply “yes”? Can a long-running task report progress without flooding a conversation? Can an attachment carry the result? What happens when the user changes their mind halfway through?
\nThese are design questions, even though none of them involve drawing a screen. The constraint has moved from pixels to context, attention, permissions, and certainty.
\nThe absence of a traditional interface does not remove the need for interface design. It changes where that design happens.
\nInstinct, a recently launched personal assistant, is a useful example because its positioning makes the interface argument unusually explicit. Its own description is almost aggressively plain: it connects to your applications and devices, it is trained to use a phone and a computer, you can text or call it, and there are no new interfaces. In practice, according to early users and press coverage, that means it lives in iMessage, WhatsApp, or plain SMS, the messaging apps you already open a hundred times a day, and it is invite-only as I write this. I have only looked at it from the outside, so treat this as a reading of its positioning rather than a review.
\nWhat interests me is not the list of things such an assistant can do. It is the abstraction it offers.
\nOnce an assistant is just another conversation in iMessage or WhatsApp, the user does not need a separate application experience for every capability behind it. And the choice of host is strategic rather than technical. Telegram could be another host — for a team that already speaks to two messaging platforms, a third is not the hard part. Where users already communicate, what interactions that environment supports, and what operational constraints come with it: that is the decision. In North America, iMessage and WhatsApp cover most of the people such a product wants to reach, so those two are enough to start.
\nThere is a second, quieter difference in how these assistants organize work.
\nChatGPT’s projects give you explicit containers: a place to group chats, files, and instructions. That structure is valuable when you want deliberate boundaries around a body of work. But it also asks you to decide, before you ask for help, whether a thought belongs in a new chat, an existing session, or a project. That is a small tax, paid constantly.
\nThe Instinct-style abstraction doesn’t have chats and projects at all. It is one ongoing relationship, and continuity is the assistant’s job rather than yours.
\nHermes Agent, from Nous Research, explores another corner of the same space: a messaging gateway, conversations that continue across platforms, persistent memory, and reusable skills. It is a different product and a different operating model — something you run yourself rather than a service — but it makes the same point. An assistant’s capabilities don’t have to be tied to one dedicated interface.
\nI don’t think these approaches are interchangeable, and I am not predicting which one wins. What they share matters more: each is a different way of mediating between human intent and software. And that creates a question for everyone building the software underneath.
\nAre you trying to become the assistant, or become something the assistant can use?
\nMy expectation is that people will not maintain a dozen equally important personal assistants.
\nThey may use different ones in different contexts: one for work, one for personal life. Preferences will differ around privacy, control, convenience, and how much organizing they want to do themselves. But being trusted with someone’s ongoing context is a demanding position to earn, and there will be room for only a few winners.
\nInstinct is competing for that relationship. So are ChatGPT, Claude, Grok Bot, and the self-hosted harnesses people like me keep building. There will not be many of them.
\nFor most product builders there is a more practical opportunity than competing for the entire relationship: become a capability the user’s chosen assistant can depend on.
\nA scheduling service does not need to become a personal assistant. A reporting service does not need to own the conversation. A specialized developer tool does not need to become another general-purpose coding environment. It needs to do something useful, expose it clearly, and return a result the assistant can work with.
\nDrawn out, the agent-first stack looks like this. Most of it isn’t yours.
\n\nflowchart TD\n H[Human<br/>intent and approvals]\n S[Host surface<br/>iMessage, WhatsApp, a chat app]\n A[Assistant<br/>ChatGPT, Claude, Instinct, a harness]\n C[Your capability<br/>API, MCP server, skills]\n E[Evidence<br/>stable identifiers, current state, artifacts]\n U[Dedicated UI<br/>optional, where it earns its place]\n\n H <--> S <--> A --> C --> E\n E --> A\n C -.-> U\n U -.-> H\n\n classDef strong fill:#0A0A0A,stroke:#00FFFF,color:#E0E0E0\n classDef weak fill:#0A0A0A,stroke:#666,color:#999\n class C,E strong\n class H,S,A,U weak\n\n
In plain text: a human expresses intent and approves actions through a host surface such as iMessage, WhatsApp, or a chat app. The assistant behind that surface — ChatGPT, Claude, Instinct, or a harness you run yourself — calls your capability, exposed as an API or an MCP server, often with a skill describing how to use it. Your capability returns evidence: stable identifiers, current state, artifacts. That evidence flows back to the assistant and, through it, to the human. A dedicated UI hangs off the capability as a dotted, optional branch. The two highlighted boxes, capability and evidence, are the only ones you control.
\nWhether a particular assistant lets you plug in directly is a platform-specific question, and it is changing month to month. Not every assistant has an open extension system, and no single integration works everywhere. But the strategic direction holds regardless: build the capability independently, then provide the appropriate ways for supported assistants and harnesses to reach it.
\nThe service should not have to change its meaning every time the user changes their assistant.
\nThere is an obvious objection here: haven’t we already separated frontends from backends? Haven’t we been building headless services and APIs for fifteen years?
\nYes. Agent-first development should build on those ideas, not pretend to have invented them. I made a related prediction earlier this year in The Back Office / Front Office Split: the operational layer of software wants to become agnostic infrastructure, operated by agents, with the interfaces optional. Agent-first is what that prediction looks like from inside the team building one service.
\nWhat changes is the consumer we design for, and the completeness of the experience we expose.
\nA human developer integrating an API can read the documentation, resolve ambiguities, write an adapter, and encode their assumptions into a stable application. In an agent-mediated workflow, some of that interpretation happens while the task is being performed, by a system that has never seen your service before. Unclear semantics stop being an annoyance. They become expensive.
\nConsider a hypothetical reservation service.
\nThe human-facing product walks someone through choosing a date, reviewing availability, entering details, accepting conditions, and receiving a confirmation. In an agent-first design, those meanings need to exist independently of the sequence of screens.
\nThe agent must be able to distinguish availability from a temporary hold, know when that hold expires, and tell a hold from a confirmed reservation. It must be able to retrieve the price and the cancellation conditions before committing. Afterward, it must be able to verify the reservation rather than infer success from a pleasant sentence. And if a request times out, the retry has to be safe: either the agent sends a client-generated idempotency key with the booking call, so the service recognizes the repeat, or it can look the reservation up by a reference it supplied, because the server’s own identifier never arrived. Otherwise a perfectly reasonable retry creates a duplicate booking.
\nThese are not cosmetic details. They are the interface.
\nAn API provides the underlying operations. An MCP server exposes tools and their schemas to compatible clients. A skill describes how to combine capabilities into a workflow. Those are different responsibilities — the MCP specification defines tool interfaces and structured results, while the Agent Skills format packages procedural instructions and supporting resources — and none of those labels, by itself, makes a product agent-first.
\nOpenAI’s plugin documentation is a concrete example of the separation. A plugin for ChatGPT and Codex can contain skills, an MCP server, or both, and the docs state that custom UI is not required: use model responses or structured results when they communicate the outcome. The important word is optional. You should be able to establish the product’s usefulness before you need a custom screen to express it.
\nThat does not mean shipping every integration on day one. I would rather have one coherent capability surface and one thoroughly tested integration than five wrappers around ambiguous behavior. The Magic Prompt argued the same thing for the entry point: a small invocation into a workflow that has actually been tested end to end beats an impressive surface that leaves the agent guessing at step four.
\nOne implication deserves more attention than it usually gets: an agent-first product has to make its outcomes verifiable.
\nThere is a difference between a service saying “done” and a service returning enough information to establish what happened.
\nFor the reservation example, I would expect a stable identifier, the confirmed details, the applicable terms, and a way to retrieve the current state. For a generated report, I would expect the actual artifact and a clear account of the data it covers. For a data update, I would expect a way to inspect the resulting state.
\nStructured results make those checks possible. MCP supports structured tool results and output schemas that clients are expected to validate against. But a response matching a schema is not proof that the underlying task succeeded. That still depends on the service’s behavior and the evidence it exposes. I keep running into this rule from the other side — in the Latch story, “the command succeeded” was never verification — and agent-first design is where a service owes that evidence to its callers.
\nThis changes how I would define a finished feature.
\nNot just: can a person click through the happy path?
\nAlso: can an unfamiliar agent understand the capability, use it with the right authority, detect failure, and verify the outcome?
\nI would test that directly. Give an agent a realistic intent without privately explaining how the product works, then watch where the interface leaves it guessing. A feature that only works because its creator knows the undocumented sequence is not finished for this audience.
\nA button used to be how an action was controlled. In an agent-first product, an action is controlled by intent, backed by data, and settled by evidence.
\nThe natural shorthand for all this is “UI-less,” and the phrase needs a boundary.
\nUsually we are not eliminating every human interface. We are eliminating the requirement for a dedicated product interface.
\nThe user still needs to understand consequential decisions. They still need ways to approve, interrupt, inspect, and recover. Authentication may need a trusted handoff. Comparing visual work may genuinely need a visual surface. Agent-first should never become a reason to force everything into prose.
\nFor the reservation service, a concise comparison card may be better than a long message. A clear confirmation may be appropriate before an expensive commitment. An operational dashboard may remain useful for resolving an exceptional failure. Those interfaces should exist because there is an actual need, not because we assumed every product had to begin with an application shell.
\nThe integration plumbing can be opaque to the user. The consequences cannot.
\nI should not need to know which adapter or protocol my assistant used. I should know which provider was selected, what I authorized, what it cost, and whether it succeeded.
\nThe interface can get thinner without accountability getting thinner.
\nThis architectural shift leads to a commercial one, and I find it at least as interesting.
\nWhat happens when the person choosing a product delegates most of the discovery and evaluation to an agent?
\nSay I ask my assistant to find a service for a specific task, compare the alternatives, and try the most suitable one. In that workflow I am not spending much time on anyone’s landing page. I may never experience the sequence of branding, visual hierarchy, testimonials, and sales calls the vendor designed for me. Instead, I expect the assistant to investigate suitability.
\nDoes the service meet my requirements? What does it cost? Which limitations matter? Can it be tested? What evidence supports the claims? Can the assistant actually integrate it into the workflow I asked for?
\nWe lived through a long era where content marketing was king and discovery was organic search. We are already in the transition where discovery happens through an agent’s web search instead. But I think the bigger shift is in what persuades. Palettes, branding, a beautiful landing page, a quick call with a friendly founder: those work on us because of biases we carry. An agent doing a functional comparison has no reason to be moved by most of that. It works from whatever it can retrieve and read, which is closer to data than to design, and it walks straight past the shortcuts we used to take.
\nI want to be careful here. This is a hypothesis about the workflow, not a claim that agents are immune to presentation or that branding disappears. Aesthetic preferences can be real requirements. Human relationships carry real information and accountability. An agent trained to weigh vision heavily in its decisions might see what we see. And an assistant should respect a user’s stated brand preferences rather than decide that being “objective” means ignoring them. But for a functional decision, a beautiful landing page should no longer be able to substitute for a missing capability — and the gaps some companies used to bridge with design, messaging, and relationships are going to be harder to bridge.
\nContent discovery is already halfway through this transition. Research on generative engine optimization studies visibility inside generated answers rather than placement in a conventional list of results. At the same time, Google is explicit that its generative search features are rooted in its core ranking and quality systems, and that the same SEO best practices still apply. This is an evolution of discovery, not a clean replacement of everything that came before.
\nAgent-first products add a further step. Being mentioned in an answer is not the same as being usable in a workflow.
\nA product can be easy to discover and impossible for the assistant to evaluate without a sales call. It can have excellent documentation and no safe trial. It can have an integration that takes longer to set up than the task itself.
\nThe opportunity is to shrink the distance between discovery and evidence. Let the agent inspect the relevant capabilities. Give it honest limitations, current information, representative examples, and a bounded way to try the product. Make the result inspectable. Put as little resistance as possible between the agent and a real trial.
\nThe strongest demonstration may not be a polished video of the product working. It may be the user’s own assistant making it work.
\nThere is an optimistic version of this argument that I don’t think we should accept uncritically.
\nIt goes like this: humans are swayed by appearances and persuasion; agents evaluate data; therefore agent-mediated markets will reward the objectively best products.
\nThat conclusion does not follow.
\nResearch on LLM-based recommendation has shown that models can be biased by the position of candidates in the prompt, and more recent work treats that position bias as a standing problem rather than a quirk. That doesn’t tell us how every deployed assistant behaves, but it is enough to reject the assumption that machine-generated recommendations are neutral. And we need to distinguish the model from the system around it. Which sources were retrieved? Which candidates were never found? Which tools were available? What did the host permit? Did the assistant actually test the product, or only summarize what the vendor said? Even a careful comparison is bounded by what entered the comparison.
\nThere is an adversarial side too. An assistant consuming external content can encounter attempts to redirect its behavior. Prompt injection is not a metaphor for persuasive marketing. It is a documented and actively benchmarked problem in browser-using agents, and the browser is exactly where an assistant goes to evaluate your competitor.
\nThis is where a genuinely new field opens up.
\nMarketing has spent a century understanding human attention and decision-making — what affects a choice, how to stand out in a crowded space. Agent-mediated discovery creates another set of selection behaviors to study: when a system notices an offering, treats it as credible, decides to investigate, and ultimately recommends or uses it. We have our biases, and models have theirs. There will be people who study them for the same reasons people studied ours.
\nSome of that work will improve communication. Some of it will try to exploit weaknesses — to trick the agent into believing a product matches the intent, or to talk its way into a conversation that should have been between the user and a bigger, better-suited player.
\nWe should keep the distinction clear. Making real capabilities easier to discover and verify is product work. Manufacturing evidence, misrepresenting suitability, or trying to override the user’s intent is not a better form of it.
\nFor builders of assistants, this creates a responsibility: preserve the user’s criteria, and distinguish claims from observations. For builders of products, it creates a choice about how to compete. My preference is to make the product easier to evaluate honestly — not merely easier to recommend.
\nOne reason I find this shift exciting is what I’ve been noticing in my own searches.
\nWhen I ask an agent to investigate a specific engineering problem, it sometimes surfaces a small repository, a recently released project, or a narrow discussion thread that I would never have found through my usual browsing. That is an observation, not evidence that AI search systematically favors small projects. But it changes how I think about discovery.
\nDiscovery for open-source projects used to be hard. GitHub does a wonderful job, and it still wasn’t enough: you needed intense marketing through the dev community to land on a platform or a list that would showcase your work. And on the other side, in my own evaluation habits, a low star count or an unfamiliar name was a perfectly good reason to move on. Popularity was a convenient shortcut for deciding where to spend attention. Incomplete, niche, recently released projects were invisible almost by definition.
\nAn intent-driven investigation asks a different question: does this particular project solve this particular problem?
\nA broad framework can be well known and poorly suited to a narrow constraint. A small project can address that constraint directly. Popularity doesn’t stop mattering. The ranking research I cited above found LLM rankers biased by popularity as well as position. A precise match simply gets another route into consideration. Google’s description of query fan-out illustrates one mechanism: to develop a response, its AI features may issue multiple related searches across subtopics and data sources. That doesn’t guarantee comprehensive or fair discovery, but it helps explain how a conversation ends up somewhere the user’s first search phrase never would have.
\nFor an open-source maintainer, that makes specificity valuable. Explain the actual problem. Show a reproducible example. State what the project does not support. Make installation, testing, and failure understandable. Give a potential evaluator enough evidence to decide whether the project fits. A small project does not have to present itself as a universal platform to deserve attention.
\nDiscovery is still not endorsement. A relevant repository needs evaluation for maintenance, licensing, security, and suitability, and an assistant should not confuse “I found something unusually specific” with “this is safe to adopt.” What excites me is the possibility of a fairer chance to demonstrate relevance — not skipping scrutiny.
\nThis connects directly to the threads I’ve been pulling on all year.
\nHarness-driven development asks what an agent needs around it to do useful work: context, tools, instructions, execution boundaries, feedback. Agent-first development looks at the software that environment operates. What must the product expose so a harness can use it without relying on hidden knowledge or a human navigating its screens?
\nThe Magic Prompt explores a related entry point: how a small invocation leads into a complete, tested workflow instead of leaving the user to assemble the missing pieces.
\nDisposable software raises another possibility. Some interfaces may not need to be permanent at all. A capable service can back a temporary report, a one-off comparison view, or a task-specific application generated for the moment and discarded afterward. The capability stays durable while its presentation changes.
\nTaken together, these ideas make me less interested in treating the application shell as the natural starting point for every product.
\nI would rather begin with a human intent, identify the capability that satisfies it, define the authority required to use it, and decide what evidence establishes success. Then make that capability reachable through the assistants and harnesses the intended users actually choose. After that, ask where a dedicated interface adds value.
\nThis is not a claim that every application should lose its UI, or that every decision should be delegated. It is a change in the default question. Instead of asking how to add agent access to the application we already designed, ask what the product would look like if agent access were a primary way of using it.
\nThe lesson I take from mobile-first is not that software should keep moving toward smaller screens.
\nIt is that a new interaction model exposes assumptions we stopped noticing.
\nMobile-first challenged the assumption that we could begin with abundant space and solve constraints later. Agent-first challenges the assumption that the user must enter our product’s interface to receive its value.
\nWe went from a full desktop to a small viewport. Now the surface is getting thinner still, all the way to no UI at all — and the applications underneath must be served through agents and harnesses, with a breadth of integrations that a personal assistant can adopt easily and that the human requesting the service never has to see.
\nI think that is a substantial opportunity for software engineers. We can build services that participate in workflows without owning the whole experience. We can make capabilities portable across assistants. We can let products prove their usefulness through evidence rather than presentation. But we have to design for it deliberately.
\nBefore drawing the first screen, I would ask one question:
\nCould someone’s assistant discover this product, use it correctly, and prove that it accomplished what the person wanted — without requiring them to open our application?
\nIf the answer is yes, the interface becomes a choice.
\nThat is where agent-first development begins.
", "date_published": "2026-10-01T00:00:00.000Z", "tags": [ "Developer Philosophy", "Agents", "AI Tools", "Software Engineering", "Software Architecture", "Predictions", "Harness", "Open Source", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-09-24-codex-operating-system-for-agents/", "url": "https://kobi.kadosh.me/blog/2026-09-24-codex-operating-system-for-agents/", "title": "Codex Is Becoming an Operating System for Agents", "summary": "Codex has become the center of my development workflow, and the model is only part of the reason. Sessions that read other sessions, voice steering, goal mode, side chats, subagents on request, MCP, and an app server other harnesses can drive: the environment around the model is where the work happens now. Coding assistant is no longer a complete description.", "content_html": "It feels appropriate to be working through this article in a conversation with GPT. This is how I begin most work now: I describe what I’m trying to achieve, explain the context, and start working with an agent on how to get there.
\nBut the more I work this way, the more I realize that the model is only part of the story.
\nThe environment around it matters at least as much. How do I give it context? How does it interact with my tools? Can it delegate? Can I steer it without restarting the work? Can it coordinate with something that is already running somewhere else?
\nThose questions are why I think Codex deserves a different conversation from the one we usually have about coding assistants.
\nIn my workflow, Codex has become something of an operating system for agents.
\nI’m not suggesting it replaces macOS, Windows, or Linux. I’m describing the role it plays for me: the place where I bring together context, tools, sessions, and other agents to pursue an outcome.
\nJust by asking, I can spin up a new project and start working across my entire computer: apps, connectors, MCP integrations, and even other coding agents.
\nAnd I’m specifically talking about Codex on my local machine. That distinction matters. A local Codex workspace, with its configured tools and permissions, is not interchangeable with a web chat.
\nWhen I use the word harness, I mean the system around the model that makes useful work possible: its instructions, context, tools, permissions, execution environment, and feedback mechanisms. I made the longer case in Harness-Driven Development: you are not using a model, you are using a harness, and the same model in a different harness is a different engineer. Harnesses are not interchangeable. As I put it in The Magic Prompt, Codex has one set of capabilities and Claude Code exposes another, and any serious workflow has to know which one it is running in.
\nThe model matters. A lot. But I don’t experience Codex as a model sitting behind a text box. I experience it as an environment in which I can establish a goal and begin working toward it.
\nThat might involve a repository, but it doesn’t have to stop at the repository.
\nCodex can connect to external tools and context through MCP servers, and the desktop app, the CLI, and the IDE extension share that configuration on the same machine. With the right setup and permissions, the desktop app can also see and operate graphical applications on macOS and Windows when a command-line tool or a structured integration is not enough. These are different routes into the environment where the work actually happens.
\nFor me, the significance is not simply that there are more integrations.
\nIt is that I spend less time acting as the integration.
\nI don’t want to copy an explanation from one window into another, reconstruct the project’s history for another agent, collect its response, and manually carry that response back. Sometimes that is necessary. But it shouldn’t be the default architecture of working with agents.
\nI want to explain the outcome, establish the boundaries, and have a capable coordinating agent work through the available interfaces.
\nThis is also why interoperability needs to work in both directions. Codex should be able to use other tools, but other tools and external harnesses should also be able to use Codex.
\nThere is a concrete foundation for that. Codex’s App Server exposes a JSON-RPC interface for thread management, approvals, and streamed agent events: create, resume, fork, or branch a thread, and steer or interrupt the turn running inside it. It exists so that rich clients and third-party integrations can drive Codex. Codex is not accessible only through a window that a human must operate.
\nThat is where the operating-system analogy starts to make sense to me. An operating system doesn’t need to be every application. Part of its value is letting different programs do useful work together. It is the same instinct behind Skills, Pipes, and the Unix Philosophy: small pieces with well-defined interfaces compose, and one large piece that tries to be everything does not.
\nLikewise, Codex doesn’t need to be my entire agent setup to become its centerpiece.
\nThe capability I lean on most in my local setup is working across sessions.
\nOne chat can look into another: read its transcript as a native tool, send a message to a session that is already running, pick up its work, or start a new project from it. Instead of treating every conversation as an isolated exchange, I can treat sessions as parts of one working environment.
\nThat doesn’t mean every chat automatically knows everything in every other chat. There is an important difference between information existing somewhere and the current agent having access to it through an available interface.
\nWhat matters to me is that I don’t always have to be the person transporting that information.
\nOnce a session has accumulated the intent behind a project, it becomes valuable in a way that a fresh prompt is not. It contains the questions we considered, the constraints we established, the approaches we rejected, and the reasons behind those decisions.
\nI want to be able to return to that working relationship. I also want other work to benefit from it without forcing everything into one enormous conversation.
\nThis changes what I ask of a chat interface. I’m no longer looking only for somewhere to enter a prompt. I’m looking for somewhere to organize and steer ongoing work.
\nVoice makes this especially interesting.
\nThe desktop app’s voice mode is more than dictation. It can start separate tasks, check on existing ones, report progress, and take an interruption mid-task when I want to change direction. Availability depends on your plan, rollout, and workspace settings, so you may not have it yet.
\nThe interaction I care about sounds something like this:
\n\n\nCheck where that investigation stands and tell me what is blocking it. Keep the implementation moving, but don’t change the approach until we’ve reviewed the alternative.
\n
That is a different relationship with a computer from opening applications one by one and performing each step myself.
\nI think voice conversation is the next way people will talk to their harnesses. Not because typing will disappear, or because every task benefits from being spoken aloud, but because expressing intent and reviewing decisions are conversational activities.
\nThe important part is continuity: being able to change how I communicate without having to restart the work.
\nThere is a difference between asking an agent to perform a step and asking it to pursue a goal.
\nA step sounds like this:
\n\n\nInspect this function.
\n
A goal sounds like this:
\n\n\nWork out why this behavior is failing, look at the relevant parts of the system, propose a fix, implement it within the boundaries we agreed, and verify the result.
\n
The second requires more than a good first response. It requires maintaining direction as new information appears.
\nThis is one of the reasons Codex has become central to my workflow. I give it work that has a trajectory, not a sequence of disconnected prompts.
\nGoal mode makes that distinction explicit. A goal needs an outcome, constraints, and verification criteria, and once it is running I can pause it, resume it, edit it, or steer it with a follow-up message.
\nBut I don’t use durable to mean an immortal process or perfect memory. I mean work that I can return to, understand, and continue without reconstructing the entire purpose from scratch. Local execution still needs an available environment; persistence of a session is not the same thing as uninterrupted execution.
\nFor a centerpiece harness, the questions I care about are practical.
\nDoes it still understand what we are trying to achieve? Can I tell what has changed? Can I interrupt an assumption without throwing away the larger goal? Does it know what evidence would justify calling the task complete?
\nA task running for a long time is not impressive by itself. What matters is whether that time is producing justified progress toward the intended outcome. That is the same architecture of verification I wanted from agents before any of this existed: plan, execute, verify, iterate, and never mistake a confident completion message for evidence.
\nThis also changes my responsibility as the operator. I need to be clearer about what “done” means, which decisions I’m delegating, and where the agent needs to stop and involve me.
\nOnce a main session has developed substantial context, I don’t want to abandon it every time another question comes to mind.
\nBut I also don’t want every question to interrupt its work.
\nMaybe I want to understand a decision. Maybe I want to explore an alternative. Maybe I want to challenge an assumption before deciding whether the main task should change direction.
\nThis is why I find side chats so useful. The documented workflow is exactly that: open a side chat for an explanation or a status recap without interrupting the main chat, in its own context, so two chats never edit the same files at once.
\nIn practice, I use that space to keep thinking around the work while the main thread continues.
\nThe main session can remain the center of the project’s execution, while I investigate something adjacent to it. I don’t need to choose immediately between derailing the current task and opening a completely disconnected conversation.
\nThere is one limitation I keep running into in my current setup: side chats don’t launch subagents.
\nSome people will reasonably say that this is not critical. And for a quick explanation, it is not.
\nBut sometimes a side question is not a small question.
\n\n\nIs this really the right approach?
\n
Answering that might mean exploring the codebase, checking a dependency, and challenging the assumptions behind the current plan.
\nAt that point, I would like the side investigation to benefit from the same delegation capabilities as the main session.
\nThat distinction is important: I use side chats to continue my own investigation alongside the work; I use subagents to delegate pieces of the work itself.
\nThey solve related, but different, problems.
\nPeople like the idea of a magic word. With Codex, one comes surprisingly close:
\n\n\nUse a subagent for this.
\n
There is nothing mystical about it. It is an instruction to use a delegation capability the subagent documentation describes plainly: ask for subagents or parallel agent work directly, and each one runs in its own thread and comes back with a focused summary. In most configurations you do have to ask; it won’t usually delegate on its own. And in my experience I haven’t needed to define a custom agent role before asking.
\nWhat I find powerful is how little ceremony I need before trying it.
\nI don’t necessarily need to stop working, design a permanent agent role, create another process, and manually manage the exchange. I can ask for a specialist suited to the problem in front of me.
\nBut there is a less obvious point here.
\nFiguring out what to delegate is often harder than spawning the agent.
\nSuppose I am evaluating whether to add a dependency to a project. What specialist do I actually need?
\nA generic “research agent” might return a feature comparison. That could be useful, but it might completely miss the decision I need to make.
\nPerhaps I first need an explorer to establish how the project currently handles the relevant behavior. Then I need someone to look for evidence that the proposed dependency solves a real gap. Perhaps I need an adversarial reviewer whose job is to find a simpler approach.
\nThose are different assignments, with different evidence requirements.
\nA request could look like this:
\n\n\nBefore proposing this dependency, use one subagent to inspect how the project handles the requirement today, and another to investigate whether a simpler approach would satisfy it. Keep both investigations read-only. Ask them to return evidence, uncertainties, and the assumptions their conclusions depend on. Compare their findings before recommending a change.
\n
The important part is not the number of agents. It is the division of responsibility.
\nOn another task I might need a fixer working against a narrowly defined failure, then a reviewer checking whether the fix actually addresses it. I might need an LLM as a judge against explicit acceptance criteria, an adversary whose only job is to give me the feedback I don’t want, or a scout whose only responsibility is to find out what we don’t yet understand.
\nI don’t want to assume that one predefined collection of roles is appropriate for every problem.
\nWhat I want is to work with the main agent to discover the right delegation structure for the task we are doing now.
\nThis is where separate working contexts earn their keep. An exploration produces a lot of intermediate material that doesn’t belong in the main conversation. Because each subagent runs in its own thread and returns a summary, the investigation moves out of the main session, and the main session stays oriented around requirements and decisions.
\nHowever, I would not treat two agents agreeing as proof of correctness. They may be working from the same mistaken assumption. A judge still needs meaningful criteria. A reviewer still needs evidence. A fixer still needs verification.
\nAnd more agents are not automatically better. The same documentation is candid about the cost: subagent workflows consume more tokens than a comparable single-agent run, and several agents editing code at once can create conflicts. Coordination is never free.
\nThe real advantage is being able to experiment with delegation without first building an orchestration system for every idea.
\nI haven’t moved everything into Codex. In Buzzcut I described my split: Claude Code for most serious repository work, Codex for a second opinion with a different set of habits, and Grok Bot for small, sharply scoped bots that live close to a conversation rather than close to a codebase. Since then, more of that work has shifted toward Codex, and Claude Code is still very good at certain tasks. What this post adds is a different axis: not which agent writes the code, but which environment holds the goal.
\nGrok Bot is also where I go when I’m thinking about a persistent collection of bots with different responsibilities. That organizational question deserves its own article: how should an AI crew be structured, which responsibilities should remain durable, and which should be created temporarily for a specific task?
\nI’ve been experimenting with durable Codex sessions as personas, too. It’s fun. It works. But the ergonomics are nowhere near what Grok Bot gives me for that style of organization.
\nThat doesn’t weaken my argument about Codex.
\nThe place where I prefer to organize persistent personas doesn’t have to be the same place where I coordinate local execution. And the agent I prefer for a specific implementation task doesn’t have to own the entire workflow.
\nI’m more interested in how well these pieces cooperate than in finding one product that replaces all the others.
\nIn my setup, Codex’s value is partly that it stays useful even when something else is doing part of the work. Its role can be to hold the broader goal, coordinate the interfaces, and help me evaluate what comes back.
\nThat is a much stronger position than simply being another isolated assistant.
\nThere are limits, and they are worth stating without losing sight of what already works.
\nThe one hard wall I have hit is computer use of Codex over Codex: asking Codex to drive its own app through the screen. The documented boundaries rule that out on purpose. Computer use will not automate terminal applications or the ChatGPT app itself, because automating them could bypass its security policies.
\nI don’t see self-operation through the screen as a prerequisite for the coordination I want. The session interfaces are a more direct way to work with existing tasks, within the permissions they expose.
\nMore broadly, I don’t want a central harness whose usefulness depends on ignoring boundaries.
\nThe more responsibility I give it, the more I care about being able to understand what it is doing, constrain its access, inspect its outputs, and intervene.
\nLikewise, I don’t want important project decisions to exist only somewhere in a long transcript. My expectation is that durable work produces durable artifacts: code, tests, recorded decisions, and enough evidence for someone to understand the result.
\nThe conversation should help operate the project. It should not become the only place where the project exists.
\nThe progression through GPT-5.5 and GPT-5.6 to GPT-6 Astra has changed what I’m willing to delegate. Things are on a different level from where they were a year ago. Astra is available in Codex, and OpenAI calls it its best model for software engineering to date.
\nSo I implore you to try Codex. Not by asking the newest model to write a function.
\nGive it a real, bounded piece of work. Let it establish context in a project. Ask it to investigate before implementing. Open a side chat while the main task is running. Ask for a subagent where a separate investigation would help. Connect the tools the work actually needs, with the permissions it actually needs.
\nThen look at how the workflow changes.
\nHow often are you reconstructing context? How much information are you carrying between tools? Can you continue thinking while execution is underway? Can you redirect the work without starting over? Are you getting evidence you can review, rather than only a convincing completion message?
\nThose are the questions that explain why I rely so heavily on Codex today.
\nI still open it to write code. But more and more, I open it because I have something I want to accomplish on my computer, and I want a capable agent to coordinate everything required to get there.
\nThat is why “coding assistant” no longer feels like a complete description.
\nFor me, Codex is becoming the operating environment in which agents do the work — not just another agent doing one part of it.
\nDictated by voice, drafted in a conversation with GPT, then edited and published with Claude Code. The arguments are mine; the drafting was collaborative.
", "date_published": "2026-09-24T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Codex", "Harness", "Claude Code", "Grok", "Developer Philosophy", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-09-17-the-magic-prompt/", "url": "https://kobi.kadosh.me/blog/2026-09-17-the-magic-prompt/", "title": "The Magic Prompt: A Minimal Invocation Into a Tested Human-Agent Workflow", "summary": "A magic prompt is not a clever wall of instructions. It is a small, portable entry point into an engineered, tested workflow that takes a human and an agent from intent to a verified outcome — pre-flight, prerequisites, installation, authentication, validation, and the next step included. Here is how it should behave, and how to build one in layers.", "content_html": "There is a particular kind of prompt I find myself wanting more and more when working with coding agents.
\nI call it a magic prompt.
\nThe name is intentionally a little misleading. There should be very little magic inside the prompt itself.
\nA magic prompt is not a giant wall of instructions. It is not the perfect combination of words that somehow makes an agent smarter. And it is definitely not another README disguised as a prompt.
\nA magic prompt is a small, portable invocation that takes a human and an agent from intent to a complete outcome.
\nYou paste it into Codex, Claude Code, Cursor, or any other sufficiently capable agent, and the expectation is simple:
\n\n\nTake me from here to there.
\n
Not 80% of the way.
\nNot until we discover that I was supposed to install three CLIs first.
\nNot until we reach a documentation page telling me to configure an account.
\nNot until the agent says, “Everything is ready, now manually follow these twelve steps.”
\nA good magic prompt owns the journey from A to Z. Zero to one. The whole process, as the person who invoked it understood it — and as the person who authored it intended it.
\nThat changes how we need to design prompts.
\nImagine I hand you a prompt for contributing to an open-source project. Say, one of Slack’s open-source SDKs. The desired outcome might be:
\n\n\nGet my environment ready and take me through making my first valid contribution.
\n
There are dozens of hidden assumptions inside that sentence.
\nDo I have the repository? Do I have the correct runtime? Am I authenticated with GitHub? Do I have the required CLI tools? Does the project require signing a Contributor License Agreement? Is there a developer program I need to join? Are there forms I need to fill out, boxes I need to check? Do I have permission to create whatever sandbox, workspace, application, or token the project requires? What operating system am I using?
\nAnd then a second set of questions, about the other participant:
\nWhat tools does my agent have? Can it operate a browser? Can it execute shell commands? Can it see what I see? Can it complete an OAuth flow? Which decisions require me, and which can it make on its own?
\nTraditional documentation distributes the answers to these questions across README files, contribution guides, documentation sites, onboarding pages, tribal knowledge, and people’s heads. Then it relies on the user to assemble the puzzle.
\nA magic prompt should not.
\nIts contract is that the puzzle has already been assembled.
\nBefore getting into the architecture, it helps to look at a magic prompt from every side of the table, because each side has a different expectation, and a good design satisfies all of them at once.
\nThe human invoker. The person who pastes the prompt. Their expectation is safety and completeness. Safe, in that the prompt will not wander off, do something destructive, or leave their environment half-configured. Complete, in that it takes them to the outcome they were promised, not to a fork in the road.
\nThe human author. The person who wrote the prompt and the workflow behind it. Their intent defines what “done” means. They know the process, and — this is important — they are biased by that knowledge. More on this later.
\nThe agent. The harness that actually executes: Claude Code, Codex, Cursor, a cloud agent with computer use, whatever. The agent needs instructions it can act on, a way to discover what it is and is not able to do here, and a way to hand control to the human at exactly the right moments.
\nThe required outcome. Not “the command returned zero.” The outcome as the invoker would recognize it: a thing exists, I can see it, it works, and I know what to do next.
\nWhen you design against all four, the shape of a magic prompt becomes fairly clear. It has a contract with the human, a contract with the agent, a layered structure, and a definition of completion that is stricter than most agents use by default.
\nThere still needs to be a boundary. A magic prompt cannot assume that absolutely nothing exists.
\nIf I want to build something for Slack, I probably know that Slack exists. I may already have a workspace, or be willing to create one. If I want to deploy something to Vercel, I probably have or am willing to create a Vercel account. If I want to build on Wix, I have some idea what Wix is. I am not completely new to the platform; I have some access to it — a free tier, a paid plan, a developer account — and I know roughly where I stand with it.
\nThese are reasonable human-level prerequisites.
\nBut they should be explicit and, more importantly, minimal.
\nThe magic prompt should not begin with an invisible dependency tree:
\n\n\nBefore using this prompt, read this guide, install these five tools, create these resources, configure these environment variables, request access here, and then come back.
\n
At that point it isn’t a magic prompt. It’s documentation with a prompt at the end.
\nInstead, configuration should become part of the execution.
\nNeed a CLI? Install it. Need an SDK? Install it. Need authentication? Start the authentication flow. Need an API token? Determine whether it can be created automatically. If not, guide the human through exactly the intervention that is required, and nothing more. Need a browser? Use one, assuming the underlying agent has that capability. Need the human to approve something? Ask at the moment approval becomes necessary.
\nThere is no assumption that everything must be pre-installed. There is no assumption that some step is too interactive, too manual, or too “outside the terminal” to belong in the prompt. Everything is up for grabs — including things that cannot be fully automated and require a browser, or computer use, or a human clicking a checkbox — provided the underlying agent can do it, or can guide the human to do it.
\nThe distinction I find useful is between human prerequisites and machine prerequisites.
\nHuman prerequisites should be minimized and declared upfront. Machine prerequisites should be owned by the workflow.
\nThere is another side to this contract: the agent.
\nThe magic prompt cannot assume every harness is identical.
\nCodex has one set of capabilities. Claude Code exposes another. An agent running inside an IDE has another. A cloud agent with computer use has capabilities that a local terminal agent doesn’t. Some agents can drive a browser; some can only ask you to open one. Some have persistent skills; some start from nothing every time.
\nSo before doing the work, the workflow needs to understand its environment.
\nI think of this as the pre-flight.
\nBefore execution, determine:
\nThis matters because a magic prompt should not blindly execute a tutorial. It should resolve a path.
\nIf GitHub authentication already works, don’t teach me how to authenticate with GitHub. If the CLI is already installed and compatible, don’t reinstall it. If I already completed developer registration, don’t send me through registration again. If I don’t have something, don’t merely report that as an error. Determine how it becomes true.
\nAnd when the pre-flight discovers a gap — a missing capability, a tool that needs a permission the agent does not have, a preference it cannot infer — that is precisely the moment to ask the human. Not as a failure, but as a configuration step. “I can’t open a browser from this session. Can you open this URL and tell me when you’ve approved the app?” is a pre-flight outcome, not an escape hatch.
\nThe pre-flight converts a generic process into a process for this human, on this machine, using this agent, right now.
\nThis leads to what I think is one of the more counterintuitive properties of a magic prompt:
\nThe magic prompt should be lean.
\nWe shouldn’t solve this by producing a 15,000-word superprompt. We already know how that goes. I argued in Your Docs Are Not the Prompt that project context is a secondary orientation layer, not the thing that drives an agent’s behavior. The same holds here. A giant prompt is a giant document with all the same problems: it drifts, it goes stale, it fights with the harness’s own instructions, and nobody can tell which part of it is actually load-bearing.
\nThe initial prompt is an invocation layer.
\nIt can contain some configuration and enough information to establish intent — who I am, what I want, what I already have, what I prefer — but its primary responsibility is to retrieve and initialize a larger workflow.
\nSomething conceptually like:
\nI want to create X.\nUse the latest workflow from Y.\nMy preferences are Z.\nRun its pre-flight, resolve missing prerequisites with me,\nexecute the workflow to completion, validate the result,\nand leave me with the next useful action.The intelligence is not primarily in those sentences.
\nThe intelligence lives behind them.
\nBehind the magic prompt should be what I’ve been thinking of as an envelope skill.
\nYou could call it a wrapper skill, an orchestration skill, an encompassing skill. The terminology matters less than the architecture.
\nThe envelope owns the complete journey. It is the glue between the different steps and the different skills that need to be invoked, and it is the part that adapts to the specific agent running it and to the human’s preferences. This is where the actual magic lives.
\nIt knows which smaller skills exist and how they fit together:
\nMagic Prompt\n ↓\nEnvelope Skill\n ↓\nPre-flight\n ↓\nEnvironment / Account Setup\n ↓\nAuthentication\n ↓\nTool Installation\n ↓\nDomain-Specific Workflow\n ↓\nValidation\n ↓\nHuman Verification\n ↓\nNext ActionEach of those pieces can then be skillified independently.
\nAn authentication skill doesn’t need to know everything about creating a Slack application. A developer-registration skill — the one that walks a human through joining a developer program, creating a sandbox workspace, and accepting the terms — doesn’t need to know how the eventual project will be implemented. A local-environment skill can specialize in determining whether this machine satisfies the requirements and fixing it when it doesn’t.
\nThe envelope composes them.
\nAnd importantly, it composes them conditionally. If pre-flight establishes that a prerequisite has already been satisfied, that branch disappears. If the agent can drive a browser, the OAuth branch runs one way; if it cannot, the same branch becomes a guided handoff to the human.
\nTwo properties of the envelope are worth spelling out.
\nFirst, it should be fetched live. The prompt points at it; the agent retrieves the current version at invocation time. That is what lets the workflow be improved, templated, and optimized without anyone re-pasting anything. A magic prompt that embeds the whole workflow inline is frozen the moment it is shared.
\nSecond, the smaller skills underneath it should be tested and evolved on their own, before the envelope depends on them. The developer-registration skill gets exercised in isolation until it reliably takes a new person through the developer program. Only then does it become a prerequisite the envelope can trust. The groundwork comes first; the composition comes after.
\nThis is the same argument I made in Skills, Pipes, and the Unix Philosophy, applied one level up. Small, well-scoped pieces, each doing one thing well, composed by something whose only job is composition.
\nThe prompt isn’t magical.
\nComposition is.
\nThere is another design property I think is important here.
\nMany agent skills are written exclusively for the agent.
\nBut these workflows inherently have two participants: the agent and the human.
\nA good skill therefore needs instructions for both.
\nThe agent side might say:
\nThe human side of the same step might become:
\n\n\nYour browser is going to open an authorization page. Sign in using the workspace you want to develop against. Approve these permissions. Tell me when the browser confirms authorization.
\n
These are different interfaces to the same operation. The agent gets rules. The human gets a guide. Both are written by the author, in the same skill, so they can never drift apart.
\nThis makes skills less like documentation and more like small collaborative protocols between humans and agents. The human is not reading a guide while the agent works; the human is participating in a step the agent is orchestrating.
\nOne of the easiest ways to accidentally break the magic is the word manual.
\nAgents frequently reach some boundary and respond with something equivalent to:
\n\n\nI can’t complete this part. Follow this guide and return when you’re finished.
\n
Sometimes human intervention genuinely is unavoidable. But human intervention and manual delegation are not the same thing.
\nIf the human needs to click a legal acceptance checkbox, the agent can navigate them to it — the exact page, the exact box, what it means, and what to do afterward.
\nIf OAuth requires the human to authenticate, the agent can initiate OAuth, explain what is happening, wait for completion, and verify authentication afterward.
\nIf information is required — a workspace name, a region, a plan choice — the agent can ask for that specific information at the appropriate point, rather than stopping and pointing at a form.
\nThe human should remain part of the execution graph. They shouldn’t be ejected from it.
\nA magic prompt therefore needs a useful rule:
\nWhen automation stops, orchestration should continue.
\nThere is also a surprisingly important question: when is the magic prompt finished?
\nAgents tend to define completion technically. The repository exists. The application was created. The deployment succeeded. The command returned zero.
\nBut that isn’t necessarily the human’s definition of completion.
\nIf I asked an agent to create something, I probably need to see it.
\nOpen the application. Show the deployment. Take me to the relevant dashboard. Render the result in my browser, or capture it and show it to me. Verify that the thing we created actually behaves as expected — send the test message, hit the endpoint, trigger the slash command.
\nCompletion should include a human-observable outcome whenever one exists.
\nAnd even that isn’t quite enough.
\nSuppose the workflow successfully created my development environment.
\nGreat. Now what?
\nTraditional setup documentation often ends there:
\n\n\nCongratulations! Your environment is ready.
\n
But from the human’s perspective, this may be precisely the point where the interesting part begins.
\nThe magic prompt should establish the next interaction. For example:
\n\n\nEverything is configured and validated. You can now ask me to find a suitable starter issue in this repository and prepare a contribution.
\n
Or:
\n\n\nYour Slack app is installed in your sandbox workspace and responding. From here, you can ask me to implement your first slash command.
\n
Or:
\n\n\nDeployment is complete. You can now describe the change you want to make and I’ll modify and redeploy it.
\n
Don’t assume the process is done because the thing we set out to create exists. The product isn’t merely the artifact. The product is also the new capability the human has acquired — and the very next sentence they can say to their agent to use it.
\nA lot of this reminds me of how we’ve historically written developer documentation.
\nDocumentation is usually written by somebody for whom the environment already works.
\nThat’s a dangerous starting point.
\nThe author already has the correct runtime. Their SSH keys work. Their accounts exist. They signed the agreement six months ago. Their machine contains some tool they installed for an unrelated project three years ago. They know what the internal terminology means — what a “workspace” is here versus there, what “sandbox” means in this company’s vocabulary, which of the three dashboards is the one you actually use.
\nThen they write:
\nnpm install\nnpm run devAnd everything works.
\nFor them.
\nWe compensate for this by expecting expertise from the reader. A sufficiently experienced engineer can usually bridge the missing pieces. They search for an error. They recognize that a credential is missing. They know what OAuth is. They infer which account they should use.
\nBut this isn’t evidence that the documentation was complete. It’s evidence that the human was capable of repairing it.
\nEvery system, every company, every community has its own way of doing things — its own onboarding rituals, its own forms, its own naming. To the author these are obvious. To a new person in a new environment they are foreign, and the “obvious” steps are exactly the ones that go unwritten. We were reckless about prerequisites, reckless about how our documentation fit into the puzzle in different people’s heads, and we relied on experts to close the gap.
\nAgents give us an opportunity to stop relying on that repair mechanism — but only if we stop carrying the old gaps into the new medium.
\nThere is a simple test for magic prompts that I think should become standard:
\nRun them from nothing.
\nNot from the machine where the workflow was developed. Not from the author’s workspace. Not from the environment where everything has been configured for six months.
\nUse a clean environment. A fresh container, a new machine, a throwaway account. Assume the human has only the minimal prerequisites that the magic prompt explicitly declares — and nothing else.
\nThen run the whole thing.
\nEvery time the workflow encounters an undocumented assumption, that assumption becomes one of three things:
\nRepeat until there are no accidental gaps.
\nThen do it again with a different agent, because the pre-flight branch that works in Claude Code may not be the one that works in Codex.
\nThis is almost like integration testing, except the system under test is a human-agent workflow. It is the same discipline I described in The Feedback Loop Series Part 3: AI Agents, pointed at a different target: instead of testing whether the agent produced correct code, you are testing whether the workflow reliably gets a stranger to the outcome.
\nWhen I build these flows honestly — mimicking the new user fully, on a clean workspace, with their setup and not mine — there is no gap left for an expert to bridge. The gap only exists when I skip that step and build on top of what I already have.
\nWe spent years treating prompts primarily as instructions.
\nI think that mental model is becoming insufficient.
\nAs agents gain shells, browsers, computer use, APIs, persistent skills, authentication, and the ability to operate external systems, a prompt can increasingly behave like an entry point into executable knowledge.
\nThat changes what good prompt engineering looks like.
\nThe interesting problem is no longer:
\n\n\nWhat exact words will make the model produce the best answer?
\n
It becomes:
\n\n\nHow do I package a process so that a human can invoke it from an unknown environment and reliably reach the intended outcome?
\n
That includes instructions. But it also includes capability discovery, dependency resolution, configuration, authentication, conditional execution, human interaction, validation, recovery, and handoff.
\nThe magic prompt is simply the smallest interface into that system.
\nThis is also why I think publishing a collection of magic prompts without the infrastructure behind them misses the point.
\nThe valuable artifact isn’t:
\n\n\nPaste this into your coding agent.
\n
The valuable artifact is everything required to make that sentence trustworthy:
\nOnly then can the invocation become tiny.
\nThat’s an interesting inversion. The more engineering we put behind the prompt, the less prompt the user should need to see.
\nAnd perhaps that’s the best definition:
\n\n\nA magic prompt is a minimal invocation into a tested, adaptive human-agent workflow that owns the path from prerequisites to a verified outcome — and leaves the human ready for what comes next.
\n
The magic isn’t that the prompt knows everything.
\nThe magic is that the user no longer needs to.
\nIn a follow-up, I plan to make this concrete: an actual magic prompt for a first open-source contribution to one of the Slack SDKs, with its envelope skill and the full skill tree underneath it — developer registration, sandbox workspace, CLI setup, authentication, and the contribution itself — tested from an empty workspace.
", "date_published": "2026-09-17T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Claude Code", "Skills", "Documentation", "Developer Experience", "Open Source", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-09-15-harness-driven-development/", "url": "https://kobi.kadosh.me/blog/2026-09-15-harness-driven-development/", "title": "Harness-Driven Development: More Than Source Code", "summary": "Software is no longer just its source code. Its harness — the tools, memory, skills, and rules guiding the agents that build and run it — is now first-class.", "content_html": "A few days ago I stopped and actually read the file tree of my most active repository. Not the src directory — the rest of it.
There was a CLAUDE.md at the root. A .claude directory holding agents, skills, and commands. A publishing-cadence document. A roadmap. Research notes from an architecture debate two agents had while I was asleep. Migration plans for migrations that already shipped. Critique outputs from a review loop. Scratchpads full of intermediate thinking that fed decisions I now take for granted.
Very little of it was written for the people who use what the repository builds. Surprisingly little of it was even written for me. Most of it was written by agents, for agents — instructions, memories, and working notes that exist so the next session starts smarter than the last one.
\nI tried to imagine actually deleting it. The site would still build. The tests would still pass. Nothing a user touches would change. And yet the project would get worse in a way I could feel but not point to — the next review would miss context, the next migration would re-derive settled decisions, the next agent session would ask questions the repository had already answered.
\nMy first instinct was to tidy it all away. My second was that I was looking at the software.
\nWe have named ways of working before — object-oriented programming, domain-driven design, test-driven development. I think the way we work now deserves a name too, and the honest name centers neither the model nor the code.
\nI’ve started calling it harness-driven development — though I don’t claim the phrase. Others have been reaching for the same language this year, and OpenAI now writes about “harness engineering” outright. What I want to add is a specific shape: an outer harness that builds the system and an inner harness that operates it, and the argument that this environment is now a first-class part of the software rather than scaffolding around it.
\nLook at any repository that has been through a few months of serious agent-assisted development and you will find the same thing: a second layer growing alongside the source code.
\nPart of that layer is native to the tools: skills that teach the agent a procedure, rules that constrain it, hooks that fire around its actions, and memory files that persist what it learned. Context documents — CLAUDE.md, AGENTS.md, and their cousins — tell it what this project is and how to behave inside it.
The other part is produced: research summaries, design debates, migration plans, review critiques, scratchpads of intermediate reasoning. Documents the agent wrote because it needed them to think, and kept because the next agent will need them to think too.
\nWe used to complain that engineers don’t write enough documentation. That problem quietly inverted. There is now far more of it than we ever wrote by hand, scattered exactly where the work happened, and most of it was never meant for human eyes.
\nI wrote before that your docs are not the prompt — descriptive documentation is a weak signal for a coding agent next to the prompt and the code. That is still true, and it is why this second layer is a different animal. A README is a brochure: it describes the software and hopes someone reads it. A skill, a rule, or a memory file is a control surface: it steers the machinery that builds the software.
\nWhich means the old reflex — treat everything that isn’t source code as clutter or ceremony — now deletes real capability. Remove a rules file and behavior changes. Lose a research document and the next session pays to re-derive it. Let a skill drift out of date and every workflow that loads it degrades. These files carry the operational weight we used to reserve for code, and they deserve the same treatment: version control, review, deliberate design.
\nThis layer doesn’t document the software. It is the software.
\nWe say “I’m using Claude” or “I’m using GPT” the way we used to say “I’m on Java.” It’s shorthand, and it hides the thing that actually matters.
\nYou are not using a model. You are using Claude Code, or Codex, or Cursor. You are using a harness.
\nA harness is everything wrapped around the model that turns raw intelligence into a working agent: the tools it can call, the memory it carries between sessions, the skills it can load, the rules that constrain it, the runtime it executes in, the processes it follows when it plans and reviews, and the interfaces through which a human steers it. The model is one component. A decisive one — a harness is only ever as good as the model it harnesses — but still one component.
\nI’ve watched this play out in a single afternoon. Give the same frontier model the same task three ways — through the raw API, inside a full coding harness, and inside a purpose-built agent with curated tools — and you can get three very different engineers. Same weights, comparable knowledge, sharply different competence, because competence, for an agent, is mostly a property of what surrounds it.
\nThe distinction shows up even inside one product. Codex runs across several surfaces — a terminal CLI, an IDE extension, a cloud task runner, and the ChatGPT app — and OpenAI has described the same core agent loop sitting under all of them. What each surface changes is the envelope around that core: which tools are wired in, which permissions are granted, what runtime it can reach. On a locked-down surface it can read and suggest; give it a sandboxed machine and write access and it can run a test suite, edit files, and open a pull request. The model and the core loop never changed — the harness wrapped around them did, and with it the whole range of what the agent can actually do.
\nThe same model in a different harness is a different engineer.
\nThe frontier labs clearly understand this, because they stopped behaving like model vendors. The API business — here are the weights, build what you want — still exists, but the strategic energy goes into the harnesses: the coding tools, the desktop apps, the migration paths that pull your existing skills and setups from one ecosystem into another. They are no longer competing only on who has the smartest model this quarter. Increasingly, they are competing on who owns the environment where the work happens.
\nOnce you see this, the benchmark conversation gets less interesting and the harness conversation gets much more interesting. The question stops being “which model is smartest” and becomes “which environment lets the intelligence I already have actually reach my problem.”
\nIf the labs are competing on the environment, the development tools show what that competition looks like up close.
\nCursor made the early move, shifting from tab-completion — the model as a faster keyboard — toward the agent window as the primary surface. Claude Code skipped the editor entirely and moved into the terminal. OpenAI folded Codex into ChatGPT on the Mac and made the conversation itself the development environment. VS Code grew an agent mode, Zed is rebuilding around one, and Antigravity arrived agent-first from day one.
\nDifferent products, different bets, one convergence: the text editor — the thing an IDE fundamentally was — is becoming the least important pane in the window. What these tools compete on now is orchestration: how well they let you direct agents, run work in parallel, review what comes back, and keep the whole thing steerable.
\nLook at where the feature velocity goes: plan modes and ask modes, permission levels that run from confirm-every-step to full autonomy for sandboxed work, background tasks, sub-agents, side chats, browser control with annotation and feedback, PR integration, automation hooks. None of these make typing faster. All of them make directing agents better. That is what the tools believe their job is now, and I think they’re right.
\nAn IDE used to integrate tools for a human who writes. These environments integrate tools for agents that build, and a human who decides. Every serious development tool is becoming a harness, whatever its marketing says.
\nIf you want a single reason this generation of tools feels categorically different, it is not the context windows and it is not the benchmark scores. It is that somebody gave the model a terminal.
\nThe Bash tool looks humble next to purpose-built integrations, but it is the strongest tool an agent has ever been handed. Everything a developer can do from a shell, an agent can now attempt: grep and find at the small end; test runners, linters, and build systems in the middle; and at the far end, your project’s own scripts, your company’s internal CLIs, your deployment tooling. The whole accumulated tool culture of computing, inherited in one move.
\nThis is the Unix philosophy paying its oldest dividend: agents didn’t need a bespoke integration for every tool humans have built over fifty years — they needed the one integration that reaches all of them.
\nWhich inverts an assumption we’ve carried for years. We used to ask what the model could do, and the answer was bounded by whatever tools someone had hand-wired into it. Now an agent’s reach is bounded by what its environment exposes: what’s installed, what’s permitted, what’s documented, what’s discoverable. Drop a frontier model into an empty container and it is clever but helpless. Drop the same model into your real project — real scripts, real access, real conventions — and it becomes startlingly capable.
\nThe ceiling moved from the model to the environment.
\nHere is the distinction I keep coming back to, the one that turns this from an observation into a practice. Every project now has two harnesses to design, and they answer different questions.
\nThe first is the outer harness: the environment through which the software gets built. It is your coding tool — Claude Code, Codex, whichever you’ve chosen — plus everything your project layers on top of it: the skills, the rules, the hooks, the memories, the context documents, the scripts it knows how to run, the commands that only make sense in this codebase. The base tool is generic. The outer harness is yours.
\nIts job is everything we used to call development, in the widest sense of the word. Writing features, yes. But also researching options before anything gets written, planning, reviewing, testing, and debating designs — literally, setting agents against a question from different positions and reading the argument. Answering the questions your teammates would otherwise ask you in Slack. Producing the throwaway prototypes that inform the real build and then get discarded without guilt.
\nMy favorite example of the outer harness at work is one I’ve written about before: opening pull requests you never intend to merge, because a PR is the outer harness’s native artifact — code, reasoning, preview, and conversation in one place. The outer harness doesn’t just produce merged code. It produces attempts.
\nA strong outer harness has a specific feel: you stop performing the mechanical parts of engineering and start directing them. The scarce resources — judgment, taste, accountability — stay with you; I’ve drawn that line before and won’t redraw it here. What changes is that everything else, the running and testing and researching and drafting, flows through an environment that has been deliberately taught how your project works.
\nAnd the teaching compounds. Every rule you write, every skill you add, every memory that persists makes next week’s work cheaper than this week’s. That is what it means for the harness to be part of the software: it accrues value the way good architecture does, invisibly, in the speed of everything that follows.
\nThe second harness lives inside the product.
\nMore and more systems now embed agents as features: a support flow that resolves issues instead of routing them, a back-office process that reconciles data overnight, an event handler that investigates an anomaly instead of merely alerting on it, a report that researches and writes itself on schedule. When your product can usefully run an agent — on a user’s request, as a background operation, in reaction to an event — that agent and everything around it is your inner harness.
\nIt has the same anatomy as the outer one: a model, tools, permissions, memories, objectives. But the design constraints are harsher, because nobody is watching. The outer harness has you in the loop; the inner harness has your error budget. What tools does the embedded agent get? What is it empowered to do without a human? What does it remember between runs? How is its output checked before it touches anything real? Those are product decisions now, as consequential as any schema.
\nAnd the boundary between the two harnesses moves. Work migrates from outer to inner. A workflow you run by hand in your coding tool today — verify the deployment, triage the flaky test, regenerate the derived data — becomes, once it has succeeded enough times to be boring, something the system runs on its own. The outer harness is where processes get discovered and hardened. The inner harness is where they retire to.
\nThe clearest example I can offer is running in the repository that publishes this essay. For months, keeping this blog healthy was outer-harness work I did in sessions: check that CI is green, hunt broken links, verify the RSS feed and the sitemap, look at what search engines and answer engines actually see, fix what’s trivial, file what isn’t. The procedure repeated until it stopped being interesting — which is exactly the signal to move it.
\nToday that procedure is written down as two persistent agents — one that sweeps for regressions, one that proposes discoverability improvements — with a scheduled workflow meant to run them weekly. I’ll be honest about the state of it: this example hasn’t yet earned the nobody-is-watching property I described above. The unattended schedule isn’t dependable yet. The recent scheduled runs have been failing, and for now I still kick the agents off by hand more often than not. What already works is the part that matters for this argument — the agents exist, their boundaries are defined, and the work has moved out of my head and into the harness. Turning that into reliable, unattended automation is exactly the kind of hardening that comes last, and I haven’t finished it.
\nThe part worth studying isn’t the automation; it’s the decisions at the boundary. The QA agent may fix trivial regressions directly, but everything it ships still arrives as a pull request I review. The improvement agent may prototype, but only as draft PRs. And both operate under one hard rule: no agent touches the essays themselves unless I have explicitly opened a writing session — content is the part of this system where my hands stay on the wheel. Tools, permissions, memories, objectives, and a human gate exactly where the error budget is thinnest. Strictly speaking these agents still do development work — they open pull requests, not support tickets — and they’re designed to run outside my sessions. They are the blog’s back office, and the boundary keeps creeping: every time one of their filed issues teaches me a procedure, that procedure becomes a candidate for the next migration.
\nThat migration is what I mean when I say these systems can begin to operate themselves. Not autonomy as a slogan — a pipeline. You develop a process with an agent, you watch it hold up, you move it inside, and your attention moves to whatever isn’t automated yet. The back office of software that keeps getting predicted isn’t a new department. It is this migration, repeated until it stops being remarkable.
\nNot every product needs an inner harness today. Some never will, and an outer harness alone already changes how a team moves. But I would bet that most serious systems end up with both — because once operating the system is a written-down process, and processes are things agents run, keeping a human on the crank becomes a choice you have to justify rather than a default you inherit.
\nPut the pieces together and you get a stack. It is worth drawing, because the interesting part is which layers get the attention.
\n\nflowchart TD\n M[Foundation model<br/>capabilities, no process]\n B[Base harness<br/>Claude Code, Codex, Cursor]\n O[Project harness<br/>skills, rules, hooks, memories]\n I[Inner harness<br/>agents inside the running product]\n A[Application<br/>what users touch]\n\n M --> B --> O --> I --> A\n\n classDef strong fill:#0A0A0A,stroke:#00FFFF,color:#E0E0E0\n classDef weak fill:#0A0A0A,stroke:#666,color:#999\n class B,O,I strong\n class M,A weak\n\n
In plain text, the diagram is a five-layer stack, each layer specializing the one beneath it. At the base sits the foundation model. The base harness — Claude Code, Codex, Cursor — wraps the model. The project harness, your skills, rules, hooks, and memories, wraps the base harness. The inner harness sits above that, running inside the product itself. The application users touch sits on top. The three middle layers — base harness, project harness, inner harness — are the harness itself.
\nThe two gray layers are the ones everyone talks about. The model, at the bottom, is the layer you control least — you pick one, and a frontier lab does the rest. The application, at the top, is the output: it is what users touch, but it sits downstream of everything below it.
\nThe three layers in the middle are where your leverage actually lives. The base harness you choose. The project harness you accumulate on top of it — every skill, rule, and memory that specializes a generic tool into your team’s tool. Those two together are what I’ve been calling the outer harness. The inner harness you embed in the product itself. Each layer specializes the one below it, and each is a body of decisions that belongs to you, not to a lab.
\nTeams argue endlessly about the gray layers and improvise the middle three. I think that ratio is exactly backwards.
\nEvery previous era of software engineering had a unit of reuse. Functions. Objects. Libraries. Packages. Services. The entire open-source economy is built on the insight that solved problems should stay solved, and code was how we shipped solutions to each other.
\nHarnesses introduce a new reusable unit, and it isn’t code. It’s process.
\nA skill that runs a design review to your team’s actual standards. A security critique that knows what your threat model cares about. A migration workflow that plans, executes in slices, and verifies each slice before the next. A research loop that fans out, reads, and synthesizes with citations. A debugging procedure that instruments the code instead of guessing at it. None of these are libraries. You don’t call them; agents perform them.
\nAnd they travel in a way code never quite did. Code reuse always came with friction — a library assumes a language, a framework, a runtime, a particular shape of problem. A well-written process assumes almost nothing. One of the skills in this repository audits documentation for drift against the code it describes; nothing in it knows about Astro, or blogs, or the web. Point it at a Rust CLI with a stale README and the procedure runs unchanged — only the nouns are different.
\nThe honest caveat is that process reuse has none of the verification infrastructure code reuse earned over decades. A schema can validate a skill’s shape — that its fields and frontmatter are well-formed — but it cannot prove the procedure is still sound: that the steps it encodes remain the right ones, that the standard it reviews against hasn’t quietly moved. No test fails when a review procedure goes stale — it simply starts reviewing for the wrong things. Which is one more reason the operational layer needs the discipline I argued for earlier: version control, review, deliberate design. The process artifacts are load-bearing precisely because nothing else checks them.
\nSkills are already shared and versioned like packages. Plugins bundle whole domains of process. Engineering know-how — the part that used to live in senior engineers’ heads and in tribal review culture — is becoming an artifact you can write down, refine, and hand to the next project.
\nWe used to share libraries. Now we share behaviors.
\nThere is an easy mistake to make when comparing these tools: reading the capability list and thinking you’ve read the harness. Image generation, browser control, code execution — those are capabilities. A harness is what turns a capability into a dependable outcome. The three examples that follow I’ve only watched from the outside, as a user, so treat the mechanics as observed behavior rather than inside knowledge.
\nClaude Design is the cleanest example I know. Its raw capabilities are nothing exotic — the same models everyone can call. What makes its output striking is process: it builds a design system before it designs, prototypes inside that system, critiques its own work, checks the result across viewports, and iterates until it’s satisfied. You could try to replicate each step locally and still struggle to match it, because the hard part is the accumulated judgment about sequencing, evaluation, and when to stop.
\nA custom pet-hatching skill I watched run on Codex makes the same point from a playful direction — and to be clear, this is someone’s hand-built workflow, not a shipped Codex feature. On the surface it’s a toy: hand it a reference, receive an animated companion. Underneath is one of the more rigorous pipelines I’ve seen — grounding the character’s identity from reference material the way an artist builds a mood board, iterating sprite sheets through sub-agents, checking its output against consistency rules, looping until the result clears the skill’s own bar. It runs long, and it earns the runtime. The impressive part was never the image model.
\nAntigravity rounds out the pattern from the opposite side. It leans on Google’s image and video models rather than generating pixels itself, so visual work flows through it as process. The capability lives elsewhere; the harness contributes the knowing-how — which model to call, with what grounding, checked by what loop.
\nA capability is a fact about what is possible, a process is a commitment about what will reliably happen. Users only ever experience the second one. Source capabilities wherever they’re strongest, but understand that the process is the product — and the process is exactly the part you can design.
\nAt some point in this journey, every engineer gets the itch: I understand the loop now — model, tools, memory, repeat. I could build this.
\nYou should scratch that itch once, as education. Building a small harness teaches you more about how these systems actually behave than a year of merely using them.
\nThen you should stop, because a production-grade base harness is one of those artifacts that looks simple and is actually thousands of accumulated decisions: permission models that are safe without being suffocating, context management under real limits, failure recovery, tool sandboxing, evaluation, parallelism, the interface through which a human stays meaningfully in control. The frontier tools have burned years of iteration on those problems, and their feature velocity is brutal.
\nThe leverage sits one layer up. Take the base harness as given and pour your effort into the project harness — the layer of skills, rules, memories, and workflows that no vendor can ship, because it encodes your system, your standards, your taste. That layer is small enough to own and valuable enough to matter.
\nTwo trends make this an even easier call. Base harnesses are turning into infrastructure — frameworks are beginning to ship agent harnesses as part of the platform, usable as an outer harness for building or embedded as an inner one, rather than as a separate product you visit. And they are getting cheaper: capable low-cost stacks are forming around strong open-weight models, including Qwen’s coder models, so the entry cost of running serious agent processes keeps falling. Exact prices move month to month; the direction — downward — is the durable part.
\nThe liabilities are real too. Committing to a harness is a platform dependency like any other: every skill written against one tool’s conventions is a small piece of lock-in. Harnesses drift — rules go stale, skills rot, memories accumulate contradictions — and the operational layer needs maintenance exactly like the code layer does. And there is a failure mode I have already watched from close range: teams so absorbed in tuning the harness that the product starves. The harness carries half the weight of the software. It is not the point of the software.
\nArchitecture has always been the discipline of decisions that are expensive to reverse. Which services exist. Where the data lives. What owns what. We treat those with respect: documents, reviews, structured debate.
\nThe harness has joined that list. Consider the decisions a serious project now embeds, whether or not anyone writes them down.
\nWhich harness owns which class of task. Which model backs which agent, at which reasoning effort — because effort is a dial now, and every position of that dial is a cost-quality tradeoff you are making whether you notice or not. What each agent may do autonomously, and where a human gate stays. What persists in memory versus what gets re-derived each session. Which evaluation loop checks which output.
\nThat last one deserves more attention than it gets, because evaluation is where harness design succeeds or fails. A test suite is the right gate when correctness is checkable — it is cheap, objective, and merciless. A critic agent is the right gate when the failure is qualitative: a review that reads the diff the way a colleague would, catching what compiles but shouldn’t ship. A judge model is the right gate when you are choosing between attempts rather than validating one. And you are the right gate when the cost of being wrong exceeds the cost of your attention. Most harness failures I’ve seen reduce to a mismatch here — qualitative output gated by nothing, or trivial output gated by a human who becomes the bottleneck.
\nNothing says you settle on one harness, either. The same project can run different harnesses for different classes of work — one SDK powering the inner agents, another driving a specialized pipeline — with the outer harness orchestrating them the way it already orchestrates compilers and test runners. “Which harness owns this task” is a real architectural question now, and pretending there is one answer for a whole system is as naive as pretending there is one database.
\nGet these decisions right and the whole development motion compounds: work parallelizes, quality gates hold, trust in the agents grows as the harness accumulates knowledge. Get them wrong and the failures are distinctly modern. The over-permissioned agent is the canonical one: give an agent broad write access and a vaguely worded objective, and it will pursue that objective with the confidence of a system that has never been embarrassed. Nothing about the model malfunctioned — the harness decision that let it act without a gate is the malfunction. The same anatomy repeats in the quieter failures: the agent hallucinating around a tool nobody provisioned, the unevaluated loop generating slop at scale. Again and again, the postmortem points at a harness decision, not a model.
\nThese are not implementation details, and they are not tool configuration. They are the same kind of decision as a service boundary: they determine what the system can safely become. They deserve the same treatment — written down, reviewed, revisited.
\nWhich brings me to the discipline hiding under the name. Harness-driven development is, at bottom, one commitment: nothing about how the software is built or operated is left outside a harness, and the harness itself is engineered, not improvised. Your outer harness should be able to run the project, test it, extend it, research for it, critique it, and debate it. If some part of your engineering practice can’t flow through it yet, that is your backlog.
\nObject-oriented programming organized code around objects. Domain-driven design organized it around the business. Test-driven development organized the act of building around feedback. Each one earned its name by moving something to the center that had been treated as incidental.
\nHarness-driven development moves the environment to the center. Not the model — the environment that surrounds the model: the tools, the memories, the skills, the rules, the processes, the permissions, the evaluation loops. The claim is simple to state and slow to sink in: that environment is now a first-class part of your software, as deliberate and as maintained as the source code, because it determines how well every future change gets made — by you, and increasingly by the system itself.
\nI don’t know if the name sticks. Names rarely survive contact with an industry, and I hold this one loosely. The practice is what matters, and the practice is already here — sitting in your repository, in files you may still be tempted to call clutter.
\nI suspect that before long, “works well with agents” will stop being a differentiating skill, the same way “uses version control” quietly stopped being one. The harness will dissolve into the frameworks, the way good ideas do. But between now and then there is a real window, and in that window the teams that engineer their harnesses — deliberately, on both sides of the product boundary — should ship faster, gate with tighter evaluation, and trust their systems with more of the work than the teams that don’t.
\nEvery line of code should arrive through a harness — the outer one while we build it, the inner one while it runs.
\nA few primary sources that shaped the framing here, chosen because they should stay useful as products churn:
\nWritten and developed with Claude. The arguments are mine; the drafting was collaborative.
", "date_published": "2026-09-15T00:00:00.000Z", "tags": [ "Developer Philosophy", "AI Tools", "Agents", "Software Engineering", "Claude Code", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-09-10-buzzcut-cutting-through-the-ai-tool-hype/", "url": "https://kobi.kadosh.me/blog/2026-09-10-buzzcut-cutting-through-the-ai-tool-hype/", "title": "Buzzcut: Cutting Through the AI Tool Hype", "summary": "Every week there is a new must-have AI tool, and somewhere inside the buzz there is usually a grain of truth. Buzzcut is a small agent whose only job is to find that grain: map the shiny new thing against what you already run and return keep, skip, or watch, with one flip condition. Not anti-hype. Anti-hype-driven architecture.", "content_html": "Every week there is a new must-have AI tool.
\nA new model. A new agent harness. A new MCP server. A new skill. A new coding workflow. A demo that looks like it just made everything you were using yesterday obsolete.
\nAnd sometimes, underneath all that buzz, there is something genuinely useful.
\nThe problem is figuring out which part.
\nThat is why I built Buzzcut.
\nBuzzcut is a small experiment in something I increasingly think belongs in the arsenal of anyone seriously working with AI: an agent whose job is not to get excited about new tools, but to evaluate whether you actually need them.
\nIts job is to cut the buzz.
\nThe one-line description on the bot says it more precisely than I could in a paragraph:
\n\n\nCuts the buzz on AI tools, skills, and harness trends. Maps each shiny demo onto what you already run, then returns keep / skip / watch with one flip condition — so adoption fatigue does not drive the shop.
\n
The rest of this post is about why that sentence exists, and what it is meant to protect.
\nI don’t actually think dismissing AI hype is particularly useful.
\nThere is usually a grain of truth somewhere inside it.
\nA new framework might genuinely have a better abstraction. A new model may be substantially better at a particular class of tasks. A new skill may solve something that previously required a lot of plumbing. A demo that is being passed around X may represent a real shift.
\nBut:
\n“This is impressive” and “I should adopt this” are two completely different conclusions.
\nThat distinction is becoming increasingly important.
\nAs engineers, we’re accumulating an enormous arsenal: Claude Code, Codex, Grok, agents, subagents, MCPs, skills, CLIs, custom harnesses, memory systems, orchestration layers, and whatever gets released next Tuesday.
\nThe cost of adding something isn’t zero.
\nEvery addition introduces another abstraction to understand, another dependency to maintain, another behavior to debug, another set of permissions to reason about, and another decision your team eventually has to revisit.
\nEventually, your AI stack can suffer from exactly the same disease as any other software stack: complexity accumulated in the name of productivity.
\nI wrote about this from a different angle in Your Docs Are Not the Prompt and in AI Slop, Human Bandwidth. The common thread is that the scarce resource is no longer capability. It is the attention required to integrate capability well.
\nThere is a tendency in technology to discover a good tool and immediately try to make it the answer to everything.
\nAI has amplified this.
\nPeople discover Claude Code and try to build their entire workflow around Claude Code. Someone gets great results from Codex and suddenly every problem becomes a Codex problem. The same thing happens with Grok, Cursor, MCP, skills, agent frameworks, and whatever comes next.
\nBut this wasn’t true before AI either.
\nA hammer is an extraordinarily effective tool. It has been one since roughly the invention of the hammer. Nobody has ever concluded from that fact that it should also be the screwdriver, the saw, and the level.
\nMastery isn’t figuring out how to use the hammer for every possible job. Mastery is knowing when to pick up the hammer, and when to leave it in the toolbox.
\nI think AI tooling should be approached the same way.
\nI use different agents and models for different things because they have different strengths, environments, interfaces, and failure modes. Claude Code is where I do most of my serious repository work. Codex is what I reach for when I want a second opinion with a different set of habits. Grok Bot is where I run small, sharply scoped bots that need to live close to a conversation rather than close to a codebase. None of them is wrong for the others’ jobs. They are just not optimal for them, and forcing the issue costs more than it saves.
\nThe objective isn’t tool loyalty.
\nThe objective is leverage.
\nBuzzcut sits one level above the tools themselves.
\nYou show it something you’re considering adopting:
\n\n\nHere’s this new agent framework everyone is talking about. Should I use it?
\n
Or:
\n\n\nSomeone published this skill. Does it improve my current workflow?
\n
Or:
\n\n\nThis new harness looks interesting. Should we migrate anything to it?
\n
Buzzcut shouldn’t begin from the assumption that the new thing is useless.
\nIt also shouldn’t begin from the assumption that because everyone is talking about it, you need it.
\nInstead, it asks a more useful question:
\nRelative to what I already have, what does this actually change?
\nThat means understanding the claim, stripping away the marketing language, identifying the underlying capability, and mapping that capability against your existing stack.
\nThen it needs to make a decision.
\nThis creates enough additional leverage to justify adopting it.
\nInteresting, perhaps even technically good, but it doesn’t meaningfully improve what you already have.
\nThere is something real here, but adoption doesn’t make sense yet.
\nAnd every verdict needs one additional thing:
\nthe flip condition.
\nWhat would have to become true for this decision to change?
\nMaybe:
\n\n\nWATCH. If the project gets native GitHub Actions support, reconsider.
\n
Or:
\n\n\nSKIP. Unless your workload grows beyond the concurrency your existing harness handles comfortably.
\n
Or:
\n\n\nWATCH. If the API becomes available independently of the hosted product, reevaluate it.
\n
That last part matters because AI changes too quickly for permanent verdicts.
\nA good evaluation should tell you not only no, but no until X.
\nThe flip condition is also what turns an opinion into a record. Six months from now, when the same tool shows up again in a different launch thread, you don’t have to re-argue the whole thing. You check whether X happened. If it did, the verdict is open again. If it didn’t, you move on without spending a second afternoon on it.
\nThis is important.
\nI don’t want Buzzcut to become a cynical bot whose personality is saying everything is hype.
\nThat would be just as useless as believing every launch thread.
\nThe goal is calibration.
\nSometimes the correct answer should be:
\n\n\nKEEP. This is legitimately better for your use case. Adopt it.
\n
There are tools surrounded by enormous amounts of hype that are nevertheless genuinely useful.
\nGrok Bot is a good example for me.
\nThere is plenty of buzz around agents and bots right now. Underneath that, I find the concept useful when I give a bot a constrained responsibility and become extremely explicit about what it should and shouldn’t do. Be direct about what you want from it. Be sincere about what it is not for. Most of the disappointment people report with these tools comes from skipping that step and expecting a general-purpose assistant to infer a very specific job.
\nThe interesting part isn’t that a bot can theoretically do everything.
\nThe interesting part is defining one thing it should do well.
\nBuzzcut itself follows that philosophy.
\nIts job isn’t to build my software.
\nIt isn’t my research agent, coding agent, or product manager.
\nIts job is to stop those systems from accumulating things simply because I saw something shiny on the internet.
\nI increasingly think this becomes an important role in an agentic system.
\nWe spend a lot of time thinking about agents that add capabilities.
\nMaybe we also need agents that challenge additions.
\nIf you maintain a serious AI harness, Buzzcut can effectively become its technology radar.
\nIt should understand:
\nNow a new tool doesn’t get evaluated in a vacuum.
\nIt gets evaluated against your reality.
\nThat is a very different question from:
\n\n\nIs this tool good?
\n
The useful question is:
\n\n\nDoes this tool make my system better enough to justify adding it?
\n
This is the same instinct behind the Unix philosophy for agents and skills: small pieces with sharp responsibilities compose better than one large piece that does everything adequately. A harness is a system, and systems have a carrying capacity. Someone, or something, has to guard the door.
\nYou don’t need some sophisticated workflow to start using Buzzcut.
\nGive it the thing you’re tempted by.
\nGive it your scenario.
\nAnd ask:
\n\n\nShould I use this?
\n
Then argue with it.
\nTell it what you’re currently doing. Show it your harness. Give it the documentation. Give it the GitHub repository. Give it the launch thread that got your attention.
\nLet it separate capability from positioning.
\nIf the tool solves a real problem, Buzzcut should identify it.
\nIf you can already accomplish 95% of the same thing with something in your stack, it should tell you that too.
\nIf it is promising but premature, WATCH it and define exactly what would change the verdict.
\nThat is the entire philosophy.
\nA concrete example of the shape of a good session:
\n\n\nMe: Everyone is posting about this new orchestration layer that runs a planner, a coder, and a reviewer agent in a loop. I already run Claude Code with subagents and a review step in CI. Should I switch?
\nBuzzcut: SKIP. The capability being demoed is a three-role loop with shared memory. You already have the three roles and the loop; what you don’t have is the shared memory, and your CI review step reads the PR diff instead, which covers most of the same ground for your repo sizes. Flip condition: if you start running loops across multiple repositories in one session and the missing shared memory shows up as repeated context rebuilding, reevaluate.
\n
That answer is worth more to me than a thumbs up or a thumbs down. It tells me what the tool actually is, what I already have, where the real gap is, and when to look again.
\nWe’re moving into a world where the number of available AI capabilities will vastly exceed anyone’s ability to seriously evaluate, learn, and integrate them all.
\nThe constraint isn’t access anymore.
\nIt’s attention.
\nThat changes the job.
\nBeing good at AI tooling isn’t going to mean knowing every tool.
\nIt will mean building a sufficiently good mental model of the landscape that you know which tools deserve a place in your arsenal.
\nAdopt deliberately. Specialize aggressively. Replace when the evidence warrants it.
\nAnd don’t confuse novelty with leverage.
\nThat’s what Buzzcut stands for.
\nIt isn’t anti-hype.
\nIt’s anti-hype-driven architecture.
\nCut the buzz. Keep the signal.
\nBring the thing you are tempted by, bring your current setup, and argue with it. If it talks you out of something you didn’t need, it has already paid for itself. If it talks you into something, it should be able to tell you exactly why.
\n![\"Meet](\"https://kobi.kadosh.me/media/link-cards/buzzcut-grok-bot.png\")
Cuts the buzz on AI tools, skills, and harness trends. Maps each shiny demo onto what you already run, then returns keep / skip / watch with one flip condition.
For most of computing history, software was treated as something expensive to create — and therefore something worth preserving.
\nThat single assumption shaped almost everything around it: engineering organizations, product management, roadmaps, QA, release cycles, support models, procurement, SaaS pricing, and the corporate machinery that decides what gets built in the first place. Software was scarce, so we built processes around the scarcity.
\nBut that scarcity is weakening.
\nWith AI agents, coding tools, research tools, and design-to-code workflows, software is becoming easier to generate, easier to explore, and easier to throw away. Not all software needs to become a product. Not all software needs a roadmap. Not all software needs to survive.
\nSome software only needs to exist long enough to solve a specific problem.
\nThat is disposable software.
\nSoftware exists because humans need help doing things.
\nBefore computers, we extended ourselves with mechanical systems, animals, paper processes, and physical tools. Computers changed the medium, not the purpose. A computer is a machine that follows instructions. Software is the instruction layer that turns general-purpose hardware into a useful tool.
\nFor decades, writing those instructions was hard. Storage was limited. Compute was limited. Hardware was expensive. Programming required deep specialization. From punch cards and tapes, through assembly, compilers, operating systems, graphical interfaces, cloud platforms, and SaaS, every generation made software more powerful — but also more central to modern work.
\nAs software became more important, it also became more institutional.
\nBecause building software was expensive, companies built layers around it: product managers, project managers, designers, analysts, executives, roadmaps, tickets, requirements, ceremonies, reviews, QA cycles, and release processes. These layers were not accidental. They existed because engineering time was scarce, coordination was costly, and mistakes were expensive.
\nWhen software is expensive, you need strong filters before deciding what deserves to be built.
\nBut what happens when the cost of building small software drops dramatically?
\nAI does not eliminate software engineering. It does not remove quality concerns. It does not magically produce reliable systems.
\nBut it changes the cost curve.
\nResearch that previously took weeks can now take hours. Prototypes that previously required days can now be generated in an afternoon. A person with a specific pain point can describe the problem, explore existing options, generate a tool, iterate on it, and use it — without waiting for a company to decide whether that problem is worth solving at scale.
\nThis matters, because many genuinely useful software ideas never became products.
\nNot because they were bad ideas, but because the market was too small. The business case was not strong enough. The audience was too niche. The workflow was too specific. The value was real, but not large enough to justify a software company, a SaaS subscription, a procurement process, or a dedicated engineering team.
\nAI agents change that math.
\nA person may not need to buy software. They may not need to wait for someone to build it. They may not even need to care which framework or language is used. They can spend some tokens, describe their need, and generate something good enough for the task.
\nThat is a fundamentally different relationship with software.
\nDisposable software is software built for a narrow purpose, used for a specific need, and then discarded, rebuilt, repurposed, or kept as context for something more permanent.
\nIt does not need to be elegant. It does not need to scale. It does not need to become a platform. It only needs to serve the job it was created for.
\nA disposable tool might reconcile a spreadsheet, generate a report, visualize an idea, test a workflow, explore an API, compare options, or demonstrate a concept to a team. It may be used once. It may be used for a week. It may be rebuilt the next time the same problem appears, because rebuilding it is cheaper than maintaining it.
\nThis is uncomfortable for traditional software thinking, because we tend to equate software value with durability. We ask whether something is maintainable, extensible, production-ready, tested, documented, and scalable.
\nThose questions still matter — but not for everything.
\nFor disposable software, the better question is simpler:
\nDid it help someone move forward?
\nThe most obvious case is the end user.
\nA person with a specific need can now build software around their own workflow, instead of bending their workflow to fit whatever software happens to exist. They can explain the pain point directly to an agent. They can research existing tools. They can generate a small app, script, dashboard, calculator, workflow, or interactive artifact.
\nFor many people, that is enough.
\nThe result may not be beautiful. It may not be engineered the way a professional team would engineer it. It may have rough edges. But if it solves the problem, the software has done its job.
\nThis is where “vibe coding” gets both interesting and dangerous.
\nYes, it introduces low-effort software. Yes, it creates quality risks. Yes, it can produce fragile systems that people do not fully understand. I have written before about the mess this style of work leaves behind, and I stand by it.
\nBut that criticism misses part of the point.
\nNot every generated tool is trying to become infrastructure. Some of it is closer to a spreadsheet, a temporary notebook, a one-off automation, or a whiteboard sketch that happens to execute. The mistake is not creating disposable software.
\nThe mistake is confusing disposable software with production software.
\nDisposable software is not only useful for non-engineers. It may be even more powerful in the hands of experienced ones.
\nProofs of concept, spikes, technical explorations, and design branches used to take real time. Today, several of them can be explored in parallel. An engineer can generate prototypes to test assumptions, compare approaches, visualize tradeoffs, or create working context for a larger system.
\nThis changes collaboration.
\nIn the past, turning an idea into shared understanding often required meetings, diagrams, written proposals, whiteboarding sessions, and repeated explanation. Now an engineer can use agents to research, prototype, and produce something interactive enough for others to respond to.
\nThe prototype does not need to be the final implementation. It can be a conversation object.
\nIt can help a team see what is being proposed. It can expose missing requirements. It can reveal UX issues. It can pull feedback forward in time. It can hand another agent the context it needs to build the real system.
\nIn this sense, disposable software becomes part of the design process. It is not the destination. It is a means to an end.
\nImagine the older path: a series of meetings and processes to flesh an idea into a design — whiteboarding, diagrams, documents — all to earn buy-in from your team. Today you can research alongside your agents and produce something visual and tangible that earns that same buy-in far faster. It does not mean the prototype is something you have to keep. It means you have a thing to point at, and the choice to toss it, reuse it, or feed it into the real build with production constraints.
\nOne of the most important shifts is that disposable software can become context for non-disposable software.
\nA prototype encodes decisions that are hard to explain in prose: layout, flow, tone, interaction model, information hierarchy, edge cases, and user intent. This is especially clear in design-oriented tools that produce interactive artifacts. A generated prototype can act like a living specification.
\nIt is similar to Figma — but with behavior.
\nA design artifact can show not only what a screen looks like, but how it responds. It can carry style tokens, layout structure, content decisions, media references, and interaction patterns. An agent can inspect it and infer far more than it could from a paragraph of requirements. It is already answering questions before they are asked.
\nThis is why tools like Claude Artifacts, Claude Design, “show me” experiences, Codex web previews, and similar agent-generated interfaces matter. They are not only producing software. They are producing shared context.
\nThink of one of these as a full export of a Figma file that happens to be a working website — the HTML and the styling are just the technical details behind an interactive prototype. An agent can go in and read the style tokens, the layout, the content, the media: all the things that are really design choices dressed up as front-end code. That does not make the artifact production-ready. It will have gaps. But it makes the target concrete in a way prose never does.
\nSometimes the artifact is good enough to use as-is. Sometimes it should be thrown away. Sometimes it becomes the clearest possible input for building the real thing.
\nThe important skill is learning where the boundary is.
\nDisposable software is appropriate when the cost of correctness is low, the scope is narrow, the lifetime is short, and the purpose is exploration, communication, or personal utility.
\nDurable software is needed when reliability, security, maintainability, compliance, scale, shared ownership, or long-term evolution matter.
\nThe future is not that everything becomes disposable. The future is that software splits more clearly into categories:
\nThe problem is that our organizations, engineering habits, and product processes were mostly built for the first two categories. We are still learning how to work with the last three.
\nDisposable software still requires judgment.
\nThere is a balance between token cost, time saved, risk, and usefulness. There is a skill in knowing when to generate, when to refine, when to stop, and when to rebuild properly. There is also a skill in knowing when a prototype has served its purpose and should not be promoted into production.
\nThe danger is not that disposable software exists.
\nThe danger is laundering disposable software into durable systems without doing the engineering work.
\nA prototype can inspire the real system. It can inform the real system. It can provide context for the real system. But production software still needs production constraints: architecture, security, tests, observability, deployment discipline, maintainability, ownership, and clear failure modes. Disposable software should accelerate that path, not bypass it.
\nThere is a smaller version of this story happening inside our daily workflow, and it is worth making the connection explicit.
\nThe pull request used to be finished code waiting to be merged. It is quietly becoming something more: a compressed software object that is generated, reviewed, tested, learned from, and — sometimes — discarded on purpose. I argue that case in detail in Reusing the Pull Request: From Code Contribution to Research Artifact.
\nDisposable software is that same pattern applied to the whole artifact rather than a single change. A PR is a microcosm; software as a whole is the macrocosm. In both, the scarce resource stopped being the code. As I have argued before, generation got cheap and judgment did not. What you spend your attention on is no longer typing the thing — it is deciding which generated thing is worth keeping, and which one has already done its job and can go.
\nSoftware is entering a new era.
\nFor decades, software was expensive enough that every serious effort carried an assumption of permanence. AI weakens that assumption. It lets software be generated for smaller needs, shorter lifetimes, narrower audiences, and more experimental purposes.
\nThat does not make engineering less important. It makes judgment more important.
\nThe question is no longer only: what software should we build?
\nIt is also: what software should we generate temporarily, so we can think, decide, communicate, or act faster?
\nDisposable software is not a lower form of software. It is a different category of software.
\nIt is software as a sketch. Software as a conversation. Software as a prototype. Software as a single-use tool. Software as context.
\nAnd in a world where agents can produce software on demand, learning when to throw software away may become just as important as learning how to build it.
\nWritten and developed with Claude. The arguments are mine; the drafting was collaborative.
", "date_published": "2026-06-18T00:00:00.000Z", "tags": [ "Developer Philosophy", "AI Tools", "Vibe Coding", "Software Engineering", "Agents", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-06-16-reusing-the-pull-request-research-artifact/", "url": "https://kobi.kadosh.me/blog/2026-06-16-reusing-the-pull-request-research-artifact/", "title": "Reusing the Pull Request: From Code Contribution to Research Artifact", "summary": "The pull request used to be finished code waiting to be merged. With agents doing most of the building, it has quietly become something more: a rich research and communication artifact — without shedding the code review and compliance checks that made it trustworthy in the first place.", "content_html": "A few weeks ago I opened a pull request I never intended to merge.
\nI knew that before I opened it. The branch was an agent’s first attempt at a feature I was still arguing with myself about. The code compiled. The preview deployed. The diff touched the database, two services, a chunk of the frontend, and an architecture diagram I had been avoiding updating for a month. And then I closed it, on purpose, after I had learned what I needed from it.
\nIf you had described that workflow to me three years ago, I would have called it a waste. You wrote code you knew you would throw away. You opened a PR you knew you would not merge. You asked another human — me — to review something that was never a candidate for production.
\nBut none of those objections survive contact with how I actually work now. The PR was not a waste. It was one of the most efficient research instruments I had that week. And the reason it worked is that the pull request, the most boring and load-bearing object in our entire workflow, has quietly taken on a second job it was never designed for — without giving up its first.
\nWe did not build a new tool for this. We reused an old one.
\nFor most of its life, the pull request had a single, well-understood job. It was a unit of finished work. You took a definition of done, you implemented it, you packaged the implementation into a branch, and you submitted it to be checked and merged. The PR was a request in the most literal sense: please pull my code into yours. Its entire future was binary. It merged, or it didn’t.
\nEverything we built around the PR assumed that frame. Review existed to gate the merge. CI existed to protect the merge. The conversation in the comments existed to unblock the merge. A PR that sat open for weeks without merging was a smell, a sign of indecision or abandonment. A PR that got closed unmerged was, softly, a small failure — somebody’s effort that didn’t make it.
\nI have written before, more than once, that you should think before you implement. Design first. Understand the problem before you reach for the keyboard. I still believe most of that. But it was built on an assumption I want to make explicit, because the assumption is the part that broke: writing the code was the expensive step. Implementation was where your hours went, so implementing the wrong thing was where your hours got wasted. “Think first” was, underneath, a budgeting rule about human time.
\nThat budget no longer looks the way it did.
\nThe most concrete change in how I work is also the most underrated: I barely type the implementation anymore.
\nI am not saying this as a slogan. I mean it as a description of where the hours physically go. My day is mostly reviewing, researching, deciding, and steering. Reading a diff and judging it. Comparing two approaches an agent took to the same problem. Working out what we actually want to build before something gets blessed as the next step. The keyboard time that used to dominate — the part where you sit and translate a known design into syntax — has collapsed into a background process that runs while I think about something else.
\nWhen the cost of producing an attempt drops to roughly the price of some tokens, the math under “think first” changes. The point of thinking first was never that thinking is holy. It was that building was costly, so you wanted to be sure before you paid. If building a serious first attempt now costs me a little compute and almost none of my own time, then building is part of how I think. The attempt is research. I can ask an agent to go implement a direction I’m unsure about, not because I expect to ship it, but because seeing it built tells me things no amount of upfront design would have.
\nThis is the same shift I keep circling back to in AI Slop, Human Bandwidth, and Where I Draw the Line: the scarce resource is not code anymore, and it is not tokens. It is responsible human attention. Generation got cheap. Comprehension and judgment did not. Once you internalize that, you stop spending your scarce attention on producing first drafts and start spending it on evaluating them. And the object you evaluate is the pull request.
\nHere is the question I keep getting, usually with a slightly impatient tone: if not every PR is headed for a merge anymore, why use a PR at all? Why not write an issue? Why not put it in the project tracker, the spec doc, the task board — the tools literally built for describing work?
\nBecause none of those tools can hold what a PR holds.
\nA project tracker can hold text and images. It can hold a description, an argument, a mockup, a checklist. That is genuinely useful, and for a lot of work it is enough. But a tracker card does not hold code. It does not have a CI status. It does not carry the perspective you only get from the system actually trying to build the thing. It has no attempt inside it.
\nA pull request has all of that, and the richness compounds:
\nThat last point is the one people underrate. A tracker card describing a feature gives you the idea of its blast radius. A PR shows you the blast radius. You can see, concretely, that this “small” change also rewrites a migration and quietly alters an API contract three layers away. That visibility is not a side effect of merging. It is independently valuable, and you get it whether or not the branch ever lands.
\nThis is the reuse. We took a mechanism built to gate merges and discovered it is also the best container we have for showing what a change means across an entire system. Same object, new job.
\nSo let me say the uncomfortable part directly, because it’s the hinge of the whole argument.
\nA pull request does not have to be mergeable. It does not have to reach production. It does not even have to be used.
\nIn Caro, the project where this way of working got most extreme for me, most PRs behave exactly like this. They are not finished contributions. They are feature requests rendered as attempts — an agent’s best one-shot pass at whatever the original session asked for. Someone described what they wanted, an agent took its single best swing at it, and the result is a branch plus a diff plus a pile of context: the research it did, the decisions it made, the next steps it would take. The PR is, at its core, sometimes just a prompt that grew a body. A prompt, a code artifact, and a description of where this could go.
\nThat sounds like a degradation of the PR. I think it’s the opposite. It’s a PR doing more than it used to, not less. An issue can tell you “here is what we should build.” A PR of this kind tells you “here is what it looks like when we actually try” — with the friction, the surprises, the parts that turned out harder than the card implied, all surfaced by the attempt instead of imagined in advance.
\nAnd critically, the agent’s attempt is almost always incomplete. That is not a defect; it is the normal condition. Any non-trivial feature takes several iterations to land. Complex work gets split across days, across multiple passes, across more than one mind. Expecting an agent’s first PR to be a complete, mergeable feature is the same mistake as expecting a human’s first PR on a hard problem to be one. It rarely is. The difference is that now we can afford to make the incomplete attempt anyway, look at it honestly, and learn from it — because it cost us tokens, not a week.
\nA PR like that doesn’t end at “merge or close.” It can feed the next PR. It can be handed to another agent that consumes the attempt and finishes it. Several of them can be folded together into a real understanding of what we should actually build.
\nA PR that’s generated, learned from, and thrown away on purpose is a small instance of a larger pattern — software itself becoming disposable, built to exist just long enough to do its job. I follow that thread up a scale in Disposable Software.
\nThis is where the vocabulary starts to strain, in a way I find genuinely interesting.
\nIf I’m staring down something hard, I don’t have to bet on one approach. I can send three agents at it from three different angles and let them run in parallel. Then I “merge” the results — except merge no longer means what it used to. I am not concatenating three diffs into one branch. I am reading three attempts, seeing where they agree and where they diverge, working out which direction actually understood the underlying problem, and using all three to decide how the real thing should be built.
\nThe output of that “merge” might be a fourth PR that resembles none of the three. The three inputs were never products. They were probes. Their value was in what they revealed about the problem, not in the lines they contained.
\nI touched the edge of this in the AI Slop piece — running multiple coders against one task and using their outputs as competing inputs to a final synthesis. I want to push it one step further here. The convergence isn’t a code-merge at all. It’s a decision. The PRs are how the options make themselves legible enough to choose between. You couldn’t do this with three issue cards, because three issue cards are three guesses. Three PRs are three demonstrations, each with its own CI status, its own preview, its own honest record of where it got stuck.
\nAnd the resource cost of running them is the thing that makes it reasonable. Three parallel attempts would have been an absurd luxury when each one cost a human a day. As tokens, with a reasonable subscription, it’s close to a rounding error — and the converged result is often better than what any single upfront design would have produced, because it was chosen against real evidence instead of imagined ahead of time.
\nI want to be careful here, because it would be easy to read everything above as “merge discipline is over.” It is not. None of this relaxes the bar for a PR that is meant to merge.
\nWhen a PR is a real contribution, it goes through the full gate, exactly as it always has. Human code review. Required status checks. Lint, type-check, the test suite. Security and license scanning. Branch protection. Whatever the project’s definition of done and compliance rules demand before anything touches a protected branch. That machinery is not a relic of the old model that the new one outgrows. It is the part that earns a change the right to ship, and I would not merge agent-written code without it any more than I would merge my own.
\nIf anything, agent-authored code raises that bar rather than lowering it. When generation is cheap, the scarce and expensive thing is the reviewer’s judgment and accountability — the same point I made in the AI Slop piece. A PR an agent produced in four minutes can still demand a careful hour to review responsibly, and it should. Cheap to write is not the same as cheap to trust.
\nAnd here is the part people miss: those same checks are what make the research mode work at all. CI is the honest signal that an attempt actually compiles and passes, not merely that it reads plausibly. Review comments are how a probe gets steered toward the real problem. The compliance gates — no forbidden license pulled in, no secret committed to the diff, no convention quietly broken — are exactly what let a PR be trusted enough for anyone to act on it. Strip those away and you do not get a richer artifact. You get a confident-looking guess wearing a green checkmark it never earned.
\nSo when I say a PR does not have to be mergeable, I do not mean review and checks are optional. I mean a PR now has two modes, and both run on the same rails. The merge-bound PR earns its merge by passing them. The research PR earns its credibility the same way.
\nThere’s a second kind of reuse hiding in here, and it’s about people rather than process.
\nBecause the PR now carries the whole vertical slice — infra to docs to UI to data — it stops being the exclusive territory of the engineer who would have written the code. A product manager can open one. A product engineer can. A designer can. They’re all working against the same constraints, in the same surfaces, with the same CI and the same preview environment standing behind their change. The PR becomes a shared workspace, and what it can do next depends only on the stage of the work: ship to a sandbox to get a feel for it, or, when it’s ready and owned, ship further.
\nAn issue body can’t be a shared workspace in that way. It can hold everyone’s words, but only one discipline’s artifact — the prose. The PR holds the running thing, which is exactly what lets a designer and a backend engineer and a PM all point at the same object and mean the same object. They’re not describing a feature to each other. They’re standing inside one.
\nWhich brings me to the friction that made me want to write this down in the first place.
\nThere is a persistent, recurring mismatch between how a pull request gets interpreted and how, increasingly, it’s meant. Someone opens a PR as a research artifact — an attempt, a probe, a way of communicating “here’s what this feature could be, here’s the research, here’s a partial working prototype.” And it gets received as what PRs have always been: a finished contribution presented for merge. The reviewer reaches for the ritual — is this correct, is this complete, is this ready to land — when the author was asking a different question entirely: is this the right direction, and what did building it teach us? The reviewer is not wrong to ask those questions. For a merge-bound PR they are exactly the right ones. The mismatch is about mode, not about rigor.
\nThat gap is not a small communication hiccup. I think it’s the central source of confusion in agentic teams right now. The artifact evolved faster than our shared understanding of it. Half the people in the conversation are using the PR as a merge candidate and half are using it as a thinking tool, and they’re staring at the same screen wondering why the other side seems to be missing the point.
\nNaming the gap is most of the fix. A PR can be a contribution to be merged. It can also be a feature request with working code attached, a product definition that happens to compile, a partial prototype, a decision document with a CI status, a first attempt meant to be consumed by the next one. These are different objects wearing the same interface. The interface stopped telling you which one you’re looking at. So we have to say it — in the description, in the conventions, in the team’s shared vocabulary: this PR is here to be merged, or this PR is here to be learned from.
\nI’ll close where I started, with the thing that still feels slightly heretical against my own old advice.
\n“Think before you implement” was good guidance in a world where implementing was the expensive part. But the implementation is now, often, part of the thinking — because asking an agent to build a direction costs almost nothing I care about, and a built attempt answers questions that staring at a design doc never will. The pull request is where that attempt becomes visible, reviewable, and shareable: code, CI, preview, and cross-cutting impact, all in one object that the rest of the system already knows how to display.
\nWe didn’t need a new tool for the agentic era. We had one all along. We just used only half of what it could do. The merge — gated by review and checks, exactly as it should be — was always one essential job, and it still is. The other job, being the richest way we have to show in running detail what a change would mean, is the one we left mostly on the table, right up until building got cheap and deciding got expensive.
\nThe PR is still a contribution waiting to be merged: gated, reviewed, checked. It’s also a research artifact now. Holding both at once, and being honest about which one you’re handing someone, is the whole shift. Once you start treating it that way, a lot of the friction dissolves — and a lot of the leverage shows up.
\nWritten and developed with Claude. The arguments are mine; the drafting was collaborative. The PR I opened and closed on purpose was, naturally, also mine.
", "date_published": "2026-06-16T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Code Review", "Developer Philosophy", "Software Engineering" ] }, { "id": "https://kobi.kadosh.me/blog/2026-04-29-your-docs-are-not-the-prompt/", "url": "https://kobi.kadosh.me/blog/2026-04-29-your-docs-are-not-the-prompt/", "title": "Your Docs Are Not the Prompt: How AI Coding Agents Really Use Project Context", "summary": "Not every piece of context an AI coding agent sees carries the same weight. The user prompt and the code dominate; documentation is a secondary orientation layer. Here's why imperfect docs are usually good enough, and where your effort actually pays off.", "content_html": "AI coding agents have made an old engineering debate feel urgent again: how much documentation does a project really need?
\nFor years, teams have struggled with stale design docs, outdated architecture notes, half-maintained onboarding guides, and README files that drift away from reality. This was already a problem before AI. Now that coding agents can read those same files and use them as part of a coding session, the question feels sharper: should we invest much more time keeping docs perfectly current because AI agents depend on them?
\nMy answer is: not as much as people think.
\nThat does not mean documentation is useless. It means we should understand what kind of signal documentation provides to an AI coding agent, and how that signal compares to other parts of the session.
\nThe strongest user-controlled signal is still the user prompt. After that comes the actual project: the source files, the file structure, the conventions, the tests, the build system, the errors, and whatever the agent can discover through local tool use. Documentation matters, but it is not equal to code. It is usually a secondary orientation layer.
\nThis distinction changes how I think about engineering docs in the age of AI.
\nWhen I give a coding agent a task, the user prompt is the most direct steering mechanism I control.
\nA bad prompt can waste the entire session. A clear prompt can make the same agent look dramatically better. This is not surprising. The prompt defines the problem, the desired outcome, the constraints, the acceptable trade-offs, and the level of autonomy expected from the agent.
\nFor coding work, assuming the request is within the model’s intended behavior and does not run into safety or policy restrictions, the prompt has enormous influence. It tells the model what to optimize for.
\nThat does not mean the model ignores the project. It means the project context is interpreted through the task.
\nA vague prompt plus perfect docs can still produce a confused session. A strong prompt plus imperfect docs often produces a useful result, especially when the agent can inspect files, run commands, ask clarifying questions, and reason from the actual codebase.
\nThis is why I do not believe documentation should be treated as the primary steering layer for coding agents.
\nThe prompt comes first.
\nWhen an agent works inside a repository, the most important information is usually not in a Markdown file. It is in the code.
\nThe project structure tells the agent what kind of system it is looking at. The source files reveal naming conventions, framework choices, architectural boundaries, testing patterns, and implementation style. TypeScript files, package boundaries, test files, routes, schemas, migrations, and configuration files often carry more reliable signal than a design doc written three months ago.
\nDocs are still useful, but they are often proxy information. They describe intent, direction, decisions, and team preferences. They are not usually the ground truth of the system.
\nThis matters because modern coding agents do not only read a documentation file and blindly obey it. They explore. They list files. They read source. They inspect nearby implementations. They infer patterns. They compare the requested task against what already exists.
\nThe docs help orient the model, but the code anchors it.
\nThat is why I would rank the practical signals roughly like this:
\n\nflowchart TD\n P[1. User prompt<br/>defines the task]\n C[2. Code & project structure<br/>ground truth]\n T[3. Local tool results<br/>read, search, test]\n R[4. Rules & memories<br/>steering constraints]\n D[5. Documentation<br/>orientation layer]\n X[6. External: MCPs, links, articles<br/>weakest signal]\n\n P --> C --> T --> R --> D --> X\n\n classDef strong fill:#0A0A0A,stroke:#00FFFF,color:#E0E0E0\n classDef weak fill:#0A0A0A,stroke:#666,color:#999\n class P,C,T strong\n class D,X weak\n\n
The exact order can vary by agent and workflow, but the main point remains: not every piece of context has the same weight.
\nA note on what this ordering means. It is roughly the order of practical influence per session, not absolute authority per token. Rules can have higher per-token authority than docs, because they are short, direct, and explicitly framed as constraints. But the agent reaches them only after the prompt and the surrounding code are already shaping the session. So a great rule cannot rescue a vague prompt, and a good prompt rarely needs much help from docs.
\nAbout MCPs and external context: tools like Model Context Protocol servers, fetched URLs, knowledge-base lookups, and pasted articles can be useful, but they tend to sit furthest from the model’s training distribution for this codebase. The model has not seen your private MCP responses or your internal wiki page during training. It treats them as foreign material and weights them accordingly. They are valuable when the local project genuinely lacks the information, but they are not a substitute for code the agent can read directly.
\nA lot of the documentation debate collapses two very different cases.
\nThere is a big difference between imperfect documentation and actively misleading documentation.
\nImperfect docs are common. They may be slightly stale, repetitive, incomplete, vague in places, or missing the newest implementation detail. Most real projects live here. Even strong teams rarely maintain perfect documentation for long.
\nBad docs are different. Bad docs point the agent in the wrong direction. They describe an architecture that no longer exists. They name systems incorrectly. They contradict the code. They encode abandoned decisions as if they were still active.
\nMy argument is not that bad documentation is safe. Very bad docs can absolutely damage an agent session.
\nMy argument is narrower: mostly correct but imperfect docs are often good enough.
\nThey give the agent shape. They communicate direction. They reduce the amount of repeated explanation required from the user. They help the model locate the project inside a familiar pattern space: this is a frontend app, this is a service-oriented backend, this is a monorepo, this is an API layer, this is a design system, this is a migration path.
\nThat orientation has value, even when the docs are not perfect.
\nOne reason imperfect docs still work is that the model’s training data almost certainly contains a lot of imperfect software projects.
\nThat is important. Real repositories are messy. They contain old READMEs, abandoned plans, inconsistent comments, half-finished migrations, TODOs, deprecated files, and documentation that lags behind implementation. The model has learned from this kind of material. It has seen the contradiction between what docs claim and what code does.
\nThis does not make the model immune to bad context. It does mean that imperfection itself is not unusual input.
\nWhen an agent encounters a stale doc, it does not necessarily collapse. A capable agent can cross-check. It can inspect implementation. It can notice that a documented file no longer exists. It can ask whether a described pattern is still preferred. It can reconcile docs with tests and source code.
\nThat is why I am more worried about unclear prompts than slightly stale docs.
\nA bad prompt gives the model the wrong job.
\nAn imperfect doc usually just creates friction.
\nPeople often treat clarifying questions from agents as a negative outcome. I do not see it that way.
\nIf the agent asks a good question, that is often a sign that the session is working. It means the agent found ambiguity and did not silently choose a path that might be wrong.
\nCould better docs reduce the number of questions? Yes.
\nIs that always worth the documentation effort? Not necessarily.
\nAnswering questions keeps the human engaged in the session. That matters. The worst workflow is often not the one where the agent asks questions. It is the one where the human gives a vague task, disengages, and returns to a large diff built on misunderstood assumptions.
\nClarifying questions create checkpoints. They surface ambiguity. They let the human correct direction before too much code is written.
\nFor fully autonomous workflows, this is a different problem. If the goal is to run agents without human involvement, then ambiguity must be encoded more aggressively into rules, tests, specs, and evaluation systems — the same control surfaces I covered in The Feedback Loop Series Part 3: AI Agents. But for interactive development, questions are not necessarily waste. They can be part of the control loop.
\nOf course, better docs are better.
\nA clear architecture document helps humans. A good onboarding guide helps new engineers. A concise decision record helps the team remember why something exists. A current integration guide reduces repeated explanations. None of this disappears because AI agents exist.
\nBut the question is not whether better docs are good. The question is whether making docs perfect is the best use of engineering time.
\nUsually, it is not.
\nThere is a point where the effort required to keep docs perfectly aligned exceeds the value gained in agent performance. The agent still needs the actual code. The agent still needs the prompt. The agent still needs to inspect the repository. The agent still needs tests or feedback.
\nFor day-to-day coding, I suspect the gain from perfect docs is often smaller than people expect.
\nThe gain from good prompts is larger.
\nThe gain from clear rules is larger.
\nThe gain from executable tests is larger.
\nThe gain from consistent project structure is larger.
\nThis does not mean docs should be neglected. It means docs should be kept useful, not worshipped.
\nThe best project docs for AI agents are not necessarily long. In fact, verbose AI-generated documentation can become its own problem. If every file has a long explanation and every decision is repeated in five places, the agent gets more text but not necessarily more signal.
\nThe goal is not to maximize documentation volume. The goal is to provide stable orientation.
\nGood project docs should answer questions like:
\nThat is enough to steer many sessions.
\nDocs do not need to explain every implementation detail. The code can do that. Docs should explain the shape of the system, the team’s preferences, and the traps that are not obvious from the code alone.
\nWhen an agent repeatedly makes the same mistake, I would not bury the correction inside a long documentation file.
\nI would turn it into a rule.
\nRules are better for behavioral constraints. They should be short, direct, and specific. For example:
\nThese are different from docs. They are not explanations of the project. They are steering instructions for the agent.
\nThis connects to a broader argument I made in Skills, Pipes, and the Unix Philosophy: the agent’s value comes from composing small, well-scoped pieces — skills, rules, tools — rather than from one monolithic instruction file trying to do everything. Rules are the small Unix-style pipes of project context. Docs are the prose around them.
\nThis distinction matters. Documentation provides orientation. Rules provide constraints. Tests provide verification. Prompts provide task direction.
\nTrying to make one layer do all of these jobs leads to bloated docs and inconsistent agent behavior.
\nOne practical workflow I like is to let agent sessions reveal documentation gaps.
\nIf the agent asks a clarifying question, answer it. If the answer represents a durable team preference, ask the agent to update the relevant doc or rule file in the same session.
\nThis keeps documentation work connected to real ambiguity.
\nInstead of scheduling a large documentation cleanup that may or may not improve future agent behavior, update the docs when the missing information actually affects a task.
\nThis is a better feedback loop:
\nThis turns documentation into a byproduct of development rather than a parallel maintenance burden.
\nA fair question follows: if docs are lower-signal than code, why not remove them?
\nBecause lower-signal does not mean no-signal.
\nDocs still provide structure. They help the agent orient itself faster. They reduce repeated explanation. They help humans understand the project. They create named places for durable knowledge. They make the repository feel intentional.
\nEven a lightweight docs folder can be useful because it tells both humans and agents that certain concepts exist: architecture, conventions, workflows, deployment, testing, data model, product decisions.
\nEmpty docs are not enough, but the structure itself is not worthless. A well-named file can serve as an invitation to fill in durable knowledge when it appears.
\nThe mistake is assuming that every doc must be polished before it has value.
\nMy position is pragmatic:
\nKeep docs good enough to orient humans and agents.
\nDo not spend disproportionate time making them perfect.
\nInvest more in prompts, rules, tests, and consistent project structure.
\nUse agent confusion as a signal for what needs to be documented.
\nTreat clarifying questions as part of the workflow, not automatically as failure.
\nDo not allow docs to become actively misleading.
\nThis is especially important in fast-moving projects. AI can generate code quickly. It can also generate documentation quickly. But humans still need to verify whether that documentation is true, useful, and worth maintaining. If AI accelerates both code and docs, the risk is not only stale docs. The risk is a flood of plausible but low-signal text.
\nThe answer is not more documentation by default.
\nThe answer is better placement of information.
\nPrompts should define the task.
\nCode should remain the source of truth.
\nTests should verify behavior.
\nRules should encode repeated constraints.
\nDocs should orient the reader.
\nWhen each layer does its job, the agent does not need perfect documentation to be effective.
\nIt needs enough structure to understand the project, enough code to infer the real patterns, enough rules to avoid repeated mistakes, and enough human engagement to resolve ambiguity at the right moments.
\nThat is a healthier standard than trying to keep every doc perfectly aligned with a codebase that is changing faster than ever.
\nThis is easy to test.
\nTake the same coding task and run it under different conditions:
\nMeasure not only whether the task succeeds, but how the session behaves. How many clarifying questions does the agent ask? How much code does it inspect? Does it follow existing patterns? Does it make wrong assumptions? Does it recover when the docs conflict with the code?
\nMy expectation is that the prompt and the codebase will dominate more often than the docs. Good docs will reduce friction. Bad docs will create risk. Imperfect docs will usually be tolerable.
\nThat is the distinction I care about.
\nThe future of AI-assisted development is not documentation maximalism. It is context design.
\nAnd in context design, not all context is equal.
", "date_published": "2026-04-29T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Documentation", "Software Engineering", "Developer Philosophy", "Software Craftsmanship" ] }, { "id": "https://kobi.kadosh.me/blog/2026-04-22-ai-slop-human-bandwidth-where-i-draw-the-line/", "url": "https://kobi.kadosh.me/blog/2026-04-22-ai-slop-human-bandwidth-where-i-draw-the-line/", "title": "AI Slop, Human Bandwidth, and Where I Draw the Line", "summary": "AI can produce code, comments, PR descriptions, and review replies faster than humans can read and own them. The real bottleneck is no longer generation — it's comprehension. Here's how I think about effort symmetry, accountability, and why I don't buy a universal taxonomy.", "content_html": "A few weeks ago I sat down to review a pull request that, on paper, looked fine.
\nThe description was crisp. The commit messages were tidy. There were comments in the code explaining the tricky parts. When I asked a question in the review, I got a confident, well-structured answer within minutes.
\nHalfway through reading it, I realized something uncomfortable: almost none of it had been written by the person whose name was on the PR. The description read like a model. The inline comments read like a model. The review reply read like a model. The code itself was somewhere between “plausible” and “actually wrong” in places that only careful reading would surface.
\nI was not annoyed because AI had been used. I was annoyed because the author had shipped me several thousand words of confident prose and zero thinking. My job as a reviewer had quietly been upgraded from check the work to audit the plausibility of an entire synthetic artifact.
\nThat is the thing that worries me most about AI in software. Not that models can generate code. That they can generate everything around the code even faster.
\nWhen people say “AI slop,” they usually mean low-quality generated code. I think that definition is too narrow.
\nAI slop is any generated artifact that is cheaper to produce than it is to evaluate.
\nSometimes that artifact is code. Sometimes it is a 700-line issue body. Sometimes it is a PR description that says everything and nothing. Sometimes it is a wall of comments added to create the feeling of rigor. Sometimes it is a review response that sounds confident but is really a proxy answer copied from another model run.
\nThe common pattern is not “AI was used.” The common pattern is that the human cost has been externalized. One person gets leverage. Everyone else inherits the reading burden.
\nThat is where the social contract breaks.
\nI am not anti-AI. That framing is too primitive.
\nI have been shipping with AI agents in my daily workflow for a while now — drafting code, exploring design space, producing scaffolding, generating test cases, arguing with my own plans. A lot of this post itself started as notes I worked through with Claude. The value of these tools is obvious to me. I am not in the abstinence camp.
\nSometimes the thing you are writing is not even primarily for a human. It is a token blob meant to prime the next tool call. An issue can be a prompt. A system prompt can be architecture. A structured spec can be less about documentation than about steering an agentic workflow.
\nThat is real work. It is often valuable work.
\nYou can push it further. Run multiple coder agents against the same task. Compare approaches. Use their outputs as competing prompts for a final synthesis. That can be a productive workflow.
\nNone of this removes the need for human judgment. It just changes where judgment is most scarce and most expensive.
\nThe real bottleneck is no longer generation. It is comprehension.
\nThis is the part I think many teams still talk past each other on.
\n“Accountability” and “understanding” are related, but they are not the same thing.
\nAccountability means I can own the result. I can defend the branch I took. I can explain why a dependency was added, what tradeoff was made, what the blast radius is, how this affects DX, reliability, and product quality, and whether the tests are actually good enough. I can say, without hiding behind the tool, this change is mine.
\nUnderstanding is narrower and deeper. Do I understand the design pattern behind this module? Do I understand why this abstraction exists? Do I understand how this generic type will behave when the next integration point arrives? Do I understand the failure modes of this virtualization strategy? Did I inspect alternatives, or did I just accept the first plausible answer?
\nSome work requires both. Some work can survive with stronger accountability than line-by-line understanding. Pretending otherwise is purity theater.
\nA rule that says “the human must fully understand all code” sounds clean. In practice, it is subjective, hard to operationalize, and easy to weaponize. Ghostty takes a strict version of that stance, requiring disclosure and saying contributors should not submit changes they cannot explain without AI help. That may be exactly right for a terminal emulator maintained by a small group with a specific culture. I do not think it scales cleanly into a general standard.
\nIn real teams, full understanding is not binary. It is uneven, contextual, and often discovered under pressure. A policy that pretends otherwise will either be ignored or weaponized, usually both.
\nSaul Pwanson’s VisiData post is thoughtful, and the taxonomy is useful as a lens. It distinguishes between cases like “bots coded, human understands completely,” “bots coded, human understands mostly,” “human specced, bots coded,” and “bots planned, human approved.” It is a serious attempt to name meaningful differences in human involvement.
\nI do not agree with treating that 10-level scheme as a de facto standard.
\nIt is too specific to one project’s culture, one maintainer’s concerns, and one style of contribution management. Even VisiData presents it as its framework, not as an ecosystem-wide norm.
\nMy issue is not that the distinctions are intellectually wrong. My issue is that they are hard to operationalize consistently in policy.
\n“Reviewed” is observable. “Generated” is observable enough. “Human approved” is at least claimable. But “understands mostly” versus “understands completely” is a subjective mental-state audit. That is not a stable enforcement boundary. It is a vibe.
\nFor a small open source project, a highly opinionated taxonomy may be acceptable. For inner-source or commercial product development, it can become friction masquerading as rigor. Teams with limited resources do not need a more ornate morality scale. They need clarity around ownership, risk, and review burden.
\nIn my own work, most AI-assisted PRs would land somewhere VisiData would call level 7 or level 8. In a simplified internal system I would describe them more bluntly as “AI-generated, human-reviewed” or sometimes “AI-generated, lightly reviewed.” That is exactly why I do not want a policy that performs precision without delivering it. My bar is not whether I can philosophically classify my state of understanding. My bar is whether I can responsibly own the outcome.
\nAnother reason I resist universalizing any one project’s framework is simple: open source itself has not converged.
\nThe Linux Foundation is permissive in spirit — AI-generated contributions are allowed, with the burden on contributors to ensure license compatibility and compliance. The Linux kernel now has official guidance for AI coding assistants, but routes them through the ordinary development process rather than through an abstract theory of “AI contribution levels.”
\nRust’s recent discussion is reacting to a different failure mode: low-effort, insufficiently self-reviewed, extractive contributions that consume maintainer attention and feel, in their words, like a denial-of-service attack on review capacity. Firefox has focused entirely on accountability and declined to require disclosure. LLVM requires disclosure and calls out extractive contributions explicitly. QEMU sits much further to the restrictive side and says it will decline contributions believed to include or derive from AI-generated content at all.
\nThese projects are not disagreeing about whether AI is good or bad. They are making different tradeoffs about which failure mode they most want to prevent: license risk, maintainer burnout, learning-opportunity capture, code quality, or contributor accountability.
\nSo no, I do not think one project’s 10-level rubric should be treated as the standard. The principles may travel. The taxonomy should not.
\nMy line is pragmatic.
\nUse AI aggressively where it compresses toil, expands exploration, or helps structure a problem.
\nDo not use it as a shield against ownership.
\nDo not use generated verbosity as a substitute for thinking.
\nDo not dump unbounded review cost on another human and call it productivity.
\nDo not answer reviewer questions by laundering model output through your keyboard.
\nAnd do not confuse “the tests pass” with “the design is sound” in areas where the real risk is architectural, operational, or product-facing.
\nIf you want a simple rule, mine is this:
\nThe more AI reduced the cost of producing the change, the more the author must compensate with clarity, verification, and accountability.
\nThat is the trade.
\nNot abstinence. Not blanket permission. Not taxonomy worship.
\nA fair exchange.
\nI think good policies should optimize for three things:
\nThat last one matters more than many teams want to admit. Human attention is the scarce resource here. Not tokens. Not compute. Not generated prose.
\nWhen a policy makes contribution harder in ways that protect scarce human review capacity, that can be reasonable. When it adds ceremony without improving accountability or reducing review cost, it becomes process cosplay.
\nThis is why I prefer simpler classifications over elaborate ladders. I would rather have a small system that contributors can apply honestly and maintainers can use consistently than a nuanced system that encodes subjective mental states nobody can verify.
\nI wrote a while back in The Unpopular Opinion About Vibe Coding and AI that AI has not replaced coding — it has shifted where the effort lives, from writing to governance. The same shift applies here. The question is no longer “did a human write this line.” It is “does a human stand behind this change, and did they invest enough effort to justify mine?”
\nThe choice is not between stopping progress and surrendering to slop.
\nThe right frame is augmentation.
\nAI should help humans move faster, see more options, and spend more time on the parts that actually require judgment. It should not become a machine for manufacturing plausible-looking burden for someone else to sort through.
\nThat is the line for me.
\nI am not against AI-generated code. I am against unaccountable output. I am against content inflation. I am against policies that pretend every use case is the same. And I am against importing a rigid framework from one project and treating it like a universal answer.
\nThe future is not human-only software development. But it also cannot be a world where machines generate explanation faster than humans can maintain trust.
\nThe scarce asset is not code.
\nIt is responsible attention.
\nThat PR I started with, the one that made me write this post — I did eventually close the review. Not because AI had been used. Because the author could not defend the parts I asked about, and the review itself had started feeling like a conversation with a model wearing a human’s badge. The fix was not a new taxonomy. The fix was a short message that said: do the next one yourself, then loop me back in.
\nThat, to me, is the whole policy in one sentence.
\nWritten and developed with Claude. The arguments are mine; the drafting was collaborative. The inciting PR review was, unfortunately, also mine.
", "date_published": "2026-04-22T00:00:00.000Z", "tags": [ "AI Tools", "Code Review", "Open Source", "Software Craftsmanship", "Developer Philosophy" ] }, { "id": "https://kobi.kadosh.me/blog/2026-03-15-unix-philosophy-agents-skills/", "url": "https://kobi.kadosh.me/blog/2026-03-15-unix-philosophy-agents-skills/", "title": "Skills, Pipes, and the Unix Philosophy: Why Agents Should Run Programs, Not Replace Them", "summary": "The Unix philosophy — small programs, composed through pipes, doing one thing well — turns out to be an ideal operating model for AI agents. Skills leverage this by guiding agents to use battle-tested programs rather than reinventing them. Here's why that beats building custom MCP servers for most workflows.", "content_html": "There is a design philosophy that has been quietly winning for over fifty years. It was articulated in the early 1970s at Bell Labs, refined through decades of practice, and embedded so deeply into how we build software that most developers absorb it by osmosis without ever reading the original texts.
\nThe Unix philosophy:
\nThree principles. That is it.
\nAnd yet, as I watch the current wave of agent tooling unfold—MCPs, custom servers, plugin architectures, tool registries—I keep coming back to the same thought:
\nWe already had the right abstraction. We just forgot we had it.
\nI started programming in 2009 on mainframes in the Israeli Defense Force’s J6 & Cyber Defense Directorate. Those systems were built on a version of this philosophy: small, focused utilities composed into pipelines. No framework-of-the-week. No plugin ecosystem. Just programs that did their job, connected by well-defined interfaces.
\nIn Handcrafted Software in the Age of Automation, I argued that we should guide AI toward existing, proven tools rather than letting it generate bespoke solutions for already-solved problems. This post is the next step in that argument.
\nThe Unix philosophy is not just good engineering advice from the past. It is the ideal operating model for AI agents right now. And skills—lightweight prompt-based guidance—are how you unlock it.
\nThere is a popular way to talk about agents that gets the abstraction slightly wrong. We describe them as if they are replacing software.
\nIn practice, the more useful framing is the opposite. An agent is not replacing the program. It is learning how to operate the program.
\nThat distinction matters.
\nYes, there are scenarios where an agent can itself behave like a tool. That boundary will shift as models improve. Some workflows that currently require explicit software will eventually collapse into the model itself. But today, agents are generally strongest when they are orchestrators—deciding what to do next, interpreting messy intent, translating goals into steps, and then driving deterministic systems on the user’s behalf.
\nA user says, “Find all the error logs from the last week and summarize the top failure modes.” The agent’s job is not to become a log parser. Its job is to figure out that find, grep, sort, uniq, and head already solve this problem—and compose them correctly.
The model handles ambiguity: what the user probably means, what the intent is, what sequence of actions makes sense.
\nThe program handles execution: parse the file, filter the lines, count the occurrences, sort the results.
\nThis is a very good pairing. And it maps directly onto the Unix philosophy.
\nThe agent is the operator at the terminal. The programs are the tools on the shelf. The pipes are the composition mechanism. The skill tells the agent which tools to reach for and how to connect them.
\nI think “prompt” is too weak a word for what a good skill does.
\nA skill is better understood as operational guidance for using a program in a particular way for a specific class of problems.
\nIt tells the agent things like:
\nIn Building a Claude Code Skill for Codebase Synchronization, I walked through a practical example: a skill that detects documentation drift across a codebase and fixes it. That skill does not contain the intelligence to understand your codebase. It contains the procedure—inspect these files, compare these sources of truth, show the delta, propose a fix, confirm with the user.
\nThe procedure is the valuable part.
\nRaw capability is not the same as applied competence. An agent might know that jq exists. A skill tells it: use jq here, with this filter pattern, pipe the output through this transformation, and verify the result has the expected shape before moving on.
An agent might know a shell exists. A skill tells it: this is a shell problem. Inspect state first. Avoid destructive commands. Verify the result. Here is the recovery path if it fails.
\nThat is not “extra prompting.” That is operational knowledge. And it is the difference between an agent that vaguely knows tools exist and one that can use them effectively in production.
\nThis is not very different from how humans work. Knowing that ffmpeg, git, jq, sed, ImageMagick, pandoc, or psql exist is not the same as knowing how to solve a real problem with them. The useful part is not awareness of the tool. The useful part is the learned procedure.
A skill packages that procedure in a form the agent can reliably follow.
\nOne reason skills work so well is that they align with the kinds of patterns models have already absorbed during training.
\nThere are two major sources of leverage here.
\nTraining data is saturated with programs being used directly. Bash commands, shell pipelines, Makefiles, Dockerfiles, Python scripts, CI configs, terminal transcripts, debugging sessions, SQL queries, CLI help pages, man pages, setup instructions.
\nThat matters because Unix tools have a text-based interface. A shell command is text. A script is text. A config file is text. An API call is usually text. For a language model, that is home territory.
\nConsider the difference:
\n# Finding error patterns in recent logs — Unix pipeline\nfind /var/log -name "*.log" -mtime -7 -exec grep -l "ERROR" {} + \\\n | xargs -I{} sh -c 'echo "=== {} ===" && grep "ERROR" "{}" | sort | uniq -c | sort -rn | head -5'An agent guided by a skill toward this pipeline is drawing on a deep prior—countless examples of humans solving concrete problems with exactly these mechanisms. The model has seen find, grep, sort, uniq, and head composed together thousands of times across its training data.
This does not mean the model is always right. But it means the model has a strong native bias toward this mode of problem-solving. The skill activates that bias and constrains it toward the specific task.
\nThe second source of leverage is even more important: the web is packed with people asking “how do I do X?” and other people answering with step-by-step procedures.
\nForums, Q&A sites, documentation, blog posts, README files, tutorials, issue trackers, troubleshooting threads—they all reinforce the same pattern:
\nThat is almost exactly the structure of agentic work.
\nWhen a user asks an agent to solve a task, the agent is often matching that request against a vast library of previously seen “how to accomplish X using Y” examples. A skill sharpens that retrieval path. It narrows the solution space. It says: in this context, use these tools, in this order, with this standard of care.
\nSo the skill is not replacing the model’s knowledge. It is activating and constraining it. Two different operations, both important.
\nNow let me say the thing directly.
\nMCP servers—Model Context Protocol servers—are a popular way to give agents access to capabilities. You write a server that exposes tools through a standardized protocol. The agent calls the server. The server runs logic and returns results.
\nFor certain cases, this makes sense. I will get to those.
\nBut for the vast majority of agent workflows, MCPs are the wrong abstraction. They add complexity where none is needed. And they actively work against the grain of what makes agents effective.
\nHere is why.
\nWhen an agent calls an MCP server, it is interacting with an interface it has likely never seen before. The tool names, parameter schemas, return formats, and behavioral semantics are all novel. The model has zero prior exposure to your custom extract-json-fields MCP tool. It is working from the schema description alone.
Compare that to a skill that guides the agent to use jq:
# Skill-guided: extract active user emails from JSON\njq '.users[] | select(.active == true) | .email' data.jsonThe model has seen jq used in hundreds of thousands of examples across its training data. It knows the syntax, common patterns, edge cases, error messages. The skill does not need to explain jq from first principles. It only needs to direct behavior: for this class of problems, use jq, here is the pattern.
That is an enormous advantage. You are building on a warm prior instead of starting cold.
\nAn MCP server requires:
\nA skill requires:
\nI am not exaggerating. A Claude Code skill is a .md file that describes a procedure. No server. No runtime. No dependencies. No deployment. You write it, the agent reads it, the agent follows the procedure using tools that already exist on the system.
The maintenance burden is not comparable. When jq gets an update, you do nothing—your skill still works. When your MCP server’s dependencies need updating, you have a maintenance task.
One of the most powerful features of Unix programs is that they compose through pipes. The output of one program becomes the input of the next. No special integration required. No orchestration layer. Just text flowing through a pipeline.
\n# Three programs composed through pipes — no orchestration code needed\ncurl -s https://api.example.com/users \\\n | jq '.[] | select(.role == "admin")' \\\n | wc -lMCPs are silos. Each MCP server is its own world. Composing two MCPs requires the agent to call one, capture the result, transform it, and call the other. That orchestration lives in the agent’s reasoning—which is the least deterministic part of the system.
\nUnix pipes move the composition into the deterministic layer. The agent constructs the pipeline. The shell executes it. The agent checks the result. That is a much more robust workflow.
\nThis is the part that bothers me most.
\nConsider what people build MCP servers for: reading files, searching codebases, extracting data from JSON, transforming text, querying databases, managing git operations, processing images, converting formats.
\nNow consider what already exists on any Unix system: cat, grep, find, jq, sed, awk, sort, uniq, curl, git, ffmpeg, convert, pandoc, psql, sqlite3, tar, diff, wc, head, tail, cut, tr, xargs.
These tools are battle-tested. They have been refined for decades. They handle edge cases. They are fast. They are documented. They are deterministic. And—crucially—the model already knows how to use them.
\nBuilding an MCP server to wrap functionality that jq or grep or git already provides is not just unnecessary overhead. It is actively counterproductive, because you are replacing a tool the model has a deep prior on with a novel interface it has never seen.
I am not saying MCPs are never the right choice. They make sense when:
\nThose are real use cases. But they are a small fraction of what I see people building MCP servers for.
\nFor file processing, text transformation, system inspection, data extraction, format conversion, log analysis, git operations, and most of the day-to-day work that agents do? You do not need a custom server. You need a good skill and access to a shell.
\nThere is an interesting compounding dynamic here.
\nIf the deterministic program already appears frequently in the model’s training data, the skill becomes more powerful. The reason is simple: the prompt is not teaching the program from scratch. It is cueing a system the model has likely seen many times before.
\nInstructing an agent to use bash, python, git, curl, ffmpeg, jq, grep, awk, or sed is effective partly because those interfaces are deeply represented in the training corpus. The model has seen them used across documentation, scripts, answers, debugging threads, and tutorials. A skill can therefore be compact while still being highly effective.
The prompt does not need to explain everything. It only needs to direct behavior toward a known operational pattern.
\nThis is one reason skills often feel disproportionately useful relative to their size. A few paragraphs of guidance can unlock a large amount of latent procedural knowledge. The skill is not providing the intelligence. It is providing the direction.
\nMCPs, by contrast, are always a cold start. Every custom MCP tool is a novel interface. The model works from the schema description, not from deep familiarity. That is a fundamentally weaker position, and no amount of schema documentation fully compensates for the absence of training data.
\nOne reason this pattern is robust is that the program is deterministic.
\nThe model is not being asked to improvise every step of the solution. It is being asked to drive something that has crisp, predictable behavior.
\nThat gives you a useful split:
\nThis is much more reliable than asking the model to do everything internally, especially when the task involves files, formats, transformations, or any workflow where correctness matters.
\nThe skill is what makes that split work consistently. It tells the model how to move between judgment and execution without losing the thread.
\nWithout that layer, the agent may still succeed on any given run. With it, the agent is far more likely to succeed repeatedly.
\nI do not think skills in their current form are permanent. Over time, models will absorb more tool-like behavior. Some explicit programs will disappear behind model interfaces. Some workflows that currently need careful orchestration will become default capabilities.
\nBut the Unix philosophy insight—composition of small, focused, deterministic units—is a design principle, not a temporary workaround. It applies regardless of whether the units are shell programs, API calls, or model-native capabilities. The principle survives because it solves a real problem: managing complexity through composition rather than consolidation.
\nToday, that composition happens through skills guiding agents to use Unix programs.
\nTomorrow, the specific tools may change. But the pattern—small units, clear interfaces, text as the universal medium, composition over monoliths—will still be the right way to build reliable systems.
\nThe Unix philosophy was not designed for AI agents. It just happens to describe exactly what they need.
\nHere is the mental model I keep coming back to:
\nThe model brings interpretation.\nIt handles ambiguity, figures out intent, translates fuzzy human goals into structured action.
\nThe program brings precision.\nIt executes deterministically, handles edge cases correctly, and produces predictable output.
\nThe skill connects the two.\nIt encodes operational knowledge—which tools, which order, which patterns, which guardrails.
\nThat connection is powerful precisely because it leverages training data twice. First through the model’s deep familiarity with tool interfaces and executable patterns. Second through the enormous corpus of human problem-solving examples—the entire internet’s worth of “how do I accomplish X using Y.”
\nA skill is not just a prompt. It is a compact operational wrapper around accumulated procedural knowledge. It tells the agent how to use a deterministic program for a specific class of problems. And when that program already lives in the model’s prior—when the agent has effectively seen it used ten thousand times—the result is surprisingly strong.
\nWe do not need to rebuild the wheel with custom servers and novel protocols for most agent workflows. The programs already exist. The training data already contains the knowledge. The composition mechanism already works.
\nAll we need is the skill to connect them.
\nBecause, for now at least, agents are not at their best when they replace programs.
\nThey are at their best when they know how to run them well.
\nThis post builds on ideas from Handcrafted Software in the Age of Automation, which argued for respecting battle-tested tools in the age of AI, and Building a Claude Code Skill for Codebase Synchronization, which demonstrated what skills look like in practice. Together they form a thread: respect the fundamentals, encode the procedures, and let agents compose what already works.
\nWritten and developed with Claude. The arguments are mine; the drafting was collaborative.
", "date_published": "2026-03-15T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Unix", "Claude Code", "Software Craftsmanship", "Developer Philosophy", "Automation" ] }, { "id": "https://kobi.kadosh.me/blog/2026-02-11-back-office-front-office-split-future-software/", "url": "https://kobi.kadosh.me/blog/2026-02-11-back-office-front-office-split-future-software/", "title": "The Back Office / Front Office Split: A Prediction for the Future of Software", "summary": "We've become unpaid staff for the applications we use. The future will separate operational back-office work from human-facing front-office experiences, with AI agents handling the infrastructure while humans focus on judgment and decision-making.", "content_html": "Look at a normal day.
\nYou’re juggling Google Calendar, email, Slack, documents, a task manager, notes, maybe a CRM, maybe finances, maybe a dozen tabs that represent “adulting.” Each one has good UX. Each one has brilliant engineering behind it.
\nAnd yet… they feel like chores.
\nNot because they’re poorly built—but because they require you to play too many roles just to keep them operational.
\nTake the simplest example: your calendar.
\nTo make a calendar useful, you have to do back office work:
\nAnd that’s before the “real life” part begins: showing up, being prepared, reading context, making decisions, following up.
\nSame story for email:
\nSame story for to-do lists, notes, social feeds, personal finance, investment portfolios—all of it.
\nWe aren’t just using software.
\nWe’re staffing it.
\nIf you’ve ever had (or worked with) a personal assistant, you’ll recognize the split:
\nThey can do the inbound handling and structuring:
\nBut you still have to do the “front office” part:
\nA good assistant doesn’t eliminate work—they move you up the stack.
\nThat’s the key.
\nI think we’re going to see a major divide in how software is built and experienced.
\nThe stuff that turns messy human life into structured systems:
\nThe part humans actually want to do:
\nMost apps today force you to do both—and that’s why they feel exhausting.
\nThe next generation won’t.
\nThis is the part that makes the split inevitable: the back office is basically operator work.
\nAnd modern services already expose the machinery needed for operators:
\nSo instead of you doing the operator work manually, the operators become:
\nAnd the “product” becomes less about “here’s a screen, please fill the form” and more about:
\nThat’s a fundamentally different UX contract.
\nOnce the separation is real, it changes incentives.
\nIf I mostly interact with a “review + decision” layer, then the underlying back office becomes interchangeable—as long as it’s reliable, auditable, secure, and composable.
\nIf the back office really becomes autonomous, then one thing follows almost immediately:
\nWe won’t care how it looks.\nWe won’t care how it’s rendered.\nWe’ll barely care who runs it.
\nWe’ll care about functionality, reliability, auditability, and alignment with our intent.
\nThat pushes the back office toward being agnostic infrastructure—not an “app” in the traditional sense, but a substrate:
\nThis is infrastructure that used to be accessible only to a narrow group of experts—operators, SREs, platform engineers, power users—the kind of tools that required deep technical literacy.
\nWhat changes now is not that the tools become simpler.
\nWhat changes is that the human-facing layer becomes radically better, and agents absorb the operational complexity.
\nToday’s model is simple but brittle:
\nThat model does not scale with human complexity.
\nIn the future, it won’t be “one app per function.”
\nIt will be:
\nThe back office becomes yours—not in the sense that you micromanage it, but in the sense that:
\nThis is where data sovereignty stops being a slogan and starts being structural.
\nOnce you accept this model, agents stop looking like “AI features” and start looking like employees:
\nMultiple agents can operate the same back office, just as multiple employees can operate the same company systems.
\nAnd just like with employees, what matters is not how they do the work—but:
\nThis naturally leads to standards:
\nOnce standards emerge, competition becomes healthy.
\nHere’s where this gets interesting.
\nIf:
\nThen open source becomes an obvious gravity well.
\nNot because it’s ideological—but because it’s practical.
\nOpen-source back offices allow:
\nCompanies can still differentiate:
\nBut the bare bones—the operational logic—benefits enormously from being shared.
\nThis creates an ecosystem where:
\nThat’s a healthier software economy than what we have today.
\nSo far, everything I described keeps agents “in the shadows”:
\nBut the uncomfortable question is unavoidable:
\nWhen do agents enter the front office themselves?
\nAt first, this will feel dystopian.
\nAn agent attending a meeting for you.\nAn agent negotiating on your behalf.\nAn agent presenting status updates while you don’t show up at all.
\nBut over time, this forces a refinement we’ve been avoiding:
\nWhat is the work that actually requires a human?
\nRight now, many humans are doing high-effort, low-meaning labor simply because the ecosystem demands it.
\nAgents change that pressure.
\nThey don’t eliminate human value—they clarify it.
\nI don’t think the front office stops at chat windows and dashboards.
\nMy prediction is that we’ll see a rapid evolution in presence-based interfaces:
\nNot as gimmicks—but because presence matters in human coordination.
\nThink of what we’re already seeing with voice agents, but extended to full-blown experiences that feel like a high-fidelity game. Imagine MetaHuman—Epic’s photorealistic digital human framework—applied not to entertainment, but to business applications. Your AI assistant with a face. Your agent representative in a virtual meeting room.
\nOver time, this extends further:
\nAt that point, your “app” is no longer something on your phone.
\nYour phone becomes a remote control.
\nThe system itself is:
\nAnd humans interact with it only where it actually makes sense.
\nWe often frame this future as “AI replacing humans.”
\nI think that’s the wrong lens.
\nWhat’s actually happening is:
\nThe real shift is from data entry to stewardship.
\nToday’s apps assume you are a data entry clerk.
\nTomorrow’s apps assume you are a steward.
\nYou don’t “keep your calendar updated.”\nYou review what your calendar became, and decide what to accept.
\nYou don’t “process your inbox.”\nYou approve a set of proposed actions with context, grouped by intent.
\nYou don’t “maintain your task system.”\nYou steer priorities while the system maintains itself.
\nAnd the moment that becomes normal, we’ll look back at today’s workflow the same way we look back at:
\nNot because we were foolish—but because the interface was wrong.
\nWe were doing back office work because nothing else could.
\nThat’s about to change.
", "date_published": "2026-02-11T00:00:00.000Z", "tags": [ "AI Agents", "Software Architecture", "Future of Work", "Predictions", "Open Source" ] }, { "id": "https://kobi.kadosh.me/blog/2026-02-11-what-exceptional-recruiting-looks-like/", "url": "https://kobi.kadosh.me/blog/2026-02-11-what-exceptional-recruiting-looks-like/", "title": "What Exceptional Recruiting Looks Like (From the Candidate's Side)", "summary": "After more than a decade in tech, I thought I'd seen every variation of the hiring process. Then I worked with a recruiter who showed me what it looks like when someone genuinely cares about doing the job right. This is a reflection on trust, transparency, and why the best recruiting feels less like a transaction and more like a partnership.", "content_html": "I’ve been working professionally since 2012. That’s more than a decade of recruiter messages, LinkedIn pitches, interview loops, and offer negotiations. I’ve seen the spectrum: the mass-blast outreach that misspells your name, the aggressive follow-ups that feel like sales pressure, the radio silence after you’ve invested hours in technical challenges.
\nNone of it prepared me for what it felt like to work with someone who actually did the job exceptionally well.
\nLet me be honest about the baseline. Most recruiting interactions feel transactional. You’re a slot to fill, a commission to close, a metric to move. The communication is either too sparse or too aggressive. Preparation is minimal. Context is generic. And somewhere in the process, you realize that the person coordinating your interviews doesn’t really understand what you do or why you might be good at it.
\nThis isn’t an indictment of recruiters as people. It’s an observation about systems. When the incentives are misaligned, when speed matters more than fit, when volume trumps quality, the candidate experience suffers. Everyone knows this. Most of us have just accepted it.
\nSo when something different happens, it’s disorienting. You notice it immediately, even if you can’t articulate why.
\nRecently, I went through a hiring process that was genuinely different. The recruiter, Megan Ashbee, approached me in a way that stood out from the first message.
\nNo hard sell. No exaggeration. Just clear information: the company, the role, the technical focus, the compensation range. She was transparent about constraints before I’d even responded. That alone is rare.
\nBut what made the experience exceptional wasn’t any single thing. It was the consistency of care across every interaction.
\nEarly in the process, Megan asked about my experience with specific technologies. She asked about my salary expectations. She shared the target range upfront: not after three rounds of interviews, not as a negotiation tactic, but as information I needed to make an informed decision.
\n“In the name of transparency,” she wrote.
\nThat phrase stuck with me. It’s easy to say. It’s harder to mean. She meant it.
\nWhen I told her my current compensation was above their initial range, she didn’t disappear. She said they could push the range if everything else aligned. No games. No false scarcity. Just honesty about what was possible.
\nThis kind of transparency changes the dynamic. You stop trying to guess what’s real. You stop performing. You start actually evaluating whether the opportunity is right for both sides.
\nBefore every interview, Megan sent context. Not just logistics, but who I’d be meeting and why. What they cared about. How to frame my experience. What to expect from the conversation.
\nThis might sound like standard practice. It isn’t.
\nMost of the time, you walk into interviews blind. You don’t know what the interviewer is looking for. You don’t know what they’ve already heard about you. You’re guessing, adapting in real-time, trying to read the room.
\nMegan eliminated that uncertainty. Not by scripting the conversation, but by giving me enough context to show up as myself: prepared, focused, and confident.
\nThat’s what good preparation does. It doesn’t make you perform better artificially. It removes the friction that prevents you from performing at your actual level.
\nOne of the things that stood out most was the sense that Megan was advocating on both sides of the process.
\nShe wasn’t just presenting me to the company. She was helping me understand the company. She wasn’t just filtering candidates for her client. She was helping me evaluate whether this was the right fit for my career.
\nThat’s a subtle but important distinction. Most recruiters are aligned with the hiring company. Their incentive is to close. Megan’s approach felt different, like she was aligned with the process itself, with making sure both sides had the information they needed to make good decisions.
\nI’m confident she represented me internally with the same care she showed me directly. That’s not something you can fake. It comes through in how someone communicates, how they prepare, how they follow up.
\nThere’s a delicate balance in professional relationships. Too formal and it feels cold. Too casual and it feels presumptuous.
\nMegan navigated this perfectly. She was warm without being unprofessional. She made space for real conversations, about my family situation, about timing, about things that mattered outside the immediate transaction, without overstepping.
\nWhen I shared that I might need to travel to Israel for a family matter, she didn’t treat it as a complication. She asked how she could help. She communicated it to the company thoughtfully. She made sure I felt supported, not exposed.
\nThat’s not process. That’s judgment. That’s someone who understands that candidates are people, not resources.
\nSenior engineers are busy. We get a lot of recruiter messages. Most of them are noise.
\nMegan’s initial outreach was concise, relevant, and respectful. She included just enough information to be useful: not so much that it felt like a pitch, not so little that I had to guess whether it was worth responding.
\nWhen we scheduled calls, she was flexible but efficient. When I needed to reschedule, there was no friction. When there were updates, she communicated them promptly. When there was nothing to report, she didn’t manufacture urgency.
\nThis sounds simple. It’s surprisingly rare.
\nThe cumulative effect of all these small choices is trust. You stop worrying about the process and start focusing on the actual decision.
\nI’ve been thinking about why this experience affected me so much. Part of it is contrast: after years of mediocre interactions, excellence stands out.
\nBut there’s something deeper. When recruiting is done well, it changes how you feel about the company you’re joining. Megan didn’t just get me through a process. She represented her client in a way that made me excited to join.
\nThat’s the multiplier effect of great recruiting. It’s not just about filling a role. It’s about starting relationships on the right foundation. It’s about signaling what kind of organization you’re joining.
\nIf a company invests in people like Megan, people who care about doing the job right, that tells you something about their values. It suggests that quality matters. That people matter. That they understand the difference between closing candidates and building teams.
\nI’m not writing this as a testimonial. I’m writing it because I think the bar for recruiting is too low, and most people have stopped noticing.
\nWe accept transactional interactions because we’ve been conditioned to expect them. We’re grateful when someone responds promptly, even though that should be table stakes. We’re surprised when a recruiter prepares, even though preparation should be the minimum.
\nWhat Megan showed me is what recruiting looks like when someone treats it as a craft. When they take pride in the process itself, not just the outcome. When they understand that every interaction is an opportunity to build trust or erode it.
\nThis should be the standard, not the exception.
\nI don’t often write about personal experiences. I prefer to keep my professional reflections abstract, focused on patterns rather than individuals.
\nBut some experiences deserve recognition. Megan made my decision to accept the offer easy, not because she persuaded me, but because she created the conditions for me to evaluate clearly and choose confidently.
\nThat’s what exceptional work looks like in any field. You don’t notice the effort. You just notice that things work.
\nTo anyone fortunate enough to work with Megan Ashbee: you’re in good hands. And to anyone building a recruiting function: this is the standard to aim for.
\n\n", "date_published": "2026-02-11T00:00:00.000Z", "tags": [ "Career", "Hiring", "Leadership", "Software Engineering", "Developer Philosophy" ] }, { "id": "https://kobi.kadosh.me/blog/2026-02-04-claude-code-skill-codebase-synchronization/", "url": "https://kobi.kadosh.me/blog/2026-02-04-claude-code-skill-codebase-synchronization/", "title": "Building a Claude Code Skill for Codebase Synchronization", "summary": "Documentation drift is the silent killer of codebases. Your roadmap says one thing, your website another, and your README hasn't been updated in months. Here's how I built a pluggable Claude Code skill that detects drift, shows exactly what's out of sync, and fixes it—with your approval.", "content_html": "About this post: This essay reflects on a recent hiring experience that stood out from more than a decade of professional interactions. It’s not a recommendation letter—it’s a reflection on what recruiting can be when done with care, transparency, and genuine investment in both sides of the process.
\n
Every codebase I’ve worked on has the same disease: documentation drift.
\nIt starts innocently. You update your roadmap in GitHub milestones because that’s where the real work happens. The ROADMAP.md file gets updated… eventually. The public roadmap page on your website? Maybe next quarter.
\nThree months later, your GitHub shows 21 issues in the v1.1.0 milestone with 5% completion. Your ROADMAP.md claims 16 issues with 7% completion. Your website says “Coming Soon” for features you shipped last month.
\nThis isn’t laziness. It’s the natural entropy of information distributed across multiple locations. Every duplicated source of truth is a lie waiting to happen.
\nI got tired of the manual hunt-and-fix cycle. So I built a Claude Code skill to automate it.
\nBefore diving into the solution, a quick primer for those unfamiliar: Claude Code is Anthropic’s official CLI for Claude. It’s an AI-powered terminal tool that can read your codebase, execute commands, edit files, and—crucially—be extended with custom skills and commands.
\nSkills are Markdown files that define specialized capabilities. When you invoke a skill, Claude Code reads those instructions and gains context about how to perform a particular task. Think of them as domain-specific prompts that turn a general-purpose AI into a specialized tool.
\nCommands are user-invokable actions that route to skills or perform specific operations.
\nThis architecture creates something powerful: pluggable, versioned, shareable AI workflows that live in your repository alongside your code.
\nThe skill I built is called code-parts-syncer. Its core insight is simple but powerful:
\n\nEvery sync domain needs exactly one source of truth. Everything else derives from it.
\n
For roadmap data, the ground truth is GitHub (milestones and issues). For project instructions, it might be CLAUDE.md. For documentation, perhaps your website or README.
The skill implements a consistent five-step process across all sync domains:
\n┌─────────────────────────────────────────────────────────────────┐\n│ CODE-PARTS-SYNCER │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ 1. FETCH GROUND TRUTH │\n│ └── Query authoritative source (e.g., GitHub API) │\n│ │\n│ 2. READ CURRENT STATE │\n│ └── Extract values from all target files │\n│ │\n│ 3. DETECT DRIFT │\n│ └── Compare ground truth with current state │\n│ │\n│ 4. REPORT DRIFT │\n│ └── Display discrepancies with ✓/✗ indicators │\n│ │\n│ 5. APPLY UPDATES (with user confirmation) │\n│ └── Edit files to align with ground truth │\n│ │\n└─────────────────────────────────────────────────────────────────┘This pattern scales to any sync domain: roadmaps, documentation, instructions, configuration—anything that exists in multiple places but should stay consistent.
\nThe skill lives entirely within the .claude/ directory, following Claude Code’s conventions:
.claude/\n├── commands/\n│ └── caro.sync.md # Main command dispatcher\n└── skills/\n └── code-parts-syncer/\n ├── README.md # Overview documentation\n ├── roadmap-sync.md # GitHub ↔ ROADMAP.md ↔ website\n ├── docs-sync.md # README ↔ website ↔ CLAUDE.md\n └── instructions-sync.md # CLAUDE.md ↔ CONTRIBUTING ↔ READMEEach module is independent. The roadmap syncer knows nothing about documentation sync. This separation makes the system easier to understand, test, and extend.
\nThe total implementation is approximately 1,766 lines of Markdown—substantial enough to be thorough, small enough to audit and understand.
\nLet me walk through the fully functional module: roadmap synchronization.
\nThis module keeps three sources in sync:
\nGitHub is authoritative because that’s where work actually happens. Issues get created, closed, moved between milestones. Any process that requires manual duplication will fall behind.
\nThe first step queries GitHub using the gh CLI:
# Fetch all milestones with issue counts\ngh api repos/owner/repo/milestones --jq '.[] | {\n title,\n description,\n due_on,\n open_issues,\n closed_issues,\n state\n}'\n\n# For each milestone, fetch its issues\ngh api repos/owner/repo/issues?milestone=1&state=all --jq '.[] | {\n title,\n number,\n state,\n labels: [.labels[].name]\n}'This gives us the real data: actual issue counts, actual completion percentages, actual due dates.
\nNext, the skill parses the current state from each target file. For ROADMAP.md, it looks for structured sections:
\n## v1.1.0 - Core Improvements\n- **Status**: 15 open, 1 closed (7% complete)\n- **Due**: March 15, 2026 (48 days)For the Astro website component, it parses the data structures:
\nconst milestones = [\n {\n version: "v1.1.0",\n title: "Core Improvements",\n openIssues: 20,\n closedIssues: 1,\n // ...\n }\n];Then comes the comparison. For each milestone, the skill checks:
\nHere’s what a real drift report looks like:
\n================================================================================\n ROADMAP DRIFT DETECTION\n================================================================================\n\nSource of Truth: GitHub API (gh api repos/wildcard/caro/milestones)\n\nv1.1.0 - Core Improvements:\n GitHub (TRUTH): 20 open, 1 closed, 21 total (5% complete, 46 days)\n ROADMAP.md: 15 open, 1 closed, 16 total (7% complete, 48 days) ✗ DRIFT\n website/roadmap: 20 open, 1 closed, 21 total (5% complete, 46 days) ✓ SYNCED\n\nv1.2.0 - Extended Platforms:\n GitHub (TRUTH): 8 open, 0 closed, 8 total (0% complete, 90 days)\n ROADMAP.md: 8 open, 0 closed, 8 total (0% complete, 90 days) ✓ SYNCED\n website/roadmap: 8 open, 0 closed, 8 total (0% complete, 90 days) ✓ SYNCED\n\n================================================================================\n SUMMARY\n================================================================================\n\n ROADMAP.md: 1 milestone needs updates\n website/roadmap: All synced ✓\n\n Recommended action: /caro.sync roadmap → Apply updates now\n\n================================================================================This report tells you exactly what’s wrong without making any changes. The --check flag runs drift detection only—a dry run that shows problems without fixing them.
When you’re ready to fix the drift, the skill:
\nNo silent overwrites. No surprises. You see exactly what will change before it happens.
\nThe command dispatcher makes this ergonomic:
\n# Show available sync modules\n/caro.sync\n\n# Full roadmap sync with updates\n/caro.sync roadmap\n\n# Drift detection only (dry run)\n/caro.sync --check roadmap\n\n# Check all modules for drift\n/caro.sync --check allThe compound all option runs every enabled module, giving you a dashboard view of documentation health across your entire codebase.
The architecture supports additional sync domains. Two are planned:
\nKeeps installation instructions, feature lists, and CLI examples consistent across:
\nCLAUDE.md (AI context file)The ground truth here is contextual—README for user-facing docs, CLAUDE.md for development context.
Synchronizes project descriptions and development workflows across:
\nCLAUDE.md (primary for development instructions)Each module follows the same five-step pattern. Adding a new sync domain means writing a new Markdown file that defines sources, ground truth, and sync logic.
\nHere’s how I built and shipped this skill—a process that’s itself worth documenting.
\nI use a git worktree pattern for feature development:
\n# Create a dedicated worktree for the feature\ngit worktree add .worktrees/010-code-parts-syncer -b feature/code-parts-syncer\n\n# Work in isolation\ncd .worktrees/010-code-parts-syncer\n\n# All changes happen here, main branch stays cleanWorktrees give you parallel working directories on different branches. I can experiment freely without polluting main or creating WIP commits.
\nThe commit follows Conventional Commits:
\nfeat: Add code-parts-syncer skill for drift detection and sync\n\nImplements a pluggable sync skill to keep related content synchronized\nacross different parts of the codebase (roadmap, docs, instructions).\n\n**Architecture**:\n- Main command dispatcher: /caro.sync\n- Pluggable module system for different sync domains\n- Ground truth pattern (authoritative source per domain)\n- Drift detection before updates\n- Safe updates with user confirmation\n\n**Modules**:\n- ✓ roadmap-sync.md: Functional - syncs ROADMAP.md ↔ website ↔ GitHub API\n- ⋯ docs-sync.md: Placeholder - will sync README ↔ website ↔ CLAUDE.md\n- ⋯ instructions-sync.md: Placeholder - will sync CLAUDE.md ↔ README ↔ CONTRIBUTINGClear, structured, and informative. Anyone reading the git log understands what changed and why.
\nNotice that only the roadmap module is fully implemented. The others are placeholders with architecture but no logic.
\nThis is intentional. Ship what works, document what’s planned. A single working module proves the pattern. The placeholders show where it’s going without blocking the release.
\nWithout a clear source of truth, sync becomes a nightmare. Which version is correct? If ROADMAP.md says 15 issues and GitHub says 21, which wins?
\nThe ground truth pattern eliminates this ambiguity. GitHub is authoritative for roadmap data—period. Everything else derives from it. No debates, no merge conflicts of intent.
\nThe obvious approach is “just sync everything.” But that’s dangerous:
\nDrift detection first means you always know what’s out of sync. You can review, understand, and approve. The tool informs; you decide.
\nClaude Code can edit files directly. It would be easy to make sync fully automatic. But that trades safety for convenience—a bad bargain.
\nThe confirmation step keeps humans in the loop. You see the proposed changes, you approve them, they happen. No surprises.
\nSkills are Markdown files, not code. This has several advantages:
\nThe trade-off is that complex logic requires verbose instructions. But for most workflows, Markdown is expressive enough and far more transparent.
\nAfter implementing the roadmap sync:
\nBefore:
\nAfter:
\n/caro.sync --check roadmapMore importantly, I now know when things are out of sync. The mental overhead of “I should probably check the roadmap files” is gone.
\nIt’s tempting to design the perfect universal sync system. Don’t. Build one module that solves one problem. Prove the pattern works. Then expand.
\nThe roadmap syncer taught me what the architecture needed. Building it first made the placeholder modules easier to design.
\nThe pluggable module pattern means adding new sync domains is trivial:
\n.claude/skills/code-parts-syncer/No refactoring. No breaking changes. Just add a file.
\nAny tool that modifies files must be safe by default. Drift detection without modification is the baseline. User confirmation for changes is required. Git diff visibility is essential.
\nBuild trust through transparency, not through hoping nothing goes wrong.
\nThe skill includes a README.md that explains the architecture, lists modules, and shows usage examples. When someone invokes /caro.sync without arguments, they get help.
Good tools are self-documenting. The skill should explain itself.
\nImagine a pre-commit hook that runs /caro.sync --check all. If any drift is detected, the commit fails with a helpful message:
❌ Commit blocked: Documentation drift detected\n\n ROADMAP.md is out of sync with GitHub milestones.\n Run `/caro.sync roadmap` to fix, then commit again.No more shipping inconsistent documentation.
\nA GitHub Action that runs drift detection on every PR:
\n- name: Check Documentation Drift\n run: |\n claude-code /caro.sync --check all --ci\n if [ $? -ne 0 ]; then\n echo "::error::Documentation drift detected. Run /caro.sync locally."\n exit 1\n fiPRs that introduce drift get flagged automatically.
\nA /caro.sync status --all command that shows sync health across all modules:
================================================================================\n CODEBASE SYNC HEALTH DASHBOARD\n================================================================================\n\n Module Status Last Sync Issues\n ─────────────────────────────────────────────────\n roadmap-sync ✓ OK 2 hours ago 0\n docs-sync ✗ DRIFT 5 days ago 3 files outdated\n instructions-sync ✓ OK 1 day ago 0\n\n Overall Health: NEEDS ATTENTION\n\n Run `/caro.sync docs` to resolve.\n================================================================================Visibility drives action. If you can see the problem, you’ll fix it.
\nIf you’re using Claude Code and maintaining documentation across multiple locations, this pattern is immediately applicable.
\nThe key insights are:
\nYou don’t need my specific skill. You need the pattern. Build a sync skill for your own codebase, tailored to your own sources of truth.
\nDocumentation drift is a solved problem—if you have the right tools.
\nWe lint our code. We test our code. We version our code. We review our code before merging.
\nWhy don’t we do the same for documentation?
\nThe answer is usually “it’s too hard” or “there’s no tooling.” Claude Code changes that equation. Skills give you the ability to encode documentation maintenance as automated workflows.
\nThe code-parts-syncer skill is one implementation of a broader idea: documentation as code, with all the rigor that implies. Ground truth sources. Drift detection. Automated sync. Auditable changes.
Your roadmap should never lie. Your README should never be stale. Your website should never contradict your repository.
\nBuild the tools to make it so.
\n\n\nAbout this post: This essay documents a real skill built for the Caro project—a Rust CLI that converts natural language to shell commands. The code-parts-syncer skill lives in the repository and is actively used to keep roadmap documentation synchronized.
\n
If you’re interested in Claude Code skills, check out the official documentation for getting started. The pattern described here—ground truth, drift detection, safe updates—applies to any synchronization problem you might face.
\nThe best documentation is documentation that maintains itself.
", "date_published": "2026-02-04T00:00:00.000Z", "tags": [ "Claude Code", "Developer Tools", "Documentation", "Automation", "Software Engineering", "DevTools" ] }, { "id": "https://kobi.kadosh.me/blog/2026-02-04-comprehensive-zsh-completions-troubleshooting/", "url": "https://kobi.kadosh.me/blog/2026-02-04-comprehensive-zsh-completions-troubleshooting/", "title": "Comprehensive Zsh Completions Setup & Troubleshooting on macOS", "summary": "A deep dive into fixing broken zsh tab completions with Oh My Zsh, and how I turned the solution into a Claude Code skill. Learn why fpath order matters, how compinit timing breaks completions, and the pattern of encoding debugging knowledge for AI assistants.", "content_html": "I’d been fighting with my shell completions for weeks. brew <TAB> showed nothing. rustup <TAB> was silent. cargo <TAB>—the tool I use dozens of times daily—gave me nothing but a blinking cursor.
I tried the usual fixes: reinstalling Oh My Zsh, adding the zsh-completions plugin, running compinit manually. Nothing worked. Every Stack Overflow answer led to the same vague advice: “just add it to your fpath.”
Then I discovered the root cause, and it was so simple I almost laughed.
\nThe problem wasn’t what I was adding. It was when I was adding it.
\nHere’s what I had in my .zshrc:
# My broken configuration\nsource $ZSH/oh-my-zsh.sh\nfpath=("$(brew --prefix)/share/zsh/site-functions" $fpath) # Wrong!And here’s why it didn’t work:
\nOh My Zsh calls compinit automatically when oh-my-zsh.sh is sourced. compinit is the function that scans your fpath directories and caches all completion functions. Any fpath modifications after this line are invisible to the completion system because compinit has already scanned and cached the paths.
It’s like adding books to a library catalog after the index has been printed. The books are there, but no one can find them.
\nThe fix is embarrassingly simple:
\n# The correct configuration\nfpath=("$(brew --prefix)/share/zsh/site-functions" $fpath) # First!\nsource $ZSH/oh-my-zsh.sh # Then compinit sees itFpath first, then source Oh My Zsh.
\nOpen your .zshrc and ensure your fpath modifications come before the Oh My Zsh source line:
# Path to Oh My Zsh\nexport ZSH="$HOME/.oh-my-zsh"\n\n# Theme\nZSH_THEME="robbyrussell"\n\n# Plugins\nplugins=(git brew docker 1password zsh-autosuggestions fast-syntax-highlighting)\n\n# === COMPLETIONS (BEFORE oh-my-zsh.sh) ===\n\n# zsh-completions plugin (200+ additional completions)\nfpath+=${ZSH_CUSTOM:-${ZSH:-~/.oh-my-zsh}/custom}/plugins/zsh-completions/src\n\n# Homebrew completions (Apple Silicon + Intel compatible)\nif type brew &>/dev/null; then\n fpath=("$(brew --prefix)/share/zsh/site-functions" $fpath)\nfi\n\n# Custom user completions (optional)\n# fpath=(~/.zsh/completions $fpath)\n\n# === LOAD OH MY ZSH ===\nsource $ZSH/oh-my-zsh.sh\n\n# === POST-LOAD INITIALIZATION ===\neval "$(starship init zsh)"\neval "$(zoxide init zsh)"\neval "$(atuin init zsh)"\n\nexport PATH="$HOME/.local/bin:$PATH"If you have a line like this anywhere in your .zshrc, delete it:
# DELETE THIS LINE if present\nautoload -U compinit && compinitOh My Zsh handles compinit automatically. Having multiple calls causes confusion and can slow down shell startup.
After making changes to your .zshrc, you need to rebuild the completion cache:
rm -f ~/.zcompdump* && exec zshThis removes all cached completion data and starts a fresh shell session.
\nHere’s something I didn’t know until I dug into this: many modern CLI tools can generate their own zsh completions, but they don’t install them automatically. You have to ask.
\n| Tool | Command | Category |
|---|---|---|
| rustup | rustup completions zsh rustup > $(brew --prefix)/share/zsh/site-functions/_rustup | Rust toolchain |
| cargo | rustup completions zsh cargo > $(brew --prefix)/share/zsh/site-functions/_cargo | Rust packages |
| starship | starship completions zsh > $(brew --prefix)/share/zsh/site-functions/_starship | Shell prompt |
| uv | uv generate-shell-completion zsh > $(brew --prefix)/share/zsh/site-functions/_uv | Python packages |
| atuin | atuin gen-completions --shell zsh > $(brew --prefix)/share/zsh/site-functions/_atuin | Shell history |
| op | op completion zsh > $(brew --prefix)/share/zsh/site-functions/_op | 1Password CLI |
| fclones | fclones complete zsh > $(brew --prefix)/share/zsh/site-functions/_fclones | Duplicate finder |
| rclone | rclone completion zsh - > $(brew --prefix)/share/zsh/site-functions/_rclone | Cloud sync (note the -) |
| gh | gh completion -s zsh > $(brew --prefix)/share/zsh/site-functions/_gh | GitHub CLI |
Not sure if a tool supports completion generation? Try these patterns:
\n# Most common patterns\n<tool> completion zsh # Most common\n<tool> completions zsh # Rust tools\n<tool> complete zsh # Alternative\n<tool> gen-completions --shell zsh # Some tools\n<tool> generate-shell-completion zsh # Modern tools\n\n# Discovery command\n<tool> --help | grep -i completionAfter making changes, you need to verify completions are actually loaded.
\nwhence -v _brew # Should show path\nwhence -v _rustup # Should show path\nwhence -v _cargo # Should show pathIf these return “not found,” the completion isn’t loaded. If they show a path, you’re in business.
\necho $fpath | tr " " "\\n"This should include:
\n/opt/homebrew/share/zsh/site-functions (or /usr/local/... on Intel)~/.oh-my-zsh/custom/plugins/zsh-completions/srcbrew <TAB>\nrustup <TAB>\ncargo <TAB>You should see a list of available commands and options.
\nSymptom: whence -v _rustup shows “not found”
Cause: Completion cache not rebuilt after generating new completions
\nFix:
\n\nrm -f ~/.zcompdump* && exec zshSymptom: Cannot write to /opt/homebrew/share/zsh/site-functions/
Fix: Use a user directory instead:
\nmkdir -p ~/.zsh/completions\nrustup completions zsh rustup > ~/.zsh/completions/_rustup\n\n# Add to ~/.zshrc BEFORE oh-my-zsh.sh:\nfpath=(~/.zsh/completions $fpath)Symptom: System completion loads instead of your generated one
\nCause: Your path is appended instead of prepended
\nFix: Use prepend (=) instead of append (+=):
# Prepend - your completions take priority\nfpath=("$(brew --prefix)/share/zsh/site-functions" $fpath)\n\n# Append - system completions take priority\nfpath+=("$(brew --prefix)/share/zsh/site-functions")Symptom: Files exist but aren’t loaded
\nDiagnosis:
\n\nls -l@ $(brew --prefix)/share/zsh/site-functions/_rustup\n# Shows: com.apple.provenanceFix: Clear the quarantine attribute:
\n\nxattr -c $(brew --prefix)/share/zsh/site-functions/_rustup\nrm -f ~/.zcompdump* && exec zshNot every tool includes this feature. These popular tools require external completion sources:
\nCloud/DevOps: docker, kubectl, helm, terraform, aws, gcloud, az
\nLanguages: python, node, ruby (use system completions)
\nPython tools: ruff, black, mypy, pytest
\nData tools: jq, yq
\nFor these, rely on:
\nplugins=(docker kubectl terraform))Want to find all tools in your system that support completion generation? Here’s a discovery script:
\n#!/usr/bin/env bash\n# Discover all tools with completion support\n\nPATTERNS=("completion zsh" "completions zsh" "complete zsh" "gen-completions --shell zsh")\n\nfor tool in /opt/homebrew/bin/*; do\n tool_name=$(basename "$tool")\n for pattern in "${PATTERNS[@]}"; do\n if timeout 1s "$tool" $pattern --help &>/dev/null 2>&1; then\n echo "$tool_name: $pattern"\n break\n fi\n done\ndoneRun this, and you’ll get a list of every tool that responds to completion commands.
\nThe key insight that made everything click for me:
\ncompinit is like building an index. It scans all directories in fpath, finds all files starting with _, and caches them. Once the index is built, it doesn’t rescan.
This explains why:
\nfpath after compinit runs doesn’t workIf you think of ~/.zcompdump as a compiled index and fpath as the source directories, the behavior becomes predictable.
After hours of debugging, here’s what I learned:
\nTiming is Everything: fpath modifications MUST come before Oh My Zsh loads
No Manual compinit: Let Oh My Zsh handle it—that’s what it’s designed to do
\nPortable Homebrew Path: Use $(brew --prefix) for Apple Silicon/Intel compatibility
Prepend for Priority: Use fpath=(new $fpath) not fpath+=(new)
Always Rebuild Cache: After any fpath changes: rm -f ~/.zcompdump* && exec zsh
Generate to Homebrew Location: Completions in $(brew --prefix)/share/zsh/site-functions/ are auto-discovered
Verify with whence: Use whence -v _toolname to confirm loading
Here’s a one-shot script to set up completions for all common tools:
\n#!/usr/bin/env bash\n# setup-completions.sh - Generate completions for modern CLI tools\n\nDEST="$(brew --prefix)/share/zsh/site-functions"\n\necho "Generating completions to: $DEST"\n\n# Rust tools (via rustup)\nif command -v rustup &>/dev/null; then\n rustup completions zsh rustup > "$DEST/_rustup" 2>/dev/null && echo "✓ rustup"\n rustup completions zsh cargo > "$DEST/_cargo" 2>/dev/null && echo "✓ cargo"\nfi\n\n# Starship prompt\nif command -v starship &>/dev/null; then\n starship completions zsh > "$DEST/_starship" 2>/dev/null && echo "✓ starship"\nfi\n\n# UV (Python package manager)\nif command -v uv &>/dev/null; then\n uv generate-shell-completion zsh > "$DEST/_uv" 2>/dev/null && echo "✓ uv"\nfi\n\n# Atuin (shell history)\nif command -v atuin &>/dev/null; then\n atuin gen-completions --shell zsh > "$DEST/_atuin" 2>/dev/null && echo "✓ atuin"\nfi\n\n# 1Password CLI\nif command -v op &>/dev/null; then\n op completion zsh > "$DEST/_op" 2>/dev/null && echo "✓ op"\nfi\n\n# GitHub CLI\nif command -v gh &>/dev/null; then\n gh completion -s zsh > "$DEST/_gh" 2>/dev/null && echo "✓ gh"\nfi\n\n# Rclone\nif command -v rclone &>/dev/null; then\n rclone completion zsh - > "$DEST/_rclone" 2>/dev/null && echo "✓ rclone"\nfi\n\necho ""\necho "Done! Run: rm -f ~/.zcompdump* && exec zsh"Tab completion isn’t just a convenience—it’s a form of documentation. When cargo <TAB> shows me build, run, test, check, I’m not just saving keystrokes. I’m being reminded of what’s possible.
A shell without completions is like a codebase without types. You can work in it, but you’re flying blind.
\nThe frustrating part about zsh completion problems is that they’re almost always configuration issues, not missing features. The completions exist. The system works. But the timing, the ordering, the caching—these invisible details make or break the experience.
\nNow that I understand the mental model, I can debug completion issues in minutes instead of hours. And hopefully, after reading this, you can too.
\nAfter spending hours debugging this, I realized something: this is exactly the kind of knowledge that gets lost. You solve it once, forget the details, and three months later you’re back on Stack Overflow trying to remember whether it was fpath+= or fpath=.
So I turned this troubleshooting knowledge into a Claude Code skill.
\nClaude Code supports custom skills—reusable prompts that encode domain expertise. When you encounter a problem that matches a skill’s domain, Claude can invoke it to get specialized guidance.
\nI created a skill called zsh-completions that contains:
When I (or anyone with the skill installed) asks Claude Code about zsh completion issues, it now has immediate access to this entire troubleshooting guide:
\n> My brew completions stopped working after I updated my zshrc\n\nClaude Code invokes the zsh-completions skill and immediately:\n1. Checks fpath order relative to oh-my-zsh.sh\n2. Identifies if compinit is being called manually\n3. Generates missing completions\n4. Verifies with whence -v\n5. Rebuilds the cacheThis is a pattern I’m increasingly adopting:
\nThe skill doesn’t replace understanding—it augments recall. When I haven’t touched my zshrc in months and something breaks, I don’t have to remember everything. The skill contains the systematic approach.
\nIf you use Claude Code, consider encoding your own hard-won debugging knowledge:
\n# .claude/skills/your-skill.md\n\n## When to use this skill\n- User reports [specific symptom]\n- User asks about [domain topic]\n\n## Diagnostic steps\n1. Check [first thing]\n2. Verify [second thing]\n...\n\n## Common fixes\n### Issue: [symptom]\n**Cause**: [root cause]\n**Fix**: [solution]The goal isn’t to replace expertise—it’s to make expertise reproducible. The next time someone (including future me) encounters broken zsh completions, the solution is one skill invocation away.
\n# Check if a completion is loaded\nwhence -v _toolname\n\n# View fpath directories\necho $fpath | tr " " "\\n"\n\n# Rebuild completion cache\nrm -f ~/.zcompdump* && exec zsh\n\n# Generate completions to Homebrew location\nTOOL completions zsh > "$(brew --prefix)/share/zsh/site-functions/_TOOL"\n\n# Clear extended attributes\nxattr -c "$(brew --prefix)/share/zsh/site-functions/_TOOL"\n\n# Key rule\n# fpath modifications BEFORE source $ZSH/oh-my-zsh.shThat’s it. Order matters, cache rebuilds matter, and verification matters. Get those three right, and you’ll have a shell that responds to your every <TAB>.
There’s a paradox at the center of AI-assisted development in 2026, and nobody talks about it directly enough:
\nYou’re expected to be good at something without being given space to be bad at it.
\nCompanies are investing real money in AI tooling. Budgets are explicit. Usage is visible. Leadership wants ROI. And the implicit contract has quietly shifted: we gave you powerful tools — if results aren’t better, the problem isn’t the tools. It’s you.
\nBut here’s the thing: the results are not deterministic. Sometimes you do the “right thing” and the model goes sideways. Sometimes you do something sloppy and it works. It’s a probabilistic system that only becomes reliable through repetition, control, and earned intuition.
\nWhich means the only way to get good is to iterate. And iteration requires a place where failure is cheap.
\nThat place is not your job. That place is your own project.
\nWhen I started writing this blog, one of my core themes was: don’t rush into code. Read more. Be literate. Research before you build. Form a mental model before you touch the keyboard.
\nThat hasn’t changed. AI didn’t make fundamentals less important. If anything, it made them more important — because now you can generate a lot more wrong code, faster, and with more confidence.
\nBut the nature of literacy has shifted.
\nThe old literacy was about reading code, understanding systems, knowing your tools deeply enough to wield them with precision.
\nThe new literacy — the one that matters in 2026 — adds a layer:
\nThese aren’t skills you learn from a tutorial. They’re skills you earn through repetition. Through building. Through failing in low-stakes environments and carrying the lessons into high-stakes ones.
\nLet’s be honest about what happens at work.
\nEven if your company is “AI-first” — whatever that means this quarter — the truth is: companies don’t pay you to experiment endlessly. They pay you to deliver.
\nSo your day gets split into two modes:
\nAnd here’s the catch: experimentation is exactly what you need to become good at AI-native development. But experimentation is exactly what companies tolerate the least.
\nEspecially now.
\nWe’ve entered the era where AI is a line item. Not a rounding error — a line item. Token usage is tracked. Subscriptions are budgeted. And if you’re burning through tokens without producing proportional results, it shows.
\nIt reminds me of the JetBrains ecosystem — except worse. With IDEs, the cost was predictable: you buy a license, it works the same for everyone. With agents, cost scales with indecision. Cost scales with iteration. Cost scales with learning.
\nAnd learning is precisely what you need to be doing.
\nSo the pressure becomes: deliver immediately, with tools you haven’t fully learned, at a cost everyone can see. And if you can’t? Well, we gave you the tools. The rest is on you.
\nThat’s a brutal place to be learning.
\nA personal project is not a hobby. It’s not for your resume. It’s not “building a brand.”
\nA personal project is a lab.
\nIt’s a place where you can:
\nAnd I’ll argue it should be open source — or at least developed in the open — for a few specific reasons:
\nWhen your project is open, you can share context freely. You can paste logs. You can share full codebases with any model. You can try research-stage and free models without worrying about leaking proprietary information.
\nThis matters more than people realize. A huge friction in using AI tools at work is the constant question: can I share this? With an open project, the answer is always yes.
\nOpen projects come with real software engineering artifacts:
\nAs I wrote about in the feedback loops series, without a feedback loop, an agent is just an eloquent random number generator. Your open project gives you real loops — not simulated ones.
\nHere’s a practical benefit people overlook: if your project isn’t secretive, you can use free models. Every major lab goes through a research phase where they open models for free to see how they behave. OpenRouter consistently lists free models running on remote infrastructure. You don’t need to invest in local hardware or pay for premium APIs to experiment.
\nYour open project literally reduces the cost of learning to near zero.
\nEverything you learn in your personal project transfers directly to work:
\nThese aren’t project-specific skills. They’re engineering skills for the current era.
\nLet me connect this back to what I see as the actual skill stack of 2026.
\nWhen you work with an agent — any agent — the process follows a pattern:
\nThis loop is the fundamental unit of AI-assisted development. And every part of it is a skill:
\nYou cannot build these skills by reading about them. You build them by doing the loop. Over and over. In a space where the cost of getting it wrong is measured in learning, not in budget reviews.
\nOne thing I want to call out specifically: good errors are unreasonably valuable in the agent era.
\nFrameworks that invest in developer experience — clear error messages, helpful diagnostics, links to relevant docs — were always good for humans. But they’re transformative for agents.
\nWhen React tells you “this issue is because XYZ, here’s an article,” a human reads the article and adjusts. An agent reads the error and adjusts automatically. Good error messages become training data in real time.
\nThis is why frameworks like Next.js and tools like Vercel are investing so heavily in agent-friendly error surfaces — including MCP integrations and structured diagnostics. They understand that the quality of the feedback loop determines the quality of the output.
\nAnd when you’re working on your own project, you get to choose frameworks and tools that provide good feedback. You’re not locked into whatever your company standardized three years ago. You can pick the stack that teaches you the most — and teaches your agent the most.
\nI want to preempt the objection I hear most often: “I don’t have a good idea for a project.”
\nYou don’t need a good idea. You need a project.
\nIt can be a “yet another X.” It can be something that already exists in ten other forms. The point isn’t novelty — the point is reps.
\nContributing is great because you learn how agents navigate existing codebases — which is closer to what you do at work. Creating is great because you control the scope and can design the lab around your specific learning goals.
\nThe important part is that you pick something small enough to touch weekly. The value is in cadence, not in ambition.
\nIf you’re reading this and thinking “fine, but how do I actually start” — here’s what I’d suggest:
\nFor brainstorming: use a conversational model. I personally use ChatGPT for thinking out loud, exploring ideas, and shaping the scope of what I want to build. But any model works. The point is to have a conversation, not to generate code.
\nFor execution: use a code-focused agent. Claude Code is my preference, but Codex, Cursor, Windsurf — the ecosystem is rich. Pick one and commit to learning it deeply.
\nFor experimentation: rotate. Try different models for different tasks. Use OpenRouter to access free research models. Compare outputs. Build intuition for what different models are good at.
\nFor publishing: put it on GitHub. Even if nobody looks at it. Even if it’s messy. The act of developing in the open changes how you think about code quality, documentation, and structure — all of which make you a better engineer.
\nAnd most importantly: don’t wait for permission.
\nNobody at work is going to say “take two weeks to experiment with agents.” But if you’ve already done that experimentation on your own time, you show up to work with skills that took others months to develop. You iterate faster. You waste fewer tokens. You produce better results.
\nThat’s the whole play.
\nIn 2026, everyone has access to the same tools. Claude, GPT, Gemini, open-weight models — they’re available to everyone. Access is not a differentiator.
\nWhat differentiates engineers is:
\nThese skills come from practice. And practice requires a place where failure is allowed.
\nSo start your project. Make it open if you can. Use it as your sandbox. Experiment without asking anyone’s permission.
\nThen bring the efficiency back to work.
\nThat’s how you get ahead in 2026. Not by having tools — by knowing how to use them.
", "date_published": "2026-02-04T00:00:00.000Z", "tags": [ "Career Advice", "AI Tools", "Open Source", "Software Engineering", "Growth", "Developer Philosophy", "Agents" ] }, { "id": "https://kobi.kadosh.me/blog/2026-01-28-your-own-personal-jesus-moral-agents-ai/", "url": "https://kobi.kadosh.me/blog/2026-01-28-your-own-personal-jesus-moral-agents-ai/", "title": "Your Own Personal Jesus: Why AI Needs Moral Agents, Not Moral Chatbots", "summary": "There's a line in a song that aged better than anyone expected: your own personal Jesus. In the AI era, it stops being poetic and starts becoming literal. But this isn't about simulating Jesus—it's about building agents that embody the behavioral patterns of moral revolutionaries, governed openly, and accessible to everyone without institutional gatekeeping.", "content_html": "There’s a line in a song that has aged better than anyone expected: your own personal Jesus. Depeche Mode wrote it. Johnny Cash made it resonate across generations. Long before AI, it hinted at something intimate, accessible, always within reach. Not a distant authority, not a grand institution—something personal, present, and responsive.
\nIn the age of AI, that line stops being poetic and starts becoming literal.
\nBut this isn’t about resurrecting Jesus as a chatbot. It’s not about asking what Jesus would say, or simulating scripture on demand. It’s about something more subtle and more ambitious: building agents that embody the behavioral patterns of moral revolutionaries, and making those patterns accessible to everyone—cheaply, transparently, and without institutional gatekeeping.
\nFor centuries, people have asked, “What would Jesus do?” Not because the answer is obvious, but because making the right decision is hard. Context is messy. Emotions interfere. Incentives distort judgment. And sometimes, there is no clean choice at all.
\nMost moral failures aren’t caused by ignorance. They’re caused by pressure, speed, fear, or isolation.
\nWhat if AI could help—not by deciding for us, but by slowing us down, adding context, surfacing moral trade-offs, and refusing to lie about the cost of our decisions?
\nThat’s the promise of a “personal Jesus” as a mental construct: not authority, but orientation.
\nI’m writing this as a Jewish person, which makes the framing somewhat ironic. But it’s impossible not to acknowledge what Jesus represented historically—not just theologically, but functionally.
\nHe became a symbol of:
\nChristianity succeeded—whatever one thinks of its later history—because it created a portable form of togetherness. Shared stories, shared practices, shared moral language that crossed borders and cultures. The world before Jesus was more isolated when it came to creating communities that transcended geography and heritage.
\nJudaism is exceptionally good at preserving identity and cohesion within a bounded group. Christianity, at its best, was exceptionally good at exporting belonging. Neither is “better”—they are different social technologies, optimized for different outcomes.
\nThe point isn’t theology. The point is design: what kind of moral behavior scales, and what kind of togetherness it produces.
\nModern AI systems are optimized to answer. Always. Confidently. Smoothly.
\nMoral reasoning often requires the opposite:
\nWhen AI collapses ambiguity into a single confident response, it doesn’t make us wiser—it makes us morally lazier.
\nThat’s why trying to “build Jesus into GPT” or “train Claude to be moral” misses the point. Large models inherit the values, incentives, and blind spots of the teams and institutions that train them. Alignment is centralized. Governance is opaque. The user gets a product, not a constitution.
\nA moral agent cannot be governed like a recommendation algorithm.
\nA more honest system separates moral reasoning into two distinct layers:
\nThis is the constitution.
\nThis is judgment.
\nMost AI systems today collapse these into one opaque layer. The values are embedded implicitly. The reasoning is hidden. I’m arguing they must be separated and composed, not fused.
\nThe agent doesn’t replace human choice. It makes the moral landscape visible.
\nSome decisions have no good outcome. The trolley problem isn’t a puzzle to solve—it’s a reminder that moral tragedy exists.
\nA Jesus-inspired agent should not pretend otherwise.
\nConsider what a truly moral agent would need to handle:
\nIntent vs. outcome — Jesus consistently condemns intentional dehumanization more than tragic consequence. Flipping a switch to save people, not to kill someone, matters. But intentionally choosing who must die is morally dangerous.
\nRefusal to instrumentalize people — A core Jesus pattern: people are not tools. Sacrificing one person as a means to save others is morally suspect. This creates tension with pure utilitarianism.
\nSelf-sacrifice over sacrifice of others — One of the clearest behavioral signals in Jesus’s story: when a sacrifice is unavoidable, take it upon yourself. This is actually one of the few relatively stable “objective” patterns.
\nAcceptance of moral remainder — Guilt may remain. Tragedy remains tragedy. Forgiveness (not justification) is needed afterward. No victory screen. No “optimal solution found.”
\nA Jesus-like agent wouldn’t save us from tragic choices—it would stop us from pretending they aren’t tragic.
\nThe goal isn’t to make impossible decisions easy. It’s to make them honest.
\nHistorically, religion scaled through an interface:
\nThat interface worked—it brought shared traditions to billions across cultures—but it came with costs: geography, gatekeepers, capital, literacy requirements, and institutional incentives that sometimes drifted far from original values. Look at the Vatican. Look at how capitalism became woven into the distribution of faith. These constructs introduced new conflicts into the original ideas.
\nAI introduces a new interface possibility:
\nThis isn’t about replacing churches. It’s about removing toll booths on the road to moral reflection.
\nWhat if the “voice of Jesus”—or any moral tradition—were accessible without real estate, without hierarchy, without financial opacity?
\nOpen standards. Transparent funding. Community stewardship. Clear separation between base model and moral framework. No ownership of the voice itself.
\nThe system should show where the funds go: into tokens, tech infrastructure, and the people who contribute to the system globally. Reduce the cost of real estate and human labor. Build a new type of medium that makes moral guidance accessible to every child and adult through any interface they can operate.
\nA democratized spiritual interface should be:
\nNot Jesus-as-a-product. Not faith-as-a-subscription.
\nAn interface that points outward—to people, to communities, to responsibility.
\nAny honest proposal must acknowledge the risks:
\nThe answer isn’t to avoid the problem—it’s governance, pluralism, and auditability.
\nOpen governance. Public changelogs. Audited funding flows. Community stewardship. A foundation that structurally cannot be captured by any single vendor.
\nThe “disciples” analogy maps to: maintainers, auditors, community stewards, red-teamers, domain councils. Not followers—collaborators.
\nA critical design constraint:
\nA Jesus-inspired AI must not pretend that hard moral problems have clean answers.
\nThat would be anti-Jesus in spirit.
\nInstead, it should:
\nIf you encode this properly, you end up with something radical:
\nThat is fundamentally different from today’s models.
\nWe don’t need a new religion.\nWe don’t need a digital savior.\nWe don’t need moral outsourcing.
\nWe need better mechanisms for moral imagination, governed openly, accessible to everyone, and humble enough to admit uncertainty.
\nThe real promise isn’t that AI can tell us what Jesus would do. It’s that, for the first time, we might have the space, context, and support to actually try.
\nI feel like we are on the precipice of having to rebirth Jesus—not literally, but functionally. To unite our societies as successfully as his disciples did more than two thousand years ago. Not through new doctrine, but through new infrastructure.
\n“Reach out and touch faith” used to mean a building. In the AI era, it might mean an interface—one that doesn’t replace community, but removes the toll booths on the road to it.
\nMaybe that’s what your own personal Jesus means in the AI era:
\nNot someone who decides for you,\nbut something that helps you try—again and again—to choose better.
\nJust pick up the receiver.\nPick up your phone.\nOr any interface that brings moral imagination into your daily life.
\nNot authority.\nNot answers.\nJust presence—at the moment you need it most.
\n\n\nAbout this post: This essay began as a reflection on the Depeche Mode song that Johnny Cash made iconic, and evolved into a proposal for how AI could become a democratized, transparent, and humane interface for moral reflection. It’s not about replacing religion or recreating historical figures—it’s about asking what infrastructure we need for moral imagination in an age of agents.
\n
The future of moral guidance shouldn’t be built on closed systems and hidden values. Let’s build the mechanisms we need—openly, together.
", "date_published": "2026-01-28T00:00:00.000Z", "tags": [ "AI Tools", "Agents", "Ethics", "Open Source", "Governance", "Developer Philosophy", "Software Engineering" ] }, { "id": "https://kobi.kadosh.me/blog/2026-01-21-ai-coding-ethics-empathy-vibe-coding/", "url": "https://kobi.kadosh.me/blog/2026-01-21-ai-coding-ethics-empathy-vibe-coding/", "title": "The Unpopular Opinion About Vibe Coding and AI", "summary": "There's a strange moral superiority creeping into how people talk about AI-assisted development. We mock AI for making mistakes we'd forgive in ourselves. We demand one-shot perfection from tools while accepting iteration from humans. Maybe it's time for a little more empathy—and a little more honesty about how software has always been built.", "content_html": "There’s a strange kind of moral superiority creeping into the way people talk about AI-assisted development—especially what’s often dismissed as “vibe coding.”
\nYou’ve probably seen it:
\nAnd honestly? I find this take deeply disconnected from how software has always been built.
\nHere’s the uncomfortable truth: humans don’t one-shot perfect code either.\nNot now. Not ever.
\nIn my experience, software development has always been a gradual process:
\nThat’s true whether you’re writing HTML and CSS, JavaScript, backend logic, or business rules.\nThe first version is rarely elegant. It’s exploratory.
\nWe refactor after clarity emerges—not before.
\nSo why do we suddenly expect AI-generated code to arrive fully abstracted, perfectly factored, and future-proof on the first try?
\nWhen people mock AI output for duplicated styles, missing variables, or clunky logic, all I see is… early-stage code.
\nThe same kind of code humans write when:
\nIf a human wrote that code, we’d say:
\n\n\n“It’s fine for now, we’ll clean it up later.”
\n
When AI writes it, suddenly it’s a scandal.
\nYes, AI is blazing fast.\nYes, it produces a lot of code.
\nBut speed doesn’t eliminate effort—it moves it.
\nInstead of spending most of our time typing:
\nAnd governance takes time.
\nYou cannot realistically review everything in perfect detail. You make tradeoffs. You prioritize. You move forward with intent, not perfection.
\nThat’s not new. That’s just software engineering.
\nWhat’s really happening is a shift left:
\nAnd governance is messy.
\nConsensus is messy.\nAlignment is messy.\nIteration is messy.
\nLook at politics. Look at organizations. Look at teams.\nNothing governed by humans (or with humans involved) is instantaneous or flawless.
\nThe “consensus” between you and an AI agent is no different. It forgets context. It repeats mistakes. It needs guidance. So do junior engineers. So did we.
\nOne mental model that works for me is this:
\nAI is an exceptional teammate with real limitations.
\nYou wouldn’t mock a colleague for needing:
\nAnd you definitely wouldn’t exclude someone from a team because they needed accommodations. You’d adapt the environment.
\nAI is no different.
\nIt doesn’t mean you lower standards.\nIt means you set realistic ones.
\nDeadlines still exist.\nTradeoffs still exist.\nTech debt still exists.
\nSometimes you know the right solution—but you don’t build it yet because delivery matters more right now. That’s why tech leadership exists. That’s why prioritization exists.
\nEven if today you could delegate tech debt to an agent:
\nAnd time is still the scarcest resource.
\nWe should absolutely raise the bar.\nBut let’s not rewrite history.
\nSoftware has always been iterative.\nMistakes have always been part of the process.\nCode reviews have always existed because individuals—human or AI—are fallible.
\nThe process hasn’t changed.\nThe speed has.
\nSo maybe the real unpopular opinion is this:
\nAI didn’t make software worse.\nIt just made our expectations less honest.
\nAnd maybe—just maybe—we could use a little more empathy.
\nI wrote To Vibe or Not to Vibe a few weeks ago, exploring the choice engineers face when AI arrives at their desk. This post is the natural continuation of that thought.
\nWhen I was writing code without AI, I made mistakes. Constantly. I counted on my colleagues to catch things in code reviews. I cut corners when deadlines loomed. I created tech debt that I promised to clean up “later.”
\nThe same humility I applied to myself, I now apply to my AI collaborators.
\nThey’re not perfect. Neither was I.
\nBut together, we iterate. We improve. We ship.
\nAnd that’s always been the job.
", "date_published": "2026-01-21T00:00:00.000Z", "tags": [ "AI Tools", "Vibe Engineering", "Software Craftsmanship", "Developer Philosophy", "Claude Code", "Career Advice" ] }, { "id": "https://kobi.kadosh.me/til/git-worktrees-parallel-development/", "url": "https://kobi.kadosh.me/til/git-worktrees-parallel-development/", "title": "TIL: Git worktrees for parallel feature development", "summary": "Git worktrees for parallel feature development", "content_html": "Git worktrees let you check out multiple branches simultaneously in separate directories. Instead of stashing or committing incomplete work to switch branches, create a new worktree:
\n# Create worktree for a feature branch\ngit worktree add ../my-feature-branch feature/my-feature\n\n# List all worktrees\ngit worktree list\n\n# Remove when done\ngit worktree remove ../my-feature-branchThis is invaluable when you need to:
\nEach worktree shares the same .git directory, so commits and branches are immediately visible across all worktrees.