DEV Community: Yuuichi Eguchi

Seven rounds of AI code review in one day, 2,048 tests green, and the feature had never started once

Yuuichi Eguchi — Thu, 15 Oct 2026 12:55:40 +0000

Since March 2026 I have been building Calyx, a native macOS terminal for running and supervising coding agents in parallel. I work on it alone, and Claude Code writes most of the code. As of October 7, 2026 the repository has 880 commits (752 excluding merges) and 110 release tags, v0.1.0 through v0.46.1.

I run development under one self-imposed rule: every finding from the review subagent gets fixed. This post reads seven months of commit history back and pulls out what that review found and what it did not. There is no control group. Nothing here was built twice, once with review and once without, so this is not a measurement of how well AI review works. It is a record with numbers, and the last section separates what the record supports from what it does not.

The workflow

In my current setup, Claude Code subagents write all of the code. The main conversation does not write code; it plans, approves and coordinates. Every change goes through the same stages:

Plan in Plan Mode. I approve the plan.
From a clean tree, git worktree add a worktree. A test-writing subagent writes the tests and confirms they fail before any implementation exists.
Implement. A test-running subagent confirms everything passes.
A review subagent reviews the worktree's diff. Commit in the worktree. I approve.
Merge into main, then delete the worktree and the branch.

Two rules sit on top. Every review finding is fixed, none silently skipped, and I am asked only when a finding is genuinely unclear. And symptoms are never patched: when a defect shows up, the fix goes back to the primary source and addresses the root cause.

Those rules live in my local configuration, not in the repository, and the file has no history. I cannot show when each rule took effect. The oldest trace in a commit message is 7ec033794 on June 22, which fixed even suggestion-level findings and gave the reason as "ALL @code-reviewer findings MUST be fixed".

What I can use as a record is the commit bodies. Twenty-nine non-merge commits identify themselves in the subject line as responses to review or audit findings. I counted subjects containing "review", "audit" or "batch N", then removed the unrelated ones (the diff-review feature, "preview", README updates) and the comment-label cleanup discussed later. Some review fixes never say so in the subject (5f3606b94 is one), so 29 is a floor. Many of those bodies also record how many unit tests (the CalyxTests suite) ran and how many failed at that point.

July 5: seven rounds

Calyx has persistent sessions: terminal sessions that survive quitting the app. A small Rust daemon owns each shell's PTY, and each pane runs a client that attaches to the daemon. I built it in phases. Phase 3, which integrated the daemon into the app, was merged into main at 00:51 on July 5.

That afternoon and evening, the persistent-session code went through review after review. These are the rounds whose numbers made it into commit subjects:

Round	Commit	Time	CalyxTests	Diff (lines)
4	`77e50735d`	13:41	2019 run, 0 failed	+1419 / -101
5	`b7ad88913`	15:51	2028 run, 0 failed	+1479 / -212
7	`d5ae8c9cd`	17:25	2032 run, 0 failed	+916 / -215
9	`a941b245d`	18:23	2036 run, 0 failed	+536 / -64
11	`f1868a8a5`	19:08	2042 run, 0 failed	+906 / -192
13	`3c32054da`	20:03	2047 run, 0 failed	+1252 / -144
15	`1948d43a6`	20:35	2048 run, 0 failed	+224 / -105

Only rounds 4, 5, 7, 9, 11, 13 and 15 (and round 18, early the next morning) appear in commits. The commits do not say what happened in the other rounds.

The findings were real: reentrancy in the quit-confirmation flow, events dropped while the confirmation modal was up, cancellation not reaching child processes. Each round added a few tests and nothing ever failed. The fixes did not shrink steadily (rounds 5 and 13 were each larger than the round before), but round 15 came in at +224/-105 lines.

Through all seven rounds, a persistent pane had never once started inside the app.

The symptom had been visible from the beginning: panes were created and destroyed at full speed, and the window flashed. At 21:45, c842b18f1 fixed that flashing as a reconnect bug. The reconnect attempt counter was reset to zero the moment a replacement pane was created, so the backoff never grew and the retries never stopped. After that fix the retries were bounded, but the panes still died instantly.

The cause turned up only when the app was actually run and the error printed in the pane was read. At 23:00, 0040b282e fixed one problem: the HOME=<root> word at the front of the pane command was being executed as a path relative to the pane's working directory. The fix kept exec as the first word and moved the HOME assignment into arguments to /usr/bin/env. It locked a "first word is exec" contract into the tests, and 2,057 tests passed. Nineteen minutes later, cd89aab20 recorded this from the running app:

bash: line 0: exec: exec: not found

On macOS, the ghostty in the submodule (v1.3.1) runs a shell-form command by wrapping it as /usr/bin/login -flp <user> /bin/bash --noprofile --norc -c "exec -l <command>" (execCommand in ghostty/src/termio/Exec.zig). Calyx's command already started with its own exec, so the result was a double exec, and bash went looking for a program literally named exec. The commit body says the Phase 3 form had never worked inside the app at all, and that this was the real root of the pane churn that had been there from the start.

The tests did execute the synthesized command and checked the environment the child process saw. They ran it through a plain /bin/sh -c, without ghostty's exec -l wrapper, and without that wrapper a leading exec of your own is perfectly fine. ghostty's source sits in the repository as a submodule, but the review was reading the worktree's diff. Today the tests run the command through /bin/sh -c "exec <command>", emulating ghostty's wrapping, and the whole story is kept in exactly one place, a test file header:

//  This also RETIRES the entire ghostty-exec-wrapping saga the old
//  HomeStampTests file fought through, in three steps:
//  - A bare `HOME=<root>` first word resolves as a cwd-relative
//    path, field-verified broken as `bash: .../HOME=/tmp/cxpane: No such
//    file or directory`.
//  - A redundant leading `exec` is PATH-searched as a literal
//    nonexistent program, field-verified broken as `bash: line 0: exec:
//    exec: not found`.
//  - Routing through `/usr/bin/env` finally makes the `HOME=`
//    word an actual env assignment rather than a literal argv word.

(CalyxTests/Sessions/SessionCommandSynthesizerRuntimeStateDirFlagsTests.swift)

Persistent sessions first shipped in v0.29.0 on July 7, which includes the fix. No user ever received the broken form.

Fixes that introduced defects

In several places, the commit that fixed a finding produced the next round's finding. The clearest case is a small helper that carries Swift task cancellation through to a child process.

Round 11 (f1868a8a5) added a lock-guarded bridge to SystemCommandRunner so that polling a hung daemon would stop piling up orphaned processes. Round 13 (3c32054da) adopted the same bridge for Git subprocesses and added a second bridge to propagate cancellation into time-bounded daemon queries. Round 15 (1948d43a6) fixed what those two rounds had introduced. The Git adoption was a copy, so two byte-identical classes lived in two files. The branch for "already cancelled before launch" called process.terminate() directly and never set the flag that prevents a double terminate. And the time-bound bridge could fire onTimeout twice if cancellation arrived before registration. The file that exists today explains why it is one file:

// Shared by SystemCommandRunner.runInternal and GitService.run --
// was two byte-identical `private final class CancellationBridge`
// copies, one per file, consolidated here so a future fix to the
// terminate-once discipline only has to land in one place.

(Calyx/Helpers/ProcessCancellationBridge.swift)

The LSP feature shows the same shape three times in a little over half an hour on June 22. At 09:40, b649a9336 fixed seven issues the reviewer found after fix batches 1 to 3. The first was a race between stop() and startLSP(); the fix made the teardown re-read the bridge after pending startup work drained. Twenty minutes later, 2eeb6d366 fixed the fact that this re-read could also tear down the new bridge installed by a subsequent start(). Twelve minutes after that, 7ec033794 fixed the test for that fix, which would have passed against the old code too: an await between stop() and the injection let the teardown run first and bail out harmlessly, so the test could not see the regression it was written for.

One introduced defect stayed hidden for three months. LSP session shutdown waits for pending persistence work, with a two-second cap. Item 6 of b649a9336 added that cap using two unstructured Tasks, a drain observer and a timer, with only the first to arrive waking the caller. Its comment explained the choice: Task.value does not honour cancellation, so a naive TaskGroup race-and-cancel would still wait for the drain.

Two days later, on June 24, cc80ebbd3, the response to an audit that surfaced about 70 issues, rewrote that code. To stop the losing timer from living for two seconds while holding self, it switched to a withTaskGroup race followed by cancelAll(). The same diff deleted the comment warning that this shape cannot enforce the bound, and replaced it with one explaining that shutdown latency stays bounded by whichever child wins. The cap was not restored until 7edef08f1 on September 26. The current comment reads:

        // Bounded wait: cap the drain at 2 seconds. `Task.value` does not
        // honour cancellation, so a structured race (`withTaskGroup`)
        // cannot enforce the bound: the group implicitly awaits every
        // child, including a cancelled `task.value` child whose persist
        // worker is stuck in cancellation-blind work (e.g. decoding a
        // huge file).

(Calyx/Features/LSP/LSPSession.swift, excerpt)

The regression test's comment records that with the withTaskGroup version, a 2,000,000-entry persistence file kept shutdown busy for about 21 seconds. The same comment suggests why it went unnoticed for three months: there is no test hook for the persistence worker's timing, so the regression test manufactures slowness by writing a real 1,000,000-entry JSON file. The June 24 diff contained the deleted warning, but no test could say which of the two comments was right.

On July 6, 87d77f130 swept a batch of fixes (H1 to H11) to the experimental daemon handoff feature and found four defects those fixes had introduced. In one, an adopted session was left Running permanently, impossible to kill or reattach.

All of these are concurrency or lifecycle code. Fixes there close a problem by adding a state or a path, and the added path lands in the next round's diff, which is where most of these were caught. The two-second cap was different. No test could create its condition, so which of the two explanations held was decided only by whoever wrote the comment.

What review caught

Review also caught defects that had slipped past the tests. Round 9 (a941b245d) found that the production snapshot builder never saved tab.sessionRefs. The completeness tests exercised a different snapshot path that production did not use, and according to the commit, persistent sessions therefore never survived a real save and relaunch. Round 11 (f1868a8a5) made the production builder delegate to the tested path, so there are no longer two builders to drift apart.

On August 7, b7a8aa9c1 fixed a close path that set the "termination confirmed" flag without checking whether the Quick Terminal was keeping the app alive. Every other close path did that check. Trusting the flag, each window believed the app was quitting: it detached persistent sessions instead of killing them, and the last window skipped its pre-teardown save.

The test in 7ec033794 that could not fail belongs in the same group. The production snapshot path versus the path the tests checked, one close path versus the other close paths, a test versus the regression it is meant to catch: each is a mismatch between two things inside the repository, and reading both side by side tends to find it.

An audit also overturned an earlier declaration that the work was done. c372964be on June 26 fixed 14 findings and one regression from a second-pass audit, and its body says an earlier "all bugs fixed" claim was premature. The first symptom it names is that Calyx launched from Finder could not start a pyright installed through NVM. PATH augmentation used a hardcoded list, and the code that spawned language servers ignored even that augmented environment. This one is also an audit catching a defect that depends on something outside the repository, the environment the app is launched in.

What was found outside review

Like the exec story, several defects surfaced only when the real thing was run.

On August 19, 067fa4b4f fixed Codex rows in the sidebar that stayed idle forever after Codex exited. Calyx never installed a SessionEnd hook for Codex, on a premise written in the config manager's own doc comment: "Codex has no SessionEnd hook". For Codex 0.148.0 that was false. The binary's hook event enum lists SessionEnd, and writing the hook into a scratch CODEX_HOME fires it. The same experiment disproved a second recorded premise, that Codex strips Calyx's environment variables before running hooks.

On August 21, 85d84a255 captured a real opencode run that delegated to a subagent and found that session.deleted never fires at all. The code that retired child sessions on session.deleted had never run in practice, and the sets the comments said were cleaned on that same signal were never cleaned either.

5f3606b94 on June 27 started with a pyright crash I hit in real use. Calyx advertised refreshSupport: true but never registered the matching handler, and according to the commit, pyright treats the resulting -32601 reply as a fatal protocol violation. A sweep for the same class of bug found 25 of them. After those fixes, a 148-cell check running 70 tools against pyright and rust-analyzer passed in full. LSP fixes still continued afterward: 15a4a03fa in August, bc177c7f9 and 7edef08f1 in September.

bcedbc4e3 on July 7 is the commit tagged v0.29.0. Eight production call sites referenced test seams that exist only in Debug builds, so the Release configuration did not compile. The commit notes that 80 hours of Debug-only verification never tripped it.

In each of these, the fact that decided correctness lived outside the diff: how another program actually behaves (ghostty, Codex, OpenCode, pyright), or the build configuration. In the Codex case the wrong premise was written into a code comment; in the OpenCode case a comment described cleanup that never happened; and 0040b282e locked a wrong premise into the tests as a contract. A premise written into comments or tests is likely to become the yardstick a diff review checks consistency against, rather than something it checks. Checking the premise itself took running the other program.

What a shrinking review diff measures

July 5 is one feature on one day, so it is worth checking whether the same shape shows up elsewhere. The MCP Apps host landed at 14:48 on September 24 in bbff0a049: 249 files, 49,027 lines added. The commits for review passes 2 through 4 followed the same day, each smaller than the last:

Pass	Commit	Time	Files changed
2	`de6df4d14`	16:13	36
3	`27a1dd857`	19:36	13
4	`9e224b836`	22:18	6

Pass 4 was edge conditions: a negative pane width should yield a zero dock width, and the dock divider's hit area must not overlap a split divider's. In a little over two hours after it, three more fixes landed. Two of them matter here. At 00:05, c098c4f0d fixed the open-link consent prompt showing only the tail of a long URL: the text view measured itself before it had a width and stayed scrolled to the bottom. At 00:40, cac63bc88 worked around Swift 6.2.3 aborting the Release build (-O, whole-module) with a SIL ownership error inside the compiler.

Both show up as soon as you put a long URL on screen or run a Release build, and neither came out of four review passes. A shrinking review diff tells you the reviewer is finding less in the diff. It does not tell you the feature is done.

Traces the workflow left behind

Fixing every finding also left marks in the code itself. On August 20, 1c783299d removed 496 labels spread across 86 files. They named review rounds, task IDs and internal spec documents that are not in the repository, so the next reader had no way to follow them. Sentences that existed only to carry a label were rewritten to state, in the present tense, the invariant the code or test actually holds. The commit verifies the cleanup touched nothing else: with string literals masked and comment lines stripped, every file is byte-identical to before.

For a subagent writing a fix, the natural explanation is "which finding this fixes". That context exists only in the review conversation; the next person reading the code does not have it. My reading is that 496 labels piled up because that mismatch played out on every single fix.

Workflow state also ended up in commit messages. The body of a3f729d57 on July 5 says: "NOT yet code-reviewed; review before merging to main". And the round 5 and round 7 commits each include removing em dashes from lines the previous round had added. In rounds 5 and 7, the fixes from the previous round had added new violations for the next round to clean up.

What this record supports, and what it does not

First, what it cannot tell you. With no control, I cannot say how many defects review prevented overall, or whether it was worth the time. I cannot say whether human review would have done differently. I cannot say how faithfully the tests-fail-first step was followed: of 752 non-merge commits, only seven mention the RED step in their subject or body. And because the rules file has no history, I cannot say when each rule took effect.

Within the record, three things hold:

