I’ve shipped three things into YEN over the last stretch that look unrelated on the surface — an agent evidence trail, a real port inspector, and full macOS scriptability. They are not unrelated. They are the same argument made three times.

Subscribe now

The argument is this: A terminal-first IDE is not a text editor with a terminal panel attached. It is the inverse. Start from the terminal and add the IDE capabilities that make the terminal safer, more contextual, and more trustworthy. Each of these three pieces is what that thesis actually looks like in code.

Here is what shipped, and why each one matters.

If an agent touches your repo then your terminal should have receipts.

The current AI coding market has a trust problem that gets ignored because the demos look productive. A tool opens an agent session, edits files, runs a few commands, and then leaves behind something that feels more like vibes than evidence. You are expected to merge based on the fact that an agent looked busy.

That is not good enough.

YEN now ships yen agents list, yen agents open, yen agents timeline, yen agents note, yen agents export, and yen agents templates as a bounded local-first surface around first-party adapter profiles like claude and codex.

yen agents open launches a session without pretending the adapter is more reliable than it is. If the binary is missing, the flow stays fail-open and drops to a normal shell. But when launch metadata is available, YEN records it: binary path, probe command, probe result, version, launch mode, fallback state, workspace identity, slot, branch, and dirty-state context. “The agent ran” is not one fact. There is a huge difference between “Claude launched normally in the expected workspace” and “the adapter was missing so the session really fell back to a shell.”

yen agents timeline is the readable history surface for that state. Workspace-scoped, source-tagged, filterable. Session events show as agent:<slot>. Human notes are human. Supervisor-style notes are **supervisor**. Internal events are system. Output renders as text or JSON, with stable schema metadata so downstream consumers don’t reverse-engineer a second unofficial contract.

The important part is not the filter set. The important part is that the timeline doesn’t stop at “agent opened” and “agent closed.” It also carries the latest linked IDE evidence that already exists elsewhere in YEN — local verify and test results, quality and workflow reports, merge-readiness snapshots, PR-review evidence, current-branch CI state, and the local build-watch snapshot — through one shared evidence model.

Status is explicit. The timeline and export surfaces share an evidenceStatus vocabulary: missing-report when the artifact does not exist, stale-report when it exists but is too old to trust, unverified when no meaningful proof exists yet, and exported-with-gaps when I can still produce a bundle but the bundle itself tells you what is missing instead of pretending completeness.

yen agents note is the missing human layer. Notes support lightweight templates for review approval, review rejection, handoff for review, and handoff for merge. They can validate that a note is actually bound to the right session or slot, so a human approval becomes a recorded part of the handoff instead of a sentence someone remembers writing in Slack ten minutes earlier.

yen agents export turns the local session history into a handoff bundle in Markdown or JSON: timeline, approvals, handoffs, workspace-keyed repo context, risk summary, adapter metadata, explicit evidence gaps, linked IDE evidence references. It does not invent a second review namespace — it reuses the same truth YEN already uses for verification, workflow, merge-readiness, and PR review.

The whole surface stays local-first. Artifacts are local. Timeline is local. Notes are local. Export is local. Archive is opt-in. Retention is short by default at 7 days. Redaction happens before saved artifacts are written. And if the capture path breaks, YEN fails open and preserves the terminal session rather than pretending the evidence story is stronger than it is.

That is what I mean by receipts.

Your terminal should know what’s running on every port.

You are running Next.js on port 3000. Django on 8000. Postgres in Docker on 5432. Then something mysterious claims port 5000 and you have no idea what it is.

The usual answer is some combination of lsof, ps, and docker ps run separately, parsed manually, and forgotten immediately. Maybe you install a third-party tool that needs Node 18+ just to show you a table.

YEN already had yen ide ports as a basic lsof dump. Now it is a full port inspection surface:

bash
yen ide ports              # Dev ports with framework detection
yen ide ports --all        # Everything, including system services
yen ide ports 3000         # Deep dive on one port + optional kill
yen ide ports ps           # All dev processes with CPU / memory
yen ide ports clean        # Find and kill orphaned / zombie processes
yen ide ports watch        # Live monitor, 2-second polling

Every subcommand supports --json for scripting and --yes to skip confirmation prompts. The default view is dev-focused — system services like ControlCenter and rapportd get filtered out unless you pass --all.

Framework detection runs in three tiers. First, process name and command-line pattern matching — python3 manage.py runserver is Django, bun run next dev is Next.js running on Bun. Twenty-plus frameworks covered: Next.js, Vite, Django, Flask, Uvicorn, Gunicorn, Rails, Spring, Supabase, Turso, Caddy, Traefik, Zig, Rust, Go, PHP, Deno, Bun, Node, Java, Ruby. Second, working-directory inspection — resolve each process’s cwd via lsof, walk up to find the project root by looking for package.json, go.mod, Cargo.toml, or pyproject.toml, then check for framework config files. Third, Docker container mapping — cross-reference docker ps to pull container names so Postgres, Redis, and nginx get named correctly instead of showing up as a mysterious docker-proxy process.

The result actually tells you what is going on:

COMMAND     PID      PORT     FRAMEWORK   UPTIME   CONTAINER   BIND
node        41023    3000     Next.js     2h 14m   —           *:3000
python3     41156    8000     Django      1h 03m   —           127.0.0.1:8000
docker-pr   41289    5432     PostgreSQL  4h 31m   myapp-db    *:5432
bun         41302    3100     Vite        22m 08s  —           *:3100

yen ide ports 3000 shows everything about the process on that port — PID, user, CPU, memory, working directory, project root, git branch — then asks if you want to kill it. SIGTERM first, not SIGKILL, with a 2-second wait. Every kill gets logged to YEN’s IDE timeline because a terminal-first IDE should keep receipts on destructive actions.

yen ide ports clean finds two kinds of problems: orphaned dev servers whose parent died and got reparented to PID 1, intersected with a dev-process allowlist so we don’t flag system daemons like httpd or cupsd as false positives; and zombie processes still holding a port. Both get listed with reasons, and you can batch-kill them with one confirmation prompt.

yen ide ports watch polls every 2 seconds and reports opened and closed ports with timestamps, with trap cleanup on Ctrl + C, SIGTERM, or SIGHUP so the temp file doesn’t leak.

About 1,300 lines of bash and Python, 8 regression tests, no new dependencies — just lsof, ps, and docker stitched together into one terminal-native view.

Your terminal should be scriptable.

Most terminals are black boxes. You launch them. Maybe you pass a command. That’s it.

The problem is that developers have workflows — not commands. “Open this project” means: navigate to the repo, split the window, start the test runner on the right, start the dev server on the left. Doing that manually every time is fine once. It’s friction at scale.

The standard answer in the macOS world is AppleScript. Terminals have historically been bad at it because they are fundamentally interactive processes — you can open a window, but can you address a specific surface? Can you tell a pane what to run?

YEN has a solution for this now. It ships a branded .sdef. Open Script Editor, find YEN.app in the Library, and browse the dictionary. The current surface is deliberate and minimal:

- new window — opens a terminal window
- new tab — opens a tab in the frontmost window
- split — splits the active surface
- surface configuration — lets you configure an individual surface
- Terminal objects have `pid` and `tty` properties

YEN-native features — layout presets, scratchpad, tab sidebar, the PR review workspace — are not exposed through AppleScript `perform action`. The `Cmd + Option + 1-0` layout presets are intentionally not cloned into a second layout source of truth. Compose three-column layouts with `new tab` + `split` calls rather than replicating preset logic externally.

The App Intents surface shares the same canonical action-string catalog as AppleScript, so Shortcuts.app, Focus Filters, and Siri Shortcuts compose with the same YEN actions.

Why these three belong together.

Each of these surfaces is a different cut at the same idea.

Agent receipts say: If a session changed the repo, the terminal should be able to answer “what exactly happened?” without asking you to trust a second system. The receipts stay close to the repo, the terminal, and the review flow you are already in.

Port inspection says: if a process is running, the terminal should be able to tell you what it is, where it lives, and let you kill it safely. With logging. Because a terminal-first IDE should keep receipts on destructive actions, even small ones.

Scriptability says: if your workflow has shape — open the project, split the panes, start the test runner — the terminal should let you encode that shape. Not as a brittle command sequence, but as something macOS Automation can address by surface, by `pid`, by `tty`.

In each case, the question is the same. Should this thing live in a separate hosted dashboard, a third-party CLI, or a JavaScript wrapper? Or should it live in the terminal you are already in?

I keep landing on the second answer. The terminal is where commands actually run, where repo state is visible, where output becomes real, where agents either prove their work or don’t. If that is true, then trust, observability, and scriptability belong there too — not bolted on, not in a browser tab, not behind a hosted account.

That is the bet. Not bigger spectacle. Better receipts.

— 8

I added a browser preview to YEN. That sentence can sound bigger than it is, so I want to be precise about it. YEN is not becoming a browser. It is not shipping Chromium. It is not turning into Electron. Eww.

Subscribe now

It is not trying to replace Safari, Arc, Chrome, Firefox, or whatever else you already use for the open web. What I shipped is much narrower and much more useful for the kind of product YEN is trying to be:

A native WebKit preview surface, launched from the command palette or yen web, for docs, HTTPS pages, and local development servers.

It is a standard window by default, with an explicit split when you ask for one. Yay.

Why Does a Terminal Need This?

I keep coming back to the same idea with YEN: The terminal-first IDE is not a text editor with a terminal panel attached. It is the reverse. Start from the terminal, then add the pieces that make terminal work more direct, more trustworthy, and less scattered.

A browser preview fits that idea, but only if it stays disciplined. Developers constantly bounce between the terminal and the browser:

• Documentation.

• Localhost servers.

• Preview pages.

• Generated docs.

• Release notes.

• Internal references.

That context switch is not always bad. The full browser is the right place for most browsing. But there is a class of terminal-adjacent web content where leaving the terminal flow feels heavier than the task deserves.

I do not want to open a whole browser tab just to check a local docs page. I do not want an embedded browser engine bundled into the terminal just because a preview window is useful. I do not want terminal links silently captured before the behavior has earned trust.

So the starting point is deliberately small: Open Cmd + Shift + P, type Browser, press Enter. Done and done.

From there, you can type an HTTPS URL, open a localhost or loopback development server, go back, go forward, reload, stop loading, or hand the current page to your default browser.

If you use yen web open, the command goes through the same policy. If you choose Browser Split or yen web open --split, YEN mounts the same preview beside the terminal in an app-owned split. That is it. That is the point.

Native First, not Browser-Engine First.

The easy way to add a browser-shaped feature is to ship a browser engine. That is also the expensive way.

Chromium-class runtimes bring subprocesses, GPU behavior, sandboxing complexity, packaging weight, security update pressure, and a huge amount of product gravity. Once you carry that runtime, the feature stops feeling like a preview window and starts pulling the whole app toward becoming a browser shell.

That is not YEN.

YEN already has a hard native-first rule: Before adding a dependency or vendored binary, check whether macOS already provides the right API. For this feature, macOS does. The preview uses Apple’s WebKit stack:

• WKWebView

• WKWebViewConfiguration

• WKNavigationDelegate

• WKUIDelegate

• WKWebsiteDataStore.nonPersistent

• NSWorkspace.open

That is the right shape for a Mac app. It keeps the feature small, native, reversible, and understandable. It also keeps the terminal engine out of the story. No Metal renderer changes. No swap-chain changes. No renderer-owned terminal-pane integration. No default-on hyperlink interception. No production data changes. No release artifact format changes. No vendored browser runtime.

Nothing that will get in the way or bloat the app.

The default browser preview is an app-owned utility window. The optional split is app-owned too. Neither one is a new foundation for the terminal engine.

The Trust Boundary is the URL Field

The interesting part of this feature is not the toolbar. The interesting part is the policy.

If I put a web view inside a terminal, I need to be clear about what it is allowed to open.

The current rule is simple: HTTPS pages can load. Loopback HTTP can load.

But external schemes like mailto: and tel: get handed off to macOS from explicit top-level opens. Unsafe or surprising schemes get blocked.

And, of course, it’s private by default.

The shipped browser uses a non-persistent WebKit data store.

That means YEN is not trying to become your browser profile. It is not importing Safari cookies. It is not keeping a long-lived browsing history. It is not turning a preview window into another place where state silently accumulates.

That choice is partly about privacy. It is also about reversibility.

If a future expansion does not earn its place, I want to remove that expansion without leaving a weird pile of browser state behind.

That is one of the standards I keep trying to apply across YEN: New surfaces should stay easy to revert until they prove they belong.

Persistent browsing state might make sense later for a specific workflow. If it does, I want that to be a deliberate decision with a clear storage policy, a clear user control, and a clear rollback path.

For now, non-persistent is the right default.

How and Why Does This Fit for YEN?

The terminal is already where the work starts. You run the dev server there. You see the port there. You read the failing command there. You open the command palette there. You jump into docs there.

Cool.

The browser preview is useful because it respects that center of gravity. It gives YEN a small native window or explicit split for web context without asking the terminal to become a browser, and without asking the browser to become the IDE.

YEN should absorb useful developer workflow pieces only when they make terminal work feel more coherent. The file browser made sense because navigating files is part of terminal work.

The command palette made sense because discovery is part of terminal work. The IDE workflows made sense because trust, verification, review, and project context are part of terminal work. The browser preview makes sense only if it stays in that same category: A focused preview for terminal-adjacent web context.

Not the open web as a lifestyle. Not browser automation. Not a Chromium distribution in disguise. Just a small native bridge between the terminal and the pages developers actually need while working.

The best part is how little had to change. The core browser code lives in one isolated macOS feature folder. The command palette has two browser actions: Browser and Browser Split. The CLI and Settings integrations are narrow. The URL policy is a pure testable layer. The WebKit configuration is created up front.

The external handoff path checks whether macOS accepted the URL instead of pretending every handoff worked. That is the shape I want more YEN features to have.

Small surface. Clear policy. Native API. Easy rollback. Tests around the weird edges.

The Bigger Point

I think terminal products keep getting pulled in two directions.

One direction says the terminal should stay dumb forever. The other says the terminal should become a browser-shaped AI workspace with a shell somewhere inside it.

I do not like either answer.

The terminal should get smarter, but it should get smarter in a terminal-native way. That means native surfaces where native surfaces make sense. Local-first state where local-first state makes sense.

Explicit trust boundaries. No surprise capture. No giant runtime unless it truly earns its cost. No feature expansion without a keep-or-revert checkpoint. The browser preview is a small example of that philosophy.

It is not the centerpiece of YEN. It is not a pivot. It is just a useful native surface that lets the terminal-first workflow breathe a little more easily.

And sometimes that is exactly the kind of feature a product needs.

— 8

I just removed three whole product surfaces from YEN:

1. Chat

2. Mail

3. Calendar

This makes me a bit sad but it was as important of an update as many others in the last few months. Focus is a feature and it’s hard to do.

Subscribe now

This is, of course, not the usual kind of release story. Most product writing is about what got added. This one is about what I decided not to keep carrying.

I think that matters, because one of the easiest ways to make a product worse is to confuse activity with progress. Shipping more things is easy to celebrate. Carrying more things forever is the part that gets expensive.

And it’s really easy to add features these days which means that the most important decisions is what you decide to not build and ship.

You see, for a while, YEN had a broader shape. It was not just a terminal-first IDE. It also had a community chat surface, a mail client, and a calendar client living inside the same product. At one level, that was interesting. It proved that the terminal could hold more of a working environment than people usually assume.

