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/DevToys-app/DevToysMac 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 2y ago

• 9 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 86% of recent commits
• ⚠ 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 DevToys-app/DevToysMac repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/DevToys-app/DevToysMac.

What it runs against: a local clone of DevToys-app/DevToysMac — 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 DevToys-app/DevToysMac | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 767 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "DevToys-app/DevToysMac(\\.git)?\\b" \\
  && ok "origin remote is DevToys-app/DevToysMac" \\
  || miss "origin remote is not DevToys-app/DevToysMac (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "DevToys/DevToys/AppDelegate.swift" \\
  && ok "DevToys/DevToys/AppDelegate.swift" \\
  || miss "missing critical file: DevToys/DevToys/AppDelegate.swift"
test -f "DevToys/DevToys/App/AppViewController.swift" \\
  && ok "DevToys/DevToys/App/AppViewController.swift" \\
  || miss "missing critical file: DevToys/DevToys/App/AppViewController.swift"
test -f "DevToys/DevToys/Body/BodyViewController.swift" \\
  && ok "DevToys/DevToys/Body/BodyViewController.swift" \\
  || miss "missing critical file: DevToys/DevToys/Body/BodyViewController.swift"
test -f "CoreUtil/CoreUtil/Export.swift" \\
  && ok "CoreUtil/CoreUtil/Export.swift" \\
  || miss "missing critical file: CoreUtil/CoreUtil/Export.swift"
test -f "CoreUtil/CoreUtil/Extensions/Combine/NSTextField+Combine.swift" \\
  && ok "CoreUtil/CoreUtil/Extensions/Combine/NSTextField+Combine.swift" \\
  || miss "missing critical file: CoreUtil/CoreUtil/Extensions/Combine/NSTextField+Combine.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 767 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~737d)"
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/DevToys-app/DevToysMac"
  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).

DevToysMac is a macOS native application built in Swift that provides a suite of developer utility tools (JSON↔YAML conversion, Base64/URL/HTML encoding-decoding, number base conversion, JSON formatting, and more). It mirrors the Windows DevToys app, offering offline developer utilities with a native AppKit interface rather than web-based solutions. Modular monorepo structure: CoreUtil/ is a reusable framework containing common utilities (extensions, reactive bindings, state management via Observable/RestorableState), while the main app likely resides at root with tool-specific modules. State flows through Combine publishers and custom Observable wrappers rather than central Redux-like store.

macOS developers and DevOps engineers who need quick, offline access to common encoding/decoding and format conversion utilities without leaving their terminal workflow or opening browser-based tools.

The project appears actively maintained with a clear feature set and distribution through Homebrew (brew install --cask devtoys), suggesting production readiness. However, the visible commit history and issue backlog cannot be fully assessed from provided data; assess by checking GitHub stars, last commit date, and active PR count before recommending for critical workflows.

Single-language dependency on Swift/AppKit (macOS 10.13+) with limited visibility into test coverage from the file list shown. Primary risk is maintainer bandwidth—verify recent commit activity and contributor count on GitHub. No CI/CD pipeline visibility in provided files; check for GitHub Actions workflows in .github/ directory.

Not visible from provided file list. Check GitHub's recent commits, open issues, and PRs to see if active development (e.g., new tools being added, macOS version compatibility updates, or bug fixes) is ongoing.

git clone https://github.com/DevToys-app/DevToysMac.git
cd DevToysMac
open DevToysMac.xcworkspace  # Opens Xcode workspace
# Or: xcodebuild -workspace DevToysMac.xcworkspace -scheme DevToys -configuration Release

Daily commands: Open DevToysMac.xcworkspace in Xcode, select the main app scheme, press Cmd+R to run. Or: xcodebuild -workspace DevToysMac.xcworkspace -scheme DevToys -configuration Debug from CLI.

• DevToys/DevToys/AppDelegate.swift — Application entry point and lifecycle management—sets up the main window and coordinates app initialization
• DevToys/DevToys/App/AppViewController.swift — Root view controller managing tool selection and navigation flow—essential for understanding the main UI structure
• DevToys/DevToys/Body/BodyViewController.swift — Central hub that routes to all tool implementations (coders, converters, generators, formatters)—defines the plugin architecture
• CoreUtil/CoreUtil/Export.swift — Public API surface of the utility framework—defines reusable components and extensions used throughout the app
• CoreUtil/CoreUtil/Extensions/Combine/NSTextField+Combine.swift — Reactive bindings for text input, the primary UI interaction pattern in this Combine-based codebase
• CoreUtil/CoreUtil/Class/Observable.swift — Custom observable abstraction wrapping native Swift Combine—foundational for state management across tools
• DevToys/DevToys.xcodeproj/project.pbxproj — Build configuration and workspace structure—required to understand how to compile and run the app

