Skip to content

getting-started.md

Latest commit

 

History

History
174 lines (127 loc) · 9.12 KB

getting-started.md

File metadata and controls

174 lines (127 loc) · 9.12 KB

Getting Started

This guide walks you from a fresh clone to a running Crow app with GitHub (or GitLab) authentication and a scaffolded workspace.

1. Clone the Repository

git clone --recurse-submodules https://github.com/radiusmethod/crow.git
cd crow

If you already cloned without --recurse-submodules:

git submodule update --init vendor/ghostty

2. Build

The one-shot build path uses the Makefile:

make build

This runs setup (initializes submodules and checks prerequisites), ghostty (builds the GhosttyKit XCFramework with Zig), and app (runs swift build). The result is two binaries in .build/debug/:

  • CrowApp — the main macOS application
  • crow — the CLI used by Claude Code sessions

Makefile Targets

Target Purpose
build Full build: submodules + ghostty + swift build (default)
setup Init submodules and verify build prerequisites (Zig 0.15.2, Metal toolchain)
check Verify all build and runtime prerequisites (includes gh, claude)
ghostty Build the GhosttyKit.xcframework only
app Run swift build (debug) without touching ghostty
release Release build + .app bundle via scripts/bundle.sh
sign Sign, create DMG, and notarize (requires DEVELOPER_ID_APPLICATION)
test Run all package tests
clean Remove .build/ (keeps the ghostty framework)
clean-all Remove .build/ and Frameworks/ (full rebuild)
help Print the target list

Advanced / Manual Build

If you need finer-grained control, you can run the individual steps that make build orchestrates:

# Build the Ghostty framework only (writes Frameworks/GhosttyKit.xcframework)
./scripts/build-ghostty.sh

# Debug build
swift build

# Release build
swift build -c release

# Create the .app bundle from a release build
./scripts/bundle.sh

# Sign and notarize the bundled .app
./scripts/sign-and-notarize.sh

Build troubleshooting:

  • Check Zig: zig version must show 0.15.2
  • Check Metal toolchain: xcrun -sdk macosx metal --version
  • Install the Metal toolchain if missing: xcodebuild -downloadComponent MetalToolchain
  • If swift build fails with linker errors, run ./scripts/build-ghostty.sh first (or just make build)

Using mise (Optional)

If you have mise installed, the predefined tasks in mise.toml wrap the same operations:

Task Runs
mise dev swift run CrowApp
mise build make build (full build)
mise build:release swift build -c release
mise build:ghostty bash scripts/build-ghostty.sh
mise test swift test
mise bundle bash scripts/bundle.sh
mise sign Depends on bundle, then sign + notarize
mise clean rm -rf .build .derived-data Crow.app
mise xcode:generate swift package generate-xcodeproj

3. GitHub Authentication

Crow uses the gh CLI to read issues, PRs, and GitHub Projects (V2) board status, and to write project board status (moving tickets to "In Progress" / "In Review") via the updateProjectV2ItemFieldValue GraphQL mutation.

gh auth login
gh auth refresh -s project,read:org,repo
gh auth status   # verify the scopes above are listed

Required Scopes

Scope Why it's needed Used by
repo Read/write issues, PRs, branches, commit statuses gh issue view/edit, gh pr view/create, gh search issues
read:org Resolve org membership so @me assignee queries work across org repos gh search issues --assignee @me
project Read AND write GitHub Projects V2 board status — required to update Status to "In Progress" / "In Review" IssueTracker.swift updateProjectStatus(), the /crow-workspace skill when starting a session

Important: read:project is not sufficient. The in-code error messages will tell you to run gh auth refresh -s project — this is the write project scope, which is a superset of read:project. See Sources/Crow/App/IssueTracker.swift:691-692 and :768-769.

If you see [IssueTracker] GitHub token missing 'project' scope in stderr or INSUFFICIENT_SCOPES from a GraphQL call, re-run gh auth refresh -s project and retry.

Runtime CLI Permissions

Crow shells out to several CLIs at runtime. This table consolidates what each one needs:

Tool Auth / Scopes Notes
gh repo, read:org, project (see above) Set via gh auth login and gh auth refresh -s project,read:org,repo
glab api, read_user, read_repository (verify for your instance) Only required for GitLab workspaces. Issue/MR reads. Write scopes needed if you expect MR status updates.
git Local only — no external auth Ships with Xcode Command Line Tools
claude No network auth; binary must be on PATH Install from claude.ai/download

4. GitLab Authentication (Optional)

If any of your workspaces use self-hosted GitLab:

glab auth login --hostname gitlab.example.com

Crow will invoke glab with GITLAB_HOST set from the workspace config. The app does not enforce specific scopes on the GitLab token; check your instance's documentation for what your user account needs.

5. First Launch

.build/debug/CrowApp

On first launch, the setup wizard asks for:

  1. A development root directory (e.g. ~/Dev) — where Crow scaffolds workspaces and stores worktrees.
  2. One or more workspaces — each is a subdirectory under the dev root with a name, provider (github or gitlab), and (for GitLab) a host.

When you finish the wizard, Crow scaffolds the following under the dev root (see Sources/Crow/App/Scaffolder.swift):

{devRoot}/
├── {workspace}/                      # one directory per workspace
├── crow-reviews/                     # temporary clones for PR reviews
└── .claude/
    ├── CLAUDE.md                     # manager-tab context (crow CLI reference)
    ├── settings.json                 # pre-approved permissions for crow/gh/git
    ├── config.json                   # workspace config (workspaces + defaults)
    ├── prompts/                      # prompt files for crow-workspace sessions
    └── skills/
        ├── crow-workspace/           # /crow-workspace skill + setup.sh
        ├── crow-review-pr/           # /crow-review-pr skill
        └── crow-batch-workspace/     # /crow-batch-workspace skill

Alternatively, you can scaffold without launching the GUI by running the CLI setup wizard:

.build/debug/crow setup            # prompts interactively
.build/debug/crow setup --dev-root ~/Dev   # skip the devRoot prompt

Next Steps