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/ejbills/DockDoor 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 — Single-maintainer risk — review before adopting

• Last commit today
• 7 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 ejbills/DockDoor repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ejbills/DockDoor.

What it runs against: a local clone of ejbills/DockDoor — 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 ejbills/DockDoor | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

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

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

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

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

DockDoor is a macOS menu bar application written in Swift that restores 'window peeking' functionality—visualizing and switching between multiple open windows of the same application by hovering over Dock icons. It also enhances the native Alt+Tab and Cmd+Tab switchers with custom window preview layouts, addressing a core macOS UX gap where the Dock alone provides insufficient context when multiple windows are open. Traditional single-target Xcode app structure: main application entry point likely in a root Sources or DockDoor folder (not visible in truncated file list), Assets folder contains all UI resources and icons organized by feature (DockPreviews.imageset, WindowSwitcher.imageset, CmdTab.imageset), GitHub Actions workflows in .github/workflows automate testing and localization. Likely uses SwiftUI or AppKit for the UI layer with low-level AccessibilityAPI calls for window enumeration.

macOS users who frequently juggle multiple windows of the same application (developers, designers, writers) and want faster window switching without the native Dock's lack of context. Also appeals to former Windows/Linux users expecting window peeking. Contributors are typically Swift developers comfortable with macOS system-level integration and AccessibilityAPI work.

Active and production-ready. The repo shows a mature CI/CD setup with GitHub Actions workflows (lint, test, PR validation, Crowdin localization sync), multiple release assets (DMG downloads visible in shields), organized issue templates, and SwiftFormat linting rules in place. Recent commits and maintenance of GitHub workflows suggest active ongoing development.

Low risk for a single-maintainer open-source project. Primary concerns: (1) macOS system APIs (Accessibility, Window management) are tightly coupled to OS versions and can break between releases, (2) reliance on window server interaction requires elevated permissions and careful permission handling, (3) single active maintainer (ejbills) means slower issue response for bugs affecting specific macOS versions. No obvious dependency bloat visible in file list.

The repo shows active localization work (Crowdin sync workflow), automated issue validation, PR linting, and changelog updates. The presence of multiple image assets for different layouts (dockpreview1/2, windowswitcher1/2 variations) and recent audio assets (Glow.wav) suggests feature refinement and UI polish are ongoing. Workflows are configured but specific recent PRs/issues are not visible in provided data.

Check README for instructions.

Daily commands: In Xcode: Cmd+R to build and run the active scheme. No build script or Makefile visible. Pre-built binary available at releases page (DockDoor.dmg). Requires macOS Monterey+ and Accessibility permissions granted in System Preferences.

• Assets/Assets.xcassets/: Contains all UI images for dock previews, window switcher, and cmd+tab enhancements—critical for visual feature implementation
• .github/workflows/: Defines CI pipeline including linting (SwiftFormat), testing, PR validation, and Crowdin localization sync—essential for contribution workflow
• .swiftformat: Swift code style enforcement rules—must pass before PRs are merged
• .github/ISSUE_TEMPLATE/: Structured bug reports and feature requests guide contributors on expected issue quality
• AGENTS.md: Likely contains contributor guidelines and project philosophy for maintainers and AI agents

Core logic likely lives in a main Sources directory (not shown but standard Xcode layout). UI previews and window switcher variants → modify Assets/Assets.xcassets/ image sets and corresponding Swift view files. Hotkey handling → search for KeyEvent or AccessibilityAPI integration. Localization strings → update Crowdin config in .github/workflows/crowdin-sync.yml and corresponding .strings files. Format check before PR: run SwiftFormat per .swiftformat config.

Accessibility permissions: The app requires Accessibility API access, which must be manually granted in System Preferences → Security & Privacy → Accessibility, or it will silently fail to intercept window events. Window server interaction is macOS version-sensitive; APIs changed notably between Big Sur (11) and Monterey (12). Multi-monitor setup bugs are non-trivial due to Dock behavior on external displays. No obvious hardcoded paths or build secrets, but ensure you test with Accessibility permissions before debugging window switching failures.

• AccessibilityAPI (macOS) — Core technology DockDoor uses to enumerate open windows, retrieve window titles/bounds, and trigger window switching without user action—requires explicit permission and crash risk if improperly called
• Window Server Communication — Low-level macOS concept for querying and manipulating windows; DockDoor must interact with the window server to get live previews and handle multi-monitor Dock positioning
• Global Hotkey Interception — DockDoor captures system-wide Alt+Tab and Cmd+Tab events before macOS handles them; requires Carbon Event Manager or AppKit NSEvent monitoring with elevated privileges
• SwiftUI vs AppKit Interoperability — Modern macOS apps must bridge SwiftUI (declarative) with AppKit (imperative) for system-level features; DockDoor likely uses NSView wrappers for low-level window management while using SwiftUI for the UI shell
• Dock API / Dock Services — macOS provides limited public APIs for Dock interaction; DockDoor reverse-engineers or hooks into Dock display logic to inject preview overlays—fragile across OS versions
• SwiftFormat Code Linting — Project enforces consistent Swift style via .swiftformat config in CI; contributors must format code before merge or PR checks fail
• Crowdin Localization Workflow — DockDoor uses Crowdin for community-driven multi-language support with automated sync via GitHub Actions; contributors need to extract strings to .strings files for translation

