jtsternberg Publish Insights
Publish a Claude Code /insights report to GitHub Pages for easy sharing and access.
Prerequisites
- GitHub CLI (
gh) - Must be installed and authenticated. Verify withgh auth status. - Git - Must be installed.
If gh is not authenticated, prompt user to run gh auth login first.
Example Session
User: "Publish my insights report"
Claude:
- Found report at
~/.claude/usage-data/report.html - Detected GitHub user:
jtsternberg - Confirmed settings: repo
claude-insights, public visibility - Created repo and enabled Pages
- Published to: https://jtsternberg.github.io/claude-usage-data/
Workflow
Placeholders like
{username}and{repo}should be replaced with actual values gathered during pre-flight.
Copy this checklist and track progress:
Publishing Progress:
- [ ] Verify prerequisites
- [ ] Locate report file
- [ ] Pre-flight confirmation
- [ ] Initialize git repo (if needed)
- [ ] Copy report and create README
- [ ] Validate files
- [ ] Commit changes
- [ ] Create GitHub repo
- [ ] Push to GitHub
- [ ] Enable GitHub Pages
- [ ] Monitor deployment
- [ ] Verify and report success
Step 1: Verify Prerequisites
gh auth status
If not authenticated: Stop and ask user to run gh auth login first.
Step 2: Locate Report File
Check for the report file:
[ -f ./report.html ] && echo "Found: ./report.html" || \
[ -f ~/.claude/usage-data/report.html ] && echo "Found: ~/.claude/usage-data/report.html" || \
echo "Not found"
- Found in current directory: Use
./report.html - Found in default location: Use
~/.claude/usage-data/report.html - Not found: Ask user for the path, or suggest running
/insightsto generate one
Step 3: Pre-Flight Confirmation
Gather all inputs upfront. Get the GitHub username:
gh api user --jq '.login'
Present a confirmation checklist with defaults:
Publish to GitHub Pages:
- Report: {detected-path}
- GitHub user: {username}
- Repo name: claude-insights (default)
- Visibility: public
Confirm to proceed, or specify changes.
User confirms once; no per-step prompts after this.
Step 4: Initialize Git Repository
Check if already in a git repo:
git rev-parse --git-dir 2>/dev/null && echo "In git repo" || echo "Not in git repo"
- Not in a repo: Create a new directory and initialize:
mkdir -p {repo} && cd {repo} git init && git branch -M main - In an existing repo: Ask user if they want to use this repo or create a new directory
Step 5: Copy Report and Create README
Copy the report as index.html:
cp {report-path} ./index.html
Create a minimal README.md:
# Claude Code Usage Insights
Interactive dashboard of Claude Code usage patterns, generated with `/insights`.
**View the report:** https://{username}.github.io/{repo}/
## Generate Your Own
Run `/insights` in any Claude Code session, then use `/publish-insights` to publish it.
Step 6: Validate Files
Verify the report file is valid HTML:
head -5 index.html | grep -q "<!DOCTYPE html\|<html" && echo "Valid HTML" || echo "Warning: May not be valid HTML"
If invalid: Warn user and confirm whether to proceed.
Step 7: Commit Changes
git add index.html README.md
git commit -m "$(cat <<'EOF'
Add Claude Code usage insights report
Generated with Claude Code /insights command.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
Step 8: Create GitHub Repository
gh repo create {username}/{repo} --public --description "Claude Code usage insights report" --source=. --remote=origin
If repo already exists: Ask user to choose a different name or confirm using the existing repo. To use existing:
git remote add origin https://github.com/{username}/{repo}.git
Step 9: Push to GitHub
git push -u origin main
If push fails (non-empty repo): May need to pull first or force push. Ask user preference.
Step 10: Enable GitHub Pages
gh api repos/{username}/{repo}/pages -X POST --input - <<'EOF'
{
"build_type": "legacy",
"source": {
"branch": "main",
"path": "/"
}
}
EOF
If Pages already enabled: This will error; that's fine, continue to monitoring.
Step 11: Monitor Deployment
Inform user: "Deployment started. You can watch progress at: https://github.com/{username}/{repo}/actions"
Then poll for completion:
# Poll every 10 seconds - Pages builds typically complete in 30-60 seconds
# Shorter intervals waste API calls; longer delays feel unresponsive
while true; do
STATUS=$(gh api repos/{username}/{repo}/pages/builds --jq '.[0].status')
if [ "$STATUS" = "built" ]; then
echo "Build complete!"
break
elif [ "$STATUS" = "errored" ]; then
echo "Build failed!"
gh api repos/{username}/{repo}/pages/builds --jq '.[0].error'
break
fi
sleep 10
done
Step 12: Verify and Report Success
Verify the page loads (may take 1-2 minutes to propagate):
curl -s -o /dev/null -w "%{http_code}" https://{username}.github.io/{repo}/
If not 200: Wait 30 seconds and retry up to 3 times.
Report to user:
- Live URL:
https://{username}.github.io/{repo}/ - Repository:
https://github.com/{username}/{repo} - Confirmation that page returns HTTP 200
Rollback
If the process fails after creating the repo, clean up:
# Delete the remote repo (requires confirmation)
gh repo delete {username}/{repo} --yes
# Remove local git artifacts if desired
rm -rf .git index.html README.md