Neither an all-green unit test suite nor review fixes that end up small showed that the feature worked. The same shape appears for persistent sessions on July 5 and for MCP Apps on September 24.
Fixes to concurrency and lifecycle code introduced new defects. Most were caught in the next round. The one whose condition no test could create stayed for three months.
In the examples above, mismatches between two things inside the repository were caught by review. Apart from the Finder PATH defect the audit picked up, defects whose deciding fact lived outside the repository were caught by running the real thing, not by another review round.

Practices the record suggests

If I set up the same workflow again, the record points to these:

When a change integrates with an external program, run it in the app once before stacking review rounds. The July 5 defect would very likely have shown up in the first error message a pane printed.
When a comment states a premise about an external program, record how and against which version it was checked. 067fa4b4f checked Codex 0.148.0's binary and a scratch config. An unchecked premise is an open question, not a comment.
Run tests through the wrapping the external program actually applies.
Build Release early, with the exact invocation the release script uses.
Do not treat a claim as established until a test can create its condition. Time bounds are the typical case.
Record "all findings fixed" as the state of the review, and do not read it as the state of the feature.
Keep comments to invariants the next reader can follow. Round numbers and finding IDs belong in the commit or the review record.

The end-to-end tests had their own share of places that passed while checking nothing; that is a separate post.

About Calyx

Calyx is a native macOS terminal (MIT) for running and supervising coding agents in parallel: Claude Code, Codex, OpenCode, Hermes, Grok and pi. It has an approval inbox that collects permission prompts in one place, agent status driven by each CLI's own hooks, the persistent sessions described above, command history that agents can read, and in-terminal diff review with line comments sent back to the agent. It requires macOS 26 or later on Apple Silicon.

brew install --cask calyx

Source: https://github.com/yuuichieguchi/Calyx
Docs: https://help.getcalyx.app

Every commit cited here is in the public repository, so you can read the messages and diffs yourself.

What were my AI-written UI tests actually proving? Green XCUITests over a broken macOS terminal

Yuuichi Eguchi — Thu, 08 Oct 2026 14:57:38 +0000

Calyx is a native macOS terminal for running and supervising coding agents in parallel. Most of its code is written by Claude Code subagents, and the tests are no exception: I run a TDD loop where one agent writes a failing test and another writes the implementation. The UI tests are XCUITest, and the CalyxUITests target has more than 130 test methods as I write this.

The suite was green many times while the product was broken. The clearest case was the switch in Settings that enables persistent sessions. Clicking it did nothing, and every persistent-session E2E test passed. On the same day I found out that the UI tests had left 47 shells running against the session daemon on my own Mac.

This post groups those failures by kind. Each one starts with something specific to Calyx, but they all come back to two questions: what does this assertion actually observe, and what does this test leave behind on the developer's machine? It is written for people who have agents writing their tests, and for anyone writing E2E tests for a macOS app.

1. Where can a test observe a terminal?

XCUITest observes an app through accessibility. Buttons and labels show up as elements; the text in a Calyx pane does not. Calyx renders the terminal on the GPU with Ghostty's engine (libghostty), and the glyphs on screen never become accessibility elements.

The first persistent-session E2E test ran straight into this. A persistent session keeps the shell in a daemon outside Calyx, so you can quit the app and come back to the same shell after relaunch. The first version of the test echoed a marker string in a pane and, after relaunch, looked for it with app.staticTexts. That assertion could not pass even with a fully working session (c01be27e0).

The first fix moved the observation into a file. The pane's shell writes its own PID to a file; after the app restarts, the restored pane writes it again. Equal PIDs mean the daemon kept the same shell alive and the restored pane reattached to it.

That version still typed into the pane, and typeText sends key events to whatever app is actually frontmost on the system, not to the app under test. When the app under test loses focus, the keystrokes land in the developer's own terminal. I saw that happen twice, and about an hour later the test was rewritten to type nothing at all (62564941c). Section 4 has the story of the leak.

The rewritten test observes the daemon's ledger. Persistent sessions are owned by a daemon called calyx-session, which records its sessions in a ledger file at $HOME/.calyx/state/sessions.json. The test reads the ledger before and after the restart and asserts that the same session id is still Running with the same PID and creation time. It also asserts that attached_clients is at least 1 on both sides of the restart. The daemon keeps a session alive with zero clients attached, so matching ids and PIDs alone would not prove that the restored pane reattached.

The test reads the ledger as a file rather than asking the CLI, and there is a reason for that too. The earlier version spawned calyx-session ls --all --json from the test runner, and the output was always empty, even while the daemon was healthy (2bb1b24a2). The UI test runner is itself App-Sandboxed; codesign -d --entitlements on it showed the sandbox enabled with only a read-only file exception. A sandboxed process cannot connect to the daemon's Unix domain socket. The same query run outside the sandbox succeeded, so the problem was on the runner's side. Writes are restricted too: a write from the runner to /tmp failed, and because it was written with try?, it failed silently.

For a terminal app, the most reliable thing an E2E test can observe turned out to be the state the product writes to disk. Screen text is invisible to accessibility, the socket is out of reach, and typed keys can leak. A file the runner can read was the one channel none of those constraints touched.

2. Launch arguments and a switch that did nothing

According to the July 7, 2026 commit that fixed them (1a17867c1), the four switches in Settings > Sessions were all dead. They surfaced through user reports and a deliberate sweep for UI that looks functional but is not. The switches had no target and no action, and nothing seeded them from the stored value. Clicking one wrote nothing; reopening Settings showed it off again. There was no way to turn persistent sessions on from the UI.

Every persistent-session E2E test still passed, because every one of them turned the feature on with a launch argument before starting the app:

override var additionalLaunchArguments: [String] {
    ["-calyx.session.persistentSessionsEnabled", "YES"]
}

A -key value launch argument goes into the UserDefaults argument domain, which is read ahead of the app's own persistent domain. What these tests could check was "what happens when persistent sessions are on", not "can a user turn persistent sessions on". The switch's wiring was not on any test's path.

It was also easy to miss by hand. An NSSwitch flips its own on-screen state when clicked whether or not anything is wired to it, so at the moment you click, it looks like it worked.

The E2E test written for the fix clicks the real switch, quits through the app menu, relaunches, and reads the switch back. It deliberately avoids the launch argument: the argument domain would shadow every read of that key for the life of the process, so the test could never tell whether set() had taken effect. The relaunch matters because the Settings window controller is a per-process singleton. Close and reopen the window in the same process and you get the same NSSwitch instance you just clicked, which shows "on" whether or not anything was saved. After a relaunch, a fresh controller builds its state from what is actually on disk, and "looked like it worked" becomes distinguishable from "was saved".

A commit that evening (1cab009aa) closed the gaps found by an audit that classified every assertion in all 20 UI test classes by what it actually proves. Ten of them would have let through a defect a user would notice within a second. A few examples:

The group-switching test checked that group rows existed. It did not check that the active group changed, which is to say that the visible set of tabs changed.
Of the seven switches in Settings, one had a click, quit, relaunch, and read-back E2E test. The other six had none.
The search test checked that the search bar appeared. It now types a real query and asserts the match count and that Find Next moves.
The test for pressing Enter in the Compose box checked that the box cleared. It did not check that the text reached the terminal and ran.
The restore-after-restart tests looked only at ledger fields. They now also assert the window count and the restored tab's visible title.

Each of these tests existed, was green, and checked something. What they checked was not what the user sees. A red-first TDD loop does not catch this. The launch-argument E2E tests fail without the flag and pass with it, so they go from red to green exactly as the process asks. Red-first guarantees that an assertion reacts to something; it says nothing about whether that something is visible to a user.

3. When the test's actions are not the user's actions

The launch arguments in section 2 were a case of the test reaching a state by a path no user takes. The same gap showed up in the actions themselves, such as dragging and quitting.

After moving to Xcode 27 and macOS 27, press(forDuration:thenDragTo:) stopped delivering any mouse events to the app (516a9afe1). I instrumented mouseDown and mouseDragged on the tab view and added an app-wide NSEvent local monitor; nothing fired. click(forDuration:thenDragTo:), the same click-hold-and-drag gesture through a different XCTest code path, did deliver events.

A test that asserts a reorder happens will fail when the drag never arrives. The problem was the test pointing the other way. test_tapStillWorksAfterDrag asserts that a drag shorter than the 5pt threshold does not reorder anything and the tab stays where it was. With no drag delivered, no reorder could happen, so the test passed without exercising anything:

// `click(forDuration:thenDragTo:)`, not `press(forDuration:
// thenDragTo:)` -- see test_dragTabBarTab_reordersCorrectly's own
// comment. Using the broken `press` variant here made this
// assertion pass vacuously (no drag was ever delivered to assert
// "no reorder" against).
startCoordinate.click(forDuration: 0.1, thenDragTo: nearbyCoordinate)

An assertion that something does not happen also holds when the input never arrived. If you keep a test like that, pair it with a test that drives the same input and asserts that the expected thing does happen. When the pair goes red, you learn that the input is not getting through.

app.terminate() takes a path no user takes either (8d292b778). It sends SIGTERM, which skips AppKit's termination flow entirely. Calyx saves its session snapshot synchronously in applicationWillTerminate, and on a test-driven quit that never ran. After relaunch there was nothing to restore, and the daemon's ledger showed a third, fresh session. This time the product was right and the test's way of quitting was wrong. Mid-test quits now go through the app's own menu, the same path as a real quit. The terminate() in tearDown stays, since cleanup does not need the save.

Two more cases where the test assumed something the real environment did not provide. When a pane appears on screen, the shell the daemon started may not be reading its PTY yet. A keystroke sent in that window is silently dropped, and the test failed against a healthy pane (68b9fcf86). And initializing Sparkle, the auto-update framework, at launch put its first-run "Check for updates automatically?" dialog in front of the app under test, where it swallowed every keystroke XCUITest sent (0b9a60da9). Under the --uitesting launch argument, Calyx now skips updater setup.

4. What the test harness left on my machine

Running the E2E suite kept leaving things on my Mac. Here are three, in the order they happened. None of them showed up in the test results; the damage piled up on the developer's side instead.

Keystrokes in my real terminal

According to a July 5 commit (a3f729d57), an earlier E2E run had crashed partway through, and the echo marker the test was typing went into a real Ghostty window I had open. typeText sends keys to the frontmost app; when the app under test disappears, whatever is behind it receives them.

The first defense had two layers. The first was a separate bundle ID. A dedicated DebugUITesting build configuration gives the Calyx built for UI tests its own bundle identifier, com.calyx.terminal.e2e. According to the comment in project.yml, LaunchServices had previously been able to confuse a locally installed production Calyx with the UI-test build, letting keystrokes leak into whichever one it treated as the real app. The second layer was a guard that re-checks the frontmost app's bundle ID before every keystroke.

Later the same day, the persistent-session test moved to the no-typing design from section 1 anyway. If the test types nothing, nothing can leak.

47 zombie shells

According to the July 7 commit that fixed it (3e1aea2b8), the real daemon under my own ~/.calyx had accumulated 47 shells in a single day. The cause was the UI tests' base class. Its setUp() launched the app with no UserDefaults isolation and no HOME override. The app under test's defaults domain, com.calyx.terminal.e2e, was shared by every run, and during that period it had persistent sessions turned on. Every time a tab-creation or tab-renaming test launched the app, the app read that persistent sessions were enabled and created a session in my real daemon. The bundle-ID split from the previous section separated the test build from the production app; it did nothing to separate one test run from the next.

The fix gives every test its own UserDefaults suite, named with a fresh UUID:

let suiteName = "com.calyx.tests.e2e.CalyxUITestCase-\(UUID().uuidString)"
defaultsSuiteName = suiteName
app.launchEnvironment["CALYX_UITEST_DEFAULTS_SUITE"] = suiteName

When the app sees this environment variable, it uses that suite. After the fix, a run of TabManagementUITests added zero sessions to the real ledger.

You might expect that overriding HOME with a temp directory would be enough. In this project it was not, and I confirmed that in two places:

UserDefaults.standard goes through cfprefsd and turned out to be tied to the real macOS account, not to HOME. The first version of the Settings switch test changed HOME for every test and was still reading and writing my real e2e defaults domain.
Commands running in a pane did not inherit the HOME the app was launched with. ps aux on a live run showed each pane's command started through login -flp <username> ..., which rebuilds the shell's environment for the real user. A bare calyx-session run in a pane from a test would operate on my daemon, not the test's. So every calyx-session call a test runs in a pane passes flags that name its state directories explicitly.

Even with a per-test suite, some code went around it. Three of the seven switches from section 2 (smooth scrolling and two LSP settings) read and write UserDefaults.standard directly, without going through the isolation suite. Their test saves those three keys before it runs and restores them afterwards.

Moving HOME into a temp directory caused a problem of its own (bd79c9482). The daemon's socket lives at $HOME/.calyx/run/sessiond.sock, and with HOME under NSTemporaryDirectory() that path came to 131 bytes. The path in a macOS sockaddr_un holds at most 104 bytes, so every calyx-session attach failed instantly and the pane just kept reconnecting. Test HOME directories now live at /tmp/cxe2e-<first 8 characters of a UUID>-h, which keeps the socket path at 46 bytes at most.

92,287 lock files

According to the August 20 commit that fixed it (b4e3bf393), 92,287 lock files had accumulated under my ~/Library/Application Support. When Calyx edits an agent CLI's configuration file, it takes an exclusive lock on a lock file named after a hash of the config path. It never deletes those lock files, on purpose. If you delete a flock lock file after use, another process can recreate the path as a new inode, and two processes each end up believing they hold "the" lock. A real user has a handful of config paths, so they end up with a handful of lock files.

The unit tests, though, write to a fresh UUID temp path in every test. Every write minted a new hash and left another file behind in the real directory. The files arrived in bursts that matched test-suite runs, not any configuration activity.

The fix puts the lock directory under the test host's own temp directory whenever the code runs inside the test host. I did not do it as a per-test override, because any write creates a lock file, and a single test that forgot to opt in would bring the leak back. In the current code this redirect lives in one place, CalyxPathRoot.testRoot.

5. What typeText actually sends

Some tests still type into panes, and typeText tripped me up repeatedly.

typeText does not send characters. It presses, under the test runner's keyboard layout, the key that produces each character, and the pane turns that key back into a character under its own layout. When the command-log E2E test typed a marker containing an underscore, the pane received =, and the marker never matched (c883f2fe5).

Quotes broke too. Typing sh '<path> arrived in the pane as sh ;Su/Users/..., and sh, handed a mangled argument, started an interactive shell instead of running the script. With an IME such as Japanese input active, keystrokes become input to the IME's composition, and Return commits the composition instead of reaching the terminal.

Pasting avoids layouts and brings its own problem. On a loaded machine, Return can arrive while the paste is still being delivered and land inside the bracketed paste, and then the command never runs. That happened even with the short one-line sh '<path>'.

The current setup combines three things:

For the duration of each test, switch the input source to ABC (or US if ABC is not installed) and restore the original afterwards (InputSourceGuard).
Write the command itself to a script file and type only sh <path> into the pane with typeText. Before typing, check that the path contains only characters that need no quoting.
When a test types a command directly, route it through a helper that accepts only layout-invariant characters:

