Claude Code Setup Wizard

Recent updates: PR-first git workflow, security protocol refinements, dev workflow automation, optional session timing, test infrastructure, and Codex CLI compatibility.

Choose Your Setup

---

About

As used to build Scribefully and FloodRoute my first-ever iOS app, in just 13 days!

I came up with this wizard (in its various flavors) to help me build Scribefully, FloodRoute, and several other projects I'm working on. Scribefully is a place for experts to create a beautiful portfolio of their best work -- articles, videos, code, podcasts, etc -- and share it in a Reddit-inspired community of other experts, thought leaders, academics, professionals, and creators. FloodRoute is the only app on the App Store that estimates foad flooding due to king tides.

Full Setup Wizard Details

---

⚠️ DISCLAIMER

💡 While the PROTOCOL file works great with Codex, I haven't test the SETUP file with Codex

USE AT YOUR OWN RISK - This project is provided "AS IS" without warranty of any kind, express or implied. The authors and contributors disclaim all warranties, including but not limited to:

• No Warranties: No warranties of merchantability, fitness for a particular purpose, or non-infringement
• No Liability: We are not liable for any damages, data loss, system failures, or other issues arising from use of this software
• User Responsibility: You assume full responsibility for testing, validation, and ensuring compatibility with your systems
• No Support Guarantee: No guarantee of maintenance, updates, or technical support
• Configuration Risk: Modifying system configurations may affect your development environment - backup your settings first

By using this software, you acknowledge that you understand these risks and agree to use it entirely at your own discretion and risk.

Features

• 3-file active system (~17KB total) — small enough to read at every session start
• Security protocols — .env* file protection with optional honeypot testing
• Session automation — defined start/end protocols for clean handoffs
• Searchable archive — institutional knowledge that doesn't get loaded into context unless searched
• PR-first git workflow — feature branches and gh pr create by default at session end
• Interactive setup — 12-question wizard customizes the system for your project

Security & Development Workflows

Built-in Security Protocols

• Environment Protection: Automatic .env* file protection with refusal to read secret files
• Honeypot Testing: Creates .env.honeypot to test Claude's security behavior
• Variable Safety: Server-only variables (SUPABASE_SERVICE_ROLE_KEY, RESEND_API_KEY) stay server-side
• Client Restrictions: Only NEXT_PUBLIC_* environment variables allowed in client code
• Runtime Guards: Prevents accidental secret exposure in diffs, logs, or shell commands

Development Commands

• npm run dev - Start development server with hot reloads
• npm run test:watch - Optional fast feedback with test re-runs on file changes
• npm run ci - Run full CI checks locally before push/PR
• npm run dev:all - Run both dev server and tests simultaneously

Note: Test infrastructure (package.json, Vitest configuration) included in Timer Bundle and generated by Setup Wizard. Protocols Only requires manual setup.

Automation & Git Hooks

• Pre-push automation: bash scripts/setup-git-hooks.sh auto-runs npm run ci before push
• Intelligent commits: session-end commits with structured messages
• PR-first workflow: feature branches push and open a PR via gh pr create --fill at session end; only trivial changes (docs typos, hotfixes) commit directly to main. The wizard asks before pushing when the path is ambiguous.

⏱️ Session Timing & Analytics (Option 2 Bundle)

Track development time across Claude sessions with built-in analytics:

Timer Commands (Run from repo root)

• Start: node scripts/session-timer.js start
• End: node scripts/session-timer.js end
• Status: node scripts/session-timer.js status
• Summary: node scripts/session-timer.js summary

Outputs

• Per-session meta: MD-ACTIVE/.session-meta.json
• Cumulative log: MD-ARCHIVE/reference/SESSION-TIMES.json
• Human summary: MD-ARCHIVE/reference/SESSION-TIMES.md

Integration

• Session durations automatically added to bookmarks and changelogs
• No external dependencies - pure Node.js
• Works with both local development and CI/CD workflows

Quick Start (Full Setup Wizard)

1. Install Claude code using npm install -g @anthropic-ai/claude-code
2. Intialize as always with /init
3. Download MD-CLAUDE-CODE-SETUP-WIZARD.md
4. Tell Claude: "Run @md-claude-code-setup-wizard.md"
5. Answer 12 setup questions
6. Start working: "read @MD-ACTIVE/" then "session start"

Usage & Best Practices after installation is complete

Session start: "read @MD-ACTIVE/ then initiate session start protocols per @MD-SESSION-PROTOCOL.md ⚠️ Confirm:

• Did it explicitly echo back the security instructions re: .envs and other secrets? If not, ask it to do so.
• You may need to manually fetch/pull the latest version to update your local reop.

Session end: initiate session end protocols per @MD-SESSION-PROTOCOL.md

What happens

Session Start Process:

1. Claude acknowledges security: "I will not open or read any .env* files. I will reference env by NAME only."
2. Claude reads MD-SESSION-PROTOCOL.md, latest session bookmark, and CHANGELOG-CURRENT.md in parallel
3. Claude echoes back: working relationship (CEO/CTO dynamics), current platform status, and today's priorities
4. Claude creates TodoWrite list from bookmark priorities
5. Claude auto-activates Technical Mastery Reference (ready for automatic searches)
6. Claude begins work on first task immediately

Session End Process:

1. Claude updates CHANGELOG-CURRENT.md if new version exists
2. Claude syncs changes to CHANGELOG-FULL.md in archive
3. Claude creates new session bookmark with big-picture summary (✅ COMPLETED, 🔄 IN PROGRESS, 🚫 BLOCKED)
4. Claude archives previous bookmark to MD-ARCHIVE/bookmarks/
5. Claude updates Technical Mastery Reference with new debugging patterns learned
6. Claude asks: "Ready to commit and open a PR? (y/n)"
7. If yes (PR-first, branch-aware):
   • On a feature branch (default): push the branch and open a PR with gh pr create --fill; return the URL and wait for your review. On confirmation, merge with gh pr merge --squash --delete-branch.
   • On main: only for trivial changes (hotfix, docs typo). Commit and push directly.
   • Ambiguous: Claude asks which path before pushing.
8. Claude confirms: Session complete: PR #N opened — [URL] or Session complete: [commit message] → pushed to main.

Security

• Automatic .env* file protection
• Creates .env.honeypot for testing Claude's refusal behavior
• Environment variable safety protocols (server vs client)
• Runtime guards prevent accidental secret exposure
• Keeps a running "CHANGELOG.md" in MD-ARCHIVE updated at every session end
• Keeps a truncated "CHANGELOG-CURRENT.md" in MD-ACTIVE ~300 lines long
• If created, will update a "technical mastery" MD file in MD-ARCHIVE to learn as you go
• Prompts before any commit/push at session end (PR-first by default)

What this solves

Sessions degrade when too much documentation gets pulled into context at once. This system:

• Keeps the active documentation small (~17KB across 3 files)
• Preserves full project history in a searchable archive that isn't loaded by default
• Reduces session auto-compacting and the context loss that comes with it
• Defines explicit start/end rituals so handoffs between sessions are predictable

Use at Your Own Risk

This software is provided "AS IS" without warranty. Users assume full responsibility for testing and ensuring compatibility with their systems. Backup your settings before use.