Add a New Encoding/Decoding Tool

1. Create a new view controller file in Body/Coder/ following the pattern of existing coders like Base64DecoderView+.swift (DevToys/DevToys/Body/Coder/NewCoderView+.swift)
2. Implement the encoding/decoding logic using Observable for reactive state updates (DevToys/DevToys/Body/Coder/NewCoderView+.swift)
3. Register the new tool in BodyViewController.swift by adding a case to the tool routing logic (DevToys/DevToys/Body/BodyViewController.swift)
4. Add the tool to the navigation menu/sidebar in AppViewController.swift (DevToys/DevToys/App/AppViewController.swift)

Add a New Format Converter

1. Create a new view controller in Body/Convert/ (e.g., NewFormatConverterView+.swift) with dual input/output panes (DevToys/DevToys/Body/Convert/NewFormatConverterView+.swift)
2. Use NSTextField+Combine extension to bind input/output reactively (CoreUtil/CoreUtil/Extensions/Combine/NSTextField+Combine.swift)
3. Route the new converter in BodyViewController by adding the selection case (DevToys/DevToys/Body/BodyViewController.swift)
4. Add a menu entry in AppViewController.swift for discoverability (DevToys/DevToys/App/AppViewController.swift)

Add a New Icon Format to the Icon Generator

1. Create a new generator class in Body/Graphic/Icon Generator/Generators/ inheriting from IconGenerator protocol (DevToys/DevToys/Body/Graphic/Icon Generator/Generators/NewIconFormatGenerator.swift)
2. Implement the generate() function to create icons at required dimensions for the format (DevToys/DevToys/Body/Graphic/Icon Generator/Generators/NewIconFormatGenerator.swift)
3. Use IconImageManager for image resizing and processing utilities (DevToys/DevToys/Body/Graphic/Icon Generator/Icon Templete/IconImageManager.swift)
4. Register the new generator in the icon tool's view controller selection logic (DevToys/DevToys/Body/Graphic/Icon Generator/Generators/IconGenerator+Model.swift)

Add a Reusable UI Extension to CoreUtil

1. Create a new extension file in CoreUtil/CoreUtil/Extensions/UI/ following the Ex+ naming convention (CoreUtil/CoreUtil/Extensions/UI/Ex+NSNewComponent.swift)
2. Implement helper methods or computed properties using NSAppearance or NSColor for consistency (CoreUtil/CoreUtil/Extensions/UI/Ex+NSNewComponent.swift)
3. Export the extension in CoreUtil/CoreUtil/Export.swift to make it available app-wide (CoreUtil/CoreUtil/Export.swift)

• Swift + AppKit (macOS native) — Native performance and tight OS integration for a Mac-first utility app; avoids cross-platform framework overhead
• Combine framework — Reactive state management with minimal boilerplate; eliminates manual KVO and callback hell for data binding
• Xcode + xcodeproj — Standard macOS build system; allows use of specialized tools (Icon Generator uses ImageIO) and system frameworks
• Custom Observable abstraction — Lightweight wrapper around Combine providing consistent, testable state patterns across all tools

• Each tool (coder, converter, generator) implemented as separate view controller

  • Why: Maximizes clarity and modularity; each tool can have distinct UI and logic without shared state coupling
  • Consequence: More boilerplate per tool, but easier to add/remove/test individual tools independently

• CoreUtil as a separate framework/module

  • Why: Promotes reusability and separates presentation concerns from core utilities
  • Consequence: Requires careful API boundary maintenance; changes to CoreUtil affect all tools

• Reactive UI updates via Combine + NSTextField+Combine bindings

  • Why: Ensures responsive, real-time conversion feedback as user types
  • Consequence: All computations must complete quickly (~50ms) to maintain responsiveness; long operations may block UI thread

• Icon Generator as a specialized subsystem within Graphic tools

  • Why: Icon generation involves image processing and multiple output formats; benefits from consolidated ImageIO handling
  • Consequence: Icon Generator is heavier than other tools; adds dependency on Foundation ImageIO and CoreGraphics

• Multi-platform support (Windows, Linux) — this is macOS-only
• Cloud/network-based tools — all processing is local-only
• User accounts or persistence beyond app preferences — no backend or authentication
• Extensibility via plugins — tools are hardcoded, not dynamically loaded
• Real-time collaboration — single-user, offline-first design

