From a56132bdbce51b3c1f5ca13a7633ff5a00707b26 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Mon, 12 Jan 2026 16:53:43 -0800 Subject: [PATCH] Add CLAUDE.md for Claude Code guidance Provides build/test commands, architecture overview, and development workflow notes including green-red-green testing cycle. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d32ec1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,52 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build and Test Commands + +```bash +# 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..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`