Show HN: One Markdown File to Set Up Claude, Codex, Cursor and Copilot

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

5 Commits

5 Commits

.github

.github

docs

docs

.gitignore

.gitignore

AI_PROJECT_SETUP.md

AI_PROJECT_SETUP.md

CHANGELOG.md

CHANGELOG.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

Repository files navigation

Drop one file. Tell your AI to read it. Done.

A single 7,000-line markdown bootstrap that turns Claude Code, ChatGPT Codex CLI, Cursor, and GitHub Copilot into a disciplined teammate — 13-section rules, 5 safety hooks, session-resume, dual-write memory, and bilingual GitHub files. Zero install. One source of truth.

Fetch the bootstrap file

curl -fsSL https://raw.githubusercontent.com/kernalix7/ai-project-setup/main/AI_PROJECT_SETUP.md > AI_PROJECT_SETUP.md

Open your AI tool, then say:

"Read AI_PROJECT_SETUP.md and execute it."

"AI_PROJECT_SETUP.md 읽고 실행해줘"

1–3 minutes later, verify:

./tmp-igbkp/verify-setup.sh # → Pass: 83 Fail: 0 Warn: 0

Works with

English  ·  한국어  ·  Setup file  ·  Contributing  ·  Security  ·  Changelog

📌 Status: v5.2 stable

ai-project-setup ships a single-file bootstrap (AI_PROJECT_SETUP.md, ~7,600 lines) that any AI coding assistant reads and executes to produce a complete, multi-tool, gitignored AI tooling layout. v5.2 is the first polished GitHub repository release: expanded README, bilingual standard docs, issue/PR templates, and stricter no-footprint .gitignore. v5.1 moved the self-update source from a gist to this repository, so projects on v5.0 or earlier fetch v5.1 once from the legacy gist (frozen as a migration bridge), then all subsequent updates come from here. The artifact is idempotent and self-healing — re-running setup on an existing project repairs drift, force-overwrites stale shipped scripts with .bak backups, and preserves user content (CLAUDE.md sections 1–7 and 11, memory files, project agents).

One file, every AI tool. Drop AI_PROJECT_SETUP.md at your project root, tell the AI to read it, and in 1–3 minutes you have rules, hooks, session-resume, slash commands, default agents, a backup toolkit, and bilingual GitHub standard files — all gitignored so your project git history stays clean. Absolute Rule #19: AI tooling leaves zero footprint in your project's git history.

📑 Table of contents

Why this exists

Quick start

What gets created

Lifecycle

Key features

Supported AI tools

Comparison

Documentation

Self-update

Forking

FAQ

Roadmap

Star history

Support

License

🎯 Why this exists

Every new project, you re-do the same AI setup. This file does it once, deterministically, across multiple AI tools:

What you used to do every time What this file does automatically

Write CLAUDE.md / AGENTS.md / .cursorrules by hand ✅ 13 sections generated + 3-tool symlink sync

Block dangerous commands (rm -rf /, force push, secret leaks) ✅ Kernel-level PreToolUse hook

Set up session resume for /clear · crash · rate-limit ✅ 3-tier auto-save (current/handoff/recovery)

Configure memory · slash commands · default agents ✅ 10+ commands + 4 agents installed

Create README / SECURITY / CONTRIBUTING / CHANGELOG ✅ Bilingual EN/KO generation

Stop AI tool files from leaking into git history ✅ 22 .gitignore entries auto-applied

⚡ Quick start

One-liner (any git repository):

curl -fsSL https://raw.githubusercontent.com/kernalix7/ai-project-setup/main/AI_PROJECT_SETUP.md \ > AI_PROJECT_SETUP.md

Then open your AI tool and tell it to execute the file:

claude # or: codex, cursor ., or VS Code with Copilot

Tell the AI (English or Korean both work):

Read AI_PROJECT_SETUP.md and execute it.

AI_PROJECT_SETUP.md 읽고 실행해줘

Wait 1–3 minutes, then verify:

./tmp-igbkp/verify-setup.sh

→ Pass: 83 Fail: 0 Warn: 0 — All required checks passed

That's it. Everything created is gitignored — your project's git history stays clean.

📦 What gets created

