Home Original page

GitHub - omarshahine/ShellCraft: macOS app for managing shell configuration through a native GUI

A native macOS app for managing your shell configuration through a GUI. No more hunting through dotfiles — edit your aliases, PATH, SSH keys, Git config, and more from a single window.

macOS 26.0+ Swift 6 No Dependencies

What It Does

ShellCraft reads your actual config files (.zshrc, .gitconfig, SSH configs, etc.), lets you edit them through a structured UI, and writes changes back safely — preserving comments, formatting, and anything it doesn't understand.

Sections

Section What It Manages
Aliases Shell aliases from .zshrc
Functions Shell functions from .zshrc
PATH $PATH entries with drag-to-reorder
Environment Environment variables from .zshrc
Oh My Zsh Themes, plugins, and settings
Git .gitconfig and global .gitignore
SSH SSH config hosts, key generation, key management
Secrets macOS Keychain secrets with encrypted export/import
Homebrew Installed packages and casks
Claude Code settings.json, permissions, hooks, plugins, MCP servers
Tools Custom CLI tools

Every section supports import/export and shows a save bar when you have unsaved changes.

Optional Tools

ShellCraft manages these tools when they're installed. Each section shows a helpful empty state if the tool is missing — nothing is required.

Tool Sections It Unlocks Install
Oh My Zsh Themes, plugins, Oh My Zsh settings sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
Homebrew Package and cask management /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Claude Code Settings, permissions, hooks, plugins, MCP servers npm install -g @anthropic-ai/claude-code
Git Git config and gitignore Included with Xcode Command Line Tools

The core sections (Aliases, Functions, PATH, Environment, SSH, Secrets) work with just a default macOS install.

Getting Started

Prerequisites

  • macOS 26.0 (Tahoe) or later
  • Xcode 17+
  • XcodeGen (brew install xcodegen)

Build & Run

xcodegen generate
xcodebuild -project ShellCraft.xcodeproj -scheme ShellCraft -configuration Debug \
  -derivedDataPath ~/Library/Developer/Xcode/DerivedData/ShellCraft build
open ~/Library/Developer/Xcode/DerivedData/ShellCraft/Build/Products/Debug/ShellCraft.app

Important: After running xcodegen generate, apply the icon fix:

sed -i '' 's|lastKnownFileType = folder; name = ShellCraft.icon; path = ShellCraft/ShellCraft.icon; sourceTree = SOURCE_ROOT;|lastKnownFileType = folder.iconcomposer.icon; path = ShellCraft.icon; sourceTree = "<group>";|' ShellCraft.xcodeproj/project.pbxproj

XcodeGen doesn't understand .icon bundles (Icon Composer format), so this sed command fixes the file type in the generated project.

Architecture

  • MVVM with @MainActor @Observable ViewModels
  • Pure SwiftUI + AppKit — no third-party dependencies
  • Round-trip safe writes — config files are parsed into memory; only targeted lines are modified on save
  • XcodeGen — project.yml is the source of truth, never edit .xcodeproj directly

See CLAUDE.md for detailed architecture docs, conventions, and contributor instructions.

Key Design Decisions

Why not just edit the files directly? You can, and ShellCraft will pick up external changes. But a GUI makes it easier to discover what's configured, avoid syntax errors, and manage things like SSH keys and Keychain secrets that are awkward from the terminal.

Why no SPM dependencies? Everything ShellCraft needs is in the platform SDKs. No dependency management, no version conflicts, no supply chain risk.

Why XcodeGen? The .xcodeproj format is hostile to version control. project.yml is human-readable and merge-friendly.

License

MIT — see LICENSE for details.