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/avatsaev/touchbar_nyancat 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.

AVOID — Stale and unlicensed — last commit 2y ago

• 11 active contributors
• Distributed ownership (top contributor 45% of recent commits)
• ⚠ Stale — last commit 2y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory 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 avatsaev/touchbar_nyancat repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/avatsaev/touchbar_nyancat.

What it runs against: a local clone of avatsaev/touchbar_nyancat — 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 avatsaev/touchbar_nyancat | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 742 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of avatsaev/touchbar_nyancat. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/avatsaev/touchbar_nyancat.git
#   cd touchbar_nyancat
#
# 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 avatsaev/touchbar_nyancat and re-run."
  exit 2
fi

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

# 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 "touchbar_nyancat/AppDelegate.swift" \\
  && ok "touchbar_nyancat/AppDelegate.swift" \\
  || miss "missing critical file: touchbar_nyancat/AppDelegate.swift"
test -f "touchbar_nyancat/NyanCatViewController.swift" \\
  && ok "touchbar_nyancat/NyanCatViewController.swift" \\
  || miss "missing critical file: touchbar_nyancat/NyanCatViewController.swift"
test -f "touchbar_nyancat/NyanCatCanvas.swift" \\
  && ok "touchbar_nyancat/NyanCatCanvas.swift" \\
  || miss "missing critical file: touchbar_nyancat/NyanCatCanvas.swift"
test -f "touchbar_nyancat/Base.lproj/Main.storyboard" \\
  && ok "touchbar_nyancat/Base.lproj/Main.storyboard" \\
  || miss "missing critical file: touchbar_nyancat/Base.lproj/Main.storyboard"
test -f "touchbar_nyancat/Info.plist" \\
  && ok "touchbar_nyancat/Info.plist" \\
  || miss "missing critical file: touchbar_nyancat/Info.plist"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 742 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~712d)"
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/avatsaev/touchbar_nyancat"
  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).

A macOS app that renders an animated Nyan Cat scrolling across the Touch Bar on MacBook Pro models. Built in Swift using native Xcode tooling, it displays a pixel-art cat sprite with a rainbow trail and optional audio accompaniment, purely as a novelty easter egg that activates when the app is in focus. Single-target Xcode project structure: touchbar_nyancat/AppDelegate.swift bootstraps the app lifecycle, NyanCatViewController.swift coordinates the Touch Bar UI, NyanCatCanvas.swift handles the animation rendering logic, and NyanCatCanvas.xib defines the layout. Assets folder contains sprite images (ic_volume_up_3x.png, ic_volume_off_3x.png) and nyan_music.mp3 for audio.

MacBook Pro users (particularly 2016+ models with Touch Bar hardware) who want a humorous desktop companion; developers curious about Touch Bar API integration in Swift or looking for example code on rendering custom animations in Apple's restricted hardware interface.

Experimental and unmaintained. This is a small, single-file Swift project (~5KB of code) with no test suite, CI/CD pipeline, or recent activity visible. It solves a novelty problem rather than a production need, and exists as a proof-of-concept for Touch Bar capabilities rather than a robust application.

Low risk for experimentation, high risk for production use. Single maintainer (avatsaev), no dependency management visible, and the app requires manual Gatekeeper bypass—indicating it's unsigned and not distributed through official channels. The Touch Bar API itself is proprietary to Apple and subject to macOS version constraints; compatibility may break with future OS updates.

No active development visible. The repo appears to be archived as a completed novelty project with no recent commits, open PRs, or issues tracked in the provided file list.

Clone the repo, open touchbar_nyancat.xcodeproj in Xcode, select the touchbar_nyancat scheme, and hit Build & Run (⌘R) on a MacBook Pro with Touch Bar hardware running a compatible macOS version.

Daily commands: Open touchbar_nyancat.xcodeproj in Xcode 11+, ensure the deployment target is set to macOS 10.12.6 or later (per typical Touch Bar requirements), select Product → Run (⌘R). The app will launch and the animation appears in the Touch Bar when the app window is active.

