If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/GitHawkApp/GitHawk shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 19 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live GitHawkApp/GitHawk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/GitHawkApp/GitHawk.

What it runs against: a local clone of GitHawkApp/GitHawk — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in GitHawkApp/GitHawk | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1284 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of GitHawkApp/GitHawk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/GitHawkApp/GitHawk.git
#   cd GitHawk
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of GitHawkApp/GitHawk and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "GitHawkApp/GitHawk(\\.git)?\\b" \\
  && ok "origin remote is GitHawkApp/GitHawk" \\
  || miss "origin remote is not GitHawkApp/GitHawk (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Classes/Bookmark/BookmarkViewController.swift" \\
  && ok "Classes/Bookmark/BookmarkViewController.swift" \\
  || miss "missing critical file: Classes/Bookmark/BookmarkViewController.swift"
test -f "Classes/Issues/Comments/IssueCommentSectionController.swift" \\
  && ok "Classes/Issues/Comments/IssueCommentSectionController.swift" \\
  || miss "missing critical file: Classes/Issues/Comments/IssueCommentSectionController.swift"
test -f "Classes/Issues/Comments/Markdown/CMarkParsing.swift" \\
  && ok "Classes/Issues/Comments/Markdown/CMarkParsing.swift" \\
  || miss "missing critical file: Classes/Issues/Comments/Markdown/CMarkParsing.swift"
test -f "Classes/Bookmark/BookmarkCloudStore.swift" \\
  && ok "Classes/Bookmark/BookmarkCloudStore.swift" \\
  || miss "missing critical file: Classes/Bookmark/BookmarkCloudStore.swift"
test -f "Classes/Issues/Comments/Reactions/IssueCommentReactionCell.swift" \\
  && ok "Classes/Issues/Comments/Reactions/IssueCommentReactionCell.swift" \\
  || miss "missing critical file: Classes/Issues/Comments/Reactions/IssueCommentReactionCell.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1284 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1254d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/GitHawkApp/GitHawk"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GitHawk is a native iOS app that provides a best-in-class GitHub client with features like Inbox Zero notification management, native markdown rendering, emoji reactions, and fast in-app commenting. It uses the GitHub GraphQL API (via Apollo codegen) to sync issues, notifications, bookmarks, and repository data with cloud persistence through CloudKit. Modular feature-based architecture under Classes/: Bookmark/ handles saved items with cloud migration, History/ tracks file commits, Issues/ contains nested sections (Assignees/, Branches/, Comments/) for issue details, and Image Upload/ wraps Imgur. Views use IGListKit for collection view sections; data flows through ViewModel and SectionController pairs (e.g., BookmarkIssueSectionController + BookmarkIssueViewModel). CloudKit and local BookmarkStore manage persistence.

iOS developers and GitHub power users who want to triage notifications, manage issues, and browse repositories on their iPhone with a native, polished experience. Contributors range from iOS engineers to designers seeking to build custom UI components beyond standard iOS patterns.

Production-ready and actively maintained. The app is distributed on the App Store (ID 1252320249), uses Bitrise CI/CD for automated testing, and has a TestFlight beta channel. The codebase is ~1.98M lines of Swift with established patterns for bookmarks, history, comments, and assignees. However, the README explicitly lists gaps: needs a dedicated Product Manager and iOS project management expertise.

Moderate risk due to organizational gaps rather than technical debt. The maintainer (@rnystrom) explicitly states no expertise in iOS project management, testing automation, or build optimizations. Single-point-of-failure risk is present. The large Swift codebase (1.98M LOC) and scattered issue backlog (unorganized features and bugs) suggest scope creep. Dependency on Apollo codegen for GraphQL model generation creates a build-time coupling.

Active development on bookmark cloud migration (BookmarkCloudMigrator.swift), file history viewing (PathHistoryViewController.swift), and comment workflows (AddCommentClient.swift, IssueCommentDetailCell.swift). The repository is accepting contributions across all skill levels, with emphasis on organizing unscheduled features and squishing labeled bugs. TestFlight beta is active.

git clone https://github.com/GitHawkApp/GitHawk.git
cd GitHawk
bundle
bundle exec pod install
npm install
open Freetime.xcworkspace/

Note: Requires Node.js (brew install node) for apollo-codegen, Ruby for Bundler/CocoaPods, and API keys configured per Setup.md.

Daily commands: After installation, open Freetime.xcworkspace/ in Xcode and build/run on a simulator or device. The app requires GitHub OAuth credentials (see Setup.md). No npm dev server; this is a compiled iOS app. Testing uses Bitrise CI (status badge in README).

