Personal utility commands and tools for Claude Code

version
2.0.1
GitHub stars
52

Install

/plugin install toolbox@claude-code-zero

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.

Contents

Discovered from source

Skills 4

Fetch Sitemap URLs

Extract URLs from an XML sitemap with optional regex filtering.

Arguments

  • $0: URL (required, must start with http:// or https://)
    • If the URL ends with .xml, use it directly as the sitemap URL (backward compatible)
    • Otherwise, run the auto-discovery logic below
  • $1: an extended regex pattern for filtering (optional)

If $0 is empty, display the usage below and stop:

Usage: /fetch-sitemap <url> [pattern]

Examples:
  /fetch-sitemap https://kotlinlang.org/docs
  /fetch-sitemap https://example.com/sitemap.xml
  /fetch-sitemap https://example.com docs
  /fetch-sitemap https://example.com/sitemap.xml 'skills|hooks'

If $0 does not start with http:// or https://, inform the user that a valid URL is required and stop.

Sitemap Auto-Discovery

When the URL does not end with .xml, automatically discover the sitemap by probing the following locations one at a time, stopping as soon as one produces output (do NOT run probes in parallel):

Probes 1–2 — fetch and extract in a single curl:

  1. {url}/sitemap.xml — path-specific (e.g., https://kotlinlang.org/docs/sitemap.xml)
  2. {origin}/sitemap.xml — site root (e.g., https://kotlinlang.org/sitemap.xml), where {origin} is the scheme + host of the URL
curl -sfL --compressed --connect-timeout 5 --max-time 10 <probe-url> | grep -oE '<loc>[^<]+</loc>' | sed 's/<loc>//;s/<\/loc>//'

If the output is non-empty, the sitemap is found and the URLs are already extracted — skip the Extraction section entirely and go straight to Output. If empty, try the next probe.

Probe 3 — robots.txt (different format, two-step):

  1. {origin}/robots.txt — fetch and parse for Sitemap: lines, use the first match
curl -sfL --compressed --connect-timeout 5 --max-time 10 <origin>/robots.txt

If a Sitemap: line is found, use that URL and proceed to the Extraction section.

If none of the probes succeed, report an error to the user and stop:

Could not auto-discover a sitemap for <url>. Try providing the direct sitemap XML URL instead.

When a sitemap is discovered (not passed directly), print which URL was found before proceeding:

Sitemap found: <discovered-url>

Extraction

If URLs were already extracted during auto-discovery, skip this entire section. If a filter pattern ($1) is provided, apply it to the already-extracted URLs in memory — do not re-fetch.

Run the following bash command to extract URLs from the sitemap:

curl -sfL --compressed --connect-timeout 10 --max-time 30 <sitemap-url> | grep -oE '<loc>[^<]+</loc>' | sed 's/<loc>//;s/<\/loc>//'

If a pattern is provided, pipe the result through grep -E '<pattern>' to filter:

curl -sfL --compressed --connect-timeout 10 --max-time 30 <sitemap-url> | grep -oE '<loc>[^<]+</loc>' | sed 's/<loc>//;s/<\/loc>//' | grep -E '<pattern>'

If the curl command fails (non-zero exit code), report the error clearly to the user (e.g., "Failed to fetch sitemap: connection timed out" or "Failed to fetch sitemap: HTTP 404").

Output

  1. Count the extracted URLs to determine the total count
    • Report: "Found 47 URLs" or "Found 12 URLs matching pattern en"
  2. Display the URL list in a fenced code block. If there are more than 100 URLs, show only the first 50 and note the total count
  3. If no URLs matched, inform the user that no results were found
  4. If curl failed, report the error clearly (do not silently show "no results")

Never re-fetch: All URLs have already been fetched. If the user later asks to save the results to a file, use the Write tool with the already-displayed output. Never run curl again for the same sitemap.

Distill the current session into a handoff document so the next agent can resume cold.

Accuracy: verify before asserting

A handoff is only worth writing if the next agent can trust it and act without re-checking. That makes a wrong fact the worst possible output: a bad path, line number, or "done" claim sends a cold agent down a false trail and costs far more than the handoff ever saved. Silence is safer than a confident error.

Almost every wrong fact comes from one habit — writing from memory of the session instead of from the repo as it is now. After a long session, or once context has been summarized, recall of specifics gets lossy and the gaps fill with plausible-but-wrong detail. So before a concrete claim goes in, ground it.

Treat two kinds of statement differently:

  • Checkable facts — paths, symbol and function names, line numbers, commands, branch, commits, dirty files, and anything you describe as done. Confirm each against the repo as you write it: git status, git log --oneline -10, and git diff --stat for state; Read / Grep / Glob for paths and symbols. Don't transcribe these from memory. If you can't confirm one, it doesn't get asserted — drop it, or mark it (unverified) so the next agent knows to check.
  • Recollection and judgment — the plan, why a decision was made, your mental state, what worked and what didn't. These can't be verified against the repo, so write them plainly as recollection and resist inventing specifics to make them sound authoritative.

Drive Current Progress from git, not memory. The state of the repo — branch, what's committed, what's still dirty — is the part that most often turns out wrong, because it's written from recall at the end of a long session. So don't recall it. Run ${CLAUDE_PLUGIN_ROOT}/skills/handoff/scripts/repo_facts.sh first and paste its output as the factual base of Current Progress, then write the narrative around it. A "done" item with no matching commit or diff in that output is the single most common wrong part — demote it to "in progress" or mark it (unverified).

Prefer durable anchors to line numbers. Reference bar.ts → parseConfig() rather than bar.ts:40. Line numbers drift between sessions and are easy to misremember, so they age into wrong facts faster than anything else; reach for one only when it genuinely helps, and grep to confirm it as you write.

Do the review yourself before saving. Re-read the finished draft and recheck every concrete reference — each path, symbol, and line — against ground truth one last time: grep the path, confirm the symbol exists. This is the review you'd otherwise leave for the next agent to discover the hard way; doing it now is the whole point.

Hand "done" claims to fresh eyes. One blind spot survives your own review: the work you believe you finished. You wrote "implemented X" from the memory of doing it and you re-read it through that same memory, so a "done" that isn't rarely catches your eye — and it's the costliest fact to miss, since the next agent then builds on a foundation that isn't there.

So once the draft is saved, hand just this slice to a subagent that carries none of your session memory — its lack of any stake in the work being done is exactly what makes it useful here. Point it at the saved draft and have it check each completed claim in Current Progress against git diff and git log, returning for each one: supported, partial, or unsupported, with the commit hash or diff hunk as evidence. Keep its scope to done-claims only — it has no context to judge the plan, the decisions, or what you were thinking (that's yours to review), and paths and symbols you already confirmed yourself. Then demote anything it can't support to "in progress" or (unverified) and save again. Skip the step when Current Progress reports only in-progress or not-yet-started work — with no completed claim there is nothing to falsify, and a fresh agent earns its cost only when there is.

Arguments

$ARGUMENTS is an optional topic name (e.g., /handoff auth-refactor). Used for filename and frontmatter. If empty, infer from session context. If inference fails, ask via AskUserQuestion — never fall back to generic names like "untitled" or "session".

Setup (first invocation per project)

Check ${CLAUDE_PLUGIN_DATA}/config.json for a key matching the current working directory.

If missing, prompt via AskUserQuestion: "Where should handoff documents be saved? (relative path from project root, e.g., docs/handoff)". Save the answer:

{
  "<cwd>": {
    "handoff_path": "<user-provided-path>"
  }
}

Create the directory if it doesn't exist. On subsequent invocations, read config and skip setup.

Same-topic detection

Before writing, scan the configured handoff directory (flat only, no recursive) for .md files. Read YAML frontmatter of each and match by topic field.

If a match is found:

  • Read it for context (understand prior state)
  • Same date → overwrite in place
  • Different date → write new file first, confirm it exists, then delete old file

Never delete before a successful write. Never insert into or append to an existing document — always rewrite from scratch.

Output

Filename

YYYY-MM-DD-<topic>.md where topic is kebab-case.

Frontmatter

---
topic: <kebab-case-topic>
date: YYYY-MM-DD
---

Sections

Always present (this order):

  1. Goal — What we're trying to accomplish
  2. First Action — Single most immediate action when resuming. Must be actionable without reading any other section. Include a skill recommendation if one installed in this session fits (e.g., "run the TDD skill to add the missing test")
  3. Context — Mental state when pausing: what you were thinking, the plan, where your attention was
  4. Current Progress — What's done, read off the commits and working tree rather than memory (see Accuracy: verify before asserting above). Include uncommitted changes (git status / git diff --stat) if any

Conditional (include only when there's meaningful content):

  1. Decisions Made — Key decisions + rationale. Prevents re-debate
  2. What Worked — Successful approaches worth reusing. Include how you worked, not only what you built — a process that paid off (grilling the design before coding, tight commit cadence) is as reusable as a technical fix
  3. What Didn't Work — Failed approaches. Mark critical constraints with ⚠️. Include process lessons too — a working rhythm that dragged (confirming every line, too slow to commit) or misfired, so the next session can adjust instead of repeating it
  4. Blockers — What must be resolved before proceeding
  5. Next Steps — Remaining action items after First Action

Agent discretion (add when relevant):

  • Infrastructure State (running servers, env vars, ports)
  • Issues & Solutions (detailed issue breakdown)
  • Session Metrics (tokens, duration)
  • Any other context-specific section

Principles

  • Distill, don't copy — filter session noise. The handoff should be shorter and more structured than the conversation that produced it. Failed experiments, tangential discussions, and corrections belong in What Didn't Work (if informative) or nowhere.
  • Reference, don't duplicate — if a PRD, ADR, plan, commit, or diff already captures information, point to it by path. Duplicating creates staleness.
  • Rewrite, don't update — when continuing a topic, read the old handoff for context, then write fresh. Merging old + current into a new document from scratch produces better results than patching.
  • Verify, don't recall — confirm every checkable fact against the repo before it goes in. See Accuracy: verify before asserting — this is the difference between a handoff the next agent trusts and one it has to re-audit.

Secret Setup

Extract hardcoded secrets from CLAUDE.md, .mcp.json, and project config into a gitignored env file, then wire up a SessionStart hook to load them automatically via CLAUDE_ENV_FILE.

Secrets in CLAUDE.md and .mcp.json get committed to git, shared with collaborators, and cached in Claude's context. This skill moves them to a gitignored file and loads them through a hook or shell profile.

If the user passes scan-only, stop after Phase 1 (report findings without modifying anything).

Phase 1: Scan for secrets

Read references/detection-patterns.md for the full list of regex patterns and scan targets.

Run Grep with each pattern against the scan targets. Present findings in a table:

| # | File | Line | Type | Value (masked) |
|---|------|------|------|----------------|
| 1 | CLAUDE.md:42 | API Key | sk-...abc1 |
| 2 | CLAUDE.md:55 | DB URL | postgres://...@host/db |

Ask the user to confirm which items are actual secrets to extract. Some may be intentional examples or documentation — do not force extraction.

Phase 2: Variable mapping

For each confirmed secret, propose an environment variable name:

  • If the secret is already referenced by a known env var name in the project (e.g., DATABASE_URL in code), reuse that name.
  • Otherwise, derive a descriptive UPPER_SNAKE_CASE name from context.

Present the mapping and ask for confirmation. Mark the source so MCP secrets get handled differently in Phase 4:

| # | Source | Current value (masked) | Proposed env var |
|---|--------|----------------------|-----------------|
| 1 | CLAUDE.md | sk-...abc1 | OPENAI_API_KEY |
| 2 | CLAUDE.md | postgres://...@host/db | DATABASE_URL |
| 3 | .mcp.json | xoxb-...token | SLACK_TOKEN |

The user may rename variables or skip items. Wait for approval before proceeding.

Phase 3: Infrastructure setup

Each step checks for existing infrastructure and merges rather than overwrites.

Step 3.1: Determine env file location

Check if the project already has a gitignored env file:

for f in .env.local .env.secret .env .env.development.local; do
  git check-ignore "$f" 2>/dev/null && echo "FOUND: $f"
done
  • If a gitignored env file exists, propose appending to it.
  • If multiple exist, ask the user which one to use.
  • If none exist, ask the user where to create one (default: .env.local).

Step 3.2: Ensure gitignore coverage

git check-ignore -q "<chosen-file>" 2>/dev/null
echo $?  # 0 = ignored, 1 = NOT ignored

If not ignored, propose adding the filename to .gitignore. Show the exact line and ask for confirmation.

Step 3.3: Write the env file

  • If the file exists, append new variables (skip duplicates).
  • If not, create with a header comment.

Format:

# Claude Code secrets — loaded via SessionStart hook
# DO NOT commit this file to git
OPENAI_API_KEY=<paste-your-key-here>
DATABASE_URL=<paste-your-connection-string-here>

Tell the user to fill in actual values. Do NOT write real secret values — always use placeholders.

Step 3.4: Create the hook script

Read the template at assets/load-secrets.sh.template. Copy it to .claude/hooks/load-secrets.sh, replacing {{ENV_FILE_PATH}} with the actual relative path from Step 3.1.

Make it executable:

chmod +x .claude/hooks/load-secrets.sh

Step 3.5: Register the hook in settings.local.json

Read .claude/settings.local.json (create if missing). Merge the SessionStart hook entry:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/load-secrets.sh"
          }
        ]
      }
    ]
  }
}