• rcmdnk/alfred-workflow-dev-tools — Alternative macOS productivity tool using system-level event monitoring and window management; shares AccessibilityAPI and hotkey handling patterns
• ianyh/Amethyst — macOS window manager using AccessibilityAPI for window enumeration and switching—direct reference for low-level window server interaction techniques
• koekeishiya/chunkwm — Advanced macOS window management system relying on system events and accessibility hooks; demonstrates robust multi-monitor Dock behavior
• Microsoft/PowerToys — Windows equivalent providing window preview and Alt+Tab enhancements; DockDoor's spiritual successor for macOS with similar UX goals
• eviltrout/discourse — Not directly related, but Crowdin i18n setup in DockDoor mirrors patterns used by large Swift/web open-source projects for multi-language support

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 Swift unit tests for core window management and preview functionality

The repo has a comprehensive test.yml workflow but the file structure shows no visible Tests/ directory or XCTest files. DockDoor's core features (window peeking, alt-tab enhancement, dock previews) are mission-critical and would benefit from unit tests covering window detection, screenshot capture, and UI state management. This ensures refactoring safety and prevents regressions in macOS-specific accessibility APIs.

• [ ] Create Tests/ directory in DockDoor/ with XCTest targets
• [ ] Add unit tests for window capture logic in DockDoor/AppDelegate.swift and related services
• [ ] Add integration tests for accessibility permissions and macOS event handling
• [ ] Update DockDoor.xcodeproj/xcshareddata/xcschemes to include test schemes
• [ ] Document test setup in README (macOS accessibility requirements for testing)

Document public API and accessibility requirements in AGENTS.md or new DEVELOPMENT.md

AGENTS.md exists but appears to be minimal. DockDoor requires specific macOS permissions (accessibility, screen recording) and uses private/semi-private macOS APIs. New contributors need clear documentation on: which APIs are used, why permissions are needed, how window detection works, and how to test locally. This reduces onboarding friction and prevents security/permission-related issues.

• [ ] Expand AGENTS.md or create DEVELOPMENT.md with macOS API overview
• [ ] Document required accessibility and screen recording permissions with code references
• [ ] Add section on testing the app locally with proper sandbox/security settings
• [ ] Include troubleshooting for common macOS permission issues
• [ ] Link to relevant files: DockDoor/AppDelegate.swift, any window service modules

Add GitHub Action to validate Swift code formatting and SwiftLint compliance

The repo has .swiftformat configuration file, lint.yml and pr-lint.yml workflows, but no clear evidence of automated Swift formatting checks in CI. Adding a swiftformat validation step ensures code consistency, reduces manual review overhead, and catches formatting drift early. This complements the existing linting setup.

• [ ] Create or enhance .github/workflows/lint.yml to run swiftformat --lint against DockDoor/
• [ ] Configure swiftformat to use .swiftformat config file
• [ ] Add fail condition if formatting violations are found
• [ ] Add documentation in CONTRIBUTING.md (if exists) or README on running swiftformat locally
• [ ] Test workflow by creating a test PR with intentional formatting violations

• Add unit tests for window enumeration logic: The .github/workflows/test.yml exists but test file coverage is not visible—a junior could write XCTest cases for the AccessibilityAPI integration that enumerates windows.
• Improve documentation for multi-monitor Dock locking feature: The 'Dock Locking' section in README is incomplete (ends with '### C'); a contributor could flesh out this feature's behavior and add a screenshot from Assets/variations/.
• Add localization for new strings: Crowdin sync is configured but specific untranslated strings are unknown—audit the codebase for hardcoded English UI strings (e.g., menu titles, tooltips) and move them to .strings files for the Crowdin workflow.

DockDoor appears to be a well-structured Swift/macOS application with moderate security posture. No critical vulnerabilities were identified in the file structure analysis. Main concerns relate to: (1) system API access requiring proper permission handling and user consent for window/accessibility features, (2) lack of automated dependency scanning, and (3) missing security disclosure guidelines. The codebase shows good organization with GitHub Actions CI/CD, but security-focused workflows could be strengthened. Recommendations focus on implementing dependency scanning, documenting security practices, and ensuring proper entitlements and privacy handling for macOS system access.

• Medium · Potential Unsafe macOS System Access — DockDoor/AppDelegate.swift and related system integration code. DockDoor is a macOS application that performs window peeking and alt-tab enhancements, which requires accessing sensitive system APIs (Accessibility Framework, window server). Without proper entitlements and user consent handling, this could pose privacy risks. Fix: Ensure proper code signing, entitlements configuration, and explicit user permissions. Verify Accessibility permissions are properly requested and documented. Implement privacy-preserving data handling for window metadata.
• Low · No Evidence of Dependency Vulnerability Scanning — .github/workflows/ directory. The codebase uses Swift Package Manager (evidenced by Package.resolved files), but no automated dependency vulnerability scanning workflow is visible in the GitHub Actions configuration. Fix: Add a dependency scanning workflow using tools like Swift Security or integrate GitHub's Dependabot for Swift packages. Include regular security audits of third-party dependencies.
• Low · Audio Assets Without Integrity Verification — Assets/audios/Glow.wav. Audio files (Assets/audios/Glow.wav) are included without visible integrity verification mechanisms or sandboxing controls. Fix: Document the source and purpose of all media assets. Consider implementing file integrity checks and ensuring audio playback is sandboxed appropriately.
• Low · Missing CODEOWNERS and Security Policy — Repository root. No SECURITY.md or CODEOWNERS file detected, which could make it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines. Implement a CODEOWNERS file for critical components to ensure security reviews.

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.