• Classes/Bookmark/BookmarkViewController.swift — Main entry point for the Inbox Zero feature—handles notification management and bookmark storage, essential for understanding the app's core UX flow
• Classes/Issues/Comments/IssueCommentSectionController.swift — Core controller for rendering and managing issue comments—critical for understanding how the app displays and handles comment interactions
• Classes/Issues/Comments/Markdown/CMarkParsing.swift — Markdown parsing engine for native rendering—load-bearing abstraction that converts GitHub markdown into native iOS views
• Classes/Bookmark/BookmarkCloudStore.swift — Cloud storage abstraction for bookmarks—manages persistence and sync layer between local and remote state
• Classes/Issues/Comments/Reactions/IssueCommentReactionCell.swift — Emoji reactions UI implementation—signature GitHawk feature that differentiates it from competitors
• Classes/Image Upload/ImgurClient.swift — Image upload service integration—handles external API calls for image hosting, critical dependency for comment attachments
• Classes/Bookmark/GitHubClient+Bookmarks.swift — GitHub API client extension for bookmark operations—bridges GitHub GraphQL/REST API with local bookmark storage

Add a new comment cell type (e.g., video embed, custom component)

1. Create a new cell subclass extending IssueCommentBaseCell in Classes/Issues/Comments/ (Classes/Issues/Comments/IssueCommentBaseCell.swift)
2. Define a corresponding model class (e.g., IssueCommentVideoModel.swift) that conforms to markdown parsing expectations (Classes/Issues/Comments/Markdown/CMarkParsing.swift)
3. Update CMarkParsing.swift to recognize the new content type and instantiate the model during markdown parsing (Classes/Issues/Comments/Markdown/CMarkParsing.swift)
4. Register the new cell in IssueCommentSectionController.swift and wire up display logic (Classes/Issues/Comments/IssueCommentSectionController.swift)

Add a new GitHub API query or mutation

1. Create or extend a Client extension file (e.g., GitHubClient+MyFeature.swift) in Classes/[Feature]/ (Classes/Bookmark/GitHubClient+Bookmarks.swift)
2. Define GraphQL query/mutation strings and call GitHub's API client with proper error handling (Classes/Issues/AddCommentClient.swift)
3. Map API response to local view models or data stores using transformation helpers (Classes/History/RepoFileHistoryQueryDataToPathHistoryViewModel.swift)
4. Integrate the API call into the appropriate view controller or section controller (Classes/Bookmark/BookmarkViewController.swift)

Add bookmark sync or cloud storage feature

1. Update BookmarkStore.swift to add new persistence methods or properties (Classes/Bookmark/BookmarkStore.swift)
2. Extend BookmarkCloudStore.swift to handle cloud sync logic and conflict resolution (Classes/Bookmark/BookmarkCloudStore.swift)
3. Add API methods in GitHubClient+Bookmarks.swift for cloud queries (Classes/Bookmark/GitHubClient+Bookmarks.swift)
4. Update BookmarkViewController.swift to trigger sync and reflect cloud state in the UI (Classes/Bookmark/BookmarkViewController.swift)

Enhance markdown rendering with new syntax support

1. Update or extend CMarkParsing.swift to recognize new markdown syntax from commonmark AST (Classes/Issues/Comments/Markdown/CMarkParsing.swift)
2. Create a new model class (e.g., MarkdownCustomModel.swift) to represent parsed content (Classes/Issues/Comments/Markdown/MarkdownAttribute.swift)
3. Create a new cell type in Classes/Issues/Comments/ to render the syntax (Classes/Issues/Comments/IssueCommentBaseCell.swift)
4. Register and wire the cell in IssueCommentSectionController.swift (Classes/Issues/Comments/IssueCommentSectionController.swift)

• IGListKit / Section Controllers — Decouples section/row logic into composable controllers, making complex issue comment layouts (mixed markdown, code, tables, reactions) manageable and reusable
• CommonMark (cmark) — Native markdown parsing on iOS—allows 100% compliant GitHub markdown rendering without WebView overhead, enabling native text interactivity
• CloudKit / iCloud sync — Free cloud sync for bookmarks without backend infrastructure; ties into iOS ecosystem for authentication and device-to-device data
• Imgur API — Offloads image storage to trusted third-party; users can paste images directly into comments without managing GitHub raw attachments
• GraphQL + REST (GitHub API) — GraphQL for efficient bookmark/notification queries; REST for mutations (comment posting) where GitHub's API is more mature

• Native markdown rendering (cmark) instead of WKWebView

  • Why: Smaller memory footprint, faster rendering, better UX for long threads; avoids JavaScript execution overhead
  • Consequence: Must manually implement each markdown block type (code, tables, checkboxes); requires ongoing maintenance as GitHub markdown evolves