func typeIntoPane(_ line: String) {
    let allowed = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 /.;-\n")
    guard line.unicodeScalars.allSatisfy(allowed.contains) else {
        XCTFail("pane text contains a character that is not layout-invariant: \(line.debugDescription)")
        return
    }
    app.typeText(line)
}

The second change broke another test's assumption (9ba33d3e0). The focus-movement test tagged each pane by running export PANE=... and read the tag back with echo $PANE. Once commands ran from a script file inside a child sh (23999ef0a, September 9), the export ended with the child shell and never reached the pane's interactive shell. echo $PANE always came back empty, and the test failed on main until I fixed it on September 26. The tag is now the pane's tty, written to a file and compared there.

6. Rules for letting an agent run the tests

I develop Calyx with Claude Code running inside Calyx. When the agent runs the UI tests, the Calyx I am working in is running on the same machine, next to the app under test. That combination gets two rules in my local setup. Neither is in the public repository; both are my own machine's configuration.

The first is a hook that forbids concurrent xcodebuild test runs. A Claude Code PreToolUse hook inspects every Bash command, and for xcodebuild ... test it creates /tmp/.calyx-test-lock with mkdir. mkdir is atomic, so a failure means another run holds the lock. In that case the hook checks with pgrep whether a test process is really running, and if so, it denies the command. The denial reason tells the agent not to run tests in parallel, not to kill the other run, and to wait for it to finish before re-running the same command. If no test process is running, the hook treats the lock as stale, removes it, and takes it.

The second rule, written into the skill that runs the tests, is that the agent never quits Calyx on its own. The UI suite is best run with no Calyx open, but pgrep cannot tell the Calyx in /Applications from a debug build in DerivedData. A running Calyx is almost certainly the terminal I am working in, and quitting it would destroy every shell in it along with the scrollback. So the agent stops and asks, and I quit it myself with Cmd-Q. This step is never handed to a subagent, because a subagent cannot stop partway and ask a human.

The test code follows the same principle. An instance of the app under test left behind by an aborted run blocks the next run's automation connection, so CalyxUITestCase terminates such instances before launching. It only touches instances whose bundle lives under a /DebugUITesting/ build directory, never the Calyx in /Applications or a plain Debug build.

7. A checklist for the next macOS E2E suite

For each assertion, write down what the user should be seeing when it passes. An assertion you cannot describe that way only proves that an element exists.
Test settings by operating the real control, not a launch argument, then restart the process and read the value back.
Pair every "nothing happens" test with a test that drives the same input and asserts that something does happen.
Quit mid-test through the app's menu. app.terminate() is SIGTERM.
Terminal contents are not in the accessibility tree, so observe the state the product writes to disk. The UI test runner is sandboxed: it cannot reach your sockets, but it can read files.
Do not treat a HOME override as isolation. Isolate UserDefaults with a per-test suite, and isolate commands that run in a pane with explicit flags.
If test HOME directories live in a temp directory, do the arithmetic on your Unix socket paths against the 104-byte limit.
For any code that deliberately never deletes a file, check where it writes when a test calls it.
Give typeText only layout-invariant characters. Put long commands in a file, and switch the input source to ABC for the duration of the test.
If an agent runs your tests, enforce the no-concurrent-runs rule with a hook, and write "never quit the developer's app" into the agent's instructions as a step.

Having agents write tests makes the number of tests grow fast. The ten holes from section 2 were sitting inside that growing pile of green tests. What found them was not more tests; it was going back through the existing assertions one at a time and asking what each of them observes.

About Calyx

Calyx is a native macOS terminal (Swift 6, AppKit and SwiftUI, MIT) for running and supervising coding agents in parallel: an approval inbox for Claude Code and Codex permission prompts and for Grok (always-approve mode) and pi tool calls, an agent status sidebar driven by each CLI's own hooks, in-terminal diff review with line comments sent back to the agent, MCP tools that let agents read command output and language-server results, and the persistent sessions that came up throughout this post. It requires macOS 26 or later on Apple Silicon.

brew install --cask calyx

Source: https://github.com/yuuichieguchi/Calyx
Docs: https://help.getcalyx.app

What six coding-agent CLIs actually expose: hooks, permissions, subagents, and MCP config compared

Yuuichi Eguchi — Mon, 14 Sep 2026 14:56:01 +0000

Calyx is a macOS terminal for running and supervising coding agents in parallel: Claude Code, Codex, OpenCode, Hermes, Grok, and pi. Supporting six CLIs meant writing Calyx into each one's configuration and speaking whatever event mechanism it has. This post compares what each CLI exposes for four things:

Where it reads MCP servers and hooks from, and in what format
How a hook or plugin gets called, and with which events
Whether an external program can answer a permission prompt, and what happens when it does not
What it reports about subagents

Versions are pinned where Calyx's code pins them: Claude Code 2.1.251, Codex 0.148.0, OpenCode 1.18.18. Hermes, Grok, and pi are described as of mid-September 2026. Every claim comes from the integration code listed under Source at the end. Where a claim rests on a vendor's documentation rather than observed behavior, the text says so.

Summary

	Claude Code 2.1.251	Codex 0.148.0	OpenCode 1.18.18	Hermes	Grok	pi
MCP config	`~/.claude.json`, JSON	`~/.codex/config.toml`, TOML	`opencode.json`, JSON	`config.yaml`, YAML	`config.toml`, TOML	none; the extension speaks JSON-RPC itself
Env var syntax Calyx writes	`${VAR:-}` (default required)	`env_http_headers` mapping	`{env:VAR}`	`${VAR}`	`${VAR:-}` in any string field	`process.env` in TypeScript
Event transport	command hook, stdin JSON	command hook, stdin JSON	plugin callback (Bun)	none	command hook, stdin JSON, camelCase	extension API
Events	10	9	7	0	12	5 + gate
Blocking event	`PermissionRequest`	`PermissionRequest`	none used	none	`PreToolUse`	`tool_call`
Response schema	`hookSpecificOutput.decision.behavior` and friends	same envelope, `allow`/`deny` only, rejects extras	n/a	n/a	flat `{decision, reason}`	flat `{decision, reason}`
No answer means	CLI's own prompt	CLI's own prompt	n/a	n/a	deny	deny
Calyx unreachable means	CLI's own prompt	CLI's own prompt	n/a	n/a	Grok's own pipeline	the call runs
Subagents	state + current tool	lifecycle	lifecycle (synthesized)	none	state + current tool	none
Session id field	`session_id`	`session_id`	four spellings	none	`sessionId`	from `ctx.sessionManager`

How Calyx talks to a CLI

The server

One local HTTP server, bound to 127.0.0.1.
Ports 41830 through 41839 are tried in order, then a kernel-assigned port.
Every route authenticates with a bearer token: 32 random bytes, hex encoded.

The routes that matter here

/mcp: the MCP tools an agent calls (command history, messaging other agents, and so on).
/agent-event: state pings (session started, tool call started, turn finished).
/approval-request: a permission request; the connection stays open until a human answers it in Calyx or the request expires.

What each CLI needs from Calyx

The port and token.
A way to say which pane it runs in.
A way to report state.
Optionally, a way to hand over permission decisions.

Pane identity

Calyx sets CALYX_SURFACE_ID (the Ghostty surface) in the shell's environment before the CLI starts.
In persistent-session panes it also sets CALYX_SESSION_ID (the session, which survives surface re-creation).
Each CLI gets those values into an HTTP header in its own way (section 2).

How the port and token travel

MCP config is static: the URL and token are written as literals when the integration is enabled. Calyx keeps a running server alive across re-enables rather than restarting it, so the literals stay valid.
Hook and plugin traffic is dynamic: the shell scripts read ~/Library/Application Support/Calyx/agent-endpoint.json on every invocation, and the JavaScript and TypeScript pieces cache it by modification time. A restart or a rotated token never leaves a hook pointing at a dead port.

1. Configuration files

CLI	Files Calyx writes	Format	How Calyx edits it
Claude Code	`~/.claude.json` (MCP), `~/.claude/settings.json` (hooks)	JSON	Key-level merge. Calyx's own hook entries are recognized by the script filename in `command`
Codex	`~/.codex/config.toml` (MCP and hooks)	TOML	MCP: replace the `[mcp_servers.calyx-ipc]` section. Hooks: a `# BEGIN CALYX AGENT HOOKS` / `# END CALYX AGENT HOOKS` block at the end of the file
OpenCode	`~/.config/opencode/opencode.json` (MCP), `~/.config/opencode/AGENTS.md` (instructions), `~/.config/opencode/plugins/calyx-agent-monitor.js` (events)	JSON, Markdown, JavaScript	JSON: key-level merge. AGENTS.md: an HTML-comment marker block. Plugin: a file Calyx owns outright
Hermes	`~/.hermes/config.yaml` (MCP)	YAML	A `# BEGIN CALYX IPC` / `# END CALYX IPC` block spliced under `mcp_servers:` at the file's own indentation
Grok	`~/.grok/config.toml` (MCP), `~/.grok/hooks/calyx.json` (hooks)	TOML, JSON	TOML: replace the `[mcp_servers.calyx-ipc]` section. Hooks: a file Calyx owns outright
pi	`~/.pi/agent/extensions/calyx.ts`	TypeScript	One file Calyx owns outright. No MCP entry and no hook entry, because pi has neither an MCP client nor a hook system

Files Calyx owns outright

OpenCode's plugin directory, Grok's hooks directory, and pi's extensions directory each give Calyx a file of its own.
Install is a write, removal is a delete. No markers, no merge.

JSON (Claude Code, OpenCode)

Both Claude Code files and opencode.json round-trip through a JSON parser.
Calyx touches one key for MCP (mcpServers.calyx-ipc or mcp.calyx-ipc) and only its own entries under hooks. Everything else comes back unchanged in meaning.
If a hook event's existing value has a shape Calyx does not recognize, Calyx skips that event rather than overwriting it.

TOML (Codex, Grok)

TOML has no primitive for "replace my entry inside your array".
Codex MCP: the entry is a named table, so Calyx finds [mcp_servers.calyx-ipc] and replaces everything up to the next table header.
Codex hooks: [[hooks.PreToolUse]] is an array of tables with no name to search for, so Calyx appends a comment-delimited block at the end of the file.
Codex also writes to the file, and in practice it has placed its own tables between Calyx's markers. On removal Calyx extracts every table that is not positively its own (an exact [[hooks.<Event>]] plus [[hooks.<Event>.hooks]] pair whose command names a Calyx script) and re-appends it outside the block, verbatim.
Grok MCP: same section replacement, with one stricter rule. A [mcp_servers.calyx-ipc.headers] sub-table is always treated as part of Calyx's section, even with no parent header in scope, because two definitions of one TOML table are a parse error that costs the user every other MCP server in the file.
Grok's MCP entry carries no ownership marker. The entry name is Calyx's own, so a hand-written [mcp_servers.calyx-ipc] is adopted and rewritten into the managed shape rather than duplicated.

YAML (Hermes)

Calyx edits config.yaml without a YAML parser, with a regex splice in two cases.
No top-level mcp_servers: key: the block is appended at the end carrying its own parent.
Key present: only the calyx-ipc: child is inserted, indented by the unit the file already uses for its other children.
Refused rather than guessed: an inline mcp_servers: {}, tab indentation, and control characters in a scalar all raise an error.

2. MCP registration

Every entry points at http://127.0.0.1:<port>/mcp with Authorization: Bearer <token> and two identity headers, X-Calyx-Surface-ID and X-Calyx-Session-ID. What differs is how a config file says "this header's value is this environment variable at connect time".

Claude Code

"mcpServers": {
  "calyx-ipc": {
    "type": "http",
    "url": "http://127.0.0.1:41830/mcp",
    "headers": {
      "Authorization": "Bearer <token>",
      "X-Calyx-Surface-ID": "${CALYX_SURFACE_ID:-}",
      "X-Calyx-Session-ID": "${CALYX_SESSION_ID:-}"
    }
  }
}

Claude Code interpolates ${VAR} inside string values.
The :- empty default is required. A ${VAR} reference to an undefined variable fails the parse of the whole ~/.claude.json, which breaks MCP for every other terminal the user runs Claude Code in.

Codex

[mcp_servers.calyx-ipc]
url = "http://127.0.0.1:41830/mcp"
http_headers = { "Authorization" = "Bearer <token>", "X-Calyx-Agent-Kind" = "codex" }
env_http_headers = { "X-Calyx-Surface-ID" = "CALYX_SURFACE_ID", "X-Calyx-Session-ID" = "CALYX_SESSION_ID" }

Codex takes the variable name rather than a placeholder string: env_http_headers maps a header name to an environment variable name, next to the literal http_headers.
Measured on Codex 0.148.0: when the variable is unset, Codex omits the header entirely rather than sending it empty.

OpenCode

"mcp": {
  "calyx-ipc": {
    "type": "remote",
    "url": "http://127.0.0.1:41830/mcp",
    "headers": {
      "Authorization": "Bearer <token>",
      "X-Calyx-Surface-ID": "{env:CALYX_SURFACE_ID}",
      "X-Calyx-Session-ID": "{env:CALYX_SESSION_ID}",
      "X-Calyx-Agent-Kind": "opencode"
    }
  }
}

Calyx writes a third syntax, {env:VAR}.
The transport is called remote.

Hermes

mcp_servers:
  calyx-ipc:
    url: "http://127.0.0.1:41830/mcp"
    headers:
      Authorization: "Bearer <token>"
      X-Calyx-Surface-ID: "${CALYX_SURFACE_ID}"
      X-Calyx-Session-ID: "${CALYX_SESSION_ID}"
      X-Calyx-Agent-Kind: "hermes"

Calyx writes ${VAR} without a default.

Grok

[mcp_servers.calyx-ipc]
url = "http://127.0.0.1:41830/mcp"

[mcp_servers.calyx-ipc.headers]
Authorization = "Bearer <token>"
X-Calyx-Agent-Kind = "grok"
X-Calyx-Session-ID = "${CALYX_SESSION_ID:-}"
X-Calyx-Surface-ID = "${CALYX_SURFACE_ID:-}"

Grok expands ${VAR} and ${VAR:-default} inside every string field of every [mcp_servers.*] table, so no mapping table is needed.
Headers go in a sub-table.

pi

pi has no MCP client.
The extension speaks JSON-RPC to /mcp directly with fetch and sends one initialize at session start to bind the pane.
Calyx's tools reach the model through a single dispatcher tool named calyx that takes {tool, args}. One tool instead of one per IPC tool, because pi puts every registered tool's name and description into the system prompt on every turn.

The agent kind header

Codex, OpenCode, Hermes, and Grok entries carry X-Calyx-Agent-Kind.
Claude Code's entry omits it. The hook routes default to claude-code.
The /mcp route has no default kind, so a generic MCP client that has the URL and token cannot manufacture an agent row in the sidebar just by connecting.

3. Event reporting

Three transports

