wild-pc/CLAUDE.md

CLAUDE.md

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

Overview

Castle is a personal software platform — a monorepo of independent projects (services, tools, libraries) managed by the castle CLI. Components declare what they do (expose HTTP, manage via systemd, install to PATH) and roles are derived, not labeled.

Key principle: Regular projects must never depend on castle. They accept standard configuration (data dir, port, URLs) via env vars. Only castle-components (CLI, gateway, event bus) know about castle internals.

Castle CLI

The CLI lives in cli/ and is installed via uv tool install --editable cli/.

castle list                              # List all components
castle list --role service               # Filter by derived role
castle info <component>                  # Show manifest details (--json for machine-readable)
castle create <name> --type service      # Scaffold new project
castle test [project]                    # Run tests (one or all)
castle lint [project]                    # Run linter (one or all)
castle sync                              # Update submodules + uv sync all
castle run <component>                   # Run component in foreground
castle logs <component> [-f] [-n 50]     # View component logs
castle gateway start|stop|reload|status  # Manage Caddy reverse proxy
castle service enable|disable <name>     # Manage individual systemd service
castle service status                    # Show all service statuses
castle services start|stop               # Start/stop everything
castle migrate                           # Convert castle.yaml to new format

Registry & Manifest Architecture

castle.yaml at the repo root is the single source of truth. It uses a manifest model (cli/src/castle_cli/manifest.py) where components declare capabilities:

• run: How to start it (RunSpec: python_uv_tool, command, container, node, remote)
• expose: What it exposes (HTTP port, health endpoint)
• proxy: How to proxy it (Caddy path prefix)
• manage: How to manage it (systemd)
• install: How to install it (PATH shim)
• build: How to build it (commands, outputs)
• triggers: What triggers it (manual, schedule, event, request)

Roles are derived from these declarations:

• service — has expose.http
• tool — has install.path or is fallback
• worker — has manage.systemd but no HTTP
• job — has schedule trigger
• frontend — has build outputs
• containerized — uses container runner
• remote — uses remote runner

Component Roles (replaces Project Types)

Role	Convention	Example
service	FastAPI, pydantic-settings, lifespan, /health endpoint	central-context
tool	argparse, stdin/stdout, exit codes, Unix pipes	devbox-connect
worker	Systemd-managed, no HTTP	(none yet)
job	Scheduled task	(none yet)
containerized	Docker/Podman container	(none yet)

Creating a New Project

castle create my-service --type service --description "Does something"
cd my-service
uv sync
uv run my-service       # starts on auto-assigned port
castle test my-service   # run tests
castle service enable my-service  # register with systemd

The castle create command scaffolds the project, generates a CLAUDE.md, and registers it in castle.yaml as a ComponentManifest.

Infrastructure

• Gateway: Caddy reverse proxy at port 9000, config generated from castle.yaml into ~/.castle/generated/Caddyfile. Dashboard served at root.
• Systemd: User units generated under ~/.config/systemd/user/castle-*.service
• Data: Service data lives in /data/castle/<service-name>/, passed via env var.
• Secrets: ~/.castle/secrets/ — never in project directories.

Per-Project Commands

All projects use uv. Commands run from each project's directory:

uv sync                     # Install deps
uv run pytest tests/ -v     # Run tests
uv run ruff check .         # Lint
uv run ruff format .        # Format

Services also support: uv run <service-name> to start.

Existing Components

Component	Roles	Port	Description
central-context	service	9001	Content storage API (submodule)
notification-bridge	service	9002	Desktop notification forwarder (submodule)
devbox-connect	tool	—	SSH tunnel manager
mboxer	tool	—	MBOX to EML converter (submodule)
toolkit	tool	—	Personal utility scripts (submodule)
protonmail	tool	—	ProtonMail email sync via Bridge
event-bus	service	9010	Inter-service event bus

Code Style

• Linting/formatting: ruff — shared ruff.toml at repo root (100-char lines)
• Type checking: pyright — shared pyrightconfig.json at repo root
• Testing: pytest, pytest-asyncio for async tests
• Python: 3.13 for services, 3.11+ minimum for tools/libraries

Agent Workflow

When creating a new service or tool:

1. castle create <name> --type <type> — scaffold and register
2. Implement the project logic
3. castle test <name> — verify tests pass
4. castle service enable <name> — deploy as systemd service (services only)
5. castle gateway reload — update reverse proxy routes