DEV Community: Yuuichi Eguchi

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!

Introducing the Constela VSCode Extension - Build UIs with JSON

Yuuichi Eguchi — Sat, 24 Jan 2026 07:22:06 +0000

Introducing the Constela VSCode Extension

I'm excited to announce the release of the official VSCode extension for Constela - a JSON-based UI DSL that compiles to minimal runtime JavaScript.

Install from VSCode Marketplace

What is Constela?

Constela is a declarative UI framework where you define your entire application in JSON. No complex JavaScript, no JSX - just pure, structured JSON that describes your UI, state, and interactions.

Here's a simple counter example:

{
  "version": "1.0",
  "state": {
    "count": { "type": "number", "initial": 0 }
  },
  "actions": [
    {
      "name": "increment",
      "steps": [
        { "do": "update", "name": "count", "with": "increment" }
      ]
    }
  ],
  "view": {
    "node": "element",
    "tag": "button",
    "props": {
      "onClick": { "action": "increment" }
    },
    "children": [
      {
        "node": "text",
        "content": { "expr": "state", "name": "count" }
      }
    ]
  }
}

Learn more at constela.dev

Extension Features

Syntax Highlighting

The extension provides full syntax highlighting for .constela.json files:

Expression types: lit, state, var, bin, cond, get, concat, and more
Action steps: set, update, fetch, navigate, delay, interval, etc.
View nodes: element, text, if, each, component, slot, etc.

IntelliSense Auto-completion

Get smart completions as you type:

Type "expr": " to see all available expression types
Type "do": " to see all action step types
Type "node": " to see all view node types
Reference completions for your defined state, actions, and components

Real-time Validation

Errors appear instantly as you type, powered by the Constela compiler:

JSON syntax errors
Missing required fields
Undefined state/action/component references
Type mismatches

Hover Documentation

Hover over any keyword to see its documentation, including:

Signature and structure
Description and usage
Available options

Go to Definition

Use Ctrl+Click (or Cmd+Click on macOS) to jump to:

State field definitions
Action definitions
Component definitions

Installation

Open VSCode
Go to Extensions (Ctrl+Shift+X)
Search for "Constela"
Click Install

Or install directly from the VSCode Marketplace.

Getting Started

Create a new file with the .constela.json extension
Start with the basic structure shown above
Enjoy syntax highlighting and real-time validation!

Technical Details

The extension uses the Language Server Protocol (LSP) for a robust editing experience:

Validation Engine: Full Constela compiler integration
Bundle Size: ~160KB (all dependencies included)
Zero External Dependencies: Everything is bundled with esbuild

Why Constela?

No Build Step Complexity: JSON is your source of truth
Type-Safe by Design: The compiler catches errors before runtime
Minimal Runtime: Compiles to optimized JavaScript
AI-Friendly: JSON structure is perfect for AI-assisted development

Feedback

Found a bug or have a feature request? Please open an issue on GitHub.

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

Introducing create-constela: Bootstrap Constela Projects in Seconds

Yuuichi Eguchi — Wed, 21 Jan 2026 23:21:45 +0000

TL;DR

npx create-constela my-app
cd my-app
npm run dev

Three commands. That's all you need to start building with Constela.

What is create-constela?

create-constela is a scaffolding CLI tool for Constela projects. Similar to create-next-app or create-vite, it lets you bootstrap a new project with a single command.

Features

Interactive mode: Choose project name and package manager interactively
Template selection: Start with examples using the --example option
Flexible options: Skip git initialization or dependency installation as needed

Usage

Basic Usage

npx create-constela my-app

This command will:

Prompt you to select a package manager (npm / yarn / pnpm)
Create the project directory
Copy template files
Initialize git repository
Install dependencies

CLI Options

Option	Description
`--example <name>`	Use a specific example template
`--template <name>`	Use a specific template
`--list`	List available templates and examples
`--no-git`	Skip git initialization
`--no-install`	Skip dependency installation
`--package-manager <pm>`	Specify package manager (npm/yarn/pnpm)

Examples

# List available templates
npx create-constela --list

# Create with a specific example
npx create-constela my-app --example counter

# Skip git and install
npx create-constela my-app --no-git --no-install

# Use pnpm
npx create-constela my-app --package-manager pnpm

Generated Project Structure

my-app/
├── constela.config.json
├── package.json
├── .gitignore
└── src/
    └── routes/
        └── index.json

The generated index.json gives you a minimal starting point:

{
  "version": "1.0",
  "state": {},
  "actions": [],
  "view": {
    "kind": "element",
    "tag": "div",
    "children": [
      {
        "kind": "element",
        "tag": "h1",
        "children": [
          { "kind": "text", "value": { "expr": "lit", "value": "Welcome to Constela" } }
        ]
      }
    ]
  }
}

What is Constela?

Constela is a compiler-first UI language designed for AI-generated UIs.

Unlike React or Next.js, you don't write UI with JavaScript. Instead, you describe UI behavior as a constrained JSON DSL, which is validated, analyzed, and compiled into minimal runtime code.

Key Differences

	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

Performance Comparison

We rebuilt Constela's official website using both Constela and Next.js:

Metric	Constela	Next.js	Difference
Build time	2.2s	12.3s	5.6× faster
node_modules size	297MB	794MB	2.7× smaller
Output size	14MB	72MB	5.1× smaller

Technical Implementation

create-constela is built with:

commander.js: CLI argument parsing
@inquirer/prompts: Interactive prompts
Node.js fs API: File copying and transformation
TDD: 163 test cases ensuring quality

Security

Path traversal protection is built-in. Malicious inputs like ../../../etc/passwd are rejected at the template resolution layer.

Getting Started

Ready to try Constela? Run:

npx create-constela my-app
cd my-app
npm run dev

Open http://localhost:3000 and start building!

Links

Have questions or feedback? Drop a comment below!