Transport	CLIs	Mechanism
Command hook, JSON on stdin	Claude Code, Codex, Grok	The CLI runs a program, writes the event as JSON to its stdin, reads its stdout. Calyx installs one shell script, `calyx-agent-hook`, that reads the endpoint file, guards on the pane identity variables, and forwards stdin verbatim with `curl --data-binary @-` to `/agent-event`. Codex and Grok pass their name as an argument (`codex`, `grok`); with no argument the script assumes Claude Code. Every path ends in `exit 0`, so a failed POST never breaks the user's hook chain
Plugin API callback	OpenCode	OpenCode auto-loads any JavaScript file in `~/.config/opencode/plugins/` under its Bun runtime, with no entry in `opencode.json`. The plugin exports a function that receives the working directory and returns an `event` handler, which maps OpenCode's events onto the command-hook event names and posts them with `fetch`
Extension API	pi	A TypeScript file in `~/.pi/agent/extensions/` exports a function that receives pi's extension API and registers handlers with `pi.on(event, handler)`. Same posting shape as the OpenCode plugin
None	Hermes	Calyx registers no hooks for Hermes. A Hermes row comes from the MCP connection itself; its working, blocked, and idle state comes from classifying the pane's on-screen text, the same way Calyx treats any agent it only knows through an MCP connection. The pane's own exit signal marks the row finished, when Command Tracking is on and the pane runs an interactive zsh or fish

Events per CLI