AppKit + Combine Mismatch: CoreUtil provides custom bridges (NSTextField+Combine.swift, NSControl+Combine.swift) because AppKit predates Combine—understand these bridges before adding new reactive UI. Objective-C Exception Handling: The ExceptionHandler bridge is required because Swift cannot catch Objective-C exceptions natively; any tool doing risky operations must route through this. Workspace, Not Project: Always open .xcworkspace, not .xcodeproj, to ensure CoreUtil framework is linked correctly. macOS Deployment Target: Verify the minimum OS version in build settings—affects available APIs for new tools.

• Combine Framework & Publishers — DevToysMac uses Combine extensively for reactive data binding (see NSTextField+Combine.swift, NSControl+Combine.swift); understanding Publishers, Subscribers, and operators like .sink(), .map(), and .debounce() is essential to modify any tool's UI logic.
• AppKit (NSViewController, NSControl, NSTextField) — DevToysMac is built on AppKit, not SwiftUI; understanding NSViewController lifecycle, responder chain, and control targets is mandatory for UI work since SwiftUI patterns (like @State) are shimmed via custom extensions.
• Observable Pattern (Custom Implementation) — CoreUtil defines a custom Observable<T> generic class (not Combine.Observable) as the primary state container; grasping this pattern and how it differs from @Published is critical for state management.
• Objective-C to Swift Exception Bridging — Swift cannot natively catch Objective-C exceptions; the ExceptionHandler mediates this gap. Essential when integrating C-based libraries or handling legacy code that throws NSException.
• Swift Keyboard Shortcuts & HotKey Management — The /HotKey directory (mentioned but not fully listed) suggests global keyboard shortcut registration; understanding macOS HotKey APIs is needed for accessibility and quick-launch features.
• State Restoration & Codable Persistence — Tools use RestorableState and RestorableData to persist user inputs across launches; understanding how Swift Codable + PropertyList serialization works is needed for durability features.
• macOS Framework Frameworks (xcworkspace) — The project uses an .xcworkspace with a separate CoreUtil framework; understanding framework linking, module interfaces, and @testable import is crucial for modular development and testing.

• veler/DevToys — The original Windows/web DevToys app this macOS version mirrors; useful for understanding feature parity and architecture decisions across platforms
• ObuchiYuki/DevToysMac — The primary upstream repository (this may be a fork; verify ownership and contribution flow)
• sindresorhus/quick-look-plugins — macOS utility app ecosystem reference for native app patterns and distribution (Homebrew cask integration)
• mas-cli/mas — Similar macOS CLI/native app distribution strategy via Homebrew; can inform release and packaging workflows

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 CoreUtil extension classes

The CoreUtil framework contains numerous extension files (Ex+NSColor.swift, Ex+NSControl.swift, Ex+CGRect.swift, etc.) with no visible test coverage in the file structure. These utilities are critical infrastructure for the main app. Adding unit tests would improve reliability and prevent regressions when these core utilities are modified.

• [ ] Create CoreUtilTests target in CoreUtil.xcodeproj
• [ ] Add test files for Ex+NSColor.swift, Ex+CGRect.swift, and Ex+Array.swift (high-impact utilities)
• [ ] Write tests covering common operations like color conversions, geometry calculations, and array transformations
• [ ] Configure test scheme in CoreUtil.xcodeproj/xcshareddata/xcschemes/
• [ ] Update .gitignore if needed to exclude test build artifacts

Add GitHub Actions CI/CD workflow for macOS builds

The repo lacks a visible CI/CD pipeline. Adding GitHub Actions would automatically build and test the app on every PR, catch compilation errors early, and verify the app runs on different macOS versions. This is critical for a desktop app where environment differences matter significantly.

• [ ] Create .github/workflows/macos-build.yml
• [ ] Configure xcodebuild commands to build both DevToys and CoreUtil targets
• [ ] Add test execution step using xcodebuild test on DevToys.xcodeproj
• [ ] Set up matrix strategy to test against multiple macOS versions (12.x, 13.x, 14.x)
• [ ] Add build artifacts upload for debugging failed builds

Refactor Observable.swift and RestorableState.swift into separate coordinator pattern files

The CoreUtil/Class/ directory contains several state management files (Observable.swift, RestorableState.swift, RestorableData.swift, StateObject.swift extension) that appear to form a cohesive state management pattern. These should be organized into a dedicated StateManagement subdirectory with clear separation of concerns, making the architecture more discoverable for contributors and easier to maintain.