But there is a point where an interesting proof stops being the right product.

The point is that I do not want YEN to become one more app that keeps every experiment alive because removing it would feel like admitting something. I would rather be honest about what is actually central.

The central thing is the terminal-first IDE.

That means:

• Native terminal quality

• Trustworthy local workflows

• File and project navigation

• Build and review tooling

• Command surfaces that make terminal work faster without making it feel fake

Chat, mail, and calendar were not strengthening that center anymore. They were competing with it. And, to be honest, not many folks were using them but that’s also because we’re still pretty small (and growing).

The deeper problem is surface area. A product feature is not just a button or a command. It is an ongoing obligation. Chat meant backend tables, storage rules, attachment handling, proxy paths, privacy assumptions, moderation-adjacent questions, cleanup rules, and public documentation that had to stay true.

Mail and calendar meant OAuth flows, keychain assumptions, callback routes, local state contracts, desktop integration residue, notification semantics, legal/privacy copy, and recovery behavior for systems YEN did not control.

Even when those features are “done,” they are not done. They keep charging rent:

• Engineering attention

• Test coverage

• Release anxiety

• Documentation maintenance

• Privacy and legal review

• Restore-path complexity during unrelated refactors

That is the part people underestimate and certainly not something that anyone non-technical would even think about (although those folks are probably not using YEN).

A small feature that touches auth, network boundaries, notifications, storage, and public docs is not small. It is a permanent tax. No one likes taxes. Taxes suck.

But the the non-obvious gain is trust.

I think product focus is often described too softly, like it is mostly an aesthetic preference. It is not. Focus improves trust. Every feature I remove is one less thing that can silently drift out of sync. One less thing that can break on release day. One less public claim that can become false. One less background system whose edge cases I have to remember when I am changing something that should have been unrelated.

That matters a lot for a terminal-first IDE, because this kind of product only works if people believe the boundaries are legible.

Subtraction is part of honesty. YEN does not get stronger by collecting adjacent ideas forever. It gets stronger by becoming more exact about what it is for.

The best version of YEN is not “the app that also does everything else.” It is the app where the terminal is the center of gravity, the desktop integration feels native, the workflows are trustworthy, and the extra surface area earns its place.

Chat, mail, and calendar stopped earning their place. So I removed them. I think more products should do that.

There is a lot of pressure in software to act like every shipped feature is sacred. I do not buy that. Sometimes the highest-leverage feature is the one you stop shipping. Sometimes the most user-respecting thing you can do is narrow the promise. Sometimes focus is not what remains after product strategy.

Focus is the product strategy. That is what this cleanup was really about.

YEN is better when it is more itself, as it has been and as it should be. Authenticity. Truthfulness. Clarity. Focus. The result? Even greater productivity.

That’s the point.

— 8

Every other Mac app in my life has trained my hands the same way. Cmd + C copies. Cmd + V pastes. If a shortcut needs a paragraph of explanation before it makes sense, the shortcut is probably wrong.

Subscribe now

I ran into exactly that problem in YEN. Ctrl + V could still move clipboard data through the terminal stack, but Cmd + V did not behave like a real Mac app. That sounds small until you remember what YEN is trying to be.

Well, this now works in v1.036.

I have been building YEN around a simple thesis: The terminal-first IDE should feel more like a real desktop app, not less. If I am asking people to live in the terminal for IDE flows and agent work and more, then, I do not get to shrug when one of the most basic desktop behaviors feels off.

So, why doesn’t upstream libghostty do this? Because it’s a terminal emulator while YEN is a terminal -first IDE with path-oriented workflows around Codex, Claude, local tools, and file-aware commands.

And so that’s fine since it’s behaving like any normal, ordinary terminal paste behavior for the kinds of payloads a terminal naturally understands. But, I wanted just a bit more than that.

That is an important distinction. This is not “libghostty forgot paste” or anything funky like that; it’s just that we have a very different product policy.

What Changed and Why This Matters

I fixed the hotkey at the right layer first.

Instead of asking “is this the Cmd + * keystroke shape?” YEN now asks “what menu action did YEN resolve this event to?” If the resolved action is paste: or pasteSelection:, and the relevant clipboard has contents, the surface routes through AppKit the way a native Mac app should.

That matters because it avoids stealing unrelated shortcuts.

If someone remaps a binding or another YEN command happens to share a similar keystroke shape, the bypass stays closed unless the resolved menu action is actually a paste action. That is the difference between a shortcut hack and a native fix.

So, why does this matter? Well, I think a lot of terminal work gets framed as performance, rendering, tabs, themes, or shell integration. All of that matters.

But the terminal-first IDE also has to solve a quieter problem: If I am asking you to live in the terminal for more of your day, the terminal has to stop feeling like the place where desktop behavior goes to die.

That means tiny things matter.

Cmd + V should mean paste. And now it behaves like it should on macOS.

And if the terminal is going to be the IDE, that is the level of care it has to absorb.

— 8

Well… we’ve done it, folks. YEN is officially v1.0! Whoot. 🎉

Subscribe now

I do not use version numbers as marketing confetti, though. I mean, v1.000 — or how I’ve been numbering it — is not me pretending the work is done. It is me saying the thesis is real now. The product I wanted to build is no longer hypothetical. It is in the repo, in the shipped app, in the release harness, in the native macOS surfaces, and in the command surface I use every day.

I use YEN to build YEN, a fun little personal project — built on top of libghostty — that a lot of folks have started to use. For that, I am super grateful.

The Thesis.

Most IDEs are text editors that bolted on a terminal panel. The editor gets the architecture. The terminal gets a rectangle near the bottom of the window. The editor gets search, code intelligence, review, migration, workflow automation, collaboration, and the language about focus and speed. The terminal gets treated like a utility room.

I wanted the opposite.

Because the terminal is where code meets reality. It is where builds fail, services restart, migrations run, diagnostics become useful, containers get launched, review comments turn into actions, and dangerous commands should feel dangerous before you press the “Enter” key.

YEN starts with a fast native terminal on macOS and layers IDE capability around that terminal-first workflow. Keep the core local-first. Use native APIs where they are genuinely better. Stay in the terminal unless a richer native surface is actually justified.

That is the whole product in one paragraph.

What v1.0 Actually Ships.

This is not a terminal with a roadmap attached. It is already a broad terminal-first system. The new IDE layer matters most here.

YEN now ships project detection, trusted environment loading, local LSP lifecycle and diagnostics, AST fallback, universal project search, verification bundles, approval gates for risky commands, workflow execution, PR review tooling, terminal sharing, local devcontainer control, deterministic VS Code inventory and import, and native macOS PR review and merge-conflict workspaces launched from the command palette. That is the point where “terminal-first IDE” stopped being a slogan and became a product characteristic.

But v1.0 is not only an IDE story. It is also a story about making the terminal feel like an environment instead of a blank shell. YEN ships a built-in file browser, command palette, tab sidebar, scratchpad, split layout presets, split labels, screenshot tooling, curated themes, keyboard remapping with conflict detection, managed notification sounds, bundled CLI tools, weather, and a pile of native macOS utility surfaces that make the product feel inhabited on first launch instead of empty.

It also ships communication where most terminals would not even try. Chat, mail, and calendar are all separate Go TUIs. Mail and calendar use OAuth with PKCE and store tokens in the macOS keychain. Chat runs through mediated YEN-owned API surfaces, binds identity server-side, and keeps anonymous direct database access intentionally closed. None of that exists as novelty for novelty’s sake. It exists because I think the terminal can hold more of a working environment than most tools assume, especially when it removes the lazy default of making you tab back out to a web app for a workflow you were already in the middle of.

The Terminal-First IDE Part.

The newest layer is the one I cared about most going into this milestone. I did not want YEN to say “terminal-first” and then quietly shove the serious workflows into a browser pane, a cloud dashboard, or a second application model. I wanted the terminal to stay central.

That is why the IDE layer stays honest about what it is doing. If YEN is using live LSP, it says so. If it falls back to AST, it says so. If a project has not been trusted, it says so. If a share session exists, it is explicit. If a command is risky, the gate should behave like it. The command palette is not just a launcher any more. It is a terminal-native IDE entry point. The native macOS review and merge-conflict windows are not an escape hatch away from the terminal. They are closer-to-the-metal extensions of the same workflow.

That distinction matters to me. I am not trying to cosplay as a giant editor suite. I am trying to build an IDE around the place where engineers already end up doing the real work.

The Technical Patterns That Made It Work.

The most important pattern in YEN is vendor, do not fork. The upstream terminal engine stays mirrored as an exact upstream tree. YEN-specific behavior lives in overlays and integration layers. The same philosophy shows up in bundled tools. If an upstream project already does the job well, I would rather integrate it carefully than reinvent it badly just to preserve some fantasy of purity.

The second pattern is native-first. If macOS already has the right API, I want to use the OS instead of shipping a giant dependency. That is why YEN uses native helpers for video, PDF, and SVG preview paths, native keychain handling, native notification delivery, native screenshot flows, and native AppKit utility windows.

It is also why the bundle shed a ridiculous amount of weight: Replacing ffmpeg, poppler, and 7zip-style baggage with native helpers and system tooling saved about 258.8 MB compared with the heavier alternative. That kind of decision is not glamorous, but it changes what the product feels like to install, ship, and maintain.

The third pattern is trust before convenience. I do not want silent authority. Project trust, environment trust, LSP trust, sharing trust, workflow trust, and release verification all exist because I would rather add a little ceremony than hide risk behind a friendly button label.

The Native macOS Bet.

YEN is intentionally macOS-first. That is not an accident and it is not a temporary inconvenience I keep apologizing for. It is the product bet.

The clearest example is speech-to-text. Press Option + Space and YEN can capture audio, transcribe it on-device using Apple’s speech stack, show live state in a floating overlay, recover cleanly when permissions or local speech assets are missing, and insert the result back into the active context.

That works inside YEN and across other macOS apps. The same native bet shows up in settings, preview helpers, notifications, launch-at-login behavior, keychain-backed auth, screenshot tooling, and the command-palette-driven utility surfaces.

The trade-off is obvious. I do not get to claim “runs everywhere.” The upside is just as obvious. I get depth instead of pretending that a lowest-common-denominator abstraction is enough.

What the Repo Says.

I did not want this post to hand-wave the effort. The numbers below are the repo snapshot as of March 29, 2026:

• Start: November 6, 2025

• Commits: 4,616

• Time: 144 days

• Average: 32.06 commits per day

• Lines of Code: 136,000

• Contributors: 1

And yes, the contributor count is the part that still hits me emotionally. There is no hidden engineering org behind this post. It is just me, the repo, the build system — which is cool af — and the users, and a stupid number of tiny decisions stacked on top of each other until they started to look like a product.

But I made it.

The Scope Was Bigger Than One App.

YEN stopped being "one app" a while ago. The repo includes the marketing site, the release metadata surface, the desktop app, the overlay system, build and release automation, the CLI entrypoint, chat, mail, calendar, shared auth packages, database migrations, docs, tests, and a fairly serious asset pipeline.

Yeah, it’s a lot.

That breadth is exactly why I keep describing YEN as a system. The desktop app matters, obviously, but the product is also the release harness, the signing discipline, the docs, the migration logic, the auth model, the sound-pack delivery, the updater, the whitepaper, and the public website that stays in sync with what ships.

I’m pretty fucking proud of it all, to be honest.

What I Learned Building This Alone.

A few thoughts on this topic, while we’re here:

1. Scope is survivable if the system is honest. A repo this broad only stays manageable if the build fails loudly, the trust model stays explicit, the docs remain current enough to lean on, and the release path is deterministic enough that I can sleep after a ship.

2. Shipping teaches faster than theorizing. I could have spent another six months polishing a grand story about terminal-first computing. That would have been a mistake. The actual product got better because I shipped, watched where friction showed up, fixed it, and repeated that process an embarrassing number of times.

3. Documentation is leverage. The 15k lines of docs in this repo are not decoration. They are a force multiplier. Once a project gets this broad, undocumented decisions become a tax on every future change, especially when the future developer is still just me.

4. Taste matters. I do not buy the idea that taste is fluff. Taste is what decides whether a shortcut belongs, whether a command palette feels honest, whether a panel deserves to exist, whether a feature should stay terminal-native, whether a native window is warranted, and whether a clever abstraction is actually making the product worse.

5. Solo does not mean small. Solo still means constrained. It still means trade-offs. It still means there are things I cannot do yet. But it does not have to mean shallow. With the right architecture, automation, documentation habits, and release discipline, a solo developer can build something wide and deep without pretending it is small.

This has been a very fun trip and one that’s just beginning since it’s a daily tool that I need to use to feed and clothe myself. So, I’ll be here for a while, cranking on YEN every single day because I just really, really, really like it.

YEN isn’t just a fast terminal. It is not just a speech-to-text experiment. It is not just a file browser wrapper. It is not just a fun macOS utility surface. It is a terminal-first IDE platform with a clear thesis, a local-first core, explicit trust boundaries, a real shipped IDE layer, native macOS depth, bundled first-launch usefulness, and a release system that can keep up with the ambition of the product.

And that’s what the milestone marks.

Not perfection.

Not completion.

Clarity.

What Comes Next.

There is still a lot left to do. There is more IDE depth to build, more workflow hardening to do, more collaboration and review ergonomics to refine, more polish to add to the native surfaces, and more places where trust, diagnostics, and context can get sharper.

But I feel very differently about the project now than I did a few months ago. The shape is clear. The identity is clear. The system can carry the ambition now.

If you have been following along, testing builds, reading posts, reporting bugs, or just quietly paying attention while I kept shipping into the void, thank you. This milestone has my name on it in git history, but no product gets here in a vacuum. The feedback loops mattered. The curiosity mattered. The pressure to keep the quality bar high mattered. It helps. I’m grateful.

YEN v1.0 is here, and I’m just getting started.

— 8

There’s a small feature in the latest YEN release that I’m weirdly proud of, and it took me longer to design than to build: The background image and wallpaper scope toggle.

Subscribe now

This is the second part of the, well, first part about wallpapers.

The Question Nobody Asks but Everyone Has

When you set a background image in YEN, what does “background” mean?

If you have three splits open — one running tests, one tailing logs, one with your editor — does the image live behind all of them? Just the focused split? The whole window? If you open a new tab, does that tab get the image too?

This is one of those settings that feels obvious until you try to define it.

I went through a few different mental models before landing on the one we ship:

1. Global (all windows) — The image is a wallpaper. It’s yours, not the terminal’s. Wherever YEN renders, the image is there. Good for people who set one image and forget it.

2. Per-tab — The image belongs to the current tab’s context. Switch tabs, different look. Split panes within a tab share the same image. This is the default because it maps cleanly to how most people think about “what I’m working on right now.”

3. Per-split — Maximum granularity. Each pane is its own visual context. You can have a dark ocean render behind your SSH session and a warm linen texture behind your local dev split. This is for people who want their terminal to reflect what each pane is doing.

But, ultimately I wanted to keep it simple. Here’s the experience:

Start with a blank canvas, your Terminal. And then you can add an image:

Or you can make the images per split:

Pretty neat and as I’ve said before, it makes it feel so much more personal. And that’s the update folks. Enjoy.

— 8

I built a background image upload that just makes it feel more like your own personal space. It’s available directly via the Settings Panel and there you go, magic.

Subscribe now

It’s stored locally in Application Support and is repeated through splits:

The Buster Sword is the GOAT:

Have fun with it! There’s also a setting I’m building which will make it either work in each and every splits — repeating, of course — or to just be a single background across all splits. I’ll have that posted in the next release soon.