• touchbar_nyancat/AppDelegate.swift — Entry point for the macOS app; initializes the window and view controller that manages the TouchBar interface.
• touchbar_nyancat/NyanCatViewController.swift — Core controller managing TouchBar item creation, animation loop timing, and user interaction (play/pause audio).
• touchbar_nyancat/NyanCatCanvas.swift — Rendering engine that draws the animated Nyan Cat sprite and trail; contains the pixel-level animation logic.
• touchbar_nyancat/Base.lproj/Main.storyboard — UI layout definition; wires AppDelegate to NyanCatViewController and defines window hierarchy.
• touchbar_nyancat/Info.plist — App metadata and configuration; defines bundle identifiers, minimum OS version, and required capabilities.
• touchbar_nyancat/NyanCatCanvas.xib — Interface Builder file for NyanCatCanvas; defines the custom view layout for rendering the animation.

• AppDelegate (Swift, AppKit NSApplicationDelegate) — Owns app lifecycle; creates main window and initializes NyanCatViewController on startup
  • Failure mode: If main window fails to load, the app crashes immediately; no fallback UI
• NyanCatViewController (Swift, NSTouchBar, AVAudioPlayer, Timer) — Manages TouchBar item creation, animation timer, and audio playback; routes button taps to audio control
  • Failure mode: If timer is not properly invalidated on dealloc, animation loop leaks memory and continues in background
• NyanCatCanvas (Swift, NSView, Core Graphics) — Renders sprite frames and trail animation; computes sprite position based on elapsed time
  • Failure mode: If draw() is too slow, frame rate drops and animation stutters; no frame-skip logic present
• Audio player (AVAudioPlayer) — Plays Nyan Cat theme music on demand; no volume control beyond play/pause
  • Failure mode: If audio file is missing or corrupted, playback fails silently; no error handling in UI

• Timer (NyanCatViewController) → NyanCatCanvas.updateAnimation() — Periodic tick (e.g., 60Hz) triggers frame counter increment
• NyanCatCanvas.updateAnimation() → NyanCatCanvas.draw() — Animation state (frame counter, sprite position) passed to rendering logic
• NyanCatCanvas.draw() → TouchBar (NSTouchBar) — Rendered bitmap of sprite and trail displayed as custom TouchBar item content
• User (TouchBar tap) → NyanCatViewController.touchBarButtonTapped() — Volume button press routed to view controller via target-action pattern
• NyanCatViewController → AVAudioPlayer.play() / .pause() — Button tap toggles audio playback state

Add a new TouchBar control button

1. Create a new NSCustomTouchBarItem in NyanCatViewController.makeTouchBar() (touchbar_nyancat/NyanCatViewController.swift)
2. Add a new @IBAction method to handle button press (e.g., toggleColor, changSpeed) (touchbar_nyancat/NyanCatViewController.swift)
3. If the action requires visual changes, update the drawing logic in NyanCatCanvas.draw() (touchbar_nyancat/NyanCatCanvas.swift)

Modify the animation or sprite rendering

1. Edit the sprite drawing coordinates and color logic in NyanCatCanvas.swift (touchbar_nyancat/NyanCatCanvas.swift)
2. Adjust the animation speed or trail length by modifying the timer interval and animation state in NyanCatViewController (touchbar_nyancat/NyanCatViewController.swift)
3. Call setNeedsDisplay() on the canvas to trigger a re-render (touchbar_nyancat/NyanCatCanvas.swift)

Replace or add audio tracks

1. Add new .mp3 file to the project in Xcode and add to target membership (touchbar_nyancat.xcodeproj/project.pbxproj)
2. Update the audio file reference in NyanCatViewController where the AVAudioPlayer is initialized (touchbar_nyancat/NyanCatViewController.swift)
3. Ensure the Info.plist includes audio capabilities if required (touchbar_nyancat/Info.plist)

