A minimal, Metal-accelerated terminal emulator for iPhone, iPad, Vision Pro, and Mac.
Shell is a minimal fork of rootshell, reduced to four capabilities:
- Local terminal: swiftty rendering behind the SwifttyKit API, tabs, splits, scrollback, search, and session restore.
- SSH: password, key, and keyboard-interactive auth, known hosts, profiles, jump host, Secure Enclave keys, and OpenSSH user certificates.
- Native tmux control mode:
tmux -CC, with windows as tabs and panes as splits. - iCloud sync: CloudKit for profiles, known hosts, public identity metadata, and settings; iCloud Keychain for secrets. Secure Enclave keys never leave their device.
If a feature does not make the terminal render, establish a secure SSH identity, make SSH connect, make tmux work, or make those configurations sync, it does not belong in the fork.
The one explicit exception is the optional Control companion: Shell Watch and the iPhone review permission requests raised on a Mac (including Claude Code and Codex prompts), through a Mac-local authority reached over Tailscale. It adds no terminal, SSH, or bulk approval to the Watch, and the terminal app builds and runs without it.
| Spec | Enables |
|---|---|
| shell.md | The fork itself: terminal, SSH identity, tmux, sync, settings, Mac build, dependency rule |
| mobile-connectivity.md | Surviving network loss: tmux session recovery, honest SSH reconnect, no silent command re-runs |
| control-protocol.md | shell-control/1 and the iPhone gateway: pairing, signed decisions, consume/receipts, Watch via iPhone, push |
| control-setup.md | Guided setup, doctor diagnostics, safe test review, no-relay mode |
| control-cli.md | The native shell-control CLI: install state, launchd lifecycle, Tailscale Serve, status |
| agent-relay.md | Answering Claude Code and Codex permission prompts and questions from iPhone and Watch |
| keyboard-replacement.md | The Shell terminal keyboard: app-owned US layout, shared modifiers, System escape hatch |
| simplification.md | Implementation simplification: stable action targets, connection-flow and session ownership, typed commands, sync durability |
iOS, iPadOS, macOS (Mac Catalyst), and visionOS 27+, built with Xcode 27 or newer. The
27 SDKs and the Swift 6.4 runtime are required: Citadel uses CryptoKit's
MLKEM768/MLDSA*, the vendored packages adopt Swift 6.4 standard library APIs, and
the sources call 26+ API without #available gates. Xcode Cloud workflows must pin
Xcode 27 or "Latest Release".
shell/ the app: App, Core, Features (LocalShell, SSH, Tmux, Profiles, Control), UI
Shared/, ShellMacSupport/ MacBridge and the Catalyst-only AppKit bundle
ShellWatch/ the watchOS app (config: Configuration/Watch.xcconfig)
Packages/SwifttyKit/ the SwifttyKit embedder API as a Swift module on swiftty
Packages/ShellControlCore/ portable control protocol, security, gateway, and client code
services/shell-control/ Mac-local broker
services/push-relay/ optional stateless push relay
cmd/ shell-controld, the shell-control CLI, and the host runtime
ShellControlHost/ sandboxed Control host LaunchAgent (Catalyst only)
adapters/, protocol/ example hook integrations; published schemas and fixtures
tests/, ShellWatchTests/ unit tests
vendor/ every external Swift package, vendored and pinned
Prerequisites: Tailscale on the Mac and iPhone, with MagicDNS and HTTPS certificates enabled. Download the signed Shell Control disk image and run:
bin/shell-control setup --guided # preflight, services, iPhone pairing, safe test review
bin/shell-control agent install claude-code # or codex: relay agent permission prompts
bin/shell-control doctor # read-only diagnosticsOn the iPhone use Settings → Control. The Watch is enrolled afterwards from the Watch
app. See cmd/README.md for every command and
services/push-relay/README.md for remote alerts.
Local development:
./scripts/run-broker.sh # dev broker on http://127.0.0.1:8443
./scripts/dev-pair.sh # loopback pairing link for Settings → Control
./scripts/dev-confirm.sh <USER-CODE> # confirm the code the phone or Watch shows
./scripts/run-watch.sh # Watch app on the paired simulatorTo test remote alerts, set SHELL_CONTROL_PUSH_RELAY_URL = https:/$()/relay.example in the
untracked Configuration/Local.xcconfig. The $() stops xcconfig reading // as a comment.
./scripts/build.sh # iOS Simulator build with a de-duplicated error summary
./scripts/test.sh # ShellTests on the iOS Simulator
./scripts/build-watch.sh # ShellWatch for the watchOS Simulator
./scripts/test-watch.sh # ShellWatchTests on the watchOS Simulator
./scripts/test-control.sh # control SwiftPM packages: core, broker, host
./scripts/test-lifecycle.sh # isolated CLI lifecycle testsThe test targets are synchronized file-system groups, so a new test file needs no project
edit. ShellTests runs on the iOS Simulator only, because the local-shell stack is excluded
from Catalyst builds. tests/MacSupportSmoke.swift is a standalone binary for
ShellMacSupport.bundle:
xcrun swiftc Shared/MacBridge.swift tests/MacSupportSmoke.swift -o /tmp/shell-mac-support-smoke
/tmp/shell-mac-support-smoke .derivedData/Build/Products/Debug/ShellMacSupport.bundleAll packages are vendored under vendor/, pinned by vendor/manifest, and managed by
scripts/vendor.py. Builds never resolve packages over the network; xcframework zips are
fetched and checked against their SHA-256. Binary-only packages (source=none in the
manifest) keep just their Package.swift, license files, and any resource the app embeds;
their full source is at the pinned commit upstream. Hand edits go in
vendor/patches/<package>/*.patch and are re-applied on each sync.
./scripts/vendor.py status # pinned vs newest upstream tag
./scripts/vendor.py update Citadel-rootshell 0.12.5 # bump a pin
./scripts/vendor.py sync # make vendor/ match the manifest
./scripts/vendor.py verify # offline consistency check (CI)CI and TestFlight run on Xcode Cloud. Workflows are configured in App Store Connect, and
this repository provides the shared shell and ShellWatch schemes plus these hooks:
| Script | What it does |
|---|---|
ci_scripts/ci_post_clone.sh |
vendor.py verify; writes Local.xcconfig from SHELL_CONTROL_PUSH_RELAY_URL if set |
ci_scripts/ci_pre_xcodebuild.sh |
Stamps CI_BUILD_NUMBER into both xcconfigs |
ci_scripts/ci_post_xcodebuild.sh |
Runs test-control.sh on test actions |
- CI runs on PRs to
mainand on pushes tomain. It testsshell(iOS) andShellWatch(watchOS). - TestFlight runs on pushes to
main. It runs the same tests, then archivesshellfor iOS, visionOS, and Mac Catalyst and sends each archive to internal testing. - The Watch app is embedded in the iOS archive (
platformFilter = ios), soMARKETING_VERSIONmust be bumped by hand in bothBase.xcconfigandWatch.xcconfig.
To archive locally, use scripts/archive.sh ios|ipados|visionos|maccatalyst. It needs
ASC_KEY_ID, ASC_ISSUER_ID, and ASC_KEY_PATH for an App Store Connect key with App
Manager access.
Shell is open source under the MIT License. Upstream rootshell is MIT-licensed by Rootshell LLC; see THIRD_PARTY_NOTICES.md for the terminal, SSH, and shell components it builds on.