— 8

The first IDE post was about ambition. The second one was about cohesion. This one is about proof (or the burden of proof). Because if you can’t trust your Terminal and IDE to do what you want, then, what’s the point?

It has to work. Or it doesn’t.

Subscribe now

You see, a Terminal-first IDE cannot stop at having a lot of commands, and it cannot stop at having those commands point at each other in mostly sensible ways. At some point the product has to answer the question that matters more than all of that: When it tells me something about my repo, should I believe it?

That is the standard that anyone should hold any Terminal to and it’s the standard that I hold to the work that I do for this tool and our growing community of users.

I do not want an IDE that performs confidence; I want one that can defend its claims. I want it to be explicit about what it knows, what it does not know, which local facts produced the answer, where the boundary of authority ends, and what has to stay a human judgment call.

If the terminal is going to remain the center of gravity, it needs to feel less like a loose toolkit and more like a system with a memory, a vocabulary, and a conscience.

That is what this phase of YEN has been about and what is necessary before I feel comfortable giving this project a real v1.000 stamp.

Readiness Has to Reuse the Evidence Model

The clearest example is yen ide merge-readiness.

Before a branch is ready, I usually already have the evidence somewhere. The repo has a working tree state.

yen ide doctor knows whether the workspace is healthy.

yen ide trust status knows whether the repo has been explicitly trusted.

yen ide verify status knows whether readiness and security gates have actually run.

Git knows how large the diff is and which files look risky. The local timeline already knows what the recent gates and review surfaces have done. Sometimes GitHub metadata is available too.

The problem was never missing evidence. The problem was fragmentation.

Once a repo gets large enough, the cost of answering a simple question like “is this safe to review?” is no longer the cost of one command. It is the cost of rebuilding the same mental model from half a dozen surfaces every single time. That is exactly the kind of work I think an IDE should eliminate.

What I did not want was the obvious fake solution.

I did not want a separate readiness database. I did not want a second approval workflow. I did not want a new trust vocabulary that would immediately start drifting from doctor, verify, review, and timeline. That is how tools become bureaucratic. They solve a visibility problem by creating a state problem.

So merge-readiness is not another authority surface. It is an aggregation surface over the evidence model that already exists.

It reads the current doctor state, trust summary, verify readiness and security snapshots, git diff heuristics, risky-file context, local gate and review history, and optional current-branch PR metadata when that exists. Then it gives me one recommendation: safe to review, safe to merge, or needs human check.

The label matters less than the defense behind it. If checks are missing, it says so. If security is blocked, it says so. If review state is still draft or changes-requested, it says so. If the repo has no baseline evidence at all, it does not pretend a green answer exists. It stays conservative and tells me exactly which facts are making it uncomfortable.

That is the point. I do not think users want a prettier green badge. I think they want a tool that can justify the badge.

The Cost Model Has to Stay Honest Too

Trust is not only about correctness. It is also about cost.

An IDE can have a convincing readiness story and still betray the user if every new layer quietly makes the terminal slower, heavier, and harder to reason about. I did not want to argue that the terminal can be the IDE while hand-waving away the performance bill.

That is why I shipped yen ide benchmark status and yen ide benchmark run.

I wanted proof checked into the product instead of folklore. The benchmark harness runs deterministic suites for search latency, LSP startup latency, verify duration, and orchestration control-plane overhead. It records cold and warm timings, captures an environment stamp, writes a latest report, compares against a saved baseline, and fails closed when the proof is missing or when a regression is large enough that I should treat it as real.

That fail-closed behavior matters. I did not want a benchmark surface that always sounds informative but never has consequences. If YEN is going to claim trust, its performance evidence has to be usable as a gate, not just as dashboard decoration.

I also wanted the performance story to reuse the same discipline as the readiness story. So the benchmark harness does not invent a separate telemetry universe. Its suite latencies are mirrored into the same non-interference SLO ledger that already exists. Search, LSP startup, verify, and orchestration become explicit entries in one guardrail story instead of becoming a second performance control plane.

The fixtures matter just as much as the ledger. I did not want these numbers to depend on whichever repo happened to be under my cursor or whichever binaries happened to be installed that morning.

So the default path uses shipped fixtures under yen-cli/fixtures/ide-benchmark. Search and LSP run against a known TypeScript-shaped fixture. Verify runs against a deterministic local package-script fixture. Orchestration runs against mock adapters on a fixture-provided PATH. That gives me repeatable proof instead of a moving target.

The terminal-first bet gets stronger when the cost model is explicit. It gets weaker when the cost disappears into vibes.

A Semantic Target Has to Survive the Handoff

There is another way to lose trust that is easier to miss.

The product can have an honest evidence model and an honest cost model, and still feel unreliable if the moment I try to act on that evidence the target gets lost between surfaces. A diagnostic that cannot land in the right file is not much better than a guess. A review hunk that jumps to the wrong place erodes confidence far faster than a missing feature ever will.

That is why I shipped yen ide open, moved yen-yazi-edit onto the same launcher contract, and then pushed that same contract into the native macOS review surfaces.

The rule is simple: Every semantic target stays path:line[:col] all the way through.

Search results, diagnostics, verify output, PR review hunks, merge-conflict selections, and file-browser edit targets should not each invent their own editor-jump syntax. They should all reduce to one location contract, then let one planner decide how that target becomes a real editor launch.

That planner now resolves repo-relative paths, preserves quoted VISUAL and EDITOR argv, understands the editor-family goto matrix, and exposes an explicit dry-run plan so I can test the launch behavior before it surprises a user.

Code-family editors use --goto. Zed takes the direct target shape. Xcode goes through xed --line. Terminal editors keep their real line-aware capabilities where they exist. Plain editors fall back to opening the resolved file only, with the loss of line-awareness made explicit instead of being silently swallowed.

The important part is not the matrix. The important part is the failure behavior.

This handoff now fails closed when the target no longer exists. It fails closed when the launcher is unavailable. If nvr is configured but there is no running server, it falls back to nvim instead of pretending a dead attach command counts as parity. Yazi uses the same planner. And on macOS, the native PR review and merge-conflict workspaces now go through the bundled yen ide open bridge for recognized GUI editors instead of maintaining a second Swift-only launch matrix with its own drift risks.

The same rule now applies to live LSP mutation. yen ide lsp code-actions takes that same semantic target, forwards matching diagnostics context when the server can actually use it, previews every returned action, and only auto-applies when there is one pure workspace edit to defend.

If the server returns multiple edit choices, a command-only action, an edit-plus-command action, or a disabled action, YEN stays in preview mode and says why. That is less magical than a universal quick-fix button. It is also much easier to trust.

That sounds like glue code. I think it is part of the trust model.

The reason is simple: if the product tells me where to look, it has to prove it can actually take me there.

Debugging Has to Leave Evidence

A debugger is where integrated tools often fall back into folklore.

A failing test might know the file. A review surface might know the risky hunk. A diagnostic might know the exact line. But the moment I want to cross from evidence into execution, a lot of products suddenly expect me to carry all of that context by hand, rebuild a launch command from memory, and trust that whatever happened in the debugger can somehow be rediscovered later.

I did not want that split either.

So the debugger work stayed on the same semantic target contract and the same trust model as everything else. yen ide debug status and yen ide debug start use the same path:line[:col] vocabulary as search, diagnostics, review, and handoff.

The shipped baseline is intentionally narrow: python-pdb, node-inspect, and lldb for the local, SSH-backed, and tracked-devcontainer cases I can actually defend. The product stays explicit about what is still blocked: attach-to-pid flows, TypeScript direct-file launch, package-debug flows, and any zero-config adapter install story beyond that shipped baseline.

The more important part is what happens after launch. Real debug runs now write summary, log, and transcript evidence into the same per-workspace state model. yen ide debug status can show me the last run. yen ide trust status can point back to the same artifacts. Timeline events carry the report paths forward. Managed local, SSH-backed, and tracked-devcontainer sessions all stay on that one surface. The debugger is not a private side quest anymore. It leaves a paper trail the rest of the IDE can reuse.

That is also why the visual layer came last. yen ide debug tui now renders the same managed-session state, source excerpt, breakpoints, watches, recent output, and transcript tail instead of inventing a second debugger UI with its own hidden state. When the file is local, the source panel is real. When the workspace is remote, the dashboard says so instead of pretending it can render code it does not actually have. The UI inherits the trust model instead of overriding it.

The same restraint now shows up in the macOS command palette. Empty-query quick IDE actions for Debug Status, Debug TUI, and Format / Lint / Fix Status are just thin launchers over the shipped CLI surfaces. They make the trustworthy path faster to reach without creating a parallel native-only debugger or quality model that would immediately start drifting from the terminal.

That makes the surrounding surfaces sharper too. yen ide test status, yen ide verify status, yen ide search, yen ide merge-readiness, yen ide pr-review, and local diagnostics only append a yen ide debug start ... handoff when the shipped debugger can genuinely launch that target. If it cannot, YEN stays quiet instead of pretending a button is better than an answer.

This is the same trust rule again: Do not promise execution where only suggestion exists. A terminal-first IDE should be willing to leave capability on the table if that is what it takes to keep the chain of evidence intact.

Remote Work Needs One Identity and One Vocabulary

Remote collaboration is where trust models usually split apart.

It is very easy to add SSH-backed behavior to a product by quietly inventing a second control plane. Local work starts using one vocabulary. Remote work starts using another. The same repo gets described differently depending on which side of the network boundary I am standing on. Status gets fuzzy. Trust becomes suggestive instead of explicit.

I did not want that.

So the remote work extended the existing yen ide surfaces instead of branching into a separate remote subsystem. yen ide detect accepts ssh://user@host/abs/path targets. So do yen ide doctor, yen ide trust status, and yen ide verify status.

The point is not that everything suddenly runs remotely. The point is that the same workspace identity now anchors both the local and SSH-backed view of the same repo.

That shared identity matters because it keeps the evidence story coherent. Remote detection reports where execution is actually happening. Trust and verify summaries key their local evidence against that shared workspace identity instead of pretending a remote repo is just another local path. Remote share state does the same thing. yen ide share host, share status, share revoke, share trust, and share untrust now speak the same target shape and the same identity model.

The lifecycle language got stricter too, because vague state is what makes remote tooling feel untrustworthy.

If the host is temporarily unreachable, a session should not suddenly look stale. Disconnected and stale do not mean the same thing. Disconnected means the runtime may still exist and the control plane has temporarily lost contact. Stale means the runtime is gone. YEN now preserves that distinction, keeps reconnect metadata explicit, and lets share status fall back to cached local metadata when the network is the only thing missing.

That is not a flourish. That is the difference between a system that tells the truth under stress and one that collapses into hand-waving the first time SSH gets weird.

Remote Execution Still Has to Admit Its Limits

The last piece of trust is restraint.

Once a remote identity model exists, it becomes very tempting to make every remote surface sound complete the moment SSH works once. That would have made for a cleaner demo. It also would have been dishonest.

So I kept the execution story explicit instead.

Remote workflow discovery is there, and so is real remote execution. yen ide workflow discover, list, show, and run all accept the same remote target shape now. Authored workflows and repo-native tasks can execute remotely over SSH on the same workspace identity, with trust, approval, reports, and timeline ownership staying local.

What is still blocked is the part I cannot defend quite yet: Remote --watch loops and any fake suggestion that the remote machine is under a richer control plane than it really is.

The same rule applies to devcontainers. yen ide devcontainer status, up, shell, and down now work for SSH-backed targets too, and the debugger can reuse that same tracked runtime through yen ide debug status --devcontainer and yen ide debug start --devcontainer when the separate devcontainer trust and health checks are satisfied. If the remote machine is missing the right CLI, the product says so.

If the tracked local state and the probed remote state disagree, the product says so. Labels like spec-drift, disconnected, and missing-remote-cli exist because a terminal-first IDE should not imply a healthy runtime it never actually verified.

That is the restraint I care about now. Ship the remote execution paths that are real. Keep trust and evidence local and explicit. Keep blocked features blocked until the control plane is strong enough that a nicer interface would not just be hiding drift.

This is the part of terminal-first IDE design I care about most now.

The product gets better when it becomes more articulate about boundaries, not less. It gets stronger when the same evidence model is reused in more places, when the same semantic target survives more handoffs, when the same workspace identity survives distance, and when the system is willing to say “I can inspect this, but I cannot honestly claim to control it yet.”

That is what earning trust looks like.

The thesis was that the terminal can be the IDE. The second post was about making that IDE hold together. This phase was about something stricter: Making it legible enough, measurable enough, and self-aware enough that I can trust it when the work gets real. That’s always been the standard.

And now it’s the standard for YEN moving forward. As it should be.

More work to come.

— 8

Last week I published an important post about how the Terminal is the IDE now and I’ve been working on making it even better.

You see, that first post was the thesis. The terminal should not be a utility room bolted onto the bottom of an editor. It should be the place where engineering work actually stays coherent. It just makes sense.

Subscribe now

This follow-up is about something slightly less glamorous and much more important: Making that IDE layer behave like one system instead of a pile of unrelated features.

Because that is the real test.

Anybody can ship a burst of commands and a few native windows and call it an IDE story. The harder part is preserving context across those surfaces, making trust legible, staying honest about what is actually answering a query, and meeting repos where they already are instead of inventing a second configuration universe.

So that is what the most recent hardening pass was really about. Here’s what’s up and the details of what I’ve added.

1. Make the Output Survive the Workflow

The biggest change was not one flashy feature. It was a contract.

I wanted YEN to stop flattening useful engineering output back into vague text the moment it crossed a surface boundary. If a result points at a real file and line, that location should survive through the terminal, the command palette, the review flow, and the native macOS windows.

So the system now leans much harder on one shared semantic location model: path:line[:col].

That shows up in yen ide parse --format tsv, in verify reports, in workflow reports, in the command palette search path, in yen ide pr-review, and in the merge-conflict workspace. Content hits, diagnostics, review evidence, workflow output, and conflict selections can all point back to the same kind of target instead of degrading into “open this file and good luck.”

That sounds small until you use it.

Once the location contract stays intact, the command palette stops feeling like a launcher with some extra sugar on top. It starts feeling like a terminal-first IDE control plane. A search result can still be a real action. A review hunk can still be a real place. A test failure can still be a real jump target.

That is the difference between “there is a lot here” and “this actually holds together.”

2. Upgrading Git Review without Becoming Git

I also spent a lot of time strengthening the review baseline.

That did not mean building a separate Git universe inside YEN. I still think that would be the wrong move. The CLI should stay the source of truth. But the review path needed to get more capable and less lossy.

So the current baseline is now bundled lazygit plus bundled delta as the shared diff renderer. On top of that, yen ide pr-review picked up deterministic hunk inventory and semantic hunk targets, while the macOS PR review workspace and merge-conflict workspace both learned how to stay anchored to those same repo targets.

That has a few nice and positive effects.

Focused hunk previews are better. Plain-text fallback is explicit instead of pretending it is the same thing. Selected files and hunks can keep their target identity all the way through a review flow. The PR evidence path can carry the latest verify readiness and security snapshot with it. And the merge-conflict workspace can show a delta-backed patch preview, keep the selected hunk as a real location, and hand that target off to the editor before staging.

That is exactly the division of labor I want. Keep the terminal-native review flow in the terminal. Use a richer native surface when it genuinely helps and don’t try to pretend that the native surface is replacing the terminal.

Makes sense, right?

3. Trust, Doctor, and Verify Finally Read Like One Story