your-project/ |-- CLAUDE.md -> symlink to .priv-storage/CLAUDE.md |-- AGENTS.md -> symlink to .priv-storage/CLAUDE.md # Codex / Copilot |-- .cursorrules -> symlink to .priv-storage/CLAUDE.md # Cursor |-- WORK_STATUS.md -> current work state (project content) | |-- .priv-storage/ [gitignored] all AI tooling lives here | |-- CLAUDE.md # 13-section project rules (~10kB cap) | |-- CLAUDE.local.md # per-developer overrides | |-- POST_SETUP_INDEX.md # 50-line pointer (saves ~25k tokens/session) | |-- AI_PROJECT_SETUP.md # archived, never re-read | |-- memory/ # dual-written to ~/.claude/projects/ (cross-machine sync) | |-- sessions/ # current.md, handoff-{date}.md, recovery.md, read-log.tsv | `-- .claude/ | |-- settings.json # statusLine + 5 hooks + outputStyle | |-- hooks/ # PreToolUse / PostToolUse / SessionStart / PreCompact / Stop | |-- agents/ # tech-lead, explorer, code-reviewer, log-analyzer | |-- commands/ # 10+ slash commands | |-- skills/ and rules/ # on-demand knowledge | |-- output-styles/terse.md | `-- statusline # context percent / rate-limit ETA | |-- tmp-igbkp/ [gitignored] backup and verification toolkit (9 scripts) | |-- verify-setup.sh # one-command health check (83+ assertions) | |-- smoke-test-hooks.sh # mock-payload hook validation | |-- secret-guard.sh # 14-pattern pre-commit scanner | |-- archive.sh / restore.sh # AES-256-CBC + PBKDF2 600k iterations | |-- purge-history.sh # git-filter-repo wrapper | |-- setup-worktree.sh # bridges worktrees to main .priv-storage/ | |-- codex-relay-{check,run}.sh # Claude Codex parallel lanes | `-- uninstall.sh # safe rollback with backup | |-- .mcp.json [gitignored] MCP server registry (env-var refs only) | |-- README.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md |-- docs/{README,SECURITY,CONTRIBUTING,CODE_OF_CONDUCT,CHANGELOG}.ko.md `-- .github/{ISSUE_TEMPLATE/,PULL_REQUEST_TEMPLATE.md}

Only WORK_STATUS.md, GitHub standard files, the docs/ Korean mirrors, and .github/ get committed. Everything inside .priv-storage/ and tmp-igbkp/ is gitignored by design.

🔄 Lifecycle

[1. INITIAL SETUP] Prompt: "Read AI_PROJECT_SETUP.md and execute it."

• Auto-detects Scenario A/B/C
• Creates everything above, then runs STEP 6
• Archives AI_PROJECT_SETUP.md into .priv-storage/
• Prints "Setup Complete" only if automode-validate.sh passes

| v

[2. NORMAL SESSIONS]

• SessionStart hook injects last handoff + current.md tail
• AI reads CLAUDE.md (~200 lines) + POST_SETUP_INDEX.md (~50)
• Does not re-read the 7000-line setup file, saving ~25k tokens/session
• PreToolUse blocks dangerous commands + oversized Reads
• PostToolUse appends to current.md + dual-writes memory
• Stop hook writes handoff-{date}.md
• PreCompact hook writes recovery.md (best-effort)

| v

[3. CRASH / RATE-LIMIT / /clear]

• Next session: SessionStart auto-loads handoff + recovery
• AI resumes without "where were we?" questions

| v

[4. SELF-UPDATE] Trigger: "update setup" or Korean "AI_PROJECT_SETUP 업데이트해"

• Fetches latest from GitHub raw URL
• Replaces archived setup file
• Force-overwrites all 30+ shipped scripts with .bak backup
• Re-runs automode-validate gate
• Reports: "Updated: vOLD -> vNEW. Recommend /clear."

Three setup scenarios

Scenario When What the AI does

A — existing .priv-storage/ exists or real CLAUDE.md at root Update/repair in place. Force-overwrite shipped scripts (with .bak), preserve user content.

B — empty/new No .priv-storage/, no CLAUDE.md at root Full setup from scratch — STEP 0 detection → STEPs 1–12 → archive.

C — broken Files at root that look like CLAUDE.md but aren't, or partial leftover state Detect, classify, convert to canonical layout, then bridge into A's STEPs 4–12.

✨ Key features

🛡️ Safety hooks (Claude Code)

PreToolUse blocks rm -rf /, force push, git add of gitignored AI files, eval, base64 | sh, curl http://, ~/.ssh reads, fork bombs