• Swift + Cocoa (AppKit) — Native macOS development; only framework with TouchBar API access (NSTouchBar introduced in macOS 10.12.1)
• NSView custom drawing — Allows pixel-level sprite rendering and smooth animation on the TouchBar canvas
• AVAudioPlayer — Simple, synchronous audio playback for the Nyan Cat theme music
• Timer-based animation loop — Provides reliable frame-rate control for smooth sprite animation

• macOS-only application

  • Why: TouchBar is exclusive to MacBook Pro hardware
  • Consequence: Cannot run on Windows, Linux, or iOS; zero cross-platform reach

• Animation only visible when app is in focus

  • Why: TouchBar hides custom items when app is backgrounded (system behavior)
  • Consequence: Users must keep the app window active to see the animation; reduces utility as a screensaver alternative

• Unsigned app requiring Gatekeeper bypass

  • Why: No Apple Developer signing; saves cost and distribution friction
  • Consequence: Users must manually approve on first run; increases support burden and trust friction

• Simple timer-based animation instead of Metal/OpenGL

  • Why: Minimal complexity for a novelty app; AppKit NSView is sufficient
  • Consequence: Lower frame rate potential; less efficient GPU utilization

• Cross-platform support (Windows/Linux/iOS)
• Persistence or configuration saving
• Real-time audio analysis or reactive visualization
• Integration with system media controls
• Background operation when app is not focused

• No explicit timer cleanup (Medium) — touchbar_nyancat/NyanCatViewController.swift: If Timer is created but never invalidated in deinit, the animation loop continues in memory even after the view controller is deallocated, causing a memory leak.
• No error handling for missing audio file — touchbar_nyancat/NyanCatViewController.swift: undefined

No CocoaPods/SPM: This is a vanilla Xcode project with no external dependencies declared—all code is native Swift/Cocoa. Touch Bar hardware required: The app will compile but the animation only renders on MacBook Pro 2016+ with actual Touch Bar hardware; simulators do not support it. Unsigned binary: The app requires manual Gatekeeper bypass (right-click → Open) on first launch because it lacks a developer certificate. macOS version sensitivity: Touch Bar API availability is tied to macOS 10.12.6+; building or running on older versions will fail. XIB coupling: The layout is tightly coupled to NyanCatCanvas.xib; modifying the view hierarchy requires synchronized changes in both the XIB and code.

• hungtruong/TouchFart — Similar novelty Touch Bar app; demonstrates alternative approaches to custom Touch Bar animations and asset management.
• AkdM/KnightTouchBar2000 — Another creative Touch Bar game/animation project; shows different animation patterns and Touch Bar control layout strategies.
• insidegui/TouchBarSpaceFight — Interactive Touch Bar game; demonstrates more complex state management and user input handling on the Touch Bar compared to this static animation.
• Apple/touchbar-samples — Official Apple sample code for Touch Bar development (if available); provides canonical API usage patterns and best practices for macOS Xcode projects.
• Jintin/DangerSwift — Unrelated but represents a mature Swift macOS project structure; useful for understanding how to scale a Swift CLI/app beyond single-file novelty code.

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.

Extract animation logic from NyanCatCanvas.swift into a separate NyanCatAnimationEngine class

NyanCatCanvas.swift likely contains both UI rendering and animation frame calculation logic mixed together. Separating the animation engine into its own class would make the code more testable, reusable, and maintainable. This is a common refactoring need in iOS apps where view controllers become god objects.

• [ ] Create new file NyanCatAnimationEngine.swift to handle frame timing and nyancat position calculations
• [ ] Move animation state management (position, velocity, direction) from NyanCatCanvas.swift to NyanCatAnimationEngine
• [ ] Update NyanCatCanvas.swift to call the engine's methods for frame updates instead of calculating directly
• [ ] Add unit tests for NyanCatAnimationEngine.swift to verify frame calculations and boundary conditions
• [ ] Update NyanCatViewController.swift if needed to use the new engine