Another major improvement is that repo state is much easier to inspect before something goes wrong.

YEN already had a lot of the raw ingredients: Project trust, env trust, LSP trust, share trust, workflow trust, local verify artifacts, devcontainer state, language-server status, and so on. The problem was not missing data. The problem was legibility.

That is why yen ide doctor matters.

It takes the existing sources of truth and turns them into one repo-health snapshot with project context, toolchain and version signals, trust and runtime summaries, verify readiness, security state, and clear blocker versus warning findings. By default it exits non-zero when blockers exist, and --strict can intentionally make warnings fail automation too. It is deliberately direct. A health command that only tells you that it successfully collected state is not useful.

The same principle drove the workspace trust center. yen ide trust status gives one aggregate view over the trust and runtime or session state YEN already had. yen ide trust revoke and yen ide trust reset delegate back to the owning commands instead of mutating trust state behind their backs. That keeps the control plane honest.

And then there is the verify path.

yen ide verify status is now a read-only snapshot over the latest local verify artifacts, while yen ide verify carries explicit local osv-scanner coverage. More importantly, that readiness and security state is no longer trapped inside one command. It can surface in doctor and in PR evidence previews too.

That matters because security is not a separate product. It is part of whether a repo looks ready to act on right now.

4. Meet Repos Where They Already Are

This is one of the places I care most about not getting cute.

A lot of developer tools become less trustworthy the moment they stop respecting the repo in front of them. They invent a second workflow system, a second task runner, or a second configuration universe and then ask you to keep both in your head forever.

I do not want that.

So a lot of the recent work was about making YEN better at reading the repo’s existing signals and putting them on one control plane.

yen ide workflow discover now inventories package scripts, Make targets, Just recipes, and Taskfile tasks with provenance, category, risk, and conflict visibility. yen ide workflow run --native is the explicit path for running one of those discovered tasks without pretending it is an authored YEN workflow, and it reuses the same trust, approval, timeline, and reporting plumbing as the rest of the workflow surface.

The quality surface follows the same rule. yen ide format, yen ide lint, and yen ide fix prefer repo-native tasks first, fall back narrowly when the repo already implies a toolchain, reuse the existing trust and approval model, and write dedicated quality reports instead of disappearing their behavior into a black box.

The test surface does too. yen ide test status and yen ide test run build on the same repo-native runner detection and verify artifacts instead of inventing a second language matrix just for testing. Grouped failures, rerun-failed behavior, and semantic jump targets all sit on that same baseline.

And the VS Code migration path got more serious in the same spirit. yen ide vscode inventory and yen ide vscode import now produce richer extension guidance, task and test parity notes, and deterministic local artifacts like migration-report.json and manual-cleanup.txt under .yen/vscode-import.

The common theme is simple: I want YEN to reduce ambiguity, not replace the repo with a parallel religion.

5. Honest Polyglot Intelligence > Pretend Coverage

The code-intelligence layer also got sharper, and I am happy about this one because it pushed the product further in a direction I care about a lot: Honesty.

In the first post about a Terminal-first IDE I said I do not want “smart” terminal tooling that lies. That rule matters even more once multiple languages and multiple fallback modes are involved.

So the install and fallback story is much more explicit now.

JavaScript and TypeScript share one managed baseline. Python and Go have their own managed paths. Rust points at rustup. Swift points at the Xcode or Swift toolchain. Zig expects zls on PATH. YEN does not silently blur those operational models together.

The AST side got stronger too. yen ide ast status, definition, and references now have real parser-backed fallback for Python, JavaScript and TypeScript, Go, and Swift, and the output says what is actually answering the query: python-ast, typescript-compiler-api, go-parser, or swiftc-dump-ast-json. Those results stay clearly labeled Source: ast so fallback never masquerades as live LSP.

Unsupported languages stay explicit instead of getting vague marketing support. Bun-backed JavaScript projects also stop falling off the AST path just because the runtime detection looked slightly different from the normalized JS family.

That is the kind of improvement I want from this layer.

Not bigger claims. Clearer contracts.

6. The Boring Internal Work Is Product Work Too

There was one other slice in this pass that matters even though it is much less visible from the outside: the IDE CLI modularization work.

I do not want every future IDE feature to keep piling into one giant Bash entrypoint until the safest answer becomes “please do not touch this file.” That is how products slow down. That is how regressions get stickier. That is how shipping momentum dies.

So the router and bootstrap layer stays stable in yen-cli/commands/core/ide, while the shared helpers and capability families live in sourced modules behind explicit loader-contract checks.

The user-facing CLI did not change. The implementation risk did.

If you want to feel the current shape of the terminal-first IDE layer, this is a pretty good compact path:

bash
yen ide doctor
yen ide trust status
yen ide lsp status
yen ide ast status
yen ide workflow discover
yen ide workflow run --native package:test --dry-run
yen ide format status
yen ide test status
yen ide verify status
yen ide pr-review 123 --list-hunks

And if you are on macOS, press Cmd + Shift + P after that.

Search the repo. Open a review surface. Inspect diagnostics. Jump to a hunk. Pull up trust state. Notice how often the system can keep the location, the context, and the repo identity intact instead of making you reconstruct it by hand.

That is what this follow-up post is really about. The first post in the series was about saying the terminal is the IDE now.

This one is about making that sentence even more true.

There is still more to do. Editor handoff parity, remote parity, merge-readiness reporting, and benchmark work are all still on the table.

But the IDE layer is already better now in the ways that matter most to me: More coherent, more inspectable, more honest, and more native to the repo that is actually in front of you.

I like where we’re going together.

— 8

There is a pattern I have been watching for years.

Most developer tools say they love the terminal, then quietly treat it like a basement utility room. And it always kind of feels like it lives in the basement at the bottom of the screen, right?

Subscribe now

The editor gets the architecture. The terminal gets a small panel.

Boohiss.

The editor gets the first-class search, the code intelligence, the review flows, the collaboration story, the automation surface, and the gentle product language about focus and speed. The terminal gets a rectangle at the bottom and maybe a button that says “open integrated terminal.”

I never thought that that was good enough, at least from my perspective!

The terminal is not a sidecar for serious engineering work. It is the place where code actually meets reality. It is where builds fail, migrations go sideways, diagnostics become actionable, PRs get reviewed, services get restarted, environment mistakes surface, and dangerous commands should feel dangerous before you press Enter.

That is why I have been pushing YEN toward a different thesis: Do not bolt a terminal onto an IDE. Build the IDE around the terminal.

And the most recent release — v0.999 — is the biggest step so far in that direction as YEN now ships a real terminal-first IDE surface.

Not a concept page.

Not a chat sidebar pretending to be an IDE.

Not a cloud account plus a terminal skin. Eww.

Nope. None of those things. Instead, we have a real, local-first workflow stack that starts in the terminal and stays there unless a richer native macOS surface is actually justified. Here are the 8 major pieces that bring it all together.

1. Project Awareness

The first big piece is project awareness.

YEN now understands enough about the current repository to make terminal workflows feel contextual instead of generic. yen ide detect finds the project root and runtime / tooling context. yen ide env gives you explicit trust-gated environment loading. yen ide history, replay, and profile turn the terminal into something closer to a project memory instead of a disposable scrollback trench.

That matters because terminal-first tooling only works if the terminal knows where it is, all the time, even when you forget.

2. Search with First-Class Objects

The second big piece is search that treats engineering artifacts like first-class objects.

yen ide search can rank across files, content, diagnostics, project history, and actions. On macOS, the same contract now powers the desktop command palette. Empty query launches actions.

A typed query searches built-in actions first, then falls back to project files, content, diagnostics, and recent history for trusted local repos. That means the search surface you invoke with Cmd + Shift + P is no longer just a launcher.

It is a project-aware terminal IDE entry point.

3. Local Code Intelligence

The third big piece is local code intelligence.

YEN now ships an explicit LSP control plane with yen ide lsp trust, start, status, diagnostics, hover, definition, references, rename, stop, and a bounded install matrix. Cool.

This all includes real resolver-backed supervision when a local language server exists, placeholder guidance when it does not, grouped diagnostics snapshots with freshness labeling, and interactive request surfaces that stay honest about whether they are using live LSP or syntax-aware fallback.

That last part matters to me a lot. I do not want “smart” terminal tooling that lies.

If YEN is using a live language server, it says so. If it is using AST fallback, it says Source: ast. If the language is unsupported or the expected local server is missing, it says that too.

Honesty is a feature. Who would have thought.

4. Syntax-Aware AST Queries

The fallback layer is the fourth piece: Syntax-aware AST queries.

When live LSP is not available, YEN can still answer useful structural questions with yen ide ast status, definition, and references for the currently shipped languages.

That means the terminal does not have to collapse all the way down to dumb text search every time a full server is absent.

5. Execution Discipline

The fifth piece is execution discipline.

This is where terminal-first IDEs have a chance to be better than editor-first ones. Or that’s the hope!

YEN now ships yen ide explain for failed command analysis, yen ide verify for multi-language verification bundles, yen ide gate for risk-aware approval checkpoints on dangerous commands, yen ide workflow for schema-validated project workflows, yen ide timeline for local audit events, and yen agents for first-party adapter coordination. Wild.

There is also yen ide pr-notify for GitHub review-request polling and yen ide pr-review for focused diff review, evidence bundles, inline comments, and explicit review decisions.

This is not about adding ceremony.

It is about making the terminal better at the parts of engineering work where context, the ability to easily review work, and general safety actually matter.

6. Collaboration without Bloat

The sixth piece is collaboration without a custom relay empire.

YEN now ships yen ide share status, host, join, revoke, trust, and untrust using an integration-first transport model: upterm first, tmate as fallback. Share tokens are encrypted locally. Hosting is per-project and explicitly trusted. Join flows validate the token locally before any transport command runs. Sessions can be read-only or interactive. TTL expiry and immediate revoke are part of the contract.

This was an important design choice.

I did not want to build a bespoke terminal-sharing service just to say YEN has collaboration, which would be fun but not entirely useful.

You see, there are good maintained tools for this job already. The right move was to build the control plane, trust model, audit trail, and operator ergonomics around them instead of pretending every feature needs a net-new backend.

7. Environment Parity and Migration

The seventh piece is environment parity and migration.

YEN now ships yen ide devcontainer status, up, shell, and down as a trust-gated wrapper around the reference devcontainer CLI. It is intentionally local-workspace scoped. No hidden runtime. No bundled container stack.

No pretending YEN needs to become Docker Desktop.

YEN also ships yen ide vscode inventory and import so teams can inspect existing VS Code workspace config, classify what is supported or partial, and write deterministic YEN-local migration artifacts without mutating the original workspace by surprise. Dry runs emit real diffs. Applied writes are convergent. That is the kind of migration behavior I want from tooling: boring, inspectable, and reversible.

8. Native macOS IDE Surfaces That Actually Help

The eighth piece is native macOS IDE surfaces where they actually help.

This is the part that makes YEN feel different.

The command palette now exposes quick IDE actions like IDE: LSP Status, IDE: LSP Diagnostics, IDE: LSP Install Matrix, IDE: Share Status, IDE: Share Host (Read-Only), IDE: Share Revoke, IDE: Devcontainer Status, IDE: VS Code Inventory, IDE: VS Code Import (Dry Run), and IDE: AST Status.

On top of that, macOS now has a dedicated desktop PR review workspace and a dedicated desktop merge-conflict workspace launched from the same palette. Those are native surfaces, not browser panes, and they stay anchored to the active repository context instead of trying to replace the terminal.

That is the pattern I want YEN to keep following.

If a task is fundamentally terminal-native, keep it in the terminal.

If a task genuinely benefits from a richer surface, build a native one and keep it close to the terminal instead of escaping into a second application model.

That is a better division of labor than the one most IDEs settled on.

Bonus: Local First

There is also a security and trust story here that I think matters more than the marketing layer most developer tools put on top.

This IDE stack is local-first. Project trust is explicit. The LSP runtime is per project. Sharing trust is per project. Diagnostics snapshots are local.

Devcontainer orchestration shells out to the reference CLI you already chose to install. VS Code import writes project-local artifacts instead of disappearing into a hidden sync service.

None of that is as flashy as saying “agentic workspace intelligence” in a launch trailer, but I think it is the right way to build tools engineers can actually trust.

And there is still plenty left to do!

Debugger work remains future work. Remote devcontainer parity is still a deliberate follow-up instead of a hand-wavy promise. Agent-runtime hardening and context reliability still have room to grow. I am not pretending YEN is finished.

But the shape is real now. You can feel the product thesis in your hands.

The command palette is not just a launcher anymore. The terminal is not just an output window anymore. The IDE is not somewhere else anymore.

It is here.

If you want a feel for the surface area, this is a compact starting path:

bash
yen ide detect
yen ide env list
yen ide lsp status --format json
yen ide lsp diagnostics
yen ide lsp hover src/app.ts:12:3
yen ide share status
yen ide share host --read-only --ttl-minutes 30
yen ide devcontainer status
yen ide vscode inventory
yen ide search verify
yen ide verify --quick
yen ide pr-review 123 --loop
yen ide timeline --limit 20

And if you are on macOS, press Cmd + Shift + P and start from there.

That shortcut has quietly become one of the best ways to feel the whole philosophy of YEN in a few seconds.

Open the palette. Launch a real IDE action. Search a repo. Review a PR.

Inspect diagnostics. Start a share session. Import a VS Code workspace in dry-run mode. Then close the palette and notice that you never left the terminal-first workflow to do it.

That is the point.

The goal is not to cosplay as a giant editor suite. The goal is to make the terminal powerful enough, contextual enough, and trustworthy enough that you stop needing to flee from it for everyday engineering work.

That is the release. That is the mission.

And for the first time, I think it is fair to say it plainly:

The terminal is the IDE now. About damn time.

— 8

There is a version of speech-to-text that looks great in a demo and still feels wrong in daily use. You hold Option + Space. You speak. You release.

Wow. So much wow.

Subscribe now

And it worked. YEN has had a strong speech-to-text foundation for a while now. It is on-device. It is native. It works across macOS apps. On macOS 26 and newer it uses Apple’s modern speech stack with unlimited sessions.

That part was never the problem.

The problem was simpler and more important. The workflow itself needed to be tightened. So, that’s what I’ve been working on since we’re coming up on our official v1.000 release — everything needs to be perfect.

But, there were some over-complications that I’ve wanted to fix and those fixes should be in as the right version of speech-to-text in a terminal-first IDE should not feel clever. It should feel dependable.

It should feel boring in the best possible way.

And, the rest of this post may be boring for most (a bit engineering and tech-heavy, so forgive me) but at the very least it showcases how much I care about this feature that’s a model for what and how I think about a Terminal-first IDE (platform).

If you want to geek out, continue on fellow nerd.

Hotkeys and Session Contracts

The first part of this hardening was the hotkey session contract.

The old problem space here was subtle. Global hotkeys on macOS are not just about catching one keyDown and one keyUp. You have to care about modifier-release ordering, event-tap rebuilds, trust loss, key repeat noise, and stop or restart churn when the user presses again quickly.

That means a sloppy implementation can accidentally treat keyboard-state drift as a real release. It can stop capture because polling noticed a mismatch instead of because the user actually let go. That is exactly the kind of thing that makes a feature feel haunted.

I tightened that.

Hotkey-up synthesis is now restricted to explicit recovery paths instead of loose session-state drift. The exact hold contract is deterministic whether Option or Space releases first. Event-tap rebuilds while the keys are still physically down no longer get to silently terminate a valid capture. Re-press during stop is treated as a queued restart instead of an invitation for stale state to bleed across sessions.