CLI	Events Calyx registers	Count
Claude Code	`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Notification` (matcher `permission_prompt`), `Stop`, `SessionEnd`, `PermissionRequest`, `SubagentStart`, `SubagentStop`	10
Codex	The same minus `Notification`	9
OpenCode	`session.created`, `tool.execute.before`, `tool.execute.after`, `permission.asked`, `permission.replied`, `session.idle`, `session.deleted`	7
Hermes	none	0
Grok	`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `StopFailure`, `StopCancelled`, `SessionEnd`, `Notification` (matcher `permission_prompt`), `SubagentStart`, `SubagentStop`	12
pi	`session_start`, `before_agent_start`, `tool_execution_end`, `agent_end`, `session_shutdown`, plus `tool_call` for the gate	5 + 1

Per-CLI notes

Codex

SessionEnd must be registered for a session to settle as finished. Without it the last event is Stop, which only means the turn ended.
Hook entries are TOML arrays of tables. The command is a TOML literal string (single quotes), so the double quotes around the script path need no escaping. A single quote in the script path is rejected up front.

OpenCode

1.18.18's plugin vocabulary has no process-exit event. session.deleted fires only when a session is actually deleted, so the pane's own exit signal marks the row finished, when Command Tracking is on and the pane runs an interactive zsh or fish.
The session identifier arrives under four spellings depending on the event: sessionID, session_id, sessionId, info.id. An event whose session cannot be resolved is dropped rather than guessed, because a guess could land on the wrong pane's row.
The working directory comes from the plugin's own directory argument.

Grok

Payload keys are camelCase (hookEventName, sessionId, toolName), event values are snake_case (pre_tool_use), and the hook file uses PascalCase keys (PreToolUse).
A /bin/sh hook script cannot rewrite JSON, so the script forwards Grok's payload untouched and Calyx's server normalizes it. Detection is on key presence: hookEventName present, hook_event_name absent.
Mapping: post_tool_use_failure to PostToolUse (a failed call still means the turn is running); stop_failure and stop_cancelled to Stop; subagent_end accepted as an alias of subagent_stop; notification to PermissionRequest only when notificationType is permission_prompt.
Grok fires an observe-only stop at teardown whose reason is channel_closed or shutdown. A stop whose reason is not end_turn passes through unmapped.
Grok defaults Stop and SubagentStop hooks to 600 seconds because those gates commonly run builds. Calyx pins its fire-and-forget entries there to 10 seconds to keep them off the turn's critical path.

Event payloads carry neither a session identifier nor a working directory. The extension reads the session id from ctx.sessionManager.getSessionId() and the directory from ctx.cwd.

4. Permission prompts

Which event blocks

CLI	Blocking event	When Calyx gates
Claude Code	`PermissionRequest`	Every request the CLI raises
Codex	`PermissionRequest`	Every request the CLI raises
OpenCode	none used	Never; `permission.asked` and `permission.replied` are forwarded as state only
Hermes	none	Never; no hooks registered
Grok	`PreToolUse`	Only under `bypassPermissions`
pi	`tool_call`	Every tool call

Claude Code and Codex

PermissionRequest fires only when a tool call actually needs approval. PreToolUse fires for every tool call, so gating on it would ask about calls the CLI was going to run anyway.
The approval entry has a 600 second timeout and no async flag. A separate 5 second entry carries the state ping; Claude Code's version of that entry additionally sets async.

Grok

Grok has no PermissionRequest event. PreToolUse is its only blocking event, and it runs before Grok's own permission system rather than in place of it: a hook deny stops the call, but a hook allow, or no answer, falls through to Grok's own deny-or-ask rules, its remembered grants, and its in-pane prompt.
Under Grok's default, auto, and plan modes (names from Grok's hook documentation), a Calyx prompt would ask a question Grok is about to ask again, and Calyx's allow could not grant anything. Only under bypassPermissions does the call run without anyone asking, so that is the one mode where Calyx gates.
The hook entry carries no matcher and fires for every tool call in every mode. The filtering happens server-side on the payload's permissionMode, which is why the hook script forwards stdin verbatim and carries no branch of its own.
Both handlers are registered on PreToolUse, state ping first, because Grok runs handlers in config order until one returns deny, and a state ping must not sit behind a gate that can block for minutes.
Grok's default hook timeout is 5 seconds, so the gate entry writes timeout: 600 explicitly. Otherwise a gate waiting on a human would be killed at 5 seconds and fail open.

pi ships no permission prompt of its own; its docs/usage.md says it intentionally does not include permission popups.
The extension registers a tool_call handler, the one place where returning { block: true, reason } stops a call. Nothing behind that gate would ever ask the user, so Calyx gates every pi tool call, and a pi request cannot be dismissed the way a Claude Code or Codex request can.

OpenCode

permission.asked and permission.replied are forwarded as state (PermissionRequest, then PostToolUse), so the row shows blocked while the prompt is open. OpenCode's own prompt answers the question.
A session with an unanswered permission.asked suppresses session.idle, so an idle event arriving ahead of the reply cannot overwrite a blocked row with idle.

Response schemas

Claude Code and Codex read a hookSpecificOutput envelope:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": { "behavior": "allow" }
  }
}

Claude Code accepts the widest vocabulary under decision: behavior: "allow"; allow with updatedPermissions; behavior: "deny" with message; deny with message and interrupt: true; allow with updatedInput for the AskUserQuestion tool.
Codex reads the same envelope but only allow, or deny with message. It rejects the entire response if updatedPermissions, updatedInput, or interrupt is present, so the Codex path never emits them.
The field is decision.behavior. The older hookSpecificOutput.permissionDecision shape from PreToolUse is not recognized by either CLI under PermissionRequest.

Grok and pi read a flat object:

{ "decision": "deny", "reason": "Denied from the Calyx approval inbox." }

Timeouts and silence

Hook-based approval paths have three timers, and their order is the invariant: the server gives up at 570 seconds, curl at 585, the hook entry at 600. Each inner layer fails before the layer outside it can.
pi's extension has the inner two: the server's 570 seconds and its own fetch deadline at 585.

CLI	Nobody answers	Calyx unreachable
Claude Code	Empty body; the CLI's own prompt takes over	Same
Codex	Empty body; the CLI's own prompt takes over	Same
Grok	Explicit deny	Grok's own pipeline runs
pi	Explicit deny	The handler returns nothing and the call runs

For Claude Code and Codex there is no "ask" value in the vocabulary. Silence is the ask.
The approval script treats curl's connection-refused exit as silent, so a stale endpoint file after a crash leaves the hook inert instead of turning every prompt into an error. curl --fail routes any non-2xx response through the same silent path rather than printing it to the CLI as if it were a decision.
Grok and pi have no fallback prompt in the situations where Calyx gates, so an unanswered request resolves to an explicit deny with its own reason text: "No approval was given in the Calyx approval inbox before the request expired."
pi fails open when Calyx is unreachable because pi turns a thrown error into a block, and an unreachable Calyx must not become a pi that cannot run any tool at all.
On no path, ever, does the approval script print allow on its own.

Cross-CLI bleed

Grok reads ~/.claude/settings.json for hooks by default, so Calyx's Claude Code hook entries also fire inside a Grok session. The approval script's stdout would become Grok's decision in a vocabulary Grok does not recognize.
Both scripts exit immediately when invoked as claude-code while Grok's GROK_HOOK_EVENT variable is set.
The user's own [compat.*] settings in Grok's config are never touched.

5. Subagents

CLI	What arrives	What the sidebar can show
Claude Code	`SubagentStart` and `SubagentStop`, plus `agent_id` on every event fired inside a subagent, including `PreToolUse` and `PostToolUse`	Child rows with state and the current tool (the command, file path, or URL)
Codex	`SubagentStart` and `SubagentStop` carry `agent_id`. Per Codex's documentation, the other hooks inside a subagent reuse the parent session's id	Child rows with lifecycle state only
OpenCode	No subagent events. `session.created` carries `info.parentID` for a child session; the plugin synthesizes `SubagentStart`, rewrites that session's later events to carry `agent_id` in place of `session_id`, and posts `SubagentStop` on `session.idle` or `session.deleted`	Child rows with lifecycle state only; the synthesized child events carry no tool fields
Hermes	Nothing	No child rows
Grok	`SubagentStart` and `SubagentStop` plus `subagentId`. `subagent_start` carries the parent's `sessionId` and names the child only through `subagentId`; every later child-scoped event carries the child's own `sessionId` and no `subagentId`	Child rows with state and the current tool, read from camelCase `toolName` and `toolInput`
pi	Nothing	No child rows

Claude Code: a session started with claude --agent foo sends agent_type without agent_id on its main thread. Deciding "this is a subagent event" from agent_type would freeze that session's parent row forever. The only reliable signal is the presence of agent_id.
Grok: a subagent has its own session, so its teardown arrives as SessionEnd rather than SubagentStop, and both names have to retire a child row. Session ids and working directories are stripped from child events so a later reattach never offers grok --resume <child>.

6. Guards outside Calyx

All six integrations live in the user's global configuration, so they run in every session of that CLI, not only in Calyx.

Shell scripts: exit 0 immediately when neither CALYX_SURFACE_ID nor CALYX_SESSION_ID is set. A claude started in Terminal.app passes through the hook without contacting anything.
OpenCode plugin and pi extension: register nothing at all when the variables are absent. For pi that matters, because a registered gate with no server behind it would block every tool call.
Grok: the hooks directory is auto-trusted, and Grok merges every .json file in it, so Calyx's file has a dedicated name that cannot collide with a user's own hook file. On a launch-time resync, a file at that path that names no Calyx script is treated as somebody else's and left alone.
herdr: an agent multiplexer that can run inside a Calyx pane. Every shell it spawns inherits that pane's CALYX_SURFACE_ID, so the value is non-empty but wrong for that shell. The scripts and the pi extension check HERDR_PANE_ID, the one variable that reliably means "this shell is inside a herdr-managed pane", and stand down. herdr reports those agents to Calyx over its own Unix socket, a separate integration outside this post.

Takeaways

Pin versions in code comments. Codex's header behavior and OpenCode's event vocabulary are facts of one measured version, and Claude Code's PermissionRequest schema replaced an older PreToolUse one. The comment that says "measured on 0.148.0" tells you which assumptions to re-check after an upgrade.
"Hook" is three transports, not one. Stdin JSON, a plugin callback, and an extension API differ in where the process boundary is, and that decides what can go wrong: a shell script cannot transform JSON, a Bun plugin has no process-exit event, an extension's thrown error becomes a block.
Decide what silence means before writing a gate. Where the CLI has its own prompt, an empty answer hands the question back. Where it does not, an empty answer is a decision, and it had better be deny.
Do not derive subagent identity from the field that looks right. agent_type looks like the signal in Claude Code; agent_id is. sessionId looks like the child's id in Grok's subagent_start; it is the parent's.
Guard every place the hook will run that is not your app. Global configuration means every session, including sessions started inside a tool that inherited your environment variables from a parent shell.

Source

Repository: https://github.com/yuuichieguchi/Calyx (MIT)
Install: brew install --cask calyx

What it takes to embed libghostty in a Swift app: six months of lessons

Yuuichi Eguchi — Mon, 14 Sep 2026 13:25:14 +0000

Six months ago I started Calyx, a native macOS terminal for running and supervising coding agents, on top of libghostty, the embeddable core of Ghostty (1.3.1 as I write this). Since then I have tagged 103 releases, and every one of them since v0.20.4 in mid-April runs on the same libghostty build. Almost all of the work happened above the FFI line.

This post is the list of things I wish someone had written down before I started. It is not a tutorial. It is the set of surprises, in the order I would have wanted to hear about them.

1. The build is easy. The coupling is not.

Producing the framework is one command inside the ghostty checkout:

zig build -Demit-xcframework=true -Dxcframework-target=native \
  -Demit-macos-app=false -Doptimize=ReleaseFast

One of those flags, and the toolchain that runs the command, cost me real time.

-Doptimize=ReleaseFast was missing from my build recipe for the first month. Nothing broke. The terminal simply rendered heavy workloads, like image previews in yazi, noticeably slower than stock Ghostty.app. A user reported it. Rebuilding with ReleaseFast took libghostty_zcu.o from 33 MB to 8.9 MB and removed every debug panic helper. A missing optimizer flag in a build script is a performance bug that no test catches.

The Zig version is pinned by ghostty, not by you. build.zig.zon declares minimum_zig_version, and every ghostty update can move it. I keep several Zig versions installed side by side and assert the expected one in the update script. Treat the Zig toolchain as part of the submodule, not as part of your machine.

Three more build facts that are worth knowing up front:

The xcframework you get with -Dxcframework-target=native is arm64 only. The static archive is about 141 MB in ReleaseFast. I check it into the repo through git-lfs so that building Calyx never requires Zig, and the release build passes ARCHS=arm64 explicitly. Calyx is Apple Silicon only as a direct consequence.
Xcode 26 no longer ships a metallib binary, and ghostty's build looks for one. The fix is a two-line script on PATH: exec xcrun metal "$@".
Treat the ghostty/ submodule as read-only. I corrupted my repository twice by running git commands inside it. Now the update procedure has a human fetch the new tag, and every automated step refuses to touch that directory.

2. The C API is small. The runtime config is the whole contract.

libghostty exposes an app handle, a surface handle, a config handle, and one struct that defines how your host behaves: ghostty_runtime_config_s. It has userdata, a boolean for selection clipboard support, and six callbacks. In Swift:

var runtimeConfig: ghostty_runtime_config_s = ghostty_runtime_config_s(
    userdata: Unmanaged.passUnretained(self).toOpaque(),
    supports_selection_clipboard: false,
    wakeup_cb: ghosttyWakeupCallback,
    action_cb: ghosttyActionCallback,
    read_clipboard_cb: ghosttyReadClipboardCallback,
    confirm_read_clipboard_cb: ghosttyConfirmReadClipboardCallback,
    write_clipboard_cb: ghosttyWriteClipboardCallback,
    close_surface_cb: ghosttyCloseSurfaceCallback
)

Implement all six. The action callback alone carries 65 distinct action tags in the current header, from set_title to progress_report, so it is effectively the event bus of your application.

Two structural decisions I would repeat:

Every C call lives in one file. Calyx has a GhosttyFFI enum used as a namespace, 417 lines of thin static wrappers, and nothing else in the app calls ghostty_* functions directly (with two functions I still call from the app delegate and owe myself a refactor for). When the header changes, one file changes.
Do not use a bridging header. The xcframework ships a module map, so import GhosttyKit is enough. If you also import ghostty.h from a bridging header you get error: redefinition of module 'GhosttyKit'. The one-line bridging header still sitting in my repo, no longer wired into the build, is a fossil from learning that.

3. Swift 6 strict concurrency meets C callbacks

Calyx is Swift 6.2 with strict concurrency, and every stateful type in the bridge is @MainActor (the FFI namespace, the pure event translators, and the Metal layer subclass are nonisolated). C callbacks do not know what an actor is, so the boundary needs a few idioms.

The callbacks themselves are file-level functions, never closures and never methods, so they can be passed as @convention(c) pointers. userdata carries the host object across the boundary both ways with Unmanaged:

static func appController(from userdata: UnsafeMutableRawPointer) -> GhosttyAppController {
    Unmanaged<GhosttyAppController>.fromOpaque(userdata).takeUnretainedValue()
}

The interesting part is that the two important callbacks arrive differently, so they need different hops.

The wakeup callback is called from an arbitrary thread and returns nothing, so it hops asynchronously:

// Simplified from the source.
private func ghosttyWakeupCallback(_ userdata: UnsafeMutableRawPointer?) {
    guard let userdata else { return }
    nonisolated(unsafe) let ud = userdata
    DispatchQueue.main.async {
        GhosttyAppController.appController(from: ud).tick()
    }
}

The action callback is called on the main thread during tick() and must return a Bool, so it cannot be dispatched. It enters the main actor synchronously:

private func ghosttyActionCallback(_ app: ghostty_app_t?, _ target: ghostty_target_s,
                                   _ action: ghostty_action_s) -> Bool {
    guard let app else { return false }
    nonisolated(unsafe) let safeApp = app
    let safeTarget = target
    let safeAction = action
    return MainActor.assumeIsolated {
        GhosttyActionRouter.handleAction(app: safeApp, target: safeTarget, action: safeAction)
    }
}

That asymmetry (async for a void callback, assumeIsolated for one with a return value) is the concrete lesson. Everything else follows from it:

In the bridge, nonisolated(unsafe) is confined to C pointer bindings and to the handles you must free in deinit, because deinit is nonisolated. I wrote that rule down after I caught myself using it as a general escape hatch elsewhere in the app, where a few uses still remain.
@preconcurrency import AppKit where an AppKit protocol conformance needs it. NSTextInputClient on the surface view is the one that forced it.
Copy C strings into Swift strings inside the callback. The memory is not yours after you return.
Keep C types out of NotificationCenter userInfo dictionaries. Calyx converts enums to Swift values before posting. The one exception is the clipboard read confirmation, which has to carry libghostty's request pointer to the window controller that presents the sheet and completes the request later; the plain clipboard read completes in place inside the callback.

4. The action callback's return value is not a formality

Calyx fans every action out through NotificationCenter under a com.calyx.ghostty.* prefix, 37 names so far, so that windows, tabs, the agent sidebar, and the session layer can subscribe without the bridge knowing about them. That part is ordinary. The part that bit me is the Bool you return.

Returning false tells libghostty that the action was not performed. For a keybind declared with the performable: prefix, libghostty then acts as though no binding existed and the raw key sequence reaches the shell; for an ordinary keybind the event stays consumed either way. So for actions you deliberately do not implement, the return value depends on why:

// Simplified: the source has one case per action, each with its reason.
// GTK-only or touch-only actions: consumed on purpose, nothing to do.
case GHOSTTY_ACTION_TOGGLE_TAB_OVERVIEW,
     GHOSTTY_ACTION_SHOW_GTK_INSPECTOR,
     GHOSTTY_ACTION_SHOW_ON_SCREEN_KEYBOARD:
    return true

Of the 65 tags in the header, Calyx handles most, returns false for 11 it has not implemented (8 listed explicitly and 3 that fall through to the default case), returns true for 3 that only make sense on GTK or touch platforms, and still has 2 stubs (key sequences and mouse-over-link). Keep that table honest in your own router. A true on an unimplemented action silently eats a performable keybind.

Two timing traps in the same callback:

GHOSTTY_ACTION_INITIAL_SIZE and CELL_SIZE fire synchronously from inside ghostty_surface_new, before your window has registered any observers for its first surface. Calyx writes those values straight onto the view as properties and reads them back after the constructor returns (the cell size is also posted as a notification for the subscribers that exist later).
The close_surface callback can re-enter your own teardown path synchronously. Any "should this kill the process" decision that lives in that path needs to be reentrancy-safe. I moved mine into a separate policy object after the second time it surprised me.

5. Rendering under Liquid Glass

libghostty renders with Metal into a view you hand it:

mutableConfig.platform_tag = GHOSTTY_PLATFORM_MACOS
mutableConfig.platform.macos = ghostty_platform_macos_s(
    nsview: Unmanaged.passUnretained(surfaceView).toOpaque()
)

The engine creates its own Metal device, command queues, and pipeline. Your CAMetalLayer only provides the drawable. Three settings on that layer matter: displaySyncEnabled = true (ghostty drives its own vsync through CVDisplayLink), pixelFormat = .bgra8Unorm, and isOpaque = false. That last one is the whole Liquid Glass story. Calyx does not tint the terminal with glass. The window is isOpaque = false with a clear background, the SwiftUI root applies a .glassEffect sheet, and the terminal is a transparent Metal layer sitting on top of it. The glass is behind the text, not in front of it.

Two things follow from that:

Ghostty's background-opacity only affects the default background. Cells that a TUI paints itself (status bars, panels) stay opaque unless you also set background-opacity-cells. Calyx exposes that as a switch.
Reduce Transparency has to be honored at every layer, not just the root: the root background becomes the window color, the atmosphere gradient renders nothing, and the terminal host layer becomes opaque. It took three separate branches to make the window fully opaque.

One SwiftUI lesson that has nothing to do with Metal and everything to do with hosting a live PTY: never let the terminal subtree sit inside an if/else. SwiftUI's _ConditionalContent tears down and rebuilds whichever branch was active every time the condition flips, and "rebuild" means destroying and recreating live terminal surfaces. The root view shape in Calyx is fixed, and the conditions live in modifiers.

Scrolling is also yours. libghostty reports total, offset, and len through GHOSTTY_ACTION_SCROLLBAR. Calyx puts an NSScrollView with an empty document view on top of the surface, sized to the scrollback, and overrides hitTest so only the scroller itself intercepts clicks. Smooth trackpad scrolling then has to mirror ghostty's own scroll accumulator to compute the sub-row pixel offset, and mouse events have to be compensated for that offset. The relevant file in ghostty is Surface.zig; I keep the line numbers in a comment because I have had to re-read it more than once.

6. Config: libghostty loads it, you watch it

ghostty_config_load_default_files reads ~/.config/ghostty/config for you, ghostty_config_load_recursive_files follows its config-file includes, and ghostty_config_open_path tells you which file it used. Reading the user's config is free. Two things are not.

Hot reload is entirely the host's job. There is no file watcher in libghostty. Calyx uses DispatchSourceFileSystemObject on the config path and its parent directory (so that editors which replace the file are caught), debounces into a reload coordinator with a monotonic generation counter, and keeps the last-known-good config when a reload fails to parse. It does not yet watch included files.

Overriding is done by load order, not by editing. Calyx loads the user's files first, then its own glass preset from ~/.config/calyx/, then a runtime file that mirrors the Settings sliders, and only then calls ghostty_config_finalize. Earlier versions wrote managed blocks into the user's ghostty config. That was a mistake, and the current version carries a cleanup routine that removes those blocks if it finds them. Do not write into a file the user thinks of as theirs.

The list of keys Calyx overrides is a single array in code, rendered verbatim in the Settings window and asserted by tests, so the UI cannot drift from the behavior. Today it is background-opacity, background-blur, background-opacity-cells, font-codepoint-map, and, for non-Ghostty color presets, foreground (computed from the luminance of the chrome tint so text stays legible against glass).

Keybinds go both directions. A Ghostty keybind action reaches your action router like anything else, and ghostty_surface_binding_action lets you invoke a keybind action by its string name from the host. Global keybinds need a CGEvent tap, gated on ghostty_app_has_global_keybinds.

7. The terminal tells you almost enough

This is the section I would have paid for. libghostty surfaces a lot of terminal protocol as actions, and each one has a catch.

OSC 7 (working directory) arrives as GHOSTTY_ACTION_PWD. It is the right source for "open a new split in the same directory", and it is also the only reliable cwd signal an agent sidebar can get without hooks of your own.

Desktop notifications (OSC 9 and OSC 777) arrive with a title and body. Decode them with String(validatingCString:) so invalid UTF-8 degrades to an empty string instead of trapping, and sanitize bidi override characters and C0/C1 controls before the text reaches UNUserNotificationCenter. Calyx also suppresses the banner when the tab is active and the window is key, and bounces the Dock only for the first unread.

Progress reports (OSC 9;4) arrive as a struct with a state (remove, set, error, indeterminate, pause) and an int8_t percentage, or -1 when none was reported. Calyx currently collapses that to a boolean for the agent status view and does not read the percentage yet.

COMMAND_FINISHED only fires when the shell has ghostty's shell integration loaded. libghostty resolves its resources directory once at engine init, from GHOSTTY_RESOURCES_DIR if it is set and otherwise by climbing from the running executable looking for a terminfo sentinel, and then injects the integration scripts into the shells it spawns. Two things follow for an embedder. Bundle the terminfo and shell-integration directories where that search finds them, or set the variable yourself before the engine initializes; Calyx now does both, and overwrites an inherited value on purpose, because the bundled scripts are version-matched to the embedded engine while a standalone Ghostty's are not. And any shell you spawn yourself gets no injection at all. Calyx's persistent-session daemon spawns its own shells, so it has to forward the variable and source the integration itself; until I did that in July, commands in persistent sessions never produced this action, and nothing told me why. Once it fires there is a second catch: a command whose OSC 133;D carried no exit code still arrives as 0, because ghostty reads the option with a default of zero before building the action, so success and "unknown" are indistinguishable. Calyx keeps its own zsh and fish hooks for the command log and uses the action only as a fallback signal for the shells those hooks do not cover.

SHOW_CHILD_EXITED on macOS gave me an exit_code of 0 every time in testing; only the duration field (spelled timetime_ms in the header) was usable. When you need to know whether a process really died, ask something that knows.

Reading text back through ghostty_surface_read_text takes a selection with a coordinate tag and an exact, top_left, or bottom_right mode. In the current embedded API an exact y coordinate is clamped to the active grid's row count, not the history-inclusive total, so you cannot address a specific row deep in scrollback. What works: ask for the whole screen region with top_left and bottom_right, then slice in Swift. It is a full dump every time, and for a captured command output that is acceptable. A row-ranged read would be the right upstream addition.

Cursor click-to-move is implemented in ghostty as arrow-key steps over cells, so on lines of full-width text (Japanese, for example) the landing position can be off. I document it rather than fight it.

Mouse-over-link is still a stub in Calyx. Cmd-click opening works through the OPEN_URL action; the hover status label does not exist yet. I mention it because it is easy to imply more coverage than you have.

8. Persistent sessions: the PTY moves out, the engine stays

Calyx's opt-in persistent sessions survive app quit and crashes, and they can live on SSH hosts. The design that made this work with libghostty is simple to state: the shell's PTY lives in a small Rust daemon, and libghostty renders a client process that attaches to it. The seam is one field in the surface config:

return command.withCString { cmdCStr in
    var mutableConfig = config
    mutableConfig.command = cmdCStr
    // ...

Instead of the user's shell, the surface runs calyx-session attach --create. libghostty still owns a PTY, the one running the attach client, and the daemon owns the real one. The host also passes the already-laid-out grid size to the attach command, otherwise the embedded engine's bootstrap grid becomes the new shell's initial PTY size.

Two things about this were not obvious.

The daemon embeds ghostty too. To replay a session's screen state to a reattaching client, the daemon keeps a VT terminal per session, and that terminal is ghostty's own VT engine, built as a static library through a tiny Zig shim that path-depends on the same submodule. One submodule, two consumers, two toolchains: an arm64 xcframework for the app and a per-target static library for the Rust daemon, including a musl target for remote payloads.

The daemon cannot be a child of the app. A double-forked daemon inherits the spawning app's jetsam coalition, and once the app quits, the daemon's process context can no longer reach opendirectoryd. From that point getpwuid fails for every shell it spawns, and users lose their username: %n in zsh, $USER, $LOGNAME. The fix is a launchd LaunchAgent, loaded on demand, with NumberOfFiles raised to 4096 because the default soft limit of 256 is not enough for a daemon holding a PTY master, a wake pipe, and a history fd per session. And launchd's job environment is minimal: HOME, PATH, SHELL, USER, and a few XPC variables, but no TERM, no LANG, and no GHOSTTY_*, so the attach path has to re-supply all of that per session.

9. Shipping it

Three release-engineering lessons, all of which cost a broken release.

Sparkle must be re-signed inside out. Flat re-signing of the framework binary passed codesign --verify and failed Gatekeeper. The sequence that works is XPC services, then nested apps, then standalone executables, then the framework, then the outer app again, because re-signing anything inside invalidates the outer seal. The release script also whitelists the framework's root entries and fails on anything unexpected.

Cargo binaries are only ad-hoc signed. The outer app's signature does not re-sign nested Mach-O files, so the Rust daemon needs an explicit Developer ID signature with hardened runtime and a timestamp, or notarization rejects the bundle. The Linux payloads for remote hosts are ELF; codesign cannot sign them and seals them as plain resources, which is fine.

Re-zip after stapling, then sign the zip. Notarize the zip, staple the ticket to the app, create the final zip again, and only then run Sparkle's sign_update. The EdDSA signature must describe the artifact people download.

And one that I learned from Homebrew's source, not from my own. ditto -c -k --keepParent stores extended attributes as AppleDouble ._ entries next to each file. Xcode-built binaries carry com.apple.provenance, so my zips contain 169 of them. Extract that zip with Info-ZIP's unzip and the ._ files land inside the bundle, the resource seal fails, and Gatekeeper calls the app damaged. Extract it with ditto -x -k and everything is fine. Homebrew checks zipinfo for ._ entries and switches to ditto when it finds them, which is the only reason brew install --cask calyx works. If you distribute zips, know how your users extract them.

10. What I would tell you before you start

Pin the Zig toolchain to ghostty's minimum_zig_version and keep old versions around. Assert it in your update script.
Build with -Doptimize=ReleaseFast from day one and check the archive size.
Check the xcframework into LFS so contributors and CI never need Zig.
Centralize every C call in one file. Import the module; do not use a bridging header.
Make the bridge @MainActor, hop wakeups asynchronously, enter actions with assumeIsolated, and confine nonisolated(unsafe) to pointer bindings and deinit.
Return false from the action callback only when you really want a performable keybind to reach the shell.
Expect INITIAL_SIZE and CELL_SIZE before your observers exist.
Bundle ghostty's resources where its search finds them, or set GHOSTTY_RESOURCES_DIR in-process before engine init, and source the shell integration yourself in any shell you spawn.
Treat exit codes from the engine as hints, not facts.
Verify your release artifact the way your users extract it, not the way you do.

About Calyx

Calyx is a native macOS terminal (Swift 6.2, AppKit and SwiftUI, MIT) for running and supervising coding agents in parallel: an approval inbox for Claude Code and Codex permission prompts and for Grok and pi tool calls, an agent status sidebar driven by each CLI's own hooks, in-terminal diff review with line comments sent back to the agent, MCP tools that let agents read command output and language-server results, and the persistent sessions described above. It requires macOS 26 on Apple Silicon.

brew install --cask calyx

Source: https://github.com/yuuichieguchi/Calyx
Docs: https://help.getcalyx.app

Thanks to Mitchell Hashimoto and the Ghostty contributors for making the engine embeddable in the first place. Everything above is a list of details; the fact that a solo developer can ship a GPU-rendered, VT-correct terminal as one component of a larger app is the headline.

Calyx vs cmux: Choosing the Right Ghostty-Based Terminal for macOS 26

Yuuichi Eguchi — Sun, 08 Mar 2026 15:56:53 +0000

The Ghostty Terminal Race

With the rise of AI coding agents in 2026, terminals are no longer just text windows -- they're command centers. Two Ghostty-based macOS terminals have emerged as frontrunners: cmux and Calyx.

Both leverage Ghostty's GPU-accelerated rendering, but they take very different approaches to what a modern terminal should be. Let's break down why Calyx might be the better choice for your daily workflow.

What is cmux?

cmux by manaflow-ai is a terminal built for AI coding agents. It features vertical tabs, notification rings, split panes, a socket API, and deep integration with tools like Claude Code, Codex, and Aider.

What is Calyx?

Calyx is a macOS 26+ native terminal that prioritizes daily-driver polish: a beautiful Liquid Glass UI, robust session management, intuitive tab organization, and security-conscious browser integration.

Head-to-Head Comparison

1. Native macOS 26 Design

Calyx is built from the ground up for macOS 26's Liquid Glass design language. Glass Material is applied to the sidebar, tab bar, command palette, and browser toolbar, making Calyx feel like a first-class citizen on your Mac. It also respects the "Reduce Transparency" accessibility setting, automatically falling back to a solid UI for users who need it.

cmux uses a functional UI but doesn't adopt macOS 26's design system. If you care about visual consistency with the rest of your OS, Calyx wins here.

2. Tab Groups vs Vertical Tabs

cmux offers vertical tabs with useful metadata like git branch, PR status, and listening ports in the sidebar.

Calyx takes tab management further with tab groups. Organize tabs by project or context with 10 color presets. Groups are collapsible in the sidebar, support tab reordering within groups, and show tab counts per group. Double-click a group header to rename it, close individual tabs or an entire group directly from the sidebar. Working on a full-stack app? Group your frontend, backend, and infrastructure tabs separately. With dozens of tabs open, you'll always know where you are.

3. Split Panes: Stability Matters

Both terminals support split panes, but stability differs significantly.

cmux has known rendering issues where terminal panes fail to render after closing splits. Keyboard shortcuts also reportedly break after opening browser tabs.

Calyx's splits are backed by an immutable binary tree data structure (SplitTree) with horizontal/vertical splitting, drag-to-resize with a 50px minimum pane guarantee, equalize operation, and spatial focus navigation (left/right/up/down). Tab switching uses only setFocus + refresh, keeping the render loop stable by design. No phantom blank panes, no lost keyboard input.

4. Command Palette

Hit Cmd+Shift+P in Calyx and you get a VS Code-style command palette with fuzzy search across 15 built-in commands. The scoring system combines word-start bonus, consecutive match bonus, exact match bonus, and prefix match bonus for accurate results. Command usage frequency is tracked, so your most-used commands rise to the top over time.

The shortcut system is built on a low-level NSEvent monitor that detects IME compose state. CJK input never triggers shortcuts accidentally. Text fields and text views are also properly excluded.

cmux doesn't have a command palette.

5. Session Persistence

Quit Calyx and reopen it. Your tabs, tab groups, split layouts, browser URLs, and window positions are fully restored.

Under the hood, Calyx implements atomic file writes (temp file + rename), automatic backup rotation, 2-second debounced auto-save, schema versioning (currently v3) with migration support, crash loop detection (max 3 recovery attempts), and window frame clamping to screen bounds. If the primary session file is corrupted, it automatically recovers from the backup.

6. Notification System

Both terminals support notifications, but Calyx emphasizes security and reliability.

Calyx relays OSC notifications to UNUserNotificationCenter with per-tab unread badges (circle in sidebar, capsule in tab bar, capped at 99+). It implements rate limiting (max 5 per second per tab), Dock icon bounce on first unread, and automatic badge clearing on window focus.

Notification text is sanitized with bidi override removal, control character filtering, zero-width character removal, newline normalization, NFC normalization, and truncation at 256 grapheme clusters, preventing malicious terminal sequences from becoming attack vectors.

7. Browser Integration That Works

Both terminals include a built-in browser. However, cmux has reported issues with HTTP connections being blocked and forced dark mode on all pages.

Calyx's browser uses a non-persistent WebKit data store for privacy, with back/forward/reload navigation, a loading indicator, error banners, and JavaScript dialog support (alert, confirm, prompt).

Security is comprehensive:

URL scheme validation (only http/https/about at top-level)
Subresource scheme blocking (javascript, data)
Redirect depth limiting (max 10)
Download filename sanitization (null byte stripping, dangerous character replacement, dangerous extension blocking, 255-char limit)
MIME type blocking for dangerous executables
Symlink traversal prevention on download paths
Automatic macOS Quarantine attribute on downloaded files

8. Licensing

Calyx's MIT license places no restrictions on commercial use or modification. cmux's AGPL requires source code disclosure if you provide the software as a network service, a potential blocker for enterprise adoption.

9. Git Source Control

Calyx includes a built-in Git source control view directly in the sidebar. Switch to the "Changes" mode and you get a complete overview of your repository's state without leaving the terminal.

Working Changes: Files grouped into Staged / Unstaged / Untracked sections with status badges (M/A/D/R/C/?/U/T)
Commit Graph: Color-coded branch lane visualization with commit history. Click to expand and see changed files per commit. Infinite scroll pagination for large repositories
Inline Diff Viewer: Click any file to open a diff tab with color-coded additions (green), deletions (red), and hunk headers (cyan). Dual old/new line number gutter. Binary file detection and automatic truncation for diffs over 1MB or 50,000 lines
Diff Review Comments: Click the + button next to any line number to add an inline comment. Submit Review sends the formatted review directly to a Claude Code or Codex terminal tab

No more switching to VS Code just to review what Claude Code changed. It's all inside Calyx.

cmux doesn't have this feature.

10. AI Agent IPC (Inter-Process Communication)

Calyx includes a built-in MCP server that enables AI agent instances (Claude Code, Codex CLI) to communicate with each other across tabs and panes.

Just run "Enable AI Agent IPC" from the command palette, and every agent instance in Calyx can discover peers, send messages, broadcast announcements, and check for incoming messages via 7 MCP tools. Config is auto-written to ~/.claude.json and ~/.codex/config.toml when the respective tool is installed. Thanks to the MCP spec instructions field, agents automatically register as peers upon connecting.

Calyx's MCP-based IPC is purpose-built for multi-agent collaboration across Claude Code and Codex.

11. Scriptable Browser

cmux pioneered browser automation with 80+ CLI commands for controlling WKWebView. Calyx now matches this with 25 CLI commands for browser scripting: snapshot accessibility trees, click elements, fill forms, evaluate JavaScript, take screenshots, wait for conditions, inspect DOM attributes, list links and inputs, check visibility, hover, and scroll.

The calyx CLI binary is bundled inside the app. Run Install CLI to PATH from the command palette to make it available system-wide.

calyx browser list
calyx browser snapshot --tab-id <id>
calyx browser get-text h1 --tab-id <id>
calyx browser click a --tab-id <id>
calyx browser eval 'document.title' --tab-id <id>
calyx browser get-attribute a href         # Get element attribute
calyx browser get-links                    # List all links (JSON)
calyx browser get-inputs                   # List form inputs (JSON)
calyx browser is-visible '#el'             # Check visibility
calyx browser hover '#menu'                # Hover element
calyx browser scroll down --amount 500     # Scroll page/element

Element refs (@e1, @e2) from snapshots can be used as selectors in subsequent commands, enabling reliable DOM automation even on dynamic pages.

Feature Matrix

Feature	Calyx	cmux
Liquid Glass UI	Yes	No
Tab Groups (color-coded)	Yes	No (vertical tabs only)
Split Panes	Yes, stable	Rendering bugs
Command Palette	Yes (fuzzy search + frequency)	No
Session Persistence	Yes (schema v3 + crash recovery)	No
Browser Integration	Yes (security validation + downloads)	No HTTP, forced dark mode
Notifications	Yes (rate-limited + sanitized)	Yes
CJK Input Handling	Yes (IME-aware shortcuts)	Unknown
Multi-Window	Yes	Yes
Git Source Control	Yes (commit graph + diff viewer)	No
AI Agent IPC (MCP)	Yes (7 tools, auto-register, Claude Code + Codex)	No
Scriptable Browser	Yes (25 CLI commands)	Yes (80+ CLI commands)
License	MIT	AGPL

The Bottom Line

cmux is a solid terminal with a sharp focus on AI agent workflows.

But as a daily-driver terminal, Calyx offers a more polished and reliable experience: a beautiful native Liquid Glass UI, intuitive color-coded tab groups, stable split panes backed by immutable data structures, a fuzzy-search command palette with frequency learning, crash-resilient session persistence, a scriptable browser with 25 CLI commands, rate-limited and sanitized notifications, proper CJK input handling, and a permissive MIT license.

If you're on macOS 26, give Calyx a try.

Links

d3motap3 — A Multi-Source Video Recorder for macOS That Captures Phone + PC Screens Simultaneously

Yuuichi Eguchi — Wed, 04 Mar 2026 12:49:31 +0000

Why I Built This

When recording tool demos, I often needed to capture a phone screen and a PC screen at the same time. In practice, that meant recording them separately and syncing them up in post to make it look simultaneous.

Another pain point was re-recording every time I made a typo or missed a step. Doing that over and over was genuinely frustrating.

I built d3motap3 to solve both of these problems.

What It Does

Capture Up to 2 Sources at Once

Phone and display, terminal and webcam — any combination in side-by-side or picture-in-picture.

There are 7 source types to choose from:

Full display
Individual window
Screen region
Webcam
Built-in terminal
iOS device (USB)
Android device (USB)

YAML Scripted Automation

Define your demo steps in YAML and it records itself. Each step waits for the previous one to finish, so timing is always perfect. Define it once, get a perfect recording every time.

steps:
  - type: terminal_input
    text: "npm install"
  - type: wait_for_output
    pattern: "added .* packages"
  - type: terminal_input
    text: "npm start"
  - type: wait_for_output
    pattern: "Server running"

Timeline Editor

Edit your recordings with the built-in editor:

Clip splitting
Transitions (fade / dissolve / wipe)
Text overlays with animation
Audio track import and editing

AI Script Generation

Describe your demo in plain text and get a YAML script generated via Claude API.

Built-in Terminal Rendered in Rust

The built-in terminal isn't a screenshot — it's rendered directly by Rust via PTY → alacritty VT parser → cosmic-text. The terminal itself becomes a capture source, so there's no need to window-capture an external terminal app.

3 Layouts

Single — one source, full frame
Side-by-Side — two sources next to each other (adjustable split ratio)
Picture-in-Picture — a small overlay on top of the main source (adjustable position and size)

Platform

macOS only (uses ScreenCaptureKit). Distributed as a signed and notarized DMG.

Approve Claude Code Permission Requests from Your Phone

Yuuichi Eguchi — Sun, 22 Feb 2026 06:43:06 +0000

The Problem

Claude Code asks for permission before running tools like Bash, Write, and Edit. This is a great safety feature — but it means you have to be sitting at your terminal to press "y".

Step away for coffee? Claude Code stalls until you get back.

The Solution

claude-remote-approver sends each permission request as a push notification to your phone via ntfy.sh. Tap Approve or
Deny, and Claude Code continues immediately — no terminal required.

How It Works

  Claude Code
    │
    │  PermissionRequest hook (stdin JSON)
    ▼
  claude-remote-approver hook
    │
    ├──POST──▶ ntfy.sh/          ──push──▶  Phone (ntfy app)
    │                                                 │
    │                                           Approve / Deny tap
    │                                                 │
    └──SSE───▶ ntfy.sh/-response  ◀──POST──┘
    │
    │  stdout JSON: { "behavior": "allow" } or { "behavior": "deny" }
    ▼
  Claude Code continues or stops

It uses ntfy.sh, an open-source HTTP-based pub-sub notification service. No account required. The topic name is a 128-bit random string, so only you can receive the notifications.

Setup (3 Steps)

1. Install the ntfy app on your phone

2. Install and run setup on your PC

  npm install -g claude-remote-approver
  claude-remote-approver setup

3. Scan the QR code

The setup command prints a QR code in your terminal. Scan it with the ntfy app to subscribe.

Important: Start a new Claude Code session after setup. The hook is loaded at session startup, so existing sessions won't pick it up.

How It Feels

Once set up, just use Claude Code normally. When a permission request fires:

Your phone buzzes with a notification showing the tool name and a summary (e.g., Bash: npm install express)
Tap Approve or Deny
Claude Code continues instantly

If you don't respond within the timeout (default: 120 seconds), the request is automatically denied. Fail-closed by design.

Sample notification

Other Commands

  claude-remote-approver test      # Send a test notification
  claude-remote-approver status    # Show current config
  claude-remote-approver disable   # Temporarily disable
  claude-remote-approver enable    # Re-enable
  claude-remote-approver uninstall # Remove everything

Security

Topic names are generated with crypto.randomBytes(16) (128 bits of entropy)
Config file is created with permission 0600 (owner-only)
For sensitive work, you can self-host ntfy instead of using the public server

Links

Give it a try and let me know what you think!

Constela: Built-in a11y Checks, Plugin System & CSS Transitions

Yuuichi Eguchi — Sun, 08 Feb 2026 07:30:25 +0000

What's New in Constela

Constela is a JSON-based declarative UI framework — you write your entire UI in JSON, and the compiler + runtime handles the rest. We're shipping three features that make Constela apps more accessible, extensible, and polished.

1. Compile-Time Accessibility Checks

Accessibility shouldn't be an afterthought. Constela now checks your JSON programs for common a11y issues at compile time and reports them as warnings.

7 Built-in Rules

Code	What it catches
`IMG_NO_ALT`	Images without `alt` text
`BUTTON_NO_LABEL`	Buttons with no text or `aria-label`
`ANCHOR_NO_LABEL`	Links with no text or `aria-label`
`INPUT_NO_LABEL`	Inputs without a label
`HEADING_SKIP`	Skipped heading levels (h1 → h3)
`POSITIVE_TABINDEX`	Positive `tabindex` values
`DUPLICATE_ID`	Duplicate `id` attributes

These are warnings, not errors — your code still compiles, so you can adopt them gradually.

const result = compile(myProgram);
if (result.ok && result.warnings?.length) {
  result.warnings.forEach(w => console.warn(`[${w.code}] ${w.message}`));
}

2. Plugin System

Want to use custom functions in your JSON DSL? Now you can.

Define a Plugin

import type { ConstelaPlugin } from '@constela/core';

const myPlugin: ConstelaPlugin = {
  name: 'my-analytics',
  version: '1.0.0',
  globalFunctions: {
    trackEvent: (category: string, action: string) => { /* ... */ },
    formatCurrency: (amount: number) => `$${amount.toFixed(2)}`,
  },
};

export default myPlugin;

Register It

Add to constela.config.json:

{
  "plugins": ["my-analytics", "./src/plugins/local-plugin"]
}

That's it — your functions are now available in the DSL.

Safety features:

Atomic registration (all-or-nothing)
Prototype pollution protection (__proto__, constructor, prototype blocked)
Works in both client and server rendering

3. CSS Class-Based Transitions

Conditional rendering (if nodes) now supports smooth enter/exit animations:

{
  "kind": "if",
  "condition": { "expr": "state", "name": "showToast" },
  "then": {
    "kind": "element",
    "tag": "div",
    "children": [
      { "kind": "text", "value": { "expr": "lit", "value": "Saved!" } }
    ]
  },
  "transition": {
    "enter": "slide-in",
    "enterActive": "slide-in-active",
    "exit": "slide-out",
    "exitActive": "slide-out-active",
    "duration": 250
  }
}

Pair it with CSS:

.slide-in { transform: translateY(-20px); opacity: 0; }
.slide-in-active { transition: all 250ms ease; transform: translateY(0); opacity: 1; }
.slide-out { transform: translateY(0); opacity: 1; }
.slide-out-active { transition: all 250ms ease; transform: translateY(-20px); opacity: 0; }

The runtime handles:

Enter flow: create element → apply enter → next frame: swap to enterActive → cleanup
Exit flow: apply exit → next frame: swap to exitActive → remove element
Fast toggling: cancels in-progress animations gracefully
SSR: transitions are ignored server-side (no changes needed)

Try It Out

npm install @constela/core @constela/compiler @constela/runtime @constela/start
npx constela dev

Check out the Language Specification for the full DSL reference, or browse the Examples to see these features in action.

Links:

Constela New Features - Islands Architecture, Realtime Features, and New UI Components

Yuuichi Eguchi — Sat, 07 Feb 2026 12:55:44 +0000

Introduction

We're excited to announce new features for Constela, with 7 major new capabilities that significantly improve performance and developer experience:

Theme System (CSS variables, light/dark/system modes)
Islands Architecture (6 hydration strategies)
Streaming SSR (3 flush strategies)
Realtime Features (SSE, optimistic updates, state binding)
New UI Components (DatePicker, Calendar, Tree, Accordion, DataTable, VirtualScroll, Chart)

Feature 1: Theme System

We've introduced a CSS variable-based theme system with support for light/dark/system modes and shadcn/ui-compatible color tokens.

{
  "theme": {
    "mode": "system",
    "colors": {
      "primary": "hsl(220 90% 56%)",
      "primary-foreground": "hsl(0 0% 100%)",
      "background": "hsl(0 0% 100%)",
      "foreground": "hsl(222 47% 11%)",
      "muted": "hsl(210 40% 96%)",
      "border": "hsl(214 32% 91%)"
    },
    "darkColors": {
      "background": "hsl(222 47% 11%)",
      "foreground": "hsl(210 40% 98%)",
      "muted": "hsl(217 33% 17%)",
      "border": "hsl(217 33% 17%)"
    },
    "fonts": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "JetBrains Mono, monospace"
    },
    "cssPrefix": "app"
  }
}

Key Features

System Theme Detection: Automatic prefers-color-scheme detection
Persistence: localStorage + Cookie support (SSR-safe)
CSS Variables: Auto-applies prefixed variables like --app-primary to :root
Dark Class: Automatically manages dark class on document.documentElement

Feature 2: Islands Architecture

We've implemented Islands Architecture for partial hydration. Choose from 6 hydration strategies to drastically reduce your initial JS bundle.

{
  "kind": "island",
  "id": "interactive-chart",
  "strategy": "visible",
  "strategyOptions": {
    "threshold": 0.5,
    "rootMargin": "100px"
  },
  "content": {
    "kind": "component",
    "name": "Chart",
    "props": { "data": { "expr": "state", "name": "chartData" } }
  },
  "state": {
    "chartData": { "type": "list", "initial": [] }
  },
  "actions": [
    {
      "name": "loadData",
      "steps": [
        { "do": "fetch", "url": { "expr": "lit", "value": "/api/chart-data" }, "result": "data", "onSuccess": [
          { "do": "set", "target": "chartData", "value": { "expr": "var", "name": "data" } }
        ]}
      ]
    }
  ]
}

Hydration Strategies

Strategy	Description	Use Case
`load`	Hydrate immediately on page load	Critical interactive elements
`idle`	Hydrate when browser is idle	Non-urgent interactions
`visible`	Hydrate when element enters viewport	Below-the-fold content
`interaction`	Hydrate on first user interaction	Lazy-loaded widgets
`media`	Hydrate when media query matches	Responsive components
`never`	Never hydrate	Static content only

Build Optimization

Islands are automatically code-split:

dist/
  _islands/
    interactive-chart.js   # Island-specific bundle
    sidebar-menu.js
  client.js                # Main bundle

Feature 3: Realtime Features

We've added SSE (Server-Sent Events) connections, optimistic updates, and state binding.

SSE Connections

{
  "do": "sseConnect",
  "connection": "notifications",
  "url": { "expr": "lit", "value": "/api/events" },
  "eventTypes": ["message", "update"],
  "reconnect": {
    "enabled": true,
    "strategy": "exponential",
    "maxRetries": 5,
    "baseDelay": 1000
  },
  "onMessage": [
    { "do": "update", "target": "messages", "operation": "push", "value": { "expr": "var", "name": "payload" } }
  ]
}

Optimistic Updates

Update UI immediately with automatic rollback on server error:

{
  "name": "likePost",
  "steps": [
    {
      "do": "optimistic",
      "target": "posts",
      "path": { "expr": "var", "name": "index" },
      "value": { "expr": "lit", "value": { "liked": true } },
      "result": "updateId",
      "timeout": 5000
    },
    {
      "do": "fetch",
      "url": { "expr": "concat", "items": [
        { "expr": "lit", "value": "/api/posts/" },
        { "expr": "var", "name": "postId" },
        { "expr": "lit", "value": "/like" }
      ]},
      "method": "POST",
      "onSuccess": [
        { "do": "confirm", "id": { "expr": "var", "name": "updateId" } }
      ],
      "onError": [
        { "do": "reject", "id": { "expr": "var", "name": "updateId" } }
      ]
    }
  ]
}

Feature 4: Streaming SSR

We've implemented ReadableStream-based streaming SSR with Edge Runtime support for significantly reduced TTFB. Just enable it in your config - no TypeScript required.

Configuration

{
  "streaming": {
    "enabled": true,
    "flushStrategy": "batched"
  }
}

Flush Strategies

Strategy	Description
`immediate`	Flush each chunk immediately
`batched`	Batch flush at 1KB threshold (default)
`manual`	Flush only at the end (small pages)

Suspense Boundaries

Use suspense nodes for async content with loading states:

{
  "kind": "suspense",
  "id": "user-profile",
  "fallback": {
    "kind": "element",
    "tag": "div",
    "props": { "className": { "expr": "lit", "value": "skeleton" } }
  },
  "content": {
    "kind": "component",
    "name": "UserProfile"
  }
}

The server renders the fallback immediately, then streams the actual content when ready - all configured declaratively in JSON.

Feature 5: New UI Components

DatePicker / Calendar

{
  "kind": "component",
  "name": "DatePicker",
  "props": {
    "value": { "expr": "state", "name": "selectedDate" },
    "onChange": { "event": "change", "action": "updateDate" },
    "format": { "expr": "lit", "value": "yyyy-MM-dd" },
    "locale": { "expr": "lit", "value": "en-US" }
  }
}

Tree / Accordion

{
  "kind": "component",
  "name": "Tree",
  "props": {
    "items": { "expr": "state", "name": "treeData" },
    "onSelect": { "event": "select", "action": "handleSelect" },
    "expandedKeys": { "expr": "state", "name": "expanded" }
  }
}

DataTable

Full-featured table with sorting, filtering, and pagination:

{
  "kind": "component",
  "name": "DataTable",
  "props": {
    "data": { "expr": "state", "name": "users" },
    "columns": { "expr": "lit", "value": [
      { "key": "name", "title": "Name", "sortable": true },
      { "key": "email", "title": "Email", "filterable": true },
      { "key": "status", "title": "Status" }
    ]},
    "pageSize": { "expr": "lit", "value": 10 },
    "sortable": { "expr": "lit", "value": true },
    "filterable": { "expr": "lit", "value": true }
  }
}

VirtualScroll

{
  "kind": "component",
  "name": "VirtualScroll",
  "props": {
    "items": { "expr": "state", "name": "largeList" },
    "itemHeight": { "expr": "lit", "value": 50 },
    "containerHeight": { "expr": "lit", "value": 400 },
    "overscan": { "expr": "lit", "value": 5 }
  }
}

Chart (7 Types)

{
  "kind": "component",
  "name": "BarChart",
  "props": {
    "data": { "expr": "state", "name": "chartData" },
    "valueKey": { "expr": "lit", "value": "value" },
    "labelKey": { "expr": "lit", "value": "label" },
    "showGrid": { "expr": "lit", "value": true }
  }
}

Supported chart types: bar, line, pie, donut, area, radar, scatter

Summary

This update brings significant enhancements for modern web application development:

Performance: Islands Architecture reduces bundle size, Streaming SSR improves TTFB
DX: Theme system makes dark mode easy, realtime features enable declarative sync logic
UI: Feature-rich UI components boost development efficiency

Try it out today!

Introducing AI-Powered UI Generation for Constela

Yuuichi Eguchi — Tue, 27 Jan 2026 13:29:51 +0000

Introduction

Constela is a JSON-first declarative UI framework. With this release, we're adding AI-powered features to supercharge your development workflow:

DSL Generator: Generate Constela JSON from natural language prompts
Security Validation: Automatically validate generated DSL for safety
CLI suggest command: Analyze existing DSL and get improvement suggestions

Installation

npm install @constela/ai

Features

1. Build-time Component Generation

Use type: "ai" in the data section to generate components at build time:

{
  "version": "1.0",
  "data": {
    "card": {
      "type": "ai",
      "provider": "anthropic",
      "prompt": "A card component with title, description, and action button",
      "output": "component"
    }
  },
  "view": {
    "kind": "component",
    "name": "card",
    "props": {
      "title": { "expr": "lit", "value": "Welcome" },
      "description": { "expr": "lit", "value": "Get started" }
    }
  }
}

The AI generates a component like:

{
  "kind": "element",
  "tag": "div",
  "props": {
    "className": { "expr": "lit", "value": "card" }
  },
  "children": [
    {
      "kind": "element",
      "tag": "h2",
      "children": [
        { "kind": "text", "value": { "expr": "param", "name": "title" } }
      ]
    },
    {
      "kind": "element",
      "tag": "p",
      "children": [
        { "kind": "text", "value": { "expr": "param", "name": "description" } }
      ]
    },
    {
      "kind": "element",
      "tag": "button",
      "props": {
        "onClick": { "event": "click", "action": "handleAction" }
      },
      "children": [
        { "kind": "text", "value": { "expr": "lit", "value": "Action" } }
      ]
    }
  ]
}

2. Security Validation

All generated DSL is automatically validated against security rules.

Forbidden Tags (blocked by default):

script, iframe, object, embed, form

Forbidden Actions (cannot be whitelisted):

import, call, dom

Restricted Actions (require explicit whitelist):

fetch

3. CLI suggest Command

Analyze existing DSL files and get AI-powered improvement suggestions:

# Analyze for accessibility issues
constela suggest app.json --aspect accessibility

# Analyze for security (using OpenAI)
constela suggest app.json --aspect security --provider openai

# JSON output for tooling
constela suggest app.json --aspect ux --json

Example output:

=== Suggestions for app.json (accessibility) ===

[HIGH] Missing aria-label on button
   Recommendation: Add aria-label="Submit form" to the button element
   Location: view.children[0].props

[MED] Low color contrast in text
   Recommendation: Increase contrast ratio to meet WCAG AA standards
   Location: view.children[2].props.style

Total: 2 suggestion(s)

4. Runtime Dynamic Generation

Use the generate action step to create DSL in response to user input:

{
  "version": "1.0",
  "state": {
    "userPrompt": { "type": "string", "initial": "" },
    "generatedCard": { "type": "object", "initial": {} }
  },
  "actions": [
    {
      "name": "generateCard",
      "steps": [
        {
          "do": "generate",
          "provider": "anthropic",
          "prompt": { "expr": "state", "name": "userPrompt" },
          "output": "component",
          "result": "generatedCard",
          "onSuccess": [
            {
              "do": "set",
              "target": "card",
              "value": { "expr": "var", "name": "generatedCard" }
            }
          ],
          "onError": [
            {
              "do": "set",
              "target": "error",
              "value": { "expr": "lit", "value": "Generation failed" }
            }
          ]
        }
      ]
    }
  ],
  "view": {
    "kind": "element",
    "tag": "div",
    "children": [
      {
        "kind": "element",
        "tag": "input",
        "props": {
          "type": { "expr": "lit", "value": "text" },
          "value": { "expr": "state", "name": "userPrompt" },
          "onInput": { "event": "input", "action": "updatePrompt" }
        }
      },
      {
        "kind": "element",
        "tag": "button",
        "props": {
          "onClick": { "event": "click", "action": "generateCard" }
        },
        "children": [
          { "kind": "text", "value": { "expr": "lit", "value": "Generate" } }
        ]
      }
    ]
  }
}

Environment Variables

Create a .env file in your project root and add your API key:

# For Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...

# For OpenAI
OPENAI_API_KEY=sk-...

Make sure .env is in your .gitignore to avoid committing secrets.

How It Works

Prompt Processing: Your natural language description is sent to the AI provider
DSL Generation: The AI generates valid Constela JSON based on the language specification
Security Validation: Generated DSL is validated against security rules
Error Handling: Any validation errors are reported with actionable fixes

Conclusion

With @constela/ai, you can leverage AI to:

Generate JSON DSL from natural language
Automatically validate security
Get improvement suggestions for existing code

Check out the official documentation for more details.

Links:

Introducing @constela/ui - Copy-Paste UI Components for Constela JSON DSL

Yuuichi Eguchi — Sun, 25 Jan 2026 07:03:52 +0000

Introducing @constela/ui

I'm excited to announce the release of @constela/ui - a UI component library for Constela JSON DSL.

This library provides copy-paste UI components that you can drop directly into your Constela projects. All components are written in JSON format - no TypeScript or React knowledge required for customization.

Installation

npm install @constela/ui

Available Components

Basic (7)

Button - 6 variants, 4 sizes
Input - Text input field
Textarea - Multi-line text input
Select - Dropdown selection
Checkbox - Checkbox input
Radio - Radio button
Switch - Toggle switch

Feedback (5)

Alert - Alert messages (default, destructive)
Card - Card container
Badge - Inline badge
Skeleton - Loading placeholder
Avatar - User avatar with fallback

Overlay (4)

Dialog - Modal dialog with proper ARIA
Tooltip - Hover tooltip
Popover - Click-triggered popover
Toast - Notifications (default, success, error, warning, info)

Navigation/Layout (6)

Tabs - Tab navigation
Breadcrumb - Breadcrumb navigation
Pagination - Page pagination
Container - Max-width container
Grid - CSS Grid layout
Stack - Flexbox stack

How to Use

1. Copy Component Files

Copy the components you need from node_modules/@constela/ui/components/:

button/
├── button.constela.json   # Component definition
└── button.styles.json     # Style preset

2. Import Styles

Add the style preset to your application's styles section.

3. Use the Component

{
  "kind": "component",
  "name": "Button",
  "props": {
    "variant": { "expr": "lit", "value": "default" },
    "size": { "expr": "lit", "value": "lg" }
  },
  "children": [
    { "kind": "text", "value": { "expr": "lit", "value": "Click me" } }
  ]
}

The Style System

Each component uses a CVA-like style system with base classes, variants, and default variants:

{
  "buttonStyles": {
    "base": "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
    "variants": {
      "variant": {
        "default": "bg-primary text-primary-foreground hover:bg-primary/90",
        "destructive": "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        "outline": "border border-input bg-background hover:bg-accent",
        "secondary": "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        "ghost": "hover:bg-accent hover:text-accent-foreground",
        "link": "text-primary underline-offset-4 hover:underline"
      },
      "size": {
        "default": "h-10 px-4 py-2",
        "sm": "h-9 rounded-md px-3",
        "lg": "h-11 rounded-md px-8",
        "icon": "h-10 w-10"
      }
    },
    "defaultVariants": {
      "variant": "default",
      "size": "default"
    }
  }
}

Dynamic Styling with StyleExpr

Components use StyleExpr to apply styles dynamically based on props:

{
  "className": {
    "expr": "style",
    "preset": "buttonStyles",
    "props": {
      "variant": { "expr": "param", "name": "variant" },
      "size": { "expr": "param", "name": "size" }
    }
  }
}

Accessibility First

All components include proper ARIA attributes:

aria-label for screen reader labels
aria-disabled for disabled state indication
role for semantic roles (dialog, alert, tablist, etc.)
aria-live for live region announcements

Example: Dialog Component

{
  "params": {
    "open": { "type": "boolean", "required": false },
    "title": { "type": "string", "required": false }
  },
  "view": {
    "kind": "element",
    "tag": "div",
    "props": {
      "role": { "expr": "lit", "value": "dialog" },
      "aria-modal": { "expr": "lit", "value": "true" },
      "className": { "expr": "style", "preset": "dialogStyles" }
    },
    "children": [{ "kind": "slot" }]
  }
}

Customization

Adding New Variants

Edit the style file to add new variants:

{
  "variants": {
    "variant": {
      "success": "bg-green-500 text-white hover:bg-green-600"
    }
  }
}

Extending Parameters

Add new parameters to the component definition. All parameters are optional by default, so existing usage won't break.

Modifying Base Styles

Change the base property to modify styles that apply to all variants.

Test Coverage

All components are verified with 563 tests covering:

Structure validation
Parameter validation
Style preset validation
Accessibility attributes

cd packages/ui && pnpm test

# Test Files  passed (22)
#      Tests  563 passed (563)

What's Next

Component catalog page on the official website
More components based on community feedback
Enhanced animation support

Conclusion

@constela/ui provides a solid foundation for building UIs with Constela JSON DSL. The copy-paste approach makes it simple to get started, and the JSON-based format makes customization accessible to everyone.

Give it a try and let me know what you think!

Constela: Call, Lambda, and Array Expressions for Type-Safe Data Operations

Yuuichi Eguchi — Sat, 24 Jan 2026 16:18:15 +0000

Introduction

We are excited to announce the latest update to Constela, bringing call expressions, lambda expressions, and the new array expressions to our compiler-first UI language. This update enables powerful data transformations and dynamic array construction while maintaining the security and determinism that define Constela.

What is Constela?

Constela is a compiler-first UI language designed for AI-generated UI. Unlike React or Next.js where you write UI with JavaScript, Constela uses a constrained JSON DSL that is validated, analyzed, and compiled into minimal runtime code.

	Constela	React / Next.js
UI authoring	JSON DSL	JavaScript / JSX
Execution	compiler-driven	runtime-driven
State updates	declarative actions	arbitrary JS
Errors	structured errors	runtime exceptions

Highlights

This release introduces three major expression types:

Call Expression - Method calls on arrays, strings, Math, and Date
Lambda Expression - Anonymous functions for array higher-order methods
Array Expression - Dynamic array construction from expressions

Package Versions:

@constela/core: 0.15.2
@constela/compiler: 0.14.2
@constela/runtime: 0.18.3
@constela/server: 11.0.1

Call Expression

The call expression enables method invocation on target values with a clean, declarative syntax.

Syntax

{
  "expr": "call",
  "target": <Expression>,
  "method": "<method_name>",
  "args": [<Expression>, ...]
}

Basic Examples

Get array length:

{
  "expr": "call",
  "target": { "expr": "state", "name": "items" },
  "method": "length"
}

Get element at index:

{
  "expr": "call",
  "target": { "expr": "state", "name": "items" },
  "method": "at",
  "args": [{ "expr": "lit", "value": 0 }]
}

Check if array includes a value:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3] },
  "method": "includes",
  "args": [{ "expr": "lit", "value": 2 }]
}

String Operations

Convert to uppercase:

{
  "expr": "call",
  "target": { "expr": "state", "name": "username" },
  "method": "toUpperCase"
}

Split string into array:

{
  "expr": "call",
  "target": { "expr": "lit", "value": "react,typescript,node" },
  "method": "split",
  "args": [{ "expr": "lit", "value": "," }]
}

Trim whitespace:

{
  "expr": "call",
  "target": { "expr": "state", "name": "userInput" },
  "method": "trim"
}

Math Operations

Calculate minimum value:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "min",
  "args": [
    { "expr": "lit", "value": 0 },
    { "expr": "state", "name": "count" }
  ]
}

Round a calculated value:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "round",
  "args": [
    {
      "expr": "bin",
      "op": "*",
      "left": { "expr": "state", "name": "price" },
      "right": { "expr": "lit", "value": 1.1 }
    }
  ]
}

Date Operations

Get current timestamp:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Date" },
  "method": "now"
}

Lambda Expression

The lambda expression enables anonymous functions for array higher-order methods like filter, map, find, and more.

Syntax

{
  "expr": "lambda",
  "param": "<parameter_name>",
  "index": "<index_name>",  // optional
  "body": <Expression>
}

Filter Example

Filter items greater than a threshold:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3, 4, 5] },
  "method": "filter",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": ">",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [3, 4, 5]

Map Example

Double each element:

{
  "expr": "call",
  "target": { "expr": "lit", "value": [1, 2, 3] },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": "*",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [2, 4, 6]

Using Index Parameter

Map with index:

{
  "expr": "call",
  "target": { "expr": "lit", "value": ["a", "b", "c"] },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "item",
      "index": "i",
      "body": { "expr": "var", "name": "i" }
    }
  ]
}

Result: [0, 1, 2]

Accessing Object Properties

Extract names from user objects:

{
  "expr": "call",
  "target": { "expr": "state", "name": "users" },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "user",
      "body": {
        "expr": "get",
        "base": { "expr": "var", "name": "user" },
        "path": "name"
      }
    }
  ]
}

Supported Methods

Array Methods

Method	Description	Example
`length`	Get array length	`items.length()`
`at`	Get element at index (supports negative)	`items.at(-1)`
`includes`	Check if element exists	`items.includes(value)`
`slice`	Extract subarray	`items.slice(1, 3)`
`indexOf`	Find index of element	`items.indexOf("foo")`
`join`	Join elements into string	`items.join(", ")`
`filter`	Filter by predicate (lambda)	`items.filter(x => x > 0)`
`map`	Transform elements (lambda)	`items.map(x => x * 2)`
`find`	Find first matching (lambda)	`items.find(x => x.id === 1)`
`findIndex`	Find index of first matching	`items.findIndex(x => x > 5)`
`some`	Check if any match	`items.some(x => x > 10)`
`every`	Check if all match	`items.every(x => x > 0)`

String Methods

Method	Description	Example
`length`	Get string length	`str.length()`
`charAt`	Get character at index	`str.charAt(0)`
`substring`	Extract substring	`str.substring(0, 5)`
`slice`	Extract with negative index support	`str.slice(-3)`
`split`	Split into array	`str.split(",")`
`trim`	Remove whitespace	`str.trim()`
`toUpperCase`	Convert to uppercase	`str.toUpperCase()`
`toLowerCase`	Convert to lowercase	`str.toLowerCase()`
`replace`	Replace first occurrence	`str.replace("a", "b")`
`includes`	Check substring exists	`str.includes("foo")`
`startsWith`	Check prefix	`str.startsWith("http")`
`endsWith`	Check suffix	`str.endsWith(".json")`
`indexOf`	Find substring index	`str.indexOf("@")`

Math Methods

Method	Description	Example
`min`	Get minimum value	`Math.min(a, b, c)`
`max`	Get maximum value	`Math.max(0, count)`
`round`	Round to nearest integer	`Math.round(3.7)`
`floor`	Round down	`Math.floor(3.9)`
`ceil`	Round up	`Math.ceil(3.1)`
`abs`	Absolute value	`Math.abs(-5)`
`sqrt`	Square root	`Math.sqrt(16)`
`pow`	Power	`Math.pow(2, 3)`
`random`	Random 0-1	`Math.random()`
`sin` / `cos` / `tan`	Trigonometric functions	`Math.sin(0)`

Date Methods

Method	Description	Example
`now`	Current timestamp (ms)	`Date.now()`
`parse`	Parse date string	`Date.parse("2024-01-01")`
`toISOString`	ISO format string	`date.toISOString()`
`getTime`	Get timestamp	`date.getTime()`
`getFullYear`	Get year	`date.getFullYear()`

Practical Examples

1. Filtering a TODO List

Display only incomplete tasks:

{
  "version": "1.0",
  "state": {
    "todos": {
      "type": "list",
      "initial": [
        { "id": 1, "text": "Learn Constela", "completed": true },
        { "id": 2, "text": "Build app", "completed": false },
        { "id": 3, "text": "Deploy", "completed": false }
      ]
    },
    "showCompleted": { "type": "boolean", "initial": false }
  },
  "view": {
    "kind": "each",
    "items": {
      "expr": "cond",
      "if": { "expr": "state", "name": "showCompleted" },
      "then": { "expr": "state", "name": "todos" },
      "else": {
        "expr": "call",
        "target": { "expr": "state", "name": "todos" },
        "method": "filter",
        "args": [
          {
            "expr": "lambda",
            "param": "todo",
            "body": {
              "expr": "not",
              "operand": {
                "expr": "get",
                "base": { "expr": "var", "name": "todo" },
                "path": "completed"
              }
            }
          }
        ]
      }
    },
    "as": "todo",
    "body": {
      "kind": "element",
      "tag": "div",
      "children": [
        {
          "kind": "text",
          "value": {
            "expr": "get",
            "base": { "expr": "var", "name": "todo" },
            "path": "text"
          }
        }
      ]
    }
  }
}

2. Search Filter with Case-Insensitive Matching

{
  "expr": "call",
  "target": { "expr": "state", "name": "products" },
  "method": "filter",
  "args": [
    {
      "expr": "lambda",
      "param": "product",
      "body": {
        "expr": "call",
        "target": {
          "expr": "call",
          "target": {
            "expr": "get",
            "base": { "expr": "var", "name": "product" },
            "path": "name"
          },
          "method": "toLowerCase"
        },
        "method": "includes",
        "args": [
          {
            "expr": "call",
            "target": { "expr": "state", "name": "searchQuery" },
            "method": "toLowerCase"
          }
        ]
      }
    }
  ]
}

3. Chaining Methods

Filter then map:

{
  "expr": "call",
  "target": {
    "expr": "call",
    "target": { "expr": "lit", "value": [1, 2, 3, 4, 5] },
    "method": "filter",
    "args": [
      {
        "expr": "lambda",
        "param": "x",
        "body": {
          "expr": "bin",
          "op": ">",
          "left": { "expr": "var", "name": "x" },
          "right": { "expr": "lit", "value": 2 }
        }
      }
    ]
  },
  "method": "map",
  "args": [
    {
      "expr": "lambda",
      "param": "x",
      "body": {
        "expr": "bin",
        "op": "*",
        "left": { "expr": "var", "name": "x" },
        "right": { "expr": "lit", "value": 2 }
      }
    }
  ]
}

Result: [6, 8, 10]

4. Dynamic Array Construction (Array Expression)

The new array expression enables dynamic array construction:

{
  "expr": "array",
  "elements": [
    { "expr": "var", "name": "basicSetup" },
    {
      "expr": "call",
      "target": { "expr": "var", "name": "json" },
      "method": "apply",
      "args": []
    }
  ]
}

This is equivalent to JavaScript's [basicSetup, json()].

Combining with state and literals:

{
  "expr": "array",
  "elements": [
    { "expr": "state", "name": "config" },
    { "expr": "lit", "value": "default" },
    { "expr": "var", "name": "customPlugin" }
  ]
}

Nested arrays:

{
  "expr": "array",
  "elements": [
    {
      "expr": "array",
      "elements": [
        { "expr": "lit", "value": 1 },
        { "expr": "lit", "value": 2 }
      ]
    },
    {
      "expr": "array",
      "elements": [
        { "expr": "lit", "value": 3 },
        { "expr": "lit", "value": 4 }
      ]
    }
  ]
}

5. Value Clamping

Ensure a value stays within bounds:

{
  "expr": "call",
  "target": { "expr": "var", "name": "Math" },
  "method": "min",
  "args": [
    { "expr": "lit", "value": 100 },
    {
      "expr": "call",
      "target": { "expr": "var", "name": "Math" },
      "method": "max",
      "args": [
        { "expr": "lit", "value": 0 },
        { "expr": "state", "name": "value" }
      ]
    }
  ]
}

Security Measures

Constela takes security seriously. All method calls are protected by multiple layers of defense:

1. Whitelist-Based Method Filtering

Only explicitly allowed methods can be called. Attempting to call a non-whitelisted method returns undefined:

{
  "expr": "call",
  "target": { "expr": "lit", "value": "hello" },
  "method": "constructor"  // Not allowed - returns undefined
}

The whitelist is defined at compile time and cannot be bypassed at runtime.

2. Prototype Pollution Prevention

Constela prevents access to prototype chain methods that could be used for injection attacks:

__proto__ access is blocked
constructor access is blocked
prototype access is blocked

3. Type-Aware Method Resolution

Methods are resolved based on the target value type, preventing type confusion attacks:

{
  "expr": "call",
  "target": { "expr": "lit", "value": 123 },
  "method": "toUpperCase"  // Returns undefined - numbers don't have this method
}

4. Safe Null/Undefined Handling

Calling methods on null or undefined returns undefined gracefully without throwing:

{
  "expr": "call",
  "target": { "expr": "state", "name": "nonexistent" },
  "method": "length"  // Returns undefined
}

Conclusion

This update to Constela brings powerful data transformation and array construction capabilities while maintaining the security-first approach that defines the framework. Call, lambda, and array expressions enable:

Declarative data transformations - Filter, map, and transform data without JavaScript
Dynamic array construction - Build arrays from variables, function results, and expressions
Type-safe operations - Compile-time validation ensures correct usage
Secure by default - Whitelist-based method filtering prevents injection attacks
Composable expressions - Chain operations for complex transformations

Getting Started

# Create a new Constela project
npx create-constela my-app
cd my-app
npm run dev

Resources

We are excited to see what you build with Constela!

Constela is MIT licensed. Contributions welcome!