• Local BookmarkStore + async cloud sync instead of real-time CloudKit subscriptions

  • Why: Simpler architecture; offline-first UX; avoids always-on background sync battery drain
  • Consequence: Bookmarks may briefly be out of sync across devices; requires

1. API keys required: Setup.md not fully provided—you must configure GitHub OAuth and Imgur API credentials before building. 2. apollo-codegen dependency: Running npm install is mandatory to download apollo-codegen for GraphQL code generation; skipping this causes build failures. 3. CloudKit entitlements: Bookmark cloud sync requires a valid Apple developer team ID and CloudKit container setup in the provisioning profile. 4. Workspace not project: The repo opens Freetime.xcworkspace (not Freetime.xcodeproj); opening the wrong file will fail to resolve CocoaPods dependencies.

• IGListKit SectionController Pattern — GitHawk's entire UI is built on SectionControllers paired with ViewModels (see BookmarkIssueSectionController + BookmarkIssueViewModel); understanding this pattern is essential for any new screen
• CloudKit Sync & Migration — BookmarkCloudMigrator and BookmarkCloudStore handle cross-device bookmark sync; critical for the app's cloud persistence strategy and offline-first design
• GraphQL Code Generation (apollo-codegen) — The build pipeline uses npm apollo-codegen to auto-generate Swift types from GraphQL queries; modifying queries requires re-running codegen and understanding the generated API
• MVVM with SwiftUI-free UIKit — GitHawk uses ViewController + ViewModel + SectionController as its architectural pattern (no SwiftUI); understanding this separation is crucial for consistency
• Inbox Zero Notification Pattern — The core value proposition of GitHawk is helping users triage GitHub notifications to zero; the notification model and archiving logic underpin the Bookmark feature
• Native Markdown Rendering (not WebView) — GitHawk renders markdown natively in UIView hierarchies (not UIWebView); this approach is visible in IssueCommentCodeBlockCell.swift and shapes performance/UI consistency
• Pod install vs Package.swift Dependencies — GitHawk uses CocoaPods (pod install) for Swift Package Manager era would use Package.swift; the .podfile orchestrates all iOS dependencies and must be understood for adding libraries

• Alamofire/Alamofire — HTTP networking library commonly paired with GitHub API clients; GitHawk likely uses this or URLSession for API calls
• apollographql/apollo-ios — Official Apollo iOS client; GitHawk's dependency for GraphQL queries (invoked via npm apollo-codegen)
• Instagram/IGListKit — Collection view diffing framework used extensively in GitHawk's SectionController pattern for performant list rendering
• realm/realm-swift — Alternative persistence layer that some GitHub clients use; GitHawk uses CloudKit but Realm is a common reference for iOS data storage
• ibireme/YYText — Rich text rendering library often paired with GitHub markdown apps; relevant for understanding native markdown rendering in GitHawk

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for IssueComment markdown parsing and rendering

The Classes/Issues/Comments/Markdown directory contains CMarkParsing.swift and CheckIfSentWithGitHawk.swift, which are critical for rendering issue comments. These files lack corresponding unit tests, making it difficult to catch regressions in markdown rendering—a core feature highlighted in the README. A new contributor could add XCTest cases to verify markdown parsing edge cases, HTML escaping, and code block handling.

• [ ] Create Classes/Issues/Comments/Markdown/CMarkParsingTests.swift with tests for inline code, nested lists, and special characters
• [ ] Create Classes/Issues/Comments/Markdown/CheckIfSentWithGitHawkTests.swift to verify detection logic
• [ ] Add integration tests in Classes/Issues/Comments/IssueCommentModelTests.swift to ensure parsed markdown renders correctly in IssueCommentDetailCell and IssueCommentHtmlCell

Add unit tests for BookmarkStore persistence and CloudKit migration

The Classes/Bookmark directory has complex stateful logic (BookmarkStore.swift, BookmarkCloudStore.swift, BookmarkCloudMigrator.swift) that handles user data persistence. There are no visible test files for these critical components, creating risk of data loss bugs. A new contributor could add comprehensive tests for save/load operations, cloud sync conflicts, and migration edge cases.

• [ ] Create Classes/Bookmark/BookmarkStoreTests.swift with tests for add, remove, and retrieve operations
• [ ] Create Classes/Bookmark/BookmarkCloudMigratorTests.swift to verify legacy-to-CloudKit migration logic handles partial syncs and network failures
• [ ] Add mock BookmarkCloudStore tests to verify sync conflict resolution and offline behavior

Add GitHub Actions workflow for SwiftLint and build validation on PRs

The repo has .swiftlint.yml configured but no visible CI automation in .github/workflows/ to enforce linting on pull requests. The README shows a Bitrise badge but no GitHub Actions integration. A new contributor could add a workflow that runs SwiftLint validation and builds the app for pull request checks, reducing manual review burden and catching style violations early.

• [ ] Create .github/workflows/swiftlint.yml to run swiftlint on changed files in PRs
• [ ] Create .github/workflows/build.yml to compile the app and run unit tests on macOS-latest
• [ ] Update .github/CONTRIBUTING.md to document the new CI requirements for PRs

• Add unit tests for BookmarkStore.swift's local persistence layer. Currently no test files visible for the bookmark storage interface; a junior can write XCTest cases for save/load/delete operations and improve coverage.
• Document the ImageUpload flow in Classes/Image Upload/. The Imgur client is present but the storyboard (ImageUpload.storyboard) lacks inline documentation; write a guide showing how image uploads integrate with comments.
• Create SectionController tests for IssueCommentCodeBlockCell.swift. Code block rendering is a visible feature but no test doubles exist for verifying markdown code block layout and styling.

The GitHawk iOS application shows reasonable security practices for an open-source GitHub client, but has several areas of concern. The main vulnerability is potential XSS risk when rendering user-generated markdown/HTML content from GitHub. Missing dependency analysis prevents full assessment. API credential handling for both GitHub and Imgur needs verification. The custom markdown parsing implementation should be reviewed for ReDoS vulnerabilities. Overall security posture is moderate—typical for a community-driven mobile application, but improvements in input sanitization, dependency management, and credential handling are recommended.

• Medium · Potential XSS Risk in HTML Rendering — Classes/Issues/Comments/Html/IssueCommentHtmlCell.swift, Classes/Issues/Comments/Markdown/ViewMarkdownViewController.swift. The codebase contains multiple HTML/markdown rendering components (IssueCommentHtmlCell, ViewMarkdownViewController, etc.) that process user-generated content from GitHub. Without proper sanitization, malicious HTML/JavaScript in comments could be executed. Fix: Ensure all HTML rendering uses WebKit's safe rendering methods with sandboxing. Validate and sanitize all user-generated content before rendering. Consider using a well-maintained HTML sanitization library.
• Medium · Missing Dependency Manifest Analysis — Podfile, Package.swift, or similar dependency manifest. The dependency/package file content was not provided in the security analysis context. Cannot assess for vulnerable third-party dependencies, outdated libraries, or supply chain risks. Fix: Provide and analyze the dependency manifest. Run pod audit or equivalent Swift Package Manager security checks. Regularly update dependencies and monitor for CVEs.
• Medium · Potential Insecure Image Upload Handling — Classes/Image Upload/ImgurClient.swift. The ImageUpload component interfaces with Imgur (ImgurClient.swift). Credentials, API keys, or tokens for image uploading may be at risk if not properly secured. Fix: Verify that API keys and credentials are not hardcoded. Use secure credential storage (Keychain). Implement certificate pinning for API communications. Never commit secrets to version control.
• Low · Potential Data Exposure in Bookmark Storage — Classes/Bookmark/BookmarkCloudStore.swift, Classes/Bookmark/BookmarkCloudMigrator.swift. BookmarkCloudStore and BookmarkCloudMigrator handle user bookmark data. If cloud storage is used (iCloud, etc.), ensure proper encryption in transit and at rest. Fix: Implement end-to-end encryption for sensitive bookmark data. Use HTTPS for all API communications. Verify iCloud sync is configured with proper protection classes.
• Low · Markdown Parsing Security — Classes/Issues/Comments/Markdown/CMarkParsing.swift, Classes/Issues/Comments/Markdown/String+CustomBuilding.swift. Custom markdown parsing logic (CMarkParsing.swift, String+CustomBuilding.swift) could be vulnerable to ReDoS (Regular Expression Denial of Service) attacks if regex patterns are not carefully constructed. Fix: Review all regular expressions for ReDoS vulnerabilities. Use tools like regex101.com to test patterns. Consider using well-tested markdown parsing libraries instead of custom implementations.
• Low · GitHub API Token Handling — Classes/Bookmark/GitHubClient+Bookmarks.swift, Classes/History/Client+History.swift. The application authenticates with GitHub API (GitHubClient+Bookmarks.swift, Client+History.swift). OAuth tokens must be securely stored and transmitted. Fix: Store OAuth tokens only in iOS Keychain, never in UserDefaults or files. Implement token refresh logic. Use HTTPS pinning for GitHub API calls. Implement proper logout that revokes tokens.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.