That sounds like implementation trivia until you use the feature all day.

Then it becomes the whole feature.

Finalization Contract for Acceptable Input

The second part was the finalization contract.

Speech-to-text gets weird when people talk about “the transcript” as if there is always only one obvious version of it. In reality there are partials, finalized segments, stop callbacks, error paths, watchdogs, and all the little ways asynchronous systems try to complete more than once or complete in the wrong order.

That is not acceptable for input.

YEN now treats stop completion as a proper per-session contract with one, single authoritative result. There is an explicit stop token. Completion is exactly once across normal release, recognizer error, results-stream failure, watchdog fallback, and forced reset paths. I also added more explicit stop telemetry so transcript loss can be diagnosed from logs instead of guessed from UI behavior.

Just as importantly, I removed “experimental” work from the default release-to-paste critical path. That part needed to happen.

If the user’s baseline expectation is “hold Option + Space, speak, release, paste,” then the core path cannot be hostage to optional experiments.

At that stage, Live Transcript Preview and Translate-on-Dictate were clearly labeled EXPERIMENTAL in Settings, and the default stop path was no longer forced to wait behind translation behavior when translation was off.

That product boundary was the right intermediate step: stabilize the core workflow first, then graduate optional surfaces only after the contract is clear.

Oh, fun.

The Contract for The Clipboard

The third part was the clipboard and paste contract. This was the most important user-facing fix.

The easy version of cross-app dictation is: Put text on the clipboard, fire Cmd + V, restore the old clipboard on a timer, hope for the best.

That is not a serious delivery contract.

If the paste target changes, if the synthetic paste does nothing, if the target app is slow, or if delivery simply cannot be proven, a timer-based clipboard restore turns into a data-loss risk. You get the worst combination: No inserted text and no recoverable text. No bueno, so, I tightened that too.

YEN now captures the insertion target at stop time and treats three cases separately: direct terminal-surface paste inside YEN, same-app responder-chain paste, and cross-app synthetic Cmd + V. Those are not the same operation and they should not pretend to be.

Inside YEN, the old clipboard can be restored after paste with a guarded delay. Same-app responder behavior stays explicit. Cross-app synthetic paste is treated more conservatively because delivery cannot actually be proven by the sender.

That means when YEN pastes into another app through synthetic Cmd + V, the dictated text now stays recoverable on the clipboard until the user replaces it.

That is a much better failure mode.

The goal is not to hide every edge case. The goal is to make the safe path the default path and the recovery path obvious when automation cannot honestly guarantee delivery.

I also tightened stale-target handling so the transcript is bound to the app or split that was focused when you released the hotkey. If that target changes or becomes invalid before insertion, YEN fails closed into manual recovery instead of pasting into the wrong place.

That is another example of the kind of boring behavior I want.

Wrong-field paste is worse than no paste.

Naturally.

Truth-Seeking in Great, Simple Product

The fourth part of this pass was simply telling the truth in the product and docs.

There was some confusion around Apple’s newer speech APIs, so I rechecked the recognizer shape carefully against Apple’s own documentation. Apparently, on macOS 26+, YEN still used SpeechAnalyzer with DictationTranscriber for the main dictation path.

That is the right pairing for what YEN is doing.

Apple also exposes SpeechTranscriber as part of the broader Speech framework stack, and it is useful, but it is not some magic replacement for session-logic bugs. SpeechAnalyzer is the container.

The real question is which speech module belongs in the workflow you are building. For YEN’s hold-to-talk dictation flow, DictationTranscriber remains the correct transcription surface.

That distinction matters because it keeps the engineering work honest.

If the problem is race conditions, stop semantics, target routing, and clipboard durability, the answer is not to wave at a nearby API name and hope the complexity disappears. The answer is to harden the workflow contract itself, so, that’s what the latest release has done.

And that ties directly back to YEN’s larger mission.

I keep saying YEN is a Terminal-first IDE, and I mean it in a very literal way.

The terminal should not just be fast. It should be trustworthy.

If a feature belongs in the terminal workflow, it has to clear a higher bar than novelty. It has to feel like something you can build real muscle memory around. It has to be explicit about what is experimental, explicit about what is guaranteed, and conservative when the system cannot actually prove success.

That is especially true for speech-to-text. Speech-to-text inside a terminal is easy to market as a fun trick. But in practice it is an input primitive.

It becomes part of how you move through the machine. Part of how you write. Part of how you reply in chat, search, command, annotate, and capture thoughts without breaking flow.

When something occupies that layer, reliability is the feature and everything else is secondary. So, this hardening pass did not add a dramatic launch trailer bullet point.

It did something better: It made the core path legible.

Hold Option + Space. Speak. Release. Done.

YEN should either paste the right final text into the right place exactly once, or leave that text recoverable so nothing is lost.

That is the bar. That is the contract.

And that is the kind of boring I want more of in software. Boring software is great software because it does precisely what I, and the community, want.

Who would have thought.

— 8

Quick story. I set up a brand new M4 Mac last week as a fresh-start check for YEN. Fresh macOS install, nothing carried over. Downloaded YEN, launched it, pressed Option + Space to dictate something.

Nothing happened. Damn.

Subscribe now

No error. No popup. No indication of what to do next.

That moment was a good reminder that onboarding is part of the feature. If speech-to-text is going to be something people rely on, setup has to be clear, guided, and accessible.

The dictation feature itself was not broken. What YEN needed was a better way to walk people through the permissions required to register the hotkey and capture audio. On an earlier build, that could leave Option + Space looking dead until someone manually dug through System Settings.

But, you know, onboarding matters. We all know it does.

YEN’s speech-to-text needs three macOS permissions to function:

1. Accessibility — The Option + Space global hotkey

2. Microphone — Audio capture for speech recognition

3. Speech Recognition — Apple’s on-device transcription engine

When any one of these is missing, speech-to-text can feel unavailable even when the fix is straightforward. That is exactly the kind of first-run experience we want to avoid.

macOS handles these permissions differently, especially Accessibility, so the app cannot assume the system will teach the user what to do. YEN now takes that responsibility more directly: show what is needed, explain why it matters, and make the recovery path obvious.

For a feature like speech-to-text, the onboarding experience is not separate from the feature. It is the feature. Naturally.

To make the experience even better I’ve made sure to expose the permissions in the Settings Panel and in the top macOS menu bar so the user has confidence that a fundamental part of their (new) workflow is always working.

Not hard to put together but important enough to build and ship. So give it a try!

— 8

We shipped a focused addition to speech-to-text in YEN: Translate-on-Dictate.

Subscribe now

The behavior is simple:

1. Hold Option + Space and dictate normally.

2. Release to finalize transcription.

3. If translation is enabled and the selected language pair is ready, YEN pastes translated text.

4. If not, YEN pastes the original transcript.

No extra prompt flow. No cloud dependency requirement from us.

Why This Is Experimental

Translation is now explicitly positioned as experimental and off by default.

That keeps the default dictation path stable while we gather real usage and edge-case feedback from opt-in users.

Core speech-to-text behavior stays unchanged when translation is disabled. I’d love feedback on this since I need more folks to try it and see if it works as well as I hope it can! Post your feedback in “chat” off your shell.

What We Hardened

Translate-on-Dictate only runs as a post-processing step on the final transcript:

• Live overlay text remains source-language during capture

• Source language follows recognizer locale

• Target language is explicitly selected in Settings

• Settings now filters the target list to language pairs that are actually compatible with the current recognizer locale

• When a supported pair is missing assets, YEN can ask macOS to prepare them while YEN is frontmost in Settings

Failure behavior is deterministic:

• Translation failed -> paste original transcript

• Translation timed out, or the translation availability check stalled -> paste original transcript

• Language pair unsupported, still preparing, or model unavailable -> paste original transcript

• )lder macOS (no Translation framework runtime) -> paste original transcript

We do not block paste on translation success.

We also now cover both the availability lookup and the translation session with the timeout guard, and we cancel translation sessions on timeout or cancellation to avoid overlap under rapid dictate cycles.

Where To Enable It

Open Cmd + , »»» Sounds »»» Speech Setup »»» Translate-on-Dictate.

Choose your target language, then test in any app where YEN dictation already works.

If macOS still needs translation assets for the selected pair, keep YEN frontmost in Settings for the preparation step. Once the pair is ready, dictation uses it. If it is not ready yet, paste still falls back to the original transcript.

Have fun with it!

— 8

There is a particular kind of terminal chaos that shows up the moment you stop demoing and start actually working.

Subscribe now

One pane and/or tab runs the dev server. Another one runs tests. And of course you’ve got one that tails logs. One is a scratch shell you swear is temporary. They all live in the same repo. They all look almost identical. And after a while, your brain is doing bookkeeping the computer should have handled for you.

Mental. Burn. Out.

The tabs help, of course, but tabs are too coarse for this problem and there’s definitely better UX available, right? If your real workflow lives inside a split layout, the unit that needs identity is the pane.

That is why YEN now has Split Labels.

Turn them on in Settings » Workspace » Split Labels. Once enabled, each split gets a small pill at the bottom-left corner using the active terminal theme colors.

Click it directly or open Cmd + Shift + P and run Rename Split Label, and that pane can become anything you want it to be: Server, tests, queue worker, staging ssh, or whatever your future self will thank you for.

Most terminals let you rename tabs. That is useful, but it is not the same thing.

If you work in a three-column layout for client, API, and tests, a tab title does not solve the real problem. The panes are still where the context lives. Split Labels are independent from window titles and tab titles, because pretending those are the same thing just moves the confusion around.

It’s a simple concept:

And the fallback behavior is intentionally boring.

Leave the field blank and YEN goes back to an automatic pane label. That path uses the pane title when it is meaningful, otherwise the working-directory leaf, otherwise Terminal. No weird placeholder nonsense. No permanent rename required just because you wanted a quick label for one session.

But, if you want, it’ll persist.

A lot of terminal UI tricks feel nice right up until you close the app and discover they were only decorative. In YEN, Split Labels are stored with restore state per pane, so they survive tab switches, window restoration, and full session restarts.

If you named the left pane api and the right pane web, YEN should remember that instead of making you rebuild your mental map every morning.

There is also some deliberate restraint here.

The label does not force itself onscreen in every situation. If a pane is too small, if a URL hover preview is visible, or if you are dragging panes around, the label hides. That is not the feature failing. That is the feature refusing to become clutter at exactly the moment the space is tight or the interaction is doing something more important.

No split, no label. Also intentional. UX is how you win minimizing the cognitive load for the user and making the quality of life better. Take a look:

This is one of those details that sounds small until you use it for a week and then wonder why terminals ever stopped at tab titles.

A terminal-first IDE lives or dies on whether it respects working memory. Engineers already keep too much state in their heads. Which pane is production logs. Which one is the migration. Which one is safe to kill. Which one has the REPL with the weird local setup. The terminal should carry more of that load.

That is the philosophy behind Split Labels. Not bigger chrome. Not decoration. Just a small, local-first piece of interface that makes multi-pane work easier to read.

Apparently I needed to build pane name tags because my own split layouts had reached the “which one of you is the test runner again” stage of evolution. Ask me how many times I clicked the wrong pane before admitting tabs were not enough.

If you live in split-heavy terminal layouts, this one should just work.

— 8

A lot of people still do not realize this exists in YEN at all.

Subscribe now

YEN has a built-in community chat system inside the terminal itself. That was already a strange and important line to cross when we first shipped it. We were not adding a side panel to a browser app. We were building what we believe was the first terminal with chat and community built into the product.

That is worth reminding people about, because once chat lives inside a terminal, the bar changes. The terminal is not a casual surface. It is where people debug production issues, inspect logs, move around sensitive files, and work inside a higher-trust environment than most ordinary consumer apps.

So when you say “chat inside a terminal,” the obvious reaction from serious users is not just curiosity. It is caution.

That is a fair reaction.

If chat inside a terminal is sloppy, it is scary. If file attachments inside terminal chat are sloppy, it gets worse fast. So this post is partly about broader file support, but more importantly it is about the security and privacy posture behind it.

First, The Feature Itself

The reason I spent the time building this seem obvious when you first encounter it:

1. It gives me immediate and direct feedback from the community about what they want and features they need. Total win.

2. It inspires me and keeps me motivated. And I can get lonely too.

So, it was built and it’s really, really cool.

And now, I’ve expanded attachment support in YEN Chat beyond the original image and document flow, including CSV, JSON, ICS, EML on top of existingsupport for images and common document formats.

That means people can share a quick export, an API payload sample, a calendar invite, a message thread, a markdown note, or a plain text artifact without leaving the terminal workflow.

That sounds like a convenience feature, but it only works if the delivery path is hardened enough to deserve the trust people place in a terminal. And it is.

I didn’t treat this as “add a few MIME types and move on.” I treated it as a trust-boundary change. That means the file expansion shipped together with private storage, proxy-only delivery, stricter response headers, mediated access paths, and tighter defaults for how different attachment types open.

These are things the user will never see. But, I know they’re air-tight and risk-free. I mean, you shouldn’t share your private keys in chat, but, you can share anything else within reason.

You see? Never share sensitive data! And we’re good. A few things I worked on:

1. Private storage and made files.yen.chat a tightly-controlled delivery path.

2. Direct anonymous storage upload, list, and read paths are denied.

3. Attachment fetches go through the proxy path instead of straight to storage.

4. Upstream fetches use service-role credentials on the server side only.

5. Proxy host and path are tightly bounded.

6. Upstream redirects are rejected.

7. Attachment responses get X-Content-Type-Options: nosniff.

8. Non-image attachments are forced to download with Content-Disposition: attachment and X-Download-Options: noopen instead of rendering inline in the browser.

And, of course, privacy reigns as a surpreme import — I am a cypherpunk, after all. Privacy matters more to me than most people could really understand. So, I extend that to everything that I try to do, especially for folks who count on using this wonderful, beautiful thing that is a Terminal.

You see, security is not only about preventing code execution or bypassing headers. It is also about how much data the system keeps, where identity is bound, and what is exposed by default. YEN Chat is built around mediated access, not direct client trust.

Sender identity is session-bound on the server side and the client uses a local device ID to request a short-lived chat session, and that device ID is treated as a private credential on disk with tightened permissions, including private directory and file modes for its local storage.

Messages and attachments are not meant to live forever. Chat messages age out after 80 hours, and attachments follow the same 80-hour cleanup window. Nothing is kept beyond ~3 days. It’s hard delete only. Let’s go.

So, on the surface it’s a simple “chat” but underneath it’s everything that I’ve learned over 20 years of writing enterprise-grade software, inside a simple frame that can be another place to drop emojis.

Go figure.

— 8

When we first shipped the tab sidebar back in January, it was a floating panel. You hit Cmd + Shift + B, a translucent overlay slid in from the left, you glanced at your tabs, and you dismissed it. It was useful. It was also temporary by design — a quick reference surface, not a workspace companion.

Subscribe now

That was fine for the first few iterations but I knew that it wouldn’t be enough. You see, the more I used it myself, the more I realized that a glanceable sidebar is only half the story. And, there was so much more I could do with it, especially as we move closer and closer to a real Terminal-first IDE.

If you’re running five agents across three projects and a production SSH session, you don’t want to keep summoning a panel. You want that context pinned to your window. Always there. Always current.

So I rebuilt it from the ground up.

What Changed

The sidebar now has two presentation modes.

The original floating panel is still there — Cmd + Shift + B still works and “Escape” still dismisses it, and it still slides in from the left edge. Nothing was removed.

