hugsy.

Getting started

Installation

One Swift file. No dependency in your app.

Copy a component

  1. Open a component page and select Source.
  2. Copy the Swift file into your project.
  3. In Xcode, select the file and confirm your iOS app is checked under Target Membership.
  4. Use the component in your SwiftUI view. Keep its supporting types in the same file.

Nothing needs to be added to Package Dependencies. Retain the MIT license notice when adopting source.

Install the native CLI

The optional hugsy command is written in Swift. The installer downloads a pinned source archive, verifies its SHA-256 checksum, and builds it with your local Swift toolchain.

Terminal
curl -fsSL https://pulkitxm.github.io/hugsy/install.sh | sh

You need macOS 14+, Xcode, Swift 6, and an internet connection for this first build. The command is installed to ~/.local/bin. Make sure that directory is on your PATH. After installation, discovery, source copying, and MCP work offline.

Prefer to inspect and build it yourself?

Terminal
git clone https://github.com/pulkitxm/hugsy.git
cd hugsy
swift build -c release --product hugsy
mkdir -p "$HOME/.local/bin"
install -m 755 .build/release/hugsy "$HOME/.local/bin/hugsy"

If Xcode is installed but Command Line Tools is selected, set DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer for Swift commands.

Add your first component

Terminal
cd YourApp
hugsy init --directory YourApp/Components/Hugsy
hugsy add expanding-cards --dry-run
hugsy add expanding-cards

Replace YourApp with your project’s actual directory. The CLI creates a small configuration file, previews the write plan, then copies the source. It does not edit your Xcode project.

hugsy.json
{
  "version": 1,
  "directory": "YourApp/Components/Hugsy"
}

For a Swift package, choose a directory inside the appropriate source target, such as Sources/YourApp/Hugsy. For a traditional Xcode app, confirm Target Membership after adding the files.

Your changes stay yours

Installing an unchanged component twice is safe. If you customize a file, Hugsy refuses to overwrite it. Run hugsy diff expanding-cards to compare your source before explicitly opting into --force.

Paths must be project-relative and use letters, numbers, underscores, hyphens, and forward slashes. Traversal, symlinked destinations, and linked files are rejected.

IntroductionCLI reference