Skip to content
chr33sPublic
forked from kitknox/rootshell

About

shell - a minimal fork of rootshell

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

328 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Shell

Shell

A minimal, Metal-accelerated terminal emulator for iPhone, iPad, Vision Pro, and Mac.

About

Shell is a minimal fork of rootshell, reduced to four capabilities:

  1. Local terminal: swiftty rendering behind the SwifttyKit API, tabs, splits, scrollback, search, and session restore.
  2. SSH: password, key, and keyboard-interactive auth, known hosts, profiles, jump host, Secure Enclave keys, and OpenSSH user certificates.
  3. Native tmux control mode: tmux -CC, with windows as tabs and panes as splits.
  4. 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.

Specifications

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

Requirements

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".

Layout

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

Control companion

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 diagnostics

On 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 simulator

To 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.

Building

./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 tests

The 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.bundle

Dependencies

All 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)

Releasing

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 main and on pushes to main. It tests shell (iOS) and ShellWatch (watchOS).
  • TestFlight runs on pushes to main. It runs the same tests, then archives shell for iOS, visionOS, and Mac Catalyst and sends each archive to internal testing.
  • The Watch app is embedded in the iOS archive (platformFilter = ios), so MARKETING_VERSION must be bumped by hand in both Base.xcconfig and Watch.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.

Open Source

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.

About

shell - a minimal fork of rootshell

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages