1 files changed, 38 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bf1e5df
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+A personal collection of bash scripts for various purposes. Scripts use `set -euo pipefail` and have inline usage documentation. New scripts should be organized into subdirectories by purpose.
+
+## Current script categories
+
+### General structure
+Each subdirectory groups scripts by deployment target or domain. Scripts are plain bash — no build step.
+
+### Git server scripts
+
+### `git-shell-commands/`
+Invoked remotely via SSH (e.g. `ssh git@treybastian.com new-project myrepo`). The git shell restricts the user to only these named commands. Scripts run in the context of the home directory of the git user.
+
+- `new-project` — creates a bare repo; `--public` also writes `public.conf` and registers the repo on the public remote; `--description <desc>` sets the repo description on both servers
+- `new-repo` — lower-level command that only creates a bare repo (called by `new-project` to register the mirror); accepts `--description <desc>`
+- `make-public` — converts an existing private repo to public by writing `public.conf` and registering the mirror
+- `set-description` — sets the description on an existing repo; if `public.conf` exists, also updates the description on the remote
+- `no-interactive-login` — blocks interactive shell access for the git user
+
+### `git-hooks/`
+Installed globally on the server via `git config --system core.hooksPath`. When `core.hooksPath` is set, git uses only that directory for hooks — repo-specific hooks are bypassed. This is solved by:
+
+- `hook-runner` — a passthrough script that checks if a repo-local hook exists at `$(pwd)/hooks/<hook-name>` and runs it. It is **symlinked** to `post-update`, `pre-recieve`, and `update` so those hooks delegate to repo-specific scripts.
+- `post-receive` — the main hook; if `public.conf` exists in the repo, it mirror-pushes to the URL inside it, then also delegates to a repo-local `post-receive` hook if present.
+
+#### Public/private distinction
+A repo is considered public if and only if it contains a `public.conf` file at its root. That file holds a single line: the remote URL to mirror to (e.g. `git@treybastian.com:repos/myrepo.git`). The `post-receive` hook reads this file to decide whether to mirror on push.
+
+#### Deployment
+- `git-shell-commands/*` → the git user's `~/git-shell-commands/` directory on the server
+- `git-hooks/*` → wherever `core.hooksPath` points (e.g. `/home/git/scripts/git-hooks`)
+
+Symlink `hook-runner` to the other hook names (`post-update`, `pre-recieve`, `update`) in the hooks directory after deploying.