# Platform & Build Boundaries

> How each repository encodes portability: tmux uses autotools, feature checks, compat sources, and C dependencies; cmux uses Xcode targets, Swift packages, bundled app resources, and a separate web backend surface.

- Repository: tmux/tmux-with-manaflow-ai-cmux
- GitHub: https://github.com/tmux/tmux
- Human wiki: https://grok-wiki.com/public/wiki/tmux-tmux-with-manaflow-ai-cmux-62db34dfaddc
- Complete Markdown: https://grok-wiki.com/public/wiki/tmux-tmux-with-manaflow-ai-cmux-62db34dfaddc/llms-full.txt

## Source Files

- `tmux-tmux:configure.ac`
- `tmux-tmux:Makefile.am`
- `tmux-tmux:compat.h`
- `manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj`
- `manaflow-ai-cmux:Packages/CMUXWorkstream/Package.swift`
- `manaflow-ai-cmux:Packages/CMUXAgentLaunch/Package.swift`
- `manaflow-ai-cmux:web/README.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [tmux-tmux:configure.ac](tmux-tmux/configure.ac)
- [tmux-tmux:Makefile.am](tmux-tmux/Makefile.am)
- [tmux-tmux:compat.h](tmux-tmux/compat.h)
- [tmux-tmux:autogen.sh](tmux-tmux/autogen.sh)
- [tmux-tmux:osdep-linux.c](tmux-tmux/osdep-linux.c)
- [tmux-tmux:osdep-darwin.c](tmux-tmux/osdep-darwin.c)
- [tmux-tmux:compat/forkpty-sunos.c](tmux-tmux/compat/forkpty-sunos.c)
- [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj](manaflow-ai-cmux/cmux.xcodeproj/project.pbxproj)
- [manaflow-ai-cmux:Packages/CMUXWorkstream/Package.swift](manaflow-ai-cmux/Packages/CMUXWorkstream/Package.swift)
- [manaflow-ai-cmux:Packages/CMUXAgentLaunch/Package.swift](manaflow-ai-cmux/Packages/CMUXAgentLaunch/Package.swift)
- [manaflow-ai-cmux:Packages/CMUXAgentVault/Package.swift](manaflow-ai-cmux/Packages/CMUXAgentVault/Package.swift)
- [manaflow-ai-cmux:Packages/CMUXAuthCore/Package.swift](manaflow-ai-cmux/Packages/CMUXAuthCore/Package.swift)
- [manaflow-ai-cmux:Packages/CMUXWorkstream/Sources/CMUXWorkstream/WorkstreamTransport.swift](manaflow-ai-cmux/Packages/CMUXWorkstream/Sources/CMUXWorkstream/WorkstreamTransport.swift)
- [manaflow-ai-cmux:Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchEnvironmentPolicy.swift](manaflow-ai-cmux/Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchEnvironmentPolicy.swift)
- [manaflow-ai-cmux:web/README.md](manaflow-ai-cmux/web/README.md)
- [manaflow-ai-cmux:web/package.json](manaflow-ai-cmux/web/package.json)
- [manaflow-ai-cmux:web/scripts/dev-local.sh](manaflow-ai-cmux/web/scripts/dev-local.sh)
- [manaflow-ai-cmux:web/db/schema.ts](manaflow-ai-cmux/web/db/schema.ts)
- [manaflow-ai-cmux:web/app/api/vm/route.ts](manaflow-ai-cmux/web/app/api/vm/route.ts)
- [manaflow-ai-cmux:web/app/api/vm/[id]/route.ts](manaflow-ai-cmux/web/app/api/vm/[id]/route.ts)
- [manaflow-ai-cmux:web/services/vms/drivers/types.ts](manaflow-ai-cmux/web/services/vms/drivers/types.ts)
- [manaflow-ai-cmux:web/services/vms/drivers/index.ts](manaflow-ai-cmux/web/services/vms/drivers/index.ts)
- [manaflow-ai-cmux:web/services/vms/providerGateway.ts](manaflow-ai-cmux/web/services/vms/providerGateway.ts)
- [manaflow-ai-cmux:web/services/vms/workflows.ts](manaflow-ai-cmux/web/services/vms/workflows.ts)
</details>

# Platform & Build Boundaries

This page compares how `tmux-tmux` and `manaflow-ai-cmux` encode portability. `tmux-tmux` is a C project that pushes platform differences into Autotools probes, conditional source selection, compatibility implementations, and small OS-specific files. `manaflow-ai-cmux` is a macOS/iOS-adjacent application that uses Xcode targets, Swift package manifests, bundled resources, and a separate Next.js backend surface.

Generation note: this comparison follows the prompt-supplied bundled Compound Engineering wiki recipe as page-shape guidance. No local `STRATEGY.md` or `docs/solutions/**` context was found in the prepared workspace, so repository code and config are treated as the source of truth.

## Boundary Model

```text
tmux-tmux
  configure.ac       -> detects host, libraries, headers, functions
  Makefile.am        -> selects flags, sources, compat objects
  compat.h + compat/ -> normalizes missing APIs for C callers
  osdep-*.c          -> isolates OS behavior behind common functions

manaflow-ai-cmux
  cmux.xcodeproj     -> app, CLI, plugin, test targets, resources
  Packages/*         -> Swift module/platform boundaries
  Resources/scripts  -> bundled terminal, shell, FFI, helper assets
  web/               -> Next.js backend, DB, provider-driver API
```

The main difference is where portability is decided. `tmux-tmux` makes portability a configure-time contract: the generated build knows what the host lacks and adds replacement objects. `manaflow-ai-cmux` makes portability a product-surface contract: native app pieces are separated into Xcode targets and Swift packages, while web/cloud behavior is delegated to the `web/` backend.

Sources: [tmux-tmux:configure.ac:135-197](), [tmux-tmux:configure.ac:895-1005](), [tmux-tmux:Makefile.am:84-241](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1694-1813](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1849-1874](), [manaflow-ai-cmux:web/README.md:1-5]()

## tmux: Autotools As The Portability Front Door

`tmux-tmux` starts by canonicalizing the host, setting compiler tools, and checking headers, functions, and libraries. Its `configure.ac` checks for headers such as `libutil.h`, `pty.h`, `sys/tree.h`, and `util.h`, then separately checks for functions that may be present, missing, or replaced by local compatibility code. That means platform support is mostly encoded as capability detection, not by assuming a particular Unix variant.

Key build-time decisions include:

| Concern | Where encoded | Effect |
|---|---|---|
| Compiler/build modes | `--enable-debug`, `--enable-optimizations`, `--enable-asan`, `--enable-static`, fuzzing | Produces conditional Automake flags and, for static builds, rejects unsupported macOS static linking |
| Core C dependencies | `libevent`, `ncurses`/`curses`, `yacc` | Fails configuration if required runtime/build libraries are unavailable |
| Optional integrations | `utempter`, `utf8proc`, `systemd`, `sixel` | Adds `HAVE_*`/`ENABLE_*` defines and conditional sources only when enabled |
| Host platform | `case "$host_os"` | Maps host OS to `PLATFORM`, then exposes Automake conditionals |

Sources: [tmux-tmux:configure.ac:44-99](), [tmux-tmux:configure.ac:242-289](), [tmux-tmux:configure.ac:291-373](), [tmux-tmux:configure.ac:379-481](), [tmux-tmux:configure.ac:895-1017]()

### Compatibility Sources And Headers

The compatibility layer has two parts. First, `configure.ac` uses `AC_REPLACE_FUNCS` and `AC_LIBOBJ` for missing or unsuitable functions such as `asprintf`, `getline`, `strlcpy`, `strtonum`, `reallocarray`, `imsg`, `daemon`, `vis`, `fdforkpty`, and `base64`. Second, `compat.h` gives callers stable declarations, fallback includes, and fallback macros such as `pledge(s, p) (0)` outside OpenBSD.

This keeps most tmux code from branching directly on OS names. A caller includes `compat.h` and relies on the build to provide either the native API or the compat object.

```c
/* tmux-tmux:compat.h */
#ifdef HAVE_QUEUE_H
#include <sys/queue.h>
#else
#include "compat/queue.h"
#endif

