Contributing

Thanks for your interest in contributing to Scarf. The canonical contributor guide lives in CONTRIBUTING.md in the repo. This page is a public-facing summary plus a few wiki-specific notes.

Quick start

Fork and clone https://github.com/awizemann/scarf.
Open scarf/scarf.xcodeproj in Xcode 16+. Two app targets: scarf (macOS) and scarf mobile (ScarfGo, iOS). Both share the local SwiftPM packages ScarfCore, ScarfIOS, and ScarfDesign.
Build and run (requires macOS 14.6+ and Hermes installed at ~/.hermes/ for the local Mac window; iOS sim or device + a SSH-reachable Hermes host for ScarfGo).
Read Build & Run for the codebase tour, Architecture Overview for the layering, and Design System for the rust palette + token usage.

Code conventions

The full list is in CONTRIBUTING.md. The non-negotiables:

MVVM-F. Features never import sibling features. Cross-feature concerns go through services or AppCoordinator.
No commented-out code, no TODOs, no deferred functionality in PRs.
Zero warnings on build.
Read-only DB access. Never write to ~/.hermes/state.db.
Swift 6 strict concurrency. @MainActor default isolation; nonisolated for service methods.
Conventional commits. feat:, fix:, chore:, refactor:, docs:, etc.

What's good to work on

Anything in the Roadmap or ScarfGo Roadmap.
iOS-specific gaps — Cron editor, Settings full-YAML editor, Insights / Activity views, iPad layout polish, push notifications wiring once Hermes ships a sender. See Platform Differences.
Test coverage — see Testing for the highest-value remaining gaps (UI tests, log streaming).
iOS localization — strings are extracted; translations welcome. See Localization.
Templates for the public catalog — see Project Templates and the catalog at awizemann.github.io/scarf/templates/.
Wiki content — every stub on the wiki is a pull request opportunity. See Wiki Maintenance for the workflow.
Bug reports with reproducible steps.

Pull request flow

Open an issue first describing the change. This avoids rework if the maintainer has constraints in mind.
One feature or fix per PR — keeps reviews tight.
Include a clear description of what changed and why.
Ensure both schemes build clean:
- xcodebuild -project scarf/scarf.xcodeproj -scheme scarf -configuration Debug build
- xcodebuild -project scarf/scarf.xcodeproj -scheme "scarf mobile" -configuration Debug -destination "generic/platform=iOS Simulator" build
Run the ScarfCore test suite if you touched anything in Packages/ScarfCore: swift test --package-path scarf/Packages/ScarfCore.

Reporting issues

Open an issue at https://github.com/awizemann/scarf/issues with:

What you expected to happen.
What actually happened.
macOS version and Hermes version.
Steps to reproduce.
The relevant log snippet from ~/.hermes/logs/errors.log if applicable (redact secrets first).

Documentation contributions

Two paths:

Small wiki edits (typos, clarifications) — click Edit on any wiki page in the GitHub UI. Editing requires push access to the main repo.
Larger wiki changes — clone the wiki directly (git clone git@github.com:awizemann/scarf.wiki.git) or open an issue describing what needs adding. See Wiki Maintenance for the full workflow including the secret-scan policy.
Internal dev docs (PRD, Hermes API discovery, raw architecture notes) live in scarf/docs/ in the main repo and follow the normal PR flow.

Code of conduct

Be kind, be specific, assume good faith. Disagreements about technical direction are welcome; personal attacks aren't.

Last updated: 2026-04-25 — Scarf v2.5.0 (two targets, ScarfCore tests, iOS contribution areas)

Getting Started

ScarfGo (iOS)

User Guide

Architecture

Developer Guide

Reference

Troubleshooting

Slow Chat Startup

Contributing

Release History

Legal & Support

Wiki edited via the local .wiki-worktree/ clone. See Wiki Maintenance for the workflow. Last sync: 2026-04-20.