Merging rules:

  • No file → create with only the hooks entry.
  • No hooks key → add it.
  • No SessionStart → add the array.
  • Existing SessionStart → append the new entry.

Step 3.6: Add deny rules

Add deny rules to .claude/settings.local.json to prevent Claude from reading the env file directly. Adjust paths to match the chosen env file (example uses .env.local):

{
  "permissions": {
    "deny": [
      "Read(.env.local)",
      "Bash(cat .env.local*)",
      "Bash(head .env.local*)",
      "Bash(tail .env.local*)",
      "Bash(less .env.local*)",
      "Bash(more .env.local*)"
    ]
  }
}

Merge with existing deny rules — do not remove existing entries.

Phase 4: Clean up source files

CLAUDE.md and config files

Replace each hardcoded value with the $ENV_VAR_NAME reference.

Before:

API_KEY: sk-1234567890abcdef

After:

API_KEY: $OPENAI_API_KEY  (loaded via SessionStart hook)

Add a brief note near the top of CLAUDE.md:

## Secrets

Environment variables are loaded automatically via SessionStart hook.
See `.claude/hooks/load-secrets.sh` for the loading mechanism.
Do not hardcode secrets in this file — use `$VAR_NAME` references.

MCP config files (.mcp.json)

MCP servers are spawned as separate processes when Claude Code starts — before SessionStart hooks run. This means MCP servers cannot receive env vars set via the SessionStart hook. They only inherit env vars already present in the parent shell environment.