The new mode is a persistent docked rail. Pin the sidebar and it becomes part of your terminal window. It expands the window frame to make room instead of overlapping your content. Your terminal columns stay exactly the same.

Unpin it and the window contracts back to its original size. It’s screen-edge-aware — if your window is against the left margin, the expansion goes right instead.

Every tab in the rail shows live metadata: the working directory, the git branch, build status, and a process activity indicator. This is not scraped from window titles. The sidebar observes the actual surface tree that the terminal engine maintains — the same data structure that tracks splits, focus, and tab ordering.

Take a look:

Why We Didn’t Invent “Agentic Tabs”

It would have been easy to build something flashy. Something like “Agent-aware” tab grouping. Automatic workspace layouts that reorganize themselves. Tabs that talk to each other through some custom IPC layer. The AI-powered IDE playbook practically writes itself.

We didn’t do any of that.

Here’s why: The terminal already has conventions for this. A tab is a tab. A split is a split. An SSH session has a hostname. A git repo has a branch. A running process has a name. These are not new concepts — they’re the vocabulary that every developer already knows.

I’m not interested in re-inventing the wheel just because I can.

When you’re running Claude Code in one tab, a local server in another, and tailing production logs in a third — you don’t need the sidebar to “understand” your workflow. You need it to show you what’s happening in each tab, clearly and immediately, so you can switch to the right one without thinking.

That’s a UX problem, not an AI problem.

The Engineering Reality

This sounds simple when you describe it. It was not simple to build.

The sidebar needs to observe YEN’s surface tree — the internal representation of windows, tabs, and splits. That tree is managed by the terminal engine, not by our overlay code. We can observe it through published properties, but we cannot own it.

The challenge is lifecycle management. When a tab closes, the observation must detach. When a window gains focus, the sidebar must reattach to the new window’s tree. When the user is switching tabs rapidly, the sidebar must not trigger cascading observation updates that feed back into the tree and create infinite loops.

I honestly spent roughly 30 commits stabilizing this. The core fix was separating the concept of “attach to a new window” from “rescan the current window’s tabs.” When the sidebar attaches, it checks whether the window actually changed. If not, it rescans without re-notifying. That single guard eliminated the recursion that was causing runaway CPU and observation storms.

The persistent docked mode added another layer of complexity. When you pin the sidebar, the window frame must expand. When you unpin it, the frame must contract by exactly the same amount it grew — not more, not less. The expansion has to be screen-aware: If expanding left would push the window off-screen, expand right instead. If there’s no room in either direction, shrink the terminal content.

We also had to handle edge cases that sound absurd until you hit them: what happens when you pin the sidebar in fullscreen? When a miniaturized window restores with the sidebar visible? When the user drags the window to a different display with different screen bounds?

The answer to all of these is the same: Fail closed. Fullscreen and miniaturized windows don’t get a docked rail. Screen changes trigger a geometry recompute. And every expansion records exactly how many points it added, so the contraction is always symmetric.

Terminal Fundamentals, Not Terminal Theater

We care deeply about aligning YEN with the way developers actually work in 2026 — running agents, juggling contexts, managing parallel workstreams. But we believe the right way to support that is not to reinvent the terminal. It’s to make the terminal’s existing concepts work better.

A tab that shows you its working directory, git branch, and process status gives you everything you need to manage six concurrent agent sessions. You don’t need the tabs to be “smart.” You need the information to be visible.

That’s the difference between terminal theater and terminal UX. Theater is building features that demo well. UX is building features that disappear into your workflow because they just work.

You know, just a wonderful experience that you know that works. No fluff here.

Straight Terminal UX.

— 8

Subscribe now

I didn’t actually have one since my presentation were simply notes viewed via my Terminal but my passion for education got the better of me and I was inspired to actually sit down and write it all out.

Whew. So, with that, here we go.

TL;DR: Skills and Harness Engineering is Technical GodMode™

I ship a signed, notarized, cryptographically verified macOS desktop app — touching 30 distinct languages, 5 compilers, 65 verification checks, and zero CI servers — from a single command on my laptop.

Yeah, it sounds pretty badass. It is.

That’s because I have a release pipeline that is orchestrated by an AI agent constrained by a bespoke harness I designed. It takes about ~15 minutes.

It used to take days.

This post is a little bit of a story of how I got here, what I built, why it works, and — most importantly — how you can apply these patterns to your own projects.

Every technique described here is production-tested. Every number is real. Every lesson was earned the hard way.

And the timing is perfect because the version currently sits as v.990 — almost to our v1.0 release! But the proof is in the pudding: I’ve compiled and shipped this product almost 1,000 times and it just works.

Every single time with 100% confidence and zero worry.

But they told me that I couldn’t “manage AI” and that it would be dangerous!

Wrong.

Table of Contents

0. Why This Matters

1. The System at a Glance

2. The Arc of Build Automation

3. What Makes a Good Harness — 3 Pillars

4. Build a Useful Skill Taxonomy

5. Polyglot Challenge — 30 Languages, One Pipeline

6. Codex-Native Skills — Progressive Disclosure and Machine-Evaluable Evals

7. Reproducible Patterns You Can Copy

8. In Conclusion

0. Why This Matters

It matters because this is about not just automation or efficiency; it’s about time.

Time is all we’ve got and it just doesn’t make much sense sitting in the old paradigm, waiting around for hours as you do things manually when you can do them in minutes (or even faster).

So, I want to save as much as I can so I can do other things.

And I’d like that for everyone else too. I hope this post helps. You see, the answer is really pretty simple. The answer is a system — not a trick, not a framework someone else built, and certainly not a SaaS product that I had to sign-up for.

Instead, it’s just a system I designed and iterated on across nearly 1,000 releases, grounded in harness engineering best practices from OpenAI’s Codex team, pressure-tested against the most fragile operations in software (code signing, notarization, cross-compilation, cryptographic verification), and running in production right now.

YEN is macOS desktop app. More specifically, it’s a modern Terminal-first IDE built on top of libghostty’s C library, bundling 12 third-party CLI tools, 3 native Swift helpers, 3 Go TUI applications that integrate with Google OAuth, the Gmail API, and the Google Calendar API, custom notification sounds with their own EdDSA-signed versioning system, and 23,000 lines of hand-crafted Swift overlay code.

The service stack spans Supabase (PostgreSQL + RLS + Storage), Vercel (Next.js 16 on Turbopack with edge deployment), Cloudflare (DNS routing + email forwarding), Sparkle (macOS auto-update framework with EdDSA cryptographic signing), and Apple’s notarization and timestamp infrastructure. The project spans 30 distinct languages and formats.

The command that starts and ends it all? One word. Easy mode:

$zip  

And that one 3-letter word kicks off a pipeline that reads, writes, transforms, compiles, verifies, signs, and bundles artifacts that cascades into calculated triggers for a web deployment to Vercel that updates the public-facing download page, public documentation, API routes, and SEO metadata in a single push.

There is no Jenkins. No GitHub Actions. No BuildKite. No Travis. No Forest. Nothing. And I have spent years learnings each one and agonizing on why they would break so often. Now? My simple MacBook Pro IS the CI.

My machine’s keychain holds the signing identity, notarization credentials, and the Sparkle EdDSA private key. A single command triggers the whole thing. And the AI agent that runs it is constrained by a harness that makes it impossible for it to do the wrong thing in the places that matter most.

The value proposition is simple: I replaced an entire DevOps team and a CI/CD infrastructure with 18 AI-orchestrated skills, 12 shared bash libraries, 7 pre-tool hooks, and a design philosophy that says “enforcement beats instruction.”

If you’re building anything that involves complex multi-step processes — release pipelines, vendor management, cross-compilation, signing workflows — the patterns in this post report will hopefully save you enormous amounts of time.

Not because they’re clever but because they’re simple, they’re mechanical, they’re boringly-predictable, and they just plain work.

1. The System at a Glance

Before we go deep, here’s the 30-second overview:

1. One command — An AI-executed skill (409 lines of instruction).

2. 12 sequential steps — Pre-flight, vendor gate, version bump, sync, verify, build, post-verify, stage, commit, verify upload, push, summarize.

3. 5 compilers triggered — Zig, Swift, Xcodebuild, Go, swiftc, AppleScript.

4. 30 languages — Swift, Zig, Go, TypeScript, C/Obj-C, Python, Bash, Metal, GLSL, Lua, AppleScript, SQL, JSON, XML, Plist, XIB, pbxproj, TOML, YAML, Gettext, and much, much more.

5. 65 verification checks — 13 pre-build + 44 core + 8 post-build categories.

6. 7 pre-tool hooks — Physical constraints (agent harness) on the AI with a discrete list of blocked commands that should never execute.

7. Local toolchain — Bun (package manager + test runner), Zig, Xcode / Xcodebuild, Go, swiftc, lipo, hdiutil, codesign, xcrun, iconutil, ImageMagick, sips, git, gh.

8. External services — Apple (codesign, notarytool, timestamp), Sparkle (EdDSA auto-update), Supabase (PostgreSQL + Storage), Vercel (Next.js edge), Cloudflare (DNS + email forwarding), Google (Gmail API, Calendar API, OAuth2).

9. Zero CI servers — My notebook computer is the CI. Magic.

10. ~15 minutes — Full clean build to published release (desktop + web + docs + infrastructure).

The output: A versioned, signed (SHA-256), notarized, stapled .DMG file hosted on Supabase, with an updated Sparkle appcast, committed and pushed — ready for users to download.

One command updates the desktop app, the web presence, and the project documentation in a single atomic flow.

It feels like we’re getting 10x or 100x engineering vibes, right?

2. The Arc of Build Automation

Build automation isn’t new. What’s new is who — or what — runs it.

• 1976 — make — Dependency graphs, file timestamps.

• 1990s — autotools — Cross-platform configure/ make / install.

• 2000s — CI/CD — Jenkins, Travis, GitHub Actions, remote machines run the build.

• 2010s — IaC — Terraform, Docker, infrastructure as code, reproducible envs.

• 2020s — GitOps — Declarative desired-state, reconciliation loops.

• 2025+ — AI Skills — The agent reads the runbook and executes it. The harness manages and constrains it while allowing it to move fast (and token count).

Every generation solved the same problem:

How do you make a complex, multi-step process reliable and repeatable?

The answer evolved from dependency graphs (make) to remote execution (CI) to declarative state (GitOps).

And now AI skills are the next step: Imperative runbooks executed by an agent that can read output, make decisions, and handle the unexpected — constrained by a harness that enforces invariants the agent cannot override.

This isn’t “AI writes code.” This is production-grade harness engineering; designing the system so the AI can reliably operate it.

The distinction matters.

I’m not asking the AI to be creative. I’m asking it to follow a precise, gated, fail-closed protocol — and I’m making sure it physically can’t deviate from that protocol in the places where deviation would be catastrophic.

3. What Makes a Good Harness — 3 Pillars

OpenAI’s harness engineering framework identifies three pillars. Here’s how I implement each, with concrete examples you can adapt:

Pillar 1: Context Engineering

The agent can only act on what it can see. So I made the repository the single source of truth for everything.

• AGENTS.md — 600+ lines of project rules. Not guidelines, not suggestions — rules. The agent reads this on every invocation and knows exactly how this project works.

• version.json — The canonical version. One file. Every other version reference in the project is derived from this file mechanically.

• required-app-bins.sh — A binary inventory. Single source of truth for what goes in the app bundle.

• privileged-action-surface-baseline.txt — And, of course, the security surface. This is a CLI command routing table + App Intent permission scopes, diffed against on every build that goes through the pipe.

Each skill file IS the context.

This $zip is a 409-line instruction set. The agent reads it and has everything it needs to execute the pipeline. No Confluence page. No Google Doc. No Slack thread from six months ago. If the agent can’t see it in the repo, it doesn’t exist.

Tip: Put your golden principles in the repo, not in documentation systems the agent can’t reach.

I keep seeing teams with build instructions in Notion or wiki pages that the AI agent has no access to.

Your repo IS the documentation.

Your skill files ARE the runbook.

Collapse the distance between “where the instructions live” and “where the agent does it’s work” to absolute zero.

Pillar 2: Golden Principles

Opinionated, mechanical rules encoded in the repo.

Not aspirational. Enforced.

Sorry AI. It’s not gen-AI spaghetti meme time any more. Serious work only.

AGENTS.md enforces things like bash 3.2 compatibility (because macOS ships this ancient tool and it just works), bottom-up code signing (because codesign --deep is a trap — more on that later), overlay-only vendor mods, and version format 0.XXX.

But here’s the critical insight from practice: Golden principles as instructions are good. Golden principles as enforcement hooks are better.

Here’s an example of a pre-tool hooks firing before the tool executes. They’re not instructions the agent might ignore — they’re physical barriers:

• block-rm.sh — rm -rf — Prevents catastrophic deletion.

• guard-force-push.sh — git push --force — Protects commit history.

• guard-codesign-deep.sh — codesign --deep — Forces bottom-up signing discipline.

• guard-vendor.sh — Direct edits to core libraries — Enforces surgical edits overlay-only mods.

• guard-sensitive-file.sh — .env, .pem, .key credentials — Prevents secret exposure.

You see, the agent doesn’t need to “remember” not to use codesign --deep. It physically can’t. The hook intercepts the command before it executes. The agent never sees it succeed.

That’s a harness and it’s the difference between hope and agentic engineering.

Tip: Identify your top 5 failure modes and make them impossible.

For me it was: destructive deletion, force-pushing, top-down signing, vendor directory mutation, and secret exposure.

Each one has a 5-line bash hook that blocks it.

Total investment: Maybe 2 hours.

Value: Incalculable.

Pillar 3: Architectural Constraints

Rigid boundaries with validated interfaces. I can’t stress this enough.

It’s counter-intuitive to think about putting any constraints on any AI but that’s what a “harness” literally is. And you, as a newly-knighted harness engineer, can control and instrument it all. The architectural constraints allow for laziness-maxing as an engineer so hard.

Why? Because I don’t have to worry if the toolkit and runbook is going to knife me in the back by doom-looping their way through my token quota.

So, here’s what I do:

• Strict dependency direction: Skills call scripts, scripts call shared libraries, shared libraries never call skills. No circular dependencies. No ambient authority.

• Shared libraries centralize invariants: Signing identity, version parsing, binary inventory, locking, mount utilities, signature verification.

• Verification checks validate boundaries at three stages: pre-build (13 checks, runs in seconds), during-build (44 core checks), and post-build (8 check categories including Mach-O binary forensics).

The architectural constraint I’m most proud of something too simple to give much more attention than a few lines: Triple verification. Many checks run at multiple stages intentionally: Sparkle for Appcast XML, Core changes Mach-0 fingerprint scan, and Binary Signing with a bundle-wide scan.

A single verification layer is a gate. Triple verification is defense in depth.

Zig packaging can corrupt plists. Sed replacements can miss edge cases. Each layer catches things the others don’t. A bit of self-governance based on the prescribed agentic harness.

Can we call all of this autonomous engineering? I honestly don’t know. But, it kind of feels like that sometimes.

4. Build a Useful Skill Taxonomy

Not every task is equally fragile.

The key design insight — straight from the Codex team’s guidance — is to match the level of specificity to the task’s fragility.

Don’t skip that part. I know I did.

So, keep it simple and follow the instructions. They exist to help you! Use text-based instructions when multiple approaches are valid and use specific scripts when operations are fragile and consistency is absolutely critical.

Here’s the running taxonomy for YEN’s compilation skill:

