# Usage: curl -sSL https://seed.show/claude.code.setup | bash -s <install-path>
# <install-path> is the directory where the file should land.

set -euo pipefail
# seed.show — assumption contract for claude.code.setup
# (printed to stderr before unpack so the agent sees it in tool output)
cat >&2 <<'ASSUMPTIONS_EOF'
- you're using Claude Code as the agent harness. other harnesses without `.claude/` conventions won't get useful behavior from this content.
- you have a writable project root and can create or modify `.claude/` (and its sub-paths) without conflicting with existing setup.
- you're choosing a fresh-or-light setup. heavy customisations already in place may conflict with the recommended structure — read before applying.

A starting point for any project where Claude Code is the primary agent. Not a rigid template — a set of conventions that prevent the predictable failures.

Three files:

- `CLAUDE.md` — the agent's operating manual. Read on every session start. Fill the `[SLOT]` markers before the first session.
- `sources.md` — fetch these for current Claude Code documentation. Don't cache them here; they change.
- `.claude/` skeletons — settings.json for permission rules, session-start.sh hook for secrets and context injection.

ASSUMPTIONS_EOF

[ -z "${1:-}" ] && {
  echo "install requires a path: curl -sSL https://seed.show/claude.code.setup | bash -s <install-path>" >&2
  exit 1
}
TARGET="$1"
mkdir -p "$TARGET"
DEST="$TARGET/seed-fold.Jv2mWX.folded.md"

cat > "$DEST" <<'PORTDOWN_3D5A561E'
<!--
This is a `.folded.md` archive — a directory packed into one markdown
file. The markers below are load-bearing; don't edit them directly.

To unpack (requires bash — if you have no shell, tell the user):
  1. curl -sSLf https://fold.dom.vin/skill | bash -s <INSTALL_DIR>
  2. <INSTALL_DIR>/fold/scripts/unfold <this-file>
     (or: unfold <this-file>  if fold/scripts is on your PATH)
-->

---
fold: true
marker: 79e4c1
at: 2026-05-07T16:15:59Z
root: seed-pack.u7j1F2
---

<!--fold:79e4c1@file path=".claude/hooks/session-start.sh" mode="644"-->
#!/usr/bin/env bash
# .claude/hooks/session-start.sh
# Runs at the start of every Claude Code session.
# Load secrets from .env.local and export them into the session environment.
# Add any project-specific context injection below.

set -euo pipefail

# Load .env.local if it exists — never commit this file.
if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.env.local" ]; then
  # shellcheck disable=SC2046
  export $(grep -v '^#' "$(git rev-parse --show-toplevel)/.env.local" | xargs)
fi

# [SLOT: Add any additional context injection here.
# e.g. export API_BASE_URL="http://localhost:3000"
# e.g. echo "Running on $(node --version)" ]
<!--fold:79e4c1@file path=".claude/settings.json" mode="644"-->
{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(git push)",
      "Bash(git fetch*)",
      "Bash(git pull*)",
      "Bash(git checkout*)",
      "Bash(git branch*)",
      "Bash(npm install)",
      "Bash(npm run*)",
      "Bash(npx*)"
    ],
    "deny": [
      "Bash(git push --force*)",
      "Bash(git push -f*)",
      "Bash(git reset --hard*)",
      "Bash(rm -rf*)",
      "Bash(git add .env*)"
    ]
  }
}
<!--fold:79e4c1@file path="CLAUDE.md" mode="644"-->
# [SLOT: Project name]

[SLOT: One paragraph. What is this project? What does it do? Who uses it? Be specific — the agent uses this to understand scope and make judgment calls.]

## Stack