Present the user with two options:

Option A (recommended for shared repos): Remove the hardcoded value from the env field. The user sets the env var in their shell profile (~/.zshrc or ~/.bashrc) instead. The MCP server inherits it from the parent process.

Before:

{
  "env": {
    "SLACK_TOKEN": "xoxb-actual-token"
  }
}

After:

{
  "env": {}
}

User adds to ~/.zshrc:

export SLACK_TOKEN="xoxb-actual-token"

Option B (simpler): Gitignore .mcp.json entirely. Secrets stay in the file but are not committed. Downside: MCP server configuration is no longer shared with collaborators.

Ask the user which option they prefer. If Option A, also add the env var to the .env.local file (as a reference, even though it won't be loaded via hook for MCP). Tell the user they must restart their shell and Claude Code for changes to take effect.

Phase 5: Verification

Test the hook script:

MOCK_ENV=$(mktemp)
CLAUDE_ENV_FILE="$MOCK_ENV" CLAUDE_PROJECT_DIR="$(pwd)" .claude/hooks/load-secrets.sh
echo "=== Loaded variable names ==="
cut -d= -f1 "$MOCK_ENV"
echo "=== Syntax check ==="
bash -n "$MOCK_ENV" && echo "OK" || echo "INVALID SHELL SYNTAX"
rm "$MOCK_ENV"

Expected output: one export VAR line per secret, and syntax check OK. Print names only: the env file may already hold real secrets, and printing values puts them into the conversation. If stderr shows load-secrets: skipping line N warnings, check the env file for malformed lines.

After verification, inform the user:

  1. Fill in actual values in the env file.
  2. The hook activates on the next session start (restart Claude Code or start a new session).
  3. Variables will be available as regular environment variables in Bash commands.
  4. Run /hooks to confirm the SessionStart hook appears.

Gotchas

  • Nested CLAUDE.md: Some projects have CLAUDE.md at multiple levels. Scan all of them, not just the root one.
  • settings.local.json is gitignored: Claude Code auto-gitignores this file. That is the correct place for hook registration and deny rules because they reference local file paths.
  • CLAUDE_ENV_FILE scope: Set only for SessionStart, Setup, CwdChanged, and FileChanged hooks; this skill uses SessionStart. The hook writes export lines to it, and Claude Code sources that file before each Bash command in the session.
  • Line ending safety: Always use Unix LF line endings in the hook script. CRLF causes command\r: not found errors.

Sync References

Pull latest from origin for all git repos under a target directory.

Setup

Config: ${CLAUDE_PLUGIN_DATA}/config.json

# Read config
cat "${CLAUDE_PLUGIN_DATA}/config.json" 2>/dev/null

# Write/update config
mkdir -p "${CLAUDE_PLUGIN_DATA}"
echo '{"default_path": "<path>"}' > "${CLAUDE_PLUGIN_DATA}/config.json"

On first run, if no config exists and no $ARGUMENTS path is given, ask the user which directory to sync and save it to config.

Execution

Resolve the target path in this order:

  1. $ARGUMENTS if provided
  2. default_path from config.json
  3. If neither exists, ask the user and save to config

Then run:

bash "${CLAUDE_SKILL_DIR}/scripts/sync.sh" <resolved-path>

Output the result as-is. If any repos failed, briefly note what went wrong.

Sponsors

Details

Marketplace
LeeJuOh/claude-code-zero
Source
plugins/toolbox
Category
Community

More from LeeJuOh/claude-code-zero

All 12