mcquack/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

# Run tests
uv run pytest

# Run a single test
uv run pytest test_mcquack.py::TestCreate::test_create_with_arguments

# Run tests matching a pattern
uv run pytest -k "test_edit"

# Type checking (uses ty via pre-commit)
uvx ty check

# Run pre-commit hooks manually
uv run pre-commit run --all-files

# Run the CLI directly (no install needed)
./mcquack.py list

Architecture

mcquack is a single-file Python CLI (mcquack.py) that manages macOS LaunchAgents for executable scripts. It uses a uv script shebang (#!/usr/bin/env -S uv run --script) so it can be run directly without installation.

Key components in mcquack.py:

• app - Typer CLI application with commands: list, create, launch, show, edit, unload, delete
• LAUNCH_AGENTS_DIR / LOGS_DIR - Paths to ~/Library/LaunchAgents and ~/Library/Logs
• get_plist_path() / get_label() - Generate plist paths and launchd labels from script paths
• create_plist_dict() - Builds the plist dictionary structure

Plist naming convention: mcquack.eblume.<scriptname>.plist

Test architecture:

• conftest.py - Fixtures that mock LAUNCH_AGENTS_DIR, LOGS_DIR, and subprocess.run to avoid real launchctl calls
• Tests use typer.testing.CliRunner to invoke CLI commands

Important Patterns

• Commands that accept script arguments (create, edit) require -- separator to distinguish mcquack flags from script args
• All launchctl interactions go through subprocess.run - tests mock this to avoid system modifications
• The mock_dirs fixture monkeypatches module-level path constants for test isolation

Development Workflow

• Use a green-red-green testing cycle: verify tests pass, write a failing test for new behavior, then implement until green
• Run type checking frequently with uvx ty check