• Hard-Gated Pipeline for fragile, high-stakes: explicit steps, HARD GATES, fail-closed, concurrency locks, no-recovery restart.

• Quality-Gated Workflow for assessing quality gates and instant rollback on failure.

• Multi-Agent Delegation for an adversarial, read-only review that spawns specialized sub-agents including a “Devil’s Advocate” for self-correction.

• Simple Automation for low fragility tasks that are single-purpose and only a few steps..

• Cross-System Delegation for finding the “meta” pattern in work, orchestrating different models for un-biased audits.

But, the big one — of course — is $zip because code signing, notarization, and DMG packaging are very, very fragile. It just works or it doesn’t.

There’s no middle-ground. As it should be. In contrast, my $check skill is 24 lines long because lint + typecheck is not supposed to be fragile.

This isn’t arbitrary; it’s purpose-built and highly calibrated.

The multi-agent skills deserve a callout. $team and $team-mac spawn 8 specialized agents for code review — and the last agent is a Devil’s Advocate that challenges every recommendation from the other 7.

Essentially a built-in “bullshit” meter.

It checks severity ratings, flags false positives, and identifies contradictions.

This is adversarial self-correction built into the agentic skill structure. The coordinator synthesizes the challenges with the original findings into a single output artifact.

One file, one source of truth.

The first-time I ran this I couldn’t actually believe it worked as advertised. I already felt like I had super-powers, but now I have an entire team at my disposal, on-demand when I really need a host of different perspectives on my work.

And this now even includes an SEO and GTM strategist helping me out (for a relatively small token fee) on every single public release.

God, it feels like a bit of magic on every compile…

… because I fucking hate marketing.

Tip: Before building a skill, classify the task’s fragility level. High fragility (signing, deployment, security) gets hard gates and fail-closed defaults.

Medium fragility (dependency updates, deployments) gets quality gates with rollback.

Low fragility (linting, formatting) gets simple pass/fail. Don’t over-constrain simple tasks — it wastes tokens and time.

Don’t under-constrain fragile tasks — it ships bugs.

5. Polyglot Challenge — 30 Languages, One Pipe

Most build systems deal with a handful of languages, maybe a dozen. A Go project compiles Go. A Swift app compiles Swift.

But YEN’s pipeline is crazy-stupid complex: It compiles Swift + Zig + Go + C + Metal + GLSL, and then transforms Swift + JSON + XML + Plist + pbxproj via sed / Python patching, and then verifies artifacts across 14 languages, signs outputs in 5 formats, and bundles 14 language runtimes into a single .dmg file.

Any upstream update can introduce changes in Zig, Swift, C, Metal, GLSL, Gettext, or pbxproj simultaneously. Totally fine. We good.

The overlay system handles all of them in one idempotent pass and the verification system catches any leaks across all of them. The signing system walks the entire bundle regardless of which languages contributed which binaries.

And all of that sounds great and all but why is this important?

Because I’m getting old.

Simply put, I no longer can remember all of these languages and their nuanced syntax with the level of expertise required for a project of this scope an size. Context-switching between all of these different interfaces is just not possible for me, especially at the speed that I want and my users demand.

They don’t want to wait for a quarterly release cycle to fix a major bug or wait for an obvious quality-of-life improvement that everyone’s agreed is a good idea.

We need good tools so that we can become super-human. And a well-thought out agentic harness is one route to these new superpowers.

In a real way we are all going to become polyglot builders and engineers, in our thinking and our use of best-in-class technology.

I think we’re already there.

So the actual output of a single $zip invocation is:

1. A signed, notarized, stapled .DMG uploaded to Supabase Storage.

2. Updated Sparkle appcast (XML, EdDSA-signed) for the auto-update framework.

3. Updated sound pack + manifests + EdDSA signatures (if source changed).

4. A deployed Next.js web app on Vercel’s edge (download page, public docs, 6+ API routes, SEO artifacts, analytics).

5. A versioned git commit with SHA-256 checksum file.

6. Updated internal documentation (~15 core Markdown files).

7. Supabase cleanup of old release artifacts; retention is set for last 3 versions.

You get a compile! You get a compile! Everyone get’s a compile! In the end I get a fully-baked desktop app + entire web presence + APIs + auto-update infrastructure + chat backend artifacts + documentation… all from one single skill command.

Takes about ~15 minutes.

Coffee time.

6. Codex-Native Skills: Progressive Disclosure and Machine-Evaluable Evals

I originally got my skill start using Claude Code — which I still love and use but for very different and specific purposes — but Codex has allowed me to have the refinement that I truly need for a complex, solo-engineer project of this magnitude.

Codex gave me things like structured telemetry, machine-evaluable evals, and respected completion demands like my three-layer verification all while calling the exact same underlying, trusted bash scripts.

Zero behavioral changes. Pure additive instrumentation.

Progressive Disclosure

Codex recommends keeping SKILL.md under ~500 lines and using references for detail. I implement three disclosure levels:

• Level 1 — SKILL.md front-matter for skill discovery, costing about ~100 tokens.

• Level 2 — SKILL.md body includes phase map, protocols, and all guards at invocation, costing about ~800-1000 tokens.

• Level 3 — Individual reference file(s) for current phase of execution, about ~200-600 tokens.

The agent never loads all references at once and my custom Phase Map table smartly routes the agent through each phase to a specific reference file so there’s no possibility of drift or contamination.

In other words, the agent reads only the reference it needs for the current phase, then moves on. I don’t constrain the model’s speed nor intelligence, I’m just telling it to not run off the road. The context window usage stays proportional to the current task, not the total skill complexity.

Just like the mama Codex always said.

Three-Layer Verification

To call it a “harness” feels weird at time because I don’t feel limited by the constraint; I feel empowered to move faster with greater confidence that every mistake is documented and then fixed and then proven via a successful compilation.

The verifications allow me to do this as part of the harness infrastructure. Another way of thinking about this is purely economical: It’s about conserving the model (and you) time by providing unambiguous guidance for repetitive, discrete, and predictable, deterministic outcomes.

But it’s on you. I have 3:

1. Script verification for build correctness with simple, existing bash scripts.

2. Agent verification for agentic decisions for things like CWD, version format, commit message, and branch using a single .sh script.

3. Eval verification for phase outcomes as machine-readable JSONL.

Why agent verification is separate from script verification is this: A script can exit 0 (correct build) while the agent made a wrong decision (wrong version format, wrong commit message, forgot to return to repo root).

Script verification validates the artifact. Agent verification validates the orchestration.

They’re orthogonal concerns. But we do them all for good measure.

Evals for Dummies: Telemetry as Append-Only JSONL

Evals aren’t that hard any more. I’ll show you.

So, I have 4 event types: phase_start, phase_end, gate, retry. JSONL — not JSON — because appending to an array requires reading + parsing + rewriting. JSONL is always a valid file after any echo >> append.

In my case, if the build crashes mid-phase, I still want all all prior events to be intact. I don’t want to waste any effort if I can.

No jq dependency for writing. Bash 3.2 compatible. Zero external dependencies. This telemetry answers:

1. Which phases take longest?

2. Which gates fail most?

3. How often do retries trigger?

These things make my current and future life easier because I have clear, time-stamped documentation on not just compiling time but now it’s relationship to the model’s actual speed through a prescribed task. I can see the correlation and I am aware of the causation to any changes in my core skill tree and the time it may take to run the full compile.

And I’m in complete control of those things. Of course, you can also poll for live reads on progress in the CLI if you’re building large systems because your ADHD doesn’t allow you to relax.

It’s a mad, mad world.

Tip: Use JSONL for build telemetry, not JSON.

It’s append-only, crash-resilient, and requires no parsing library to write. A crashed build at step 5 preserves telemetry from steps 1-4.

With JSON, a crash mid-write corrupts the entire file.

Boohiss.

7. Reproducible Patterns You Can Copy

Let me be specific about what you can take from this and apply immediately.

These are patterns, not YEN-specific implementation details and much of this comes directly from the source.

Pattern 1: The Skill File Structure

Every skill should follow this layout:

skill-name/
  SKILL.md                    # Orchestrator (what to do, in what order)
  agents/openai.yaml          # Interface config
  scripts/                    # Executable automation
  references/                 # Phase-specific detail (loaded on demand)
  assets/                     # Static resources (schemas, templates)

SKILL.md establishes the frame with clear boundaries, phase routing, success criteria. Scripts are self-contained with clear dependencies.

References are progressive disclosure and the agent loads them one at a time as needed. Assets are static resources that don’t change between invocations.

Pattern 2: Fail-Closed Gate Variables

Apply this pattern to any gate in your pipeline. The default is always “block.” Here’s how it literally looks in my codebase:

# Every gate defaults to enforce. Override requires explicit opt-in.
YEN_DMG_LAYOUT_GATE_MODE=”${YEN_DMG_LAYOUT_GATE_MODE:-enforce}”

if [ “$YEN_DMG_LAYOUT_GATE_MODE” = “enforce” ]; then
    # Gate logic here — failure blocks the pipeline
elif [ “$YEN_DMG_LAYOUT_GATE_MODE” = “report” ]; then
    # Same logic, but failure is a warning, not a blocker
fi

Emergency bypass requires setting an environment variable — which means it shows up in logs, is searchable, and creates accountability.

Pattern 3: Categorized Retry

Every retry point in the pipeline classifies errors.

is_retryable_error() {
    local output=”$1”
    # Transient: retry
    echo “$output” | grep -q “FileNotFound” && return 0
    echo “$output” | grep -q “connection reset” && return 0
    # Structural: don’t retry
    return 1
}

Retryable errors get retried with cleanup between attempts. Non-retryable errors fail immediately. The worst thing you can do is retry a real error — it wastes time and can mask the actual failure.

Pattern 4: Pre-Tool Hooks

#!/bin/bash
# guard-codesign-deep.sh — blocks codesign --deep
if echo “$TOOL_INPUT” | grep -q ‘\-\-deep’; then
    echo “BLOCKED: codesign --deep produces invalid nested signatures.”
    echo “Sign bottom-up: innermost binary first, outermost app last.”
    exit 1

Five lines. An intentional physical constraint. The agent will never successfully execute codesign --deep. This is stronger than any amount of “vibe coding”; it’s actual (harness) engineering.

It’s knowing what will rekt you and then programming it into the machine. Identify your catastrophic failure modes and make them effectively impossible.

Pattern 5: Source-Only Checks Before Compile

Never spend 10 minutes compiling code that will fail a 2-second check.

Step 4:  Component verification  →  reads SOURCE files only  →  seconds
Step 5:  Build                   →  compile + sign + package  →  10+ minutes

I initially had some verifications running post-build. Moving source-only checks to pre-build was one of the highest-leverage changes I made — it saves 10+ minutes on every caught issue.

Pattern 6: Append-Only JSONL Telemetry

emit_telemetry() {
    local event=”$1” phase=”$2” metadata=”$3”
    local ts
    ts=”$(date -u +%Y-%m-%dT%H:%M:%SZ)”
    echo “{\”ts\”:\”${ts}\”,\”skill\”:\”${SKILL_NAME}\”,\”event\”:\”${event}\”,\”phase\”:\”${phase}\”${metadata:+,${metadata}}}” \
        >> “${TELEMETRY_DIR}/${SKILL_NAME}-$(date +%Y-%m-%d).jsonl”
}

No dependencies. Crash-resilient. Bash 3.2 compatible.

Drop this into any pipeline and start collecting data about where time is spent.

Pattern 7: Success Criteria as a Contract

Define what success looks like before writing the skill.

## Success Criteria
- Outcome: Signed, notarized, uploaded DMG; appcast updated; git pushed
- Process: All 12 steps completed sequentially; no step skipped
- Style: Zero manual intervention; all verification gates passed in enforce mode
- Efficiency: Full build completes in under 20 minutes

The criteria that you want will span these four dimensions:

1. Outcome: What was produced.

2. Process: How it was produced.

3. Style: How clean was the execution?

4. Efficiency: How long did it take?

This turns “did it work?” from a subjective judgment into a measurable contract.

8. In Conclusion

The patterns described in this post are not YEN-specific. They’re design principles that you can use for your own projects and skill library:

1. Enforcement beats instruction. If a rule is important, don’t just write it in the skill — enforce it at the tool level. Hooks beat just vibin’ it every single time.

2. Match constraint depth to fragility. A lint check needs one gate. Code signing may need 10 times that. Over-constraining simple tasks wastes tokens. Under-constraining fragile tasks ships bugs. Calibrate.

3. The repo is the single source of truth. If the agent can’t see it in context, it doesn’t exist. Put your golden principles in the repo, not in documentation systems the agent can’t reach. This seems obvious to some but not to a lot of folks still.

4. Fail closed by default. Every gate should default to “block.” Emergency overrides should require explicit opt-in, be logged, and create accountability.

5. Source checks before compile. Never spend 10 minutes building something that will fail a 2-second source check.

6. Categorize your retries. Retrying transient errors is resilience. Retrying structural errors is waste.

7. Design for crash recovery. Your locking, your telemetry, your state management — all of it should survive a crash at any point in the pipeline.

8. Triple verify the things that matter most. Pre-build, during-build, post-build. Each layer catches things the others miss.

The age of AI-orchestrated build systems is here. I’m living it every single day.

And I can never go back.

The question isn’t whether to use AI agents with a harness in your pipeline — it’s whether your harness is good enough to actually constrain them to maximize output.

Build the harness first. Make the catastrophic failures impossible. Then let the agent do what agents do best: Read output, make decisions, handle the unexpected, and move fast through a well-defined protocol.

I ship a 30-language desktop app from a single command. The pipeline has never shipped a bad release. And I sleep well at night — not because the AI is perfect, but because the harness makes what we’re doing together safe.

And may you have sweet, sweet agentic dreams.

— 8

In a previous post, I talked about selling pickaxes during the AI gold rush — why terminal infrastructure compounds quietly while flashy applications grab headlines.

A few people asked me to go deeper on one specific claim: That bundling CLI tools like fd, ripgrep, and fzf is a meaningful feature, not a gimmick.

Subscribe now

Fair question. Let me answer it by walking through every tool YEN ships, why each one exists, and why the bundle as a whole is the product.

The Problem With “Just Install It”

Here is a scenario every developer has lived through.

You open a new terminal. You try to search your codebase. Oh wait — you haven’t installed ripgrep yet on this machine. So you brew install ripgrep. Then your file manager plugin wants fd. Then your fuzzy finder needs fzf. Then you realize bat isn’t configured with the right theme, and zoxide doesn’t have your directory history, and the versions are mismatched, and now you’ve spent forty-five minutes on tool setup instead of actual work.

Damn. What a waste.

Multiply that by every machine you touch. Every fresh OS install. Every coworker you try to onboard.

The terminal ecosystem has extraordinary tools. What it has never had is a (hyper-opinionated) curator. Someone who says: These proven power tools work together, they are pre-configured, pre-signed, and ready on first launch. No homebrew. No dotfile archaeology. No version conflicts.

That is what YEN does. And that is a harder problem than it sounds. But, it’s totally worth it because it elevates the user’s abilities while minimizing onboarding time.

That’s a win.

The Present Tool List

Eleven third-party tools ship inside YEN, alongside the terminal engine itself — twelve vendored binaries total, all signed and updated together.

Every tool listed below ships inside the YEN application bundle. Each binary is individually code-signed and notarized by Apple. They are updated together through a single vendor pipeline.

They work on first launch with zero configuration.

Magic.

Yazi — The File Browser