#ifdef HAVE_TREE_H
#include <sys/tree.h>
#else
#include "compat/tree.h"
#endif
```

Sources: [tmux-tmux:configure.ac:173-240](), [tmux-tmux:configure.ac:648-728](), [tmux-tmux:compat.h:133-187](), [tmux-tmux:compat.h:388-415]()

### OS-Specific Files Stay Narrow

`Makefile.am` includes the shared tmux source list and then adds `osdep-@PLATFORM@.c`, with conditional extras for `forkpty`, systemd, utf8proc, and sixel. The OS files themselves are targeted: Linux reads `/proc` paths and disables epoll for `/dev/null`; Darwin uses `proc_pidinfo`/`sysctl` and disables libevent kqueue/poll. Solaris has a dedicated `forkpty` implementation for `/dev/ptmx`.

Sources: [tmux-tmux:Makefile.am:221-241](), [tmux-tmux:osdep-linux.c:29-102](), [tmux-tmux:osdep-darwin.c:37-109](), [tmux-tmux:compat/forkpty-sunos.c:32-92]()

## cmux: Xcode Targets And Swift Packages As Native Boundaries

`manaflow-ai-cmux` encodes native boundaries through Xcode targets. The project defines an application target, a CLI tool target, UI tests, a Dock Tile plugin bundle, and unit tests. The main app target depends on the CLI and Dock Tile plugin targets, and it links local and remote Swift package products.

This is a different portability shape from tmux: instead of detecting many host Unix capabilities, the project pins a macOS app environment and isolates product surfaces by target.

| Native surface | Evidence | Boundary role |
|---|---|---|
| `cmux.app` | `productType = "com.apple.product-type.application"` | Main desktop app bundle |
| `cmux-cli` | `productType = "com.apple.product-type.tool"` | Separate command-line tool shipped with the app |
| `CmuxDockTilePlugin` | `productType = "com.apple.product-type.bundle"` | Dock/plugin extension surface |
| `cmuxTests`, `cmuxUITests` | XCTest bundle target types | Test-only build surfaces |
| Local Swift packages | `Packages/CMUX*`, `vendor/bonsplit`, `vendor/stack-auth...` | In-repo or vendored module boundaries |
| Remote Swift packages | Sparkle, Sentry, PostHog, MarkdownUI | External app dependencies |

Sources: [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1694-1813](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1849-1874](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:2873-3022]()

### Deployment And App Configuration

The Xcode build settings pin the native project to `SDKROOT = macosx` and `MACOSX_DEPLOYMENT_TARGET = 14.0` in the shared Debug/Release build configurations. The app target also distinguishes Debug and Release identity: Debug uses `cmux DEV`, a development callback scheme, and no entitlements file, while Release uses `cmux`, `Resources/cmux.entitlements`, and the production callback scheme.

Sources: [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:2512-2589](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:2591-2669]()

### Bundled Resources Are Part Of The Platform Contract

The main app resources include assets, `xterm-ghostty`, third-party licenses, localized strings, an AppleScript definition, `opencode-plugin.js`, `feed-tui`, and `markdown-viewer`. A shell build phase copies Ghostty resources, terminfo, shell integration files, and builds a Ghostty CLI helper for `arm64`, `x86_64`, or universal architectures.

This is portability by bundling: the app carries terminal/runtime assets it needs, rather than relying entirely on the user’s machine.

Sources: [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1878-1894](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1918-1955]()

## cmux Swift Packages: Platform Pins And Module Scope

The Swift package manifests show that cmux is not one monolithic app module. `CMUXWorkstream` supports both iOS 18 and macOS 14. `CMUXAuthCore` follows the same iOS/macOS split. `CMUXAgentLaunch` is macOS-only and depends on `CMUXAgentVault`; `CMUXAgentVault` is macOS 13+ and links SQLite.

This structure lets portable domain code live in packages that can compile for iOS and macOS, while process-launch and local agent/session code remains macOS-specific.

Sources: [manaflow-ai-cmux:Packages/CMUXWorkstream/Package.swift:1-24](), [manaflow-ai-cmux:Packages/CMUXAuthCore/Package.swift:1-25](), [manaflow-ai-cmux:Packages/CMUXAgentLaunch/Package.swift:1-28](), [manaflow-ai-cmux:Packages/CMUXAgentVault/Package.swift:1-30]()

### Portable Interfaces Inside Packages

`CMUXWorkstream`’s `WorkstreamTransport` is a small example of provider-neutral interface design: the store can use a Unix socket on macOS, an in-memory pipe in tests, or a relay WebSocket on iOS without changing store code. `CMUXAgentLaunch` takes a different approach: it allowlists selected environment keys and sanitizes values before launching/resuming agents, which keeps BYOK-style environment configuration possible without forwarding arbitrary secrets.

Sources: [manaflow-ai-cmux:Packages/CMUXWorkstream/Sources/CMUXWorkstream/WorkstreamTransport.swift:3-17](), [manaflow-ai-cmux:Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchEnvironmentPolicy.swift:26-96]()

## cmux Web Backend: Separate Runtime Surface

The `web/` directory is a Next.js app that serves the website, Stack Auth handlers, feedback endpoint, and Cloud VM backend routes. Its scripts use Bun, Next.js, Drizzle, local Docker Postgres helpers, and cloud-VM preflight/smoke/stress scripts. Local dev sources secrets from user-local files, derives ports from `CMUX_PORT`, starts/migrates Postgres, and runs `next dev` on the selected port.

That makes web/cloud portability distinct from the native app. The native app can ship app resources and CLI tools, while cloud VM creation, provider credentials, auth, billing, and database state stay behind server-side route handlers and services.

Sources: [manaflow-ai-cmux:web/README.md:1-26](), [manaflow-ai-cmux:web/README.md:40-94](), [manaflow-ai-cmux:web/package.json:6-30](), [manaflow-ai-cmux:web/scripts/dev-local.sh:126-153]()

### Provider-Neutral VM Boundary

The web VM subsystem is explicitly driver-based. `ProviderId` is currently `"e2b" | "freestyle"`, but callers consume a `VMProvider` interface with operations such as `create`, `destroy`, `exec`, `snapshot`, `restore`, `openAttach`, `openSSH`, and `revokeSSHIdentity`. A registry maps provider ids to concrete providers, and `VmProviderGateway` wraps provider calls as typed Effect services.

The route layer validates provider overrides before creating a VM, resolves the image for the selected provider, and calls `createVm` through `runVmWorkflow`. The workflow then composes repository, provider gateway, and billing gateway services. This keeps BYOC/BYOK direction intact: provider credentials and implementation details stay server-side, while the API deals in provider ids, images, leases, and typed workflow errors.

Sources: [manaflow-ai-cmux:web/services/vms/drivers/types.ts:1-104](), [manaflow-ai-cmux:web/services/vms/drivers/index.ts:8-30](), [manaflow-ai-cmux:web/services/vms/providerGateway.ts:17-76](), [manaflow-ai-cmux:web/app/api/vm/route.ts:93-190](), [manaflow-ai-cmux:web/app/api/vm/route.ts:261-327](), [manaflow-ai-cmux:web/services/vms/workflows.ts:50-60](), [manaflow-ai-cmux:web/services/vms/workflows.ts:70-170]()

### Persistence Boundary

The backend uses Drizzle schema definitions for Cloud VM state, leases, usage events, and billing grants. Provider is stored as a database enum, VM status has a lifecycle enum, and idempotency/provider identifiers are protected by partial unique indexes. The delete route shows the API boundary: a request is authenticated, a VM id is read from the route, and `destroyVm` runs through the workflow layer.

Sources: [manaflow-ai-cmux:web/db/schema.ts:14-55](), [manaflow-ai-cmux:web/db/schema.ts:57-126](), [manaflow-ai-cmux:web/app/api/vm/[id]/route.ts:12-32]()

## Comparison: What Each Repository Does Better

| Dimension | `tmux-tmux` | `manaflow-ai-cmux` | Portable idea |
|---|---|---|---|
| Host portability | Strong compile-time probing for Unix variants, libraries, and broken APIs | Mostly pinned to Apple native platforms for the app, with web runtime separated | Put platform decisions at a small number of explicit boundaries |
| Dependency handling | Required C deps are discovered at configure time; optional deps are enabled by flags | Native dependencies are Swift package products; web dependencies live in `web/package.json` | Keep dependency graphs scoped to the runtime that needs them |
| Compatibility | Missing C APIs are normalized through `compat.h` and `compat/` sources | Cross-surface behavior is normalized through Swift protocols and web service interfaces | Prefer stable local contracts over scattered platform/provider checks |
| Bundling | Builds a single `tmux` binary plus selected compat/platform objects | Ships app resources, CLI helper, plugin bundle, and packaged terminal assets | Bundle only what the runtime cannot safely assume from the host |
| BYOC/BYOK posture | Vendor-neutral in the Unix/C sense: depends on system libraries and detected host capabilities | Provider-aware but gateway-based: VM providers are behind driver/service contracts and credentials remain backend-owned | Treat providers as replaceable adapters, not as product-wide assumptions |

Sources: [tmux-tmux:Makefile.am:18-47](), [tmux-tmux:Makefile.am:50-82](), [tmux-tmux:Makefile.am:221-241](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1715-1734](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1736-1755](), [manaflow-ai-cmux:web/services/vms/drivers/types.ts:76-104]()

## Maintenance Guidance

For tmux-style changes, ask: is this a missing host capability, a broken host capability, or a genuinely different OS behavior? Missing or broken APIs belong in `configure.ac`, `compat.h`, and `compat/`; OS behavior belongs in `osdep-*.c`; user-facing build modes belong in Autoconf options and Automake conditionals.

For cmux-style changes, ask: is this native app behavior, reusable Swift domain code, bundled runtime asset, CLI behavior, or backend/provider behavior? Native product shape belongs in Xcode targets and build phases; reusable Swift contracts belong in `Packages/`; cloud/provider work belongs in `web/services/**` and thin Next route handlers. Keep provider-specific logic behind typed adapters so BYOC/BYOK support remains portable across file, repository, or catalog-sourced integrations.

Sources: [tmux-tmux:configure.ac:717-728](), [tmux-tmux:Makefile.am:221-241](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1694-1813](), [manaflow-ai-cmux:Packages/CMUXWorkstream/Sources/CMUXWorkstream/WorkstreamTransport.swift:3-17](), [manaflow-ai-cmux:web/app/api/vm/route.ts:99-190](), [manaflow-ai-cmux:web/services/vms/providerGateway.ts:55-76]()

In short, `tmux-tmux` optimizes for broad Unix source portability through configure-time evidence and compatibility code, while `manaflow-ai-cmux` optimizes for product-surface separation: Apple-native targets and packages on one side, a provider-gateway web backend on the other. Both patterns are portable when the boundary stays explicit and narrow. Sources: [tmux-tmux:configure.ac:993-1005](), [manaflow-ai-cmux:cmux.xcodeproj/project.pbxproj:1849-1874](), [manaflow-ai-cmux:web/services/vms/drivers/types.ts:1-4]()