Add linux version

[scgopi]

Discussed in #68

^{Originally posted by kyp0717 August 8, 2026}
Hi,
Can I make contribution to the project by add linux compatibility?
Please advise.
Thanks,
Phat

[scgopi]

[graphcode-fixer] Classified as enhancement (out of scope for automated bug fixing): this asks for new Linux compatibility for a macOS-only app (Swift/SwiftUI + AppKit), which is a new capability rather than a report of broken behaviour.

---

Generated by Claude Code

[scgopi]

I looked into what a Linux version actually requires, and landed the first concrete step in #110. Findings below — and @kyp0717, contributions are very much possible here; the bottom section is effectively a contributor roadmap.

How the codebase splits, portability-wise

Component	What it is	Linux status
GraphcodeKit	Shared framework: domain types, graph store, daemon IPC, PTY sessions	✅ Builds on Linux as of #110 — it's almost entirely pure Foundation
graphcode (CLI)	Talks to the daemon over a Unix socket	✅ Builds and runs on Linux as of #110
graphcoded	The orchestrator daemon	✅ Builds on Linux as of #110 (service/install story still open)
zmx	Session persistence (Zig, ThirdParty/)	🟡 Zig cross-compiles; not yet wired into Linux CI
graphcode.app	The UI: SwiftUI + TCA + GhosttyKit + Carbon	❌ Not portable as-is — this is the real work

What #110 does

• Adds a root Package.swift so the three non-UI products build with SwiftPM on Linux (Tuist keeps building the app from Project.swift and ignores it).
• Guards the handful of Darwin-isms: openpty works on both platforms (glibc ≥ 2.34 has it in libc); sockaddr_un.sun_len and launchd bootstrap are macOS-gated; SOCK_STREAM/timeval differences handled.
• Adds a Linux CI workflow (swift:6.2 container) that builds everything and smoke-runs the CLI, so Linux stays green from here on.

What's still needed for a usable Linux version, roughly in order

1. Daemon service story — a systemd user unit as the launchd LaunchAgent equivalent, plus a Linux install path (make daemon-install mostly works already since everything lives in ~/.graphcode).
2. zmx on Linux — build the Zig submodule for Linux and add it to CI; it's what makes sessions survive restarts.
3. Shell/backend assumptions — spawn paths default to /bin/zsh; Linux needs $SHELL//bin/bash fallbacks.
4. Headless usability pass — with daemon + CLI running on Linux, graphcode node create/status/send should work end-to-end without the app; needs real-machine testing beyond CI's build gate.
5. The UI — the big one. SwiftUI/TCA/GhosttyKit/Carbon don't port. Realistic options: (a) headless-first (daemon + CLI only, drive it from a Mac app remotely — the RemoteProjectLocation/relay plumbing already points this way), (b) a separate Linux front end (GTK, web-based, or a TUI) speaking the same socket protocol, or (c) wait on upstream cross-platform Swift UI efforts. (a) is nearly free after steps 1–4; (b) is a project-sized effort.

Steps 1–4 are well-scoped, independent contributions if anyone wants to pick one up.