Replaces: ranger, nnn, lf
Written in: Rust (Tokio async runtime)

What makes a file manager “modern” is not aesthetics — it is whether the UI freezes when you open a directory with twenty thousand files. Ranger is single-threaded Python. It chokes. nnn is fast but minimal — no preview, no plugins, no image support. lf is Go and reasonably quick, but its ecosystem is thin.

Yazi runs directory reads, thumbnail generation, and file operations on separate async tasks. You navigate a directory with ten thousand entries and the cursor moves instantly because rendering never waits on I/O.

It supports image preview via terminal graphics protocols, has a Lua plugin system, and — critically — it delegates to specialized tools for specific tasks instead of reimplementing everything badly.

This is why Yazi is the orchestrator. It calls fd for search, ripgrep for content grep, fzf for fuzzy selection, bat for syntax-highlighted preview, zoxide for directory jumping, and jq for JSON parsing. Each tool does one thing well. Yazi composes them into a cohesive experience.

In YEN, you hit Cmd + Shift + O (or just type “y” off the shell) and you are in a file browser that took zero seconds to configure. Git status indicators, syntax-colored previews, cd-on-quit. Forty-five lines of Swift integration replaced 850 lines of custom file-browser UI we prototyped and threw away.

fd — The File Finder

Replaces: find
Written in: Rust

If you have ever typed find . -name “*.ts” -not -path “*/node_modules/*” and thought “this is absurd,” well, then fd exists for you.

fd respects .gitignore by default. It parallelizes directory traversal across CPU cores using the ignore crate — the same one ripgrep uses. It has smart case matching. It uses regex. On a large repository, fd finishes a file search five to ten times faster than find because find walks the tree single-threaded and searches everything — including the 200 MB of node_modules you never wanted to look at.

In YEN, Yazi delegates all file search to fd. When you type a query in the file browser, results appear instantly. That speed comes from fd, not from Yazi being clever about I/O. The right tool for the job.

ripgrep — The Content Search

Replaces: grep, ag (Silver Searcher), ack
Written in: Rust (by Andrew Gallant, aka BurntSushi)

ripgrep is one of the most important command-line tools written in the last decade. It uses a finite automata-based regex engine that avoids catastrophic backtracking — a class of bug where a pathological regex pattern causes grep to hang for minutes. ripgrep cannot hang. The algorithm guarantees linear-time matching.

It also respects .gitignore, searches files in parallel, skips binary files automatically, and handles Unicode correctly. On benchmarks against grep, Silver Searcher, and ack, ripgrep wins on every workload and it is not close.

In YEN, ripgrep powers content search in the file browser. The difference between ripgrep and grep is the difference between “search is instant” and “search is tolerable.” When you are navigating a codebase, that gap changes your behavior — you search more, you explore more, you find things faster.

fzf — The Fuzzy Finder

Replaces: nothing (created the category)
Written in: Go

fzf invented interactive fuzzy finding for the command line. There was no predecessor because nobody had built a real-time, interactive filter that works as a Unix pipe. You feed it a list — file names, grep results, git branches, shell history, anything — and it renders a TUI where you type characters and the list narrows in real time.

The matching algorithm is a modified Smith-Waterman — borrowed from bioinformatics sequence alignment — tuned for human typing patterns. Go was the right language choice because goroutines handle the concurrency model cleanly. Readers, matchers, and renderers run in parallel, so typing never blocks even on a million-line input.

In YEN, fzf is the glue between tools. Yazi pipes fd results through fzf for interactive file picking. The experience is: you hit a key, you start typing, the entire codebase narrows in real time. No configuration. No key binding setup. It works because the tools were designed to compose.

zoxide — The Directory Jumper

Replaces: cd, autojump, z, fasd
Written in: Rust (SQLite backend)

Every developer has a handful of directories they visit constantly. Typing out a full path six directories deep is not a reasonable thing to do every day. Classic solutions like autojump and z were shell scripts backed by text-file databases that degraded over time and broke on concurrent access.

zoxide uses a “frecency” algorithm — frequency multiplied by recency — stored in SQLite. You visit a directory, it records it. Next time you type z settings and it jumps to the right place. SQLite handles concurrent access correctly, which matters when you have multiple terminal tabs.

In YEN, zoxide powers quick directory jumping inside the file browser. The directories you visit most frequently rise to the top. Your muscle memory from shell z shortcuts carries directly into the file browser.

bat — The File Viewer

Replaces: cat
Written in: Rust (syntect library, Sublime Text grammars)

bat is what cat should have been. Automatic syntax highlighting for over 200 languages. Git diff markers in the gutter. Line numbers. Paging. Themes.

The key technical detail: bat uses the syntect library, which loads Sublime Text grammar files. These are the same grammars used by VS Code and Sublime Text — battle-tested, comprehensive, accurate. When bat highlights your Python file, it is using the same parser rules as your editor.

In YEN, bat serves double duty. The file browser’s pane preview uses bat for syntax coloring. When you press Enter for full-file view, it opens the same file with the same bat theme. Preview and full view never drift because they use the same rendering engine. The theme is bundled and configured at build time. One thing that just works.

jq — The JSON Processor

Replaces: nothing at this level of capability
Written in: C (custom parser, bytecode VM)

jq is the oldest tool in the bundle and the least “modern” by the Rust-wave definition — it shipped in 2012. But it remains the undisputed standard for command-line JSON processing because nobody has built anything better.

jq has its own query language. You can filter, transform, map, reduce, and restructure JSON with expressions that would take twenty lines of Python. The C implementation compiles to a tiny binary and executes instantly.

In YEN, Yazi’s plugins use jq to parse JSON metadata — file info, archive contents, git status. It is the one-megabyte binary that eliminates the need for embedding a full scripting runtime just to read a config file.

lazygit — The Git UI

Replaces: memorizing git rebase -i, git add -p, git stash
Written in: Go (gocui TUI library)

There are two kinds of developers: those who are fluent in interactive rebase, and those who are honest about it. lazygit gives the second group — and the first, when they are tired — a visual interface for staging hunks, resolving conflicts, managing branches, stashing, cherry-picking, and rebasing. All keyboard-driven in a TUI.

Go’s goroutine model means git operations run asynchronously without freezing the UI. You can stage a hunk and the diff updates in real time while git is still writing.

In YEN, lazygit is accessible via the lazygit command. It is a full visual git client that never leaves the terminal. The kind of tool that makes people stop reaching for a GUI app.

resvg — The SVG Renderer

Replaces: librsvg, ImageMagick SVG path, Inkscape CLI
Written in: Rust (tiny-skia, a Skia subset in pure Rust)

SVG rendering sounds simple until you try to do it without pulling in the entire GNOME graphics stack. librsvg depends on Cairo, Pango, and GLib. ImageMagick’s SVG support is inconsistent. Inkscape is a 200 MB desktop application.

resvg achieves strict SVG spec compliance — it passes the SVG test suite better than most browsers — in a statically-linked binary with zero system dependencies. It does this by implementing its own 2D rendering engine in pure Rust, avoiding the transitive dependency nightmare entirely.

In YEN, resvg is the fallback for SVG thumbnail generation. The primary path uses macOS native APIs, which handles most cases. resvg catches the edge cases where the native renderer diverges from spec. Native first, vendor for the gap.

btop — The System Monitor & fastfetch — The System Info

btop (C++) is a full-dashboard system monitor — CPU, memory, disk, network, GPU, all on one screen with real-time graphs. We compile it from source because upstream does not publish macOS universal binaries. fastfetch (C) is the spiritual successor to neofetch — instant system info in fifty milliseconds instead of three seconds, using native macOS APIs instead of shell subprocess spawning.

Together they close the gap between “tools for your code” and “tools for your machine.” We wrote a dedicated post about both with the full technical story — why btop requires a source build, how fastfetch replaced neofetch’s architecture, and the vendor pipeline details.

The Bundle Is the Product

Here is the part that matters more than any individual tool.

A terminal that ships fd, ripgrep, fzf, zoxide, bat, jq, lazygit, resvg, btop, and fastfetch alongside a Rust file browser is not just a terminal with some extra binaries. It is an integrated environment where the tools are pre-configured to work together.

The Neovim problem, solved differently.

Power users who build terminal-native development environments from scratch assemble roughly this same stack. Neovim plus telescope plus treesitter plus fzf plus ripgrep plus lazygit — the tools are almost identical.

The difference is the setup cost. A productive Neovim configuration takes hours to days. Plugin conflicts are common. Version mismatches break things. Upgrades require debugging Lua.

YEN ships the same capabilities with zero configuration. Not because the tools are simpler — they are the exact same tools. Because the configuration is done once, at build time, and tested together before it ships.

The IDE problem, inverted.

Most IDEs are text editors that bolted on a terminal panel. The terminal is an afterthought — a small rectangle at the bottom of the screen where the AI features stop working. Type a shell command in Cursor and the AI context evaporates.

YEN takes the opposite approach. Start with the fastest terminal on macOS — a GPU-accelerated Zig/Metal engine rendering at 60 FPS with sub-millisecond input latency — and add IDE capabilities directly inside it. The file browser, the git client, the search tools — they all render where your cursor already is. Over SSH, they work identically. AI coding tools like Claude Code already run in the terminal. YEN gives them the best possible runtime.

Every binary is signed.

This matters more than developers realize. macOS code signing and notarization require every embedded Mach-O binary to be individually signed.

YEN’s build pipeline signs all eleven tools (plus the terminal engine — twelve vendored binaries total), verifies entitlements, and notarizes the bundle as a unit. If you download these tools separately via homebrew, they are unsigned. Gatekeeper will warn you. Some enterprise machines will block them entirely.

One update command.

When ripgrep ships a new version, it flows into YEN through a single vendor update pipeline. All twelve vendored binaries are checked, downloaded, baseline-tracked, signed, and shipped together. No dependency hell. No “which version do I have” debugging.

Nine of the eleven tools are written in Rust or C/C++ — compiled to native code, zero runtime overhead, statically linkable. The two Go binaries (fzf and lazygit) are still single-binary with no transitive dependencies. Every tool in the bundle was chosen because it does exactly one thing, does it better than the alternatives, composes with Unix pipes, and ships as a single binary. That pattern is the design decision.

The terminal has survived every platform shift for sixty years — teletypes, minicomputers, PCs, the web, mobile, cloud, and now AI. It survived because the interface contract is simple and the composability is real.

YEN’s bet is that curating the best terminal tools, signing them, testing them together, and shipping them as a single app is more valuable than any one feature.

If you start from first principles — what does a developer actually need every single day — you end up with a fast terminal, a good file browser, instant search, fuzzy finding, smart navigation, syntax preview, a git client, and system monitoring.

Not as separate homebrew packages you configure yourself. As a thing that works when you open it.

That is the toolbox under the hood. And it keeps getting better and better.

— 8

YEN’s settings window got an overhaul. Not because the old one was broken — it worked fine. But “fine” is not the bar we aim for, and the toolbar tab pattern had started showing its limits.

Subscribe now

Here is what changed, why, and how we shipped it without breaking anything for existing users.

The Problem With Toolbar Tabs

macOS settings windows have used toolbar tabs since the System Preferences era. Five icons in a row, click to switch. It works.

Until it doesn’t.

The moment you have more than five or six categories, the toolbar gets crowded. Labels get truncated. The window stretches. You cannot search. You cannot see descriptions. You are clicking icons and reading tiny labels, hoping you guessed the right one.

YEN had five settings categories — General, Sounds, Workspace, Themes, Keyboard — and even at five, the toolbar felt like it was working against us. Every category was a single word and a symbol. No context. No grouping. No way to discover what lived where without clicking through each tab.

We looked at how the best macOS apps handle settings today. Raycast. Linear. Arc. The pattern is clear: A left sidebar with icons, titles, descriptions, and grouped sections. It scales. It is searchable. It communicates hierarchy. And it feels native on modern macOS.

So I rebuilt it.

What Changed

There are a bunch of changes but I’ll try to keep this concise since I have a terrible habit of over-sharing:

• Sidebar Navigation: The toolbar is gone. In its place: a fixed-width left sidebar with two grouped sections — Primary (General, Sounds) and Workflow (Workspace, Themes, Keyboard).

• Search Moved to the Sidebar: Global settings search used to live at the top of the detail pane. That meant it was contextually tied to whatever tab you were on, even though it searched across all categories. Now search lives in the sidebar header, above the navigation rows. Type a query and results appear inline. Hit Return to jump to the matching category. Hit Escape to clear. The search field stays in one predictable place regardless of which section you are viewing.

• Descriptions That Actually Help: Every sidebar item now has a human-readable description, like “General — Core terminal appearance and behavior.” Simple, I know, but these aren’t just labels. They are search aliases too — type “dictation” and you land on Sounds. Type “scratchpad” and you land on Workspace. Type “palette” and you land on Themes.

• Accessibility Built In: The sidebar respects every macOS accessibility setting we could find, like reducing transparency, motion, and differentiating without color. Small things to help folks get around faster like keyboard navigation works end-to-end, no mouse required.

The small things matter, my friends!

Why This Matters

Settings is the second most-opened window in any app, after the main window itself. It is also the window where users form opinions about quality. A settings window that feels organized and discoverable signals that the rest of the app is equally considered.

The toolbar tab pattern served macOS well for twenty years. But apps have gotten more complex, and user expectations have shifted. A sidebar with descriptions, grouping, and integrated search is not a novelty — it is the new baseline.

YEN’s settings window now meets that baseline. And because the rollout is flag-gated, we can iterate on the sidebar without risking the experience for users who prefer the toolbar.

Small surfaces, big signals.

— 8

YEN now includes a native scratchpad panel! Press Cmd + Shift + J and a right-side panel opens. Type. Paste. Close it. Reopen it later. Your text is still there.

Subscribe now

Copy/paste works with standard macOS shortcuts, and mouse text selection auto-copies. No setup. No plugin. No cloud account. No extra app.

Why We Built It

When you’re deep in terminal work, random text shows up constantly:

• A command you want to run later

• A branch name from chat

• An error snippet worth keeping

• A checklist for a deploy

Switching to Notes breaks flow. Dropping text into random files creates noise. Temporary buffers disappear when they matter most.

The scratchpad is built for that exact gap: Quick capture without context switching. And you never have to leave your Terminal.

How It Works Under the Hood

It’s as simple as you might think.

1. Fixed, Predictable Shortcut — Scratchpad uses Cmd + Shift + J. It is intentionally a fixed app shortcut, shown as locked in Keyboard settings so users can discover conflicts without accidentally remapping core behavior. The Workspace tab also has a Scratchpad toggle with clear hotkey hints.

2. Right-Side Native Panel — The panel is a native floating panel that anchors to the active terminal window and slides in/out on toggle. It is keyboard-first, stays lightweight, and does not add a browser-style surface to your terminal workflow.

3. One Global Buffer — Scratchpad is app-global with one buffer, shared across windows and tabs, and holds the same content everywhere. That keeps it dead simple for fast capture.

4. Smart Fresh Start + Local Persistence — On a brand-new install, scratchpad starts with a short helper template and the cursor positioned below it so you can type immediately. After that, your own content is persisted locally in Application Support with atomic file writes. That also means that the content survives app restarts, writes are crash-safe by default, and there isn’t a sync layer and zero account dependency. Local-first!

5. Standard Editing Behavior — Scratchpad now respects the editing behavior macOS users expect: Cmd + C, Cmd + V, and highlight-to-auto-copy.

Tiny feature, big daily-use win. Open, paste, close, continue.

Only forward.

— 8