[SLOT: Language, framework, database, key dependencies. One line each. Include version constraints only if they matter for the agent's work.]

## How to run

```bash
[SLOT: commands to install deps and start the dev server]
```

[SLOT: How to run tests. The agent needs this to verify changes before pushing.]

```bash
[SLOT: test command]
```

## What good work looks like

- Every session ends with changes committed and pushed. The deliverable is the file, not the chat.
- One logical change per commit. If a change does two things, split it.
- Tests pass before anything is pushed.
- [SLOT: Add any project-specific quality standards — linting, coverage thresholds, performance budgets.]

## What to never do without checking

- Force push (`git push --force`, `git push -f`) — ask first, always.
- Drop database tables or run destructive migrations.
- Commit `.env`, `.env.local`, `*.pem`, or any file matching `.gitignore`.
- Amend a commit that has already been pushed.
- [SLOT: Add project-specific dangerous operations — e.g. "delete records from production", "change the Stripe webhook endpoint".]

## Secrets

[SLOT: Where do secrets live and how does the agent access them?

Example A — env file loaded by hook:
".env.local — never committed. Loaded by the session-start hook at .claude/hooks/session-start.sh. Once the hook runs, $API_KEY etc. are available in the session env."

Example B — secrets service:
"Secrets are in 1Password. The agent should ask the user to export the relevant values before the session if they're needed."]

## Branch strategy

[SLOT: e.g. "main is the deploy branch. Commit directly to main for small changes. Branch only for multi-step refactors or changes that need review before going live."]

## Agent notes

[SLOT: Things the agent specifically needs to know that don't fit elsewhere. Good candidates:

- Parts of the codebase that look broken but aren't ("the migration script throws a warning on first run — ignore it")
- External dependencies with unusual behavior ("the staging API is rate-limited to 10 req/min — slow down if you're hitting it in tests")
- Decisions made that might look wrong ("we use X instead of Y because of Z — don't change this")
- Recurring errors the agent will encounter and what to do about them

Leave this section out entirely if there's nothing to say. Don't fill it with generic advice.]

---

## Hook skeleton

The session-start hook lives at `.claude/hooks/session-start.sh`. Register it in `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}
```

The hook itself handles two jobs. Adapt as needed:

```bash
#!/bin/bash
# SessionStart hook — loads secrets and optionally injects context.
set -euo pipefail

# --- Job 1: Load secrets into session env ---
# Reads .env.local (or .env.shared), exports KEY=VALUE lines via $CLAUDE_ENV_FILE.
# The agent then has $API_KEY etc. available without hardcoding.
ENV_FILE="${CLAUDE_PROJECT_DIR:-$(pwd)}/.env.local"

if [ -f "$ENV_FILE" ] && [ -n "${CLAUDE_ENV_FILE:-}" ]; then
  count=0
  while IFS= read -r line || [ -n "$line" ]; do
    [ -z "$line" ] && continue
    case "$line" in
      \#*) continue ;;
      *=*) printf 'export %s\n' "$line" >> "$CLAUDE_ENV_FILE"; count=$((count + 1)) ;;
    esac
  done < "$ENV_FILE"
  echo "[session-start] Loaded $count secret(s)." >&2
fi

# --- Job 2: Inject context as a system reminder (optional) ---
# Uncomment and point CONTEXT_FILE at a markdown file to inject.
# The content appears before the first prompt and re-injects after compaction.
#
# CONTEXT_FILE="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/context.md"
# if [ -f "$CONTEXT_FILE" ]; then
#   CONTENT=$(cat "$CONTEXT_FILE")
#   cat <<EOF
# {
#   "hookSpecificOutput": {
#     "hookEventName": "SessionStart",
#     "additionalContext": $(printf '%s\n' "$CONTENT" | jq -Rs .)
#   }
# }
# EOF
# fi
```

Make it executable: `chmod +x .claude/hooks/session-start.sh`
<!--fold:79e4c1@file path="README.md" mode="644"-->
# claude.code.setup


## Assumptions

- you're using Claude Code as the agent harness. other harnesses without `.claude/` conventions won't get useful behavior from this content.
- you have a writable project root and can create or modify `.claude/` (and its sub-paths) without conflicting with existing setup.
- you're choosing a fresh-or-light setup. heavy customisations already in place may conflict with the recommended structure — read before applying.

A starting point for any project where Claude Code is the primary agent. Not a rigid template — a set of conventions that prevent the predictable failures.

Three files:

- `CLAUDE.md` — the agent's operating manual. Read on every session start. Fill the `[SLOT]` markers before the first session.
- `sources.md` — fetch these for current Claude Code documentation. Don't cache them here; they change.
- `.claude/` skeletons — settings.json for permission rules, session-start.sh hook for secrets and context injection.

## What AI is changing

Claude Code doesn't just write code on request. It runs multi-step tasks autonomously: reading files, running tests, committing, pushing, deploying — across an entire session, without checking in. The hook system lets you inject context before any session starts and intercept every tool call before it executes. MCP integration means the agent can call external APIs, browsers, and services as first-class tools.

This raises the stakes on the setup moment. A poorly structured CLAUDE.md costs time on every session — the agent either over-asks (friction) or under-checks (mistakes). Get it right once and the whole project lifecycle benefits.

## What CLAUDE.md actually is

Not documentation. Not a README. Not a list of rules.

It's instructions for a capable colleague who just joined the project. Write it so that colleague knows: what the project is, what good work looks like, what they should never do without checking, and where the sharp edges are. The agent reads it before touching anything — every session, not just the first.

The mental model: CLAUDE.md is the operating manual. If something goes wrong that CLAUDE.md would have prevented, update CLAUDE.md.

## What to do with this seed

1. Read CLAUDE.md. Every `[SLOT]` marker is a decision you need to make explicitly.
2. Fill in the slots. Stack, run commands, secrets location, branch strategy, agent-specific notes.
3. Wire the hook skeleton. The session-start hook loads secrets and can inject context. Both matter.
4. Register the hook in `.claude/settings.json` under `hooks.SessionStart`.
5. Start a session. The agent reads CLAUDE.md first — verify it did by asking it to summarize what the project is.

## What agents get wrong without this

**Treating CLAUDE.md as documentation.** Agents write what they'd put in a README: architecture overviews, dependency lists, historical context. None of that is instructions. The agent doesn't need to understand your system — it needs to know what to do and what not to do.

**Not filling the slots.** The template ships with `[SLOT]` markers. If they're still there when the first session starts, the agent is operating with gaps. It will fill them with assumptions — usually wrong ones about secrets, branches, and what "done" means.

**Ignoring hooks.** The session-start hook is how the agent gets secrets, loads external context, and establishes baseline environment. Without it, the agent either has no API keys (fails on external calls) or you hardcode them somewhere they don't belong.

**No "what to never do" section.** Agents treat everything not explicitly forbidden as permitted. Force push, dropping tables, committing .env — all are legitimate tools to an agent that hasn't been told otherwise.

## What good CLAUDE.md invariants look like

The template includes four non-negotiables:

- **Deliverable is the file** — every session ends with changes committed and pushed, not described in chat.
- **Force push requires confirmation** — name it as a destructive op.
- **Never commit secrets** — name the exact file patterns (`.env`, `.env.local`, `*.pem`).
- **Split commits** — one logical change per commit.

These are floor, not ceiling. Add project-specific invariants whenever you discover a "the agent did X and shouldn't have" moment.

## The hook skeleton

`session-start.sh` handles two things:

1. **Secrets** — reads a `.env.shared` or `.env.local` file, exports each `KEY=VALUE` line into the session env via `$CLAUDE_ENV_FILE`. The agent then has `$API_KEY` etc. available without them being hardcoded anywhere.
2. **Context injection** — outputs JSON with `hookSpecificOutput.additionalContext` to inject a file's contents as a system reminder before the first prompt. Use this to surface a skill, a domain map, or a project-specific routing doc.

Both survive context compaction if you register the hook correctly — hooks fire on session start, resume, clear, and compact events.

See `sources.md` for the full hooks reference.
<!--fold:79e4c1@file path="sources.md" mode="644"-->
# sources

Fetch these at task time. Ordered by importance.

1. Claude Code documentation — how CLAUDE.md is parsed, hooks, slash commands, settings schema:
   https://docs.anthropic.com/en/docs/claude-code/overview

2. CLAUDE.md format and best practices (official guide):
   https://docs.anthropic.com/en/docs/claude-code/memory

3. Claude Code hooks reference — SessionStart, PreToolUse, PostToolUse events and output format:
   https://docs.anthropic.com/en/docs/claude-code/hooks

4. Claude Code settings.json schema — permission rules, allow/deny patterns:
   https://docs.anthropic.com/en/docs/claude-code/settings
<!--fold:79e4c1@end-->
PORTDOWN_3D5A561E

# ── post ──
MARKER=$(awk '/^---$/ { f++; if (f==2) exit; next } f==1 && /^marker:[[:space:]]/ { sub(/^marker:[[:space:]]+/, ""); print; exit }' "$DEST")
[ -z "$MARKER" ] && { echo "seed: archive has no marker — corrupt" >&2; exit 1; }
awk -v m="$MARKER" -v outdir="$TARGET" '
  BEGIN {
    # Match <!--fold:<m>@file path="X"--> with an optional mode attr after
    # the path (fold emits  mode="644"  on executables).
    file_re = "^<!--fold:" m "@file path=\"([^\"]+)\"( mode=\"[0-9]+\")?-->$"
    end_re  = "^<!--fold:" m "@end-->$"
  }
  $0 ~ end_re { if (current) close(current); exit }
  $0 ~ file_re {
    if (current) close(current)
    line = $0
    sub(/^<!--fold:[^@]+@file path="/, "", line); sub(/".*$/, "", line)
    current = outdir "/" line
    dir = current; sub(/\/[^\/]*$/, "", dir)
    if (dir != current) system("mkdir -p \"" dir "\"")
    printf "" > current
    next
  }
  current { print >> current }
' "$DEST"
SEED_EXTRACTED=$(find "$TARGET" -type f -not -path "$DEST" 2>/dev/null | wc -l)
if [ "$SEED_EXTRACTED" = "0" ]; then
  echo "seed: archive contained no files — refusing to delete the source" >&2
  echo "  archive preserved at: $DEST" >&2
  exit 1
fi
rm -f "$DEST"

echo "" >&2
echo "✓ seed unpacked → $TARGET ($SEED_EXTRACTED files)" >&2
find "$TARGET" -type f | sort | while IFS= read -r _sf; do
  echo "  ${_sf#${TARGET}/}" >&2
done
echo "" >&2
if [ -f "$TARGET/SKILL.md" ]; then
  echo "This seed contains a skill (SKILL.md). Install it in your agent's skills directory." >&2
  echo "" >&2
fi
echo "Install the seed skill if not already installed:" >&2
echo "  https://seed.show/skill" >&2
echo "" >&2
echo "Publisher prompt:" >&2
sed 's/^/  /' >&2 <<'__SEED_PROMPT_END_AC1F2B__'
You have the Claude Code project setup context. Read README.md, then use CLAUDE.md as your template — fill the [SLOTS] and adapt the hooks skeleton. Fetch sources.md for current Claude Code documentation. To share your own context bundles: curl seed.show/skill | bash
__SEED_PROMPT_END_AC1F2B__
exit 0