Blocks oversized Read (>1000 lines without offset/limit)

Blocks commit messages mentioning AI tooling

PostToolUse appends to sessions/current.md + dual-writes memory

SessionStart auto-loads last handoff + current.md tail + recovery

PreCompact writes recovery.md snapshot (best-effort)

Stop writes handoff-{date}.md + archives old handoffs

🔄 Resilience

3-tier session log: current.md (every call) → handoff-{date}.md (session end) → recovery.md (pre-compact)

Memory dual-write: every memory file mirrors to ~/.claude/projects/{path-encoded}/memory/ → new laptop restores instantly

Idempotent setup: SHA256 markers in .priv-storage/.setup-step-{N}.done

Force-overwrite of shipped scripts on every update (with .bak) — stale bugs auto-resolve

83+ assertion verify-setup.sh — single-command health check

smoke-test-hooks.sh fires each hook with mock payload

🤖 Default agents (token-efficient)

tech-lead — auto-evaluates complexity, forms teams (modules ≥ 2 OR files ≥ 5 OR cross-module work)

explorer — read-only codebase search, returns summaries, preserves main context window

code-reviewer — security/correctness/style review

log-analyzer — parses crash logs / hook-error logs

Subagent delegation MANDATORY above thresholds (>3 files, >500 lines, codebase-wide search)

⚡ Slash commands

/status — current task + recent activity summary

/health — runs verify-setup.sh + smoke-test-hooks.sh

/recover — load latest handoff + recovery into context

/ship — pre-commit secret-guard + clean check

/save — manual snapshot to current.md

/clean — rotate old handoffs, prune sessions

/codex-{brief,review,fix,relay-status} — Claude ↔ Codex parallel lanes

💰 Token discipline (Absolute Rule #20)

CLAUDE.md hard-capped at 16k chars (WARN) / 32k (FAIL)

PreToolUse BLOCKS Read of >1000-line files without offset/limit

Subagent delegation MANDATORY above thresholds

read-log.tsv flags duplicate Reads within a session

Auto-extends from terse → verbose only when reasoning is requested

Expected: 30–60% token reduction vs naive AI-pair-programming

🔐 Secret guard

14 regex patterns: AKIA…, ASIA…, sk-…, sk-proj-…, ghp_…, ghs_…, gho_…, glpat-…, xox[abprs]-…, sk_live_…, rk_live_…, AIza…, JWTs, -----BEGIN PRIVATE KEY-----

Special .mcp.json rule — env-var references only

Per-line # secret-guard:ignore allow-list for false positives

--install-hook mode wires into git pre-commit

AES-256-CBC + PBKDF2 600k for archived backups

🌏 Multi-tool parity

Same CLAUDE.md drives Claude Code, Codex CLI, Cursor, Copilot via symlinks

All three rule files (CLAUDE.md / AGENTS.md / .cursorrules) point to the same target — atomic updates

MCP servers registered via gitignored .mcp.json (env-var refs only)

VS Code settings symlinked for Copilot integration

Hooks are Claude Code-specific; other tools get policy-only enforcement

🔀 Cross-AI Codex relay (v4.9+, Claude Code only)

When codex CLI is on PATH, Claude offloads implementation to Codex while keeping planning/review authority

Flow: Claude (plan) → /codex-brief → Codex (implement) → Claude (/codex-review) → Codex (/codex-fix)

v5.0+ parallel per-agent relay lanes for TeamCreate work

Conflict prevention: disjoint allowed-paths per lane via paths_overlap check

Lockfiles in .priv-storage/sessions/codex-relay/locks/ + active.tsv ledger

🤝 Supported AI tools

Tool Min version Reads Hook support

Claude Code 2.0+ CLAUDE.md ✅ Full (5 hook events)

ChatGPT Codex CLI 0.10+ AGENTS.md → CLAUDE.md ❌ Policy-only

Cursor 0.40+ .cursorrules → CLAUDE.md ❌ Policy-only

GitHub Copilot 1.150+ AGENTS.md ❌ Policy-only

claude.ai (web) current upload CLAUDE.md ❌ Policy-only

Any MCP-aware tool — depends ❌ Policy-only

Policy-only = rules enforced via prompt content. No kernel-level block, but the AI follows them because they're in the rules file it reads.

⚖️ Comparison

This file .cursorrules only Custom CLAUDE.md Per-tool CLI tool

Single source of truth acro

[truncated for AI cost control]