@supa-media/claude

@supa-media/claude

Claude Code configuration for a Supa app, kept in one place and synced in. Ships a CLAUDE.md, a conservative permissions file, an empty hooks file, and seven slash-command templates; supa-claude sync copies them into your repo with your app's name substituted, and never clobbers a file you've edited unless you ask it to.

Install

pnpm add -D @supa-media/claude

Or run it one-off, without adding a dependency:

npx @supa-media/claude sync

Usage

npx @supa-media/claude sync              Sync templates and generate CLAUDE.md
npx @supa-media/claude sync --force      Overwrite existing files
npx @supa-media/claude sync --dry-run    Print the plan, write nothing
npx @supa-media/claude help              Show usage

sync is the only command (and the default when none is given). --help / -h work anywhere. The project root is the nearest ancestor of the cwd containing a package.json.

What it writes

Path	Source	Substituted
CLAUDE.md (project root)	templates/CLAUDE.md	yes
.claude/settings.json	templates/settings.json	no — copied verbatim
.claude/hooks.json	templates/hooks.json	yes
.claude/commands/*.md	templates/commands/	yes

The seven commands: auto-worker, feature-validate, fix-ci, ios-build, isolate, lock-up, review-cycle.

Every file follows the same rule: created if absent, skipped if it already exists, and rewritten only under --force (and then only when the content actually differs). Each run prints created / updated / skipped / unchanged.

Configuration

Values are read from supa.config.ts, .js, or .mjs in the project root, falling back to package.json's name for both name fields.

Value	Substitutes
appName (or name)	{{APP_NAME}}
displayName	{{APP_DISPLAY_NAME}} (defaults to appName)
githubOwner (or owner)	the literal word OWNER
githubRepo (or repo)	the literal string "REPO"

The owner/repo tokens exist for the GitHub GraphQL queries in commands/review-cycle.md; leave them unset and the templates keep their placeholders with the accompanying "replace OWNER and REPO" notes.

The config file is scanned with regexes, not imported. Each pattern takes the first match anywhere in the file, so an unrelated name: earlier in the config wins. And the GitHub substitution is a blind global replace of the bare word OWNER and the quoted string "REPO" — an unquoted REPO (e.g. in a repos/OWNER/REPO/... path) is left alone, and any other occurrence of the word OWNER in a template you add will be replaced too.

Permissions

templates/settings.json ships a deliberately conservative permissions.allow list — routine, reversible commands only:

• pnpm — install, and the dev:/build:/test:/lint:/typecheck:/clean:/--filter: prefixes, plus convex:dashboard and convex:logs
• Convex — npx convex dev, npx convex run, npx convex logs
• Build/test — npx tsc, node --test
• Read-only git and gh — status, diff, log, show, branch, fetch; gh pr view|list|diff|checks, gh run view|list, gh api graphql
• Local git writes — git add, git commit, git checkout

It also denies reads of .env and .env.*, at the project root and nested.

Everything not listed still prompts — deliberately. That includes git push, git reset --hard, git clean, gh pr merge, convex deploy, and eas: the commands that publish, deploy, or destroy work. This is a floor, not a finished policy. Widen it for your own repo once you know which of those you're comfortable granting; sync will not overwrite an existing .claude/settings.json without --force, so your edits survive later syncs.

templates/hooks.json ships empty — a starting point for your own PreToolUse / PostToolUse / Stop entries. Any command you register must point at a script that actually exists in your repo; a missing script makes the hook fail on every invocation.

No tests ship with this package.

---

Part of the Supa Media framework — https://github.com/Supa-Media/supa-framework. MIT.