• [ ] Create CoreUtil/CoreUtil/StateManagement/ directory
• [ ] Move Observable.swift, RestorableState.swift, RestorableData.swift into StateManagement/
• [ ] Move NSViewController+StateObject.swift to StateManagement/
• [ ] Create StateManagement/README.md documenting the state pattern used in the project
• [ ] Update import statements in DevToys project to reference new file locations
• [ ] Update CoreUtil.h to reflect new file organization

• Add unit tests for CoreUtil/Class/Observable.swift and state mutation edge cases—the file has no visible test coverage and is critical to app reliability.
• Create comprehensive documentation in CoreUtil/Export.swift and top-level README detailing how to add a new tool (state setup, UI binding, persistence)—currently only inferred from code.
• Extend CoreUtil/Extensions/Swift/Ex+Localize.swift with missing localizations for existing tool names/descriptions across supported languages, or add infrastructure for community translations.

The DevToysMac application is a developer utility with moderate security concerns. The primary risks stem from processing user input in multiple data format handlers (SQL, JWT, HTML, etc.) without visible validation and sanitization mechanisms. The Terminal.swift component and SQL formatter present potential injection risks. The codebase lacks centralized input validation framework and has insufficient visible error handling safeguards. The application handles sensitive data formats (JWT tokens) without visible security verification. However, the app's scope as a local development tool reduces some attack surface. Recommend implementing comprehensive input validation, adding security-focused unit tests, regular dependency audits, and secure error handling practices.

• Medium · SQL Injection Risk in SQL Formatter — DevToys/DevToys/Body/Format/SQLFormatterView+.swift. The codebase includes a SQLFormatterView component that processes SQL queries. Without evidence of parameterized queries or input validation, there is a potential risk of SQL injection if user input is directly passed to SQL processing functions. Fix: Implement input validation and sanitization for SQL queries. Use parameterized queries or prepared statements where applicable. Validate and escape user input before processing.
• Medium · Potential Code Execution via Terminal Component — CoreUtil/CoreUtil/Class/Terminal.swift. The codebase includes a Terminal.swift class that may execute shell commands. Without visible input validation or command escaping, this could present a command injection vulnerability if user input is passed to terminal operations. Fix: Implement strict input validation and use safe APIs for command execution. Avoid shell interpretation of user input. Use process execution APIs that don't invoke shell interpreters. Escape or quote arguments properly.
• Medium · JWT Decoder Without Validation — DevToys/DevToys/Body/Coder/JWTDecoderView+.swift. The JWT decoder component processes JWT tokens without evidence of signature verification or expiration checking visible in the file structure. This could allow processing of tampered or expired tokens. Fix: Implement proper JWT signature verification before decoding. Validate token expiration and claims. Use established JWT libraries with built-in validation mechanisms.
• Low · Missing Input Validation Framework — DevToys/DevToys/Body/Coder/ and DevToys/DevToys/Body/Format/ directories. The codebase handles various data formats (Base64, HTML, URL, JSON, YAML, XML) but there is no visible centralized input validation or sanitization mechanism across formatters and decoders. Fix: Implement a centralized input validation framework. Create validators for each data type being processed. Implement output encoding to prevent injection attacks.
• Low · HTML Decoder Without Sanitization Evidence — DevToys/DevToys/Body/Coder/HTMLDecoderView+.swift. HTML decoder component may parse and process HTML without visible sanitization, potentially allowing XSS-like vulnerabilities if decoded content is rendered. Fix: Implement HTML sanitization using established libraries. Strip potentially dangerous tags and attributes. Apply Content Security Policy principles. Never directly render user-provided HTML.
• Low · Insufficient Dependency Visibility — DevToys.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file location indicates Swift Package Manager dependencies, but the actual dependency content is not provided for analysis. Unknown vulnerabilities may exist in third-party packages. Fix: Regularly audit and update all dependencies. Use dependency scanning tools. Review Package.resolved for outdated or vulnerable packages. Implement automated dependency checking in CI/CD.
• Low · No Visible Error Handling for User Input — CoreUtil/CoreUtil/ExceptionHanlder/ and related view components. Exception handling is present (ExceptionHandler) but there's no evidence of secure error messages that don't expose sensitive information in converters and decoders. Fix: Implement secure error handling that doesn't expose internal implementation details. Log detailed errors server-side only. Display generic messages to users. Avoid stack traces in UI.

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.