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.

Creating Components

When creating a new service, tool, or frontend, follow the detailed guides:

@docs/component-registry.md — Manifest architecture, castle.yaml structure, role derivation, lifecycle
@docs/web-apis.md — FastAPI service patterns (config, routes, models, testing)
@docs/python-tools.md — CLI tool patterns (argparse, stdin/stdout, piping, testing)
@docs/web-frontends.md — React/Vite/TypeScript frontend patterns

Quick start

# Service
castle create my-service --type service --description "Does something"
cd components/my-service && uv sync
uv run my-service               # starts on auto-assigned port
castle service enable my-service # register with systemd
castle gateway reload            # update reverse proxy routes

# Tool
castle create my-tool --type tool --description "Does something"
cd components/my-tool && uv sync

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

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 tool list                         # List all tools
castle tool info <name>                  # Show tool details
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

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.

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

Key Files

castle.yaml — Component registry (single source of truth)
core/src/castle_core/manifest.py — Pydantic models (ComponentManifest, RunSpec, etc.)
core/src/castle_core/config.py — Config loader (castle.yaml → CastleConfig)
core/src/castle_core/generators/ — Systemd unit and Caddyfile generation
cli/src/castle_cli/templates/scaffold.py — Project scaffolding templates
pyproject.toml — uv workspace root (core, cli, castle-api)
ruff.toml / pyrightconfig.json — Shared lint/type config

4.3 KiB Raw Blame History