Add sound toggle persistence using UserDefaults in AppDelegate.swift

Currently the app has ic_volume_up_3x.png and ic_volume_off_3x.png suggesting sound toggle functionality exists, but there's no .plist configuration visible for persisting user preferences. Users likely have to re-toggle sound every time they launch the app. Add UserDefaults persistence to remember the user's audio preference.

• [ ] Add a 'soundEnabled' key to UserDefaults in AppDelegate.swift applicationDidFinishLaunching method
• [ ] Update NyanCatViewController.swift to read the persisted soundEnabled value on init
• [ ] Modify the sound toggle button action to save the preference to UserDefaults
• [ ] Document the new preference in README.md under a 'Settings' or 'Preferences' section
• [ ] Test that preference persists across app launches

Create a GitHub Actions workflow to auto-build and notarize the app on releases

The README mentions GateKeeper issues requiring users to manually bypass security. The app could be notarized by Apple to provide a better user experience. Adding a GitHub Actions CI workflow to automatically build, sign, and notarize the app on new releases would eliminate security warnings and streamline the release process.

• [ ] Create .github/workflows/build-and-notarize.yml with macOS runner configuration
• [ ] Add build step using xcodebuild for the touchbar_nyancat.xcodeproj target
• [ ] Integrate Apple notarization using xcrun notarytool (requires adding signing certificates to GitHub Secrets)
• [ ] Configure workflow to trigger on GitHub Releases
• [ ] Update README.md to explain the new automated signing/notarization process and link to releases
• [ ] Document required setup for maintainers (Apple Developer ID, app-specific password secrets)

• Add unit tests for animation timing in NyanCatCanvas.swift—currently there is no test suite. Create tests in a new touchbar_nyancat-Tests target to verify frame advancement logic and sprite position calculations.: Medium
• Extract hardcoded animation parameters (frame duration, sprite offsets, color values) from NyanCatCanvas.swift into a configuration struct or plist file, making animation tweaks easier without recompiling.: Small
• Add documentation comments (HeaderDoc or markdown) to NyanCatViewController.swift and NyanCatCanvas.swift explaining the Touch Bar API integration and animation loop—currently there are minimal code comments for new developers.: Small

The application is a benign utility with low complexity and minimal security attack surface. The primary security concern is the lack of code signing, which requires users to bypass macOS security protections. No injection vulnerabilities, hardcoded secrets, or dangerous API calls were identified in the codebase structure. The application appears to be a simple UI animation without network requests, data persistence, or sensitive operations. Recommend implementing proper code signing before distribution to users.

• Medium · Unsigned Application Distribution — README.md and general application distribution. The README explicitly mentions that the app is not signed and users must bypass Gatekeeper to run it. This is a security risk as it bypasses macOS code signing verification, which is designed to protect against malware and tampering. Fix: Properly sign the application using a valid Apple Developer certificate. This ensures code integrity and allows macOS to verify the application's authenticity without requiring users to bypass security features.
• Low · User-Specific Xcode Data Committed — touchbar_nyancat.xcodeproj/xcuserdata. The repository contains user-specific Xcode data including xcuserdata, breakpoints, and debug configurations (xcuserdata/avatsaev.xcuserdatad). This should typically be excluded from version control. Fix: Add xcuserdata/ to .gitignore to prevent committing user-specific development data. This keeps the repository clean and prevents merge conflicts.
• Low · No Dependencies Security Assessment Possible — Project root - missing dependency manifest. No package dependency file (Podfile, Cartfile, or Package.swift) was found in the provided file structure, making it impossible to assess third-party dependency vulnerabilities. The audio file (nyan_music.mp3) is embedded without version tracking. Fix: If using any third-party libraries, maintain an explicit dependency file (Package.swift for SPM, Podfile for CocoaPods, etc.) and regularly update dependencies to patch known vulnerabilities.

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.