A native SwiftUI app on top of a CLI

Published: November 2, 2026
Reading time: 9 min
Series: lemon-code in 30 days, part 7 of 13

The first commit of lemon-code's macOS app, on May 16, 2026, had no screens. The message was "define app contract and execution rules". The window only showed up in the next commit.

That order was the app's most important decision. This post shows how a SwiftUI app can sit on top of a CLI without rewriting the agent in Swift, and the rules that keep both standing.

TL;DR

• The CLI runs the agent and providers; the app owns the UI and RPC calls.
• Commands and mutations go over JSON-RPC 2.0 on stdio; live state comes through events.
• A feature only shows up if the CLI advertises the capability with its implementing methods.
• Without a backend the app opens in degraded mode instead of breaking.

The intuition: dashboard and engine

A car dashboard shows speed, fuel and warnings, and has buttons that send commands. It doesn't burn fuel. Swap the dashboard and the engine stays the same.

The app is the dashboard; the CLI is the engine. The app repo's first rule says it plainly: keep lemon-code as the only execution engine.

Agent operations and changes to core state go through the CLI; the app UI does not open SQLite. The embedded terminal is separate: the app launches the child process and owns its PTY using launch configuration returned by the CLI.

The minimal example

The contract is newline-delimited JSON-RPC 2.0 over the CLI process's stdio. The app sends lc.app.initialize without parameters; the response includes contractVersion (app.v2), sessionId, serverInfo and capabilities.

{"jsonrpc":"2.0","id":1,"method":"lc.app.initialize"}

The app launches the CLI process, writes a line and reads the matching response. Agent logic stays in the CLI; the SwiftUI app also owns the PTY for its embedded terminal.

Commands one way, events the other

• Commands and mutations go through lc.app.* methods: projects, threads, approvals, review, automations, installation.
• Live state comes through canonical events.

lc.app.chat.send runs the prompt through the same controller as the CLI, persists messages and returns route provenance: requested and actual provider/model, ordered attempts and whether fallback was used. lc.app.chat.cancel cancels only the matching requestId, and cancellation is terminal: no new fallback attempt.

For the embedded terminal, the CLI returns only the launch config (cwd, login shell, args, environment) and the app owns the PTY and child process.

Capabilities: a successful initialize isn't enough

ADR 0058 fixed this. The risk was the app reading a successful initialize as support for every optional feature. With an older CLI, the app showed buttons the core couldn't execute. Now:

1. lc.app.getCapabilities advertises each optional feature with the methods implementing it.
2. The CLI won't advertise agentRooms: true unless the minimum method set is registered.
3. A successful initialize, an existing namespace or an open process grants nothing.
4. A missing capability means the feature is hidden by default.

An integrity test in the CLI prevents advertising a capability without matching methods.

Degraded mode

If the backend isn't running, the app opens in degraded mode. If the JSON-RPC connection fails, a dismissible banner appears that doesn't block typing. That's the difference between an app you use daily and one you close in frustration.

The app in numbers

From Git: 152 commits between May 16 and October 12, 2026. It requires macOS 13 and Swift 5.9 and runs with swift build and swift run LemonCodeApp.

Checklist: is your app on top of the CLI or beside it?

• Agent and provider actions go through the CLI; the embedded terminal uses the app's PTY.
• The app never writes to the core database.
• A versioned contract exists, written before the screens.
• Optional features depend on advertised capabilities with methods.
• Cancellation is terminal and doesn't trigger fallback.
• Without a backend, the app degrades instead of hanging.

Conclusion

A native app on top of a CLI works when the contract comes first and the app accepts being the dashboard. The engine lives in one place, tested through CLI, TUI and RPC. SwiftUI does what it's good at: windows, shortcuts, an embedded terminal and notifications.

Wednesday's post covers observability: keeping the Collector under your control and leaving conversation content out of telemetry.

If your team wants a desktop app on top of an existing command-line tool, designing that contract is work I do at LEMON.DEV.

References

• JSON-RPC 2.0 specification
• Apple, Process documentation

Related reading

• Bun + Ink: a terminal UI in React
• ADRs as project memory for multiple agents