Sets up git version control in your CRAFT project folder
The AI checks whether git is already configured, initializes a repository if needed, sets your identity, creates a CRAFT-aware .gitignore, makes an initial commit, and optionally connects a GitHub remote — all idempotent, so running it twice won’t break anything.
Cowork Git Initialization
Tags: Introduced in Beta, Git, Version Control, Safety, Initialize, Cowork, Essential, Workspace Setup
TL;DR
What It Does
Sets up git version control in your CRAFT project folder. The AI checks whether git is already configured, initializes a repository if needed, sets your identity, creates a CRAFT-aware .gitignore, makes an initial commit, and optionally connects a GitHub remote — all idempotent, so running it twice won’t break anything.
How It Works
The AI runs git commands directly in your workspace folder. It detects existing git state first — if a repo already exists, it reports the current status and asks whether to skip or update the configuration. For new repos, it initializes on the main branch, auto-detects your name and email from project context, writes a .gitignore that excludes sensitive files and OS artifacts, and commits all project files. If you provide a GitHub URL, it configures the remote and can push with a Personal Access Token that gets scrubbed immediately after use.
What To Expect
A clean git repository in under 5 minutes. The AI will confirm branch name, commit hash, identity, remote status, .gitignore presence, and total tracked file count. If anything needs your input (email address, whether to push), it will ask before proceeding.
Best Results When You
Run this early in your project — ideally right after session initialization (CWK-001) creates your project structure. Having your project files in place before git init means the initial commit captures a complete baseline.
Typical Time
2–5 minutes (remote setup with push adds 1–2 minutes).
Difficulty
Beginner — the AI handles all git commands. You just confirm identity and optional remote settings.
How To Start
Run this recipe after your CRAFT project structure exists in the workspace folder. The recipe is idempotent — safe to run on an already-initialized repo.
STEP 1Tell the AI to Initialize Git
Provide the directive with optional parameters. If you have a GitHub repository URL ready, include it now. Your name and email can be auto-detected from project context, or you can specify them explicitly.
Available parameters
-
github_repo_url
· string · optional
GitHub remote URL (e.g., “https://github.com/Org/Repo.git”). If omitted, the repository stays local-only. You can add a remote later by running this recipe again with the URL. -
user_name
· string · optional
Git user.name for commits. If omitted, auto-detected from your project’s ABOUT_ME configuration. -
user_email
· string · optional
Git user.email for commits. If omitted, auto-detected from project context. The AI will ask if it cannot detect one.
Example invocations
Local only (no remote)
#H->AI::Directive: (Initialize git in workspace folder)
With GitHub remote
#H->AI::Directive: (Initialize git in workspace folder with remote https://github.com/MyOrg/my-project.git)
With explicit identity
#H->AI::Directive: (Initialize git in workspace folder with user_name "Jane Smith" and user_email "jane@example.com")
STEP 2Review the Git Status Report
The AI checks for an existing repository. If git is already initialized, it reports the current branch, last commit, and remote status, then asks whether to skip initialization or update the configuration. For new repos, it proceeds automatically.
STEP 3Confirm Identity and .gitignore
The AI configures your git identity and creates a .gitignore tailored to CRAFT projects — excluding sensitive files (.env, tokens, keys), OS artifacts (.DS_Store), temporary files, and Cowork VM artifacts. If a .gitignore already exists, it is preserved.
STEP 4Verify the Initial Commit and Optional Push
The AI stages all project files and creates an initial commit. It reports the commit hash and file count. If you provided a GitHub URL, it asks whether to push now — you will need a Personal Access Token. The token is used once and scrubbed from the remote URL immediately after the push completes.
Usage Examples
Two scenarios showing git initialization — one for a new local project, and one connecting an existing project to GitHub.
Example 1 · First-time local initialization
User:
#H->AI::Directive: (Initialize git in workspace folder)
AI:
Checking for existing git repository. No git repo found. Initializing new repository on branch main. Configuring identity: Richard <rich.ketelsen@gmail.com> (detected from project context). Creating .gitignore with CRAFT defaults. Staging 47 files. Initial commit created.
User:
Looks good.
AI:
Git initialization complete. Branch: main. Commit: a1b2c3d. Identity: Richard <rich.ketelsen@gmail.com>. Remote: none (local only). 47 files tracked. Run this recipe again with a GitHub URL to add a remote.
[Repository ready for checkpoints via CWK-005]
Example 2 · Adding a GitHub remote to an existing repo
User:
#H->AI::Directive: (Initialize git in workspace folder with remote https://github.com/CRAFTFramework/CFT-PROJ-CP-068.git)
AI:
Git already initialized. Branch: main. Last commit: “H003 session close artifacts” (2 hours ago). 12 commits, no uncommitted changes. Remote not configured. Adding origin. Push to GitHub? You will need a Personal Access Token.
User:
Yes, here is the token: ghp_xxxxxxxxxxxx
AI:
Pushing to origin/main. Success — 12 commits pushed. Token scrubbed from remote URL. Remote: configured (https://github.com/CRAFTFramework/CFT-PROJ-CP-068.git).
[Remote connected; future pushes via CWK-005]
How AI Reads This Recipe
When this recipe is triggered, the AI acts as a git setup assistant that runs shell commands in the workspace. The AI should:
- CHECK for an existing git repository using git status before making any changes.
- REPORT existing state (branch, last commit, remote) if a repo is found, and ASK whether to skip or update configuration.
- INITIALIZE with git init and rename the default branch to main if no repo exists.
- AUTO-DETECT user name and email from the project’s ABOUT_ME field or CLAUDE.md context before asking the user.
- CREATE a .gitignore with CRAFT-specific exclusions only if one does not already exist — never overwrite an existing .gitignore.
- STAGE all files and create an initial commit with a descriptive message that includes the project ID and a Co-Authored-By line.
- CONFIGURE the GitHub remote only when a URL is provided, and SCRUB the Personal Access Token from the remote URL immediately after a successful push — never leave credentials in git config.
The AI should NOT skip the existing-repo check even when the user says “initialize.” Idempotency is a core design principle — running this recipe on an already-initialized repo must not corrupt state. The token scrub after push is a security requirement, not optional.
When to Use This Recipe
Use this recipe when you:
- Start a new CRAFT project and need version control from the beginning.
- Have an existing CRAFT project folder that is not yet under git.
- Need to connect a local CRAFT repository to a GitHub remote for the first time.
- Want to verify or update the git identity configured for your project.
- Are setting up a project on a new device and need to re-establish the git configuration.
Do not use this recipe when:
You already have a fully configured git repository with the correct identity, .gitignore, and remote. In that case, CWK-005 (Git Checkpoint) is the recipe you need for ongoing commits and pushes. This recipe is for initial setup, not daily operations.
Recipe FAQ
Q.What if I already have a git repo in this folder?
The recipe detects existing repos automatically. It reports the current state and asks whether to skip or update. It will not re-initialize or destroy commit history.
Q.Will this overwrite my existing .gitignore?
No. If a .gitignore already exists, the recipe preserves it and moves on. It only creates one when none is present.
Q.What happens to the Personal Access Token after push?
The token is embedded in the remote URL only for the duration of the push. Immediately after the push completes, the AI rewrites the remote URL to the clean HTTPS form, removing the token entirely. The token is never stored in any file.
Q.Can I add a remote later if I skip it now?
Yes. Run this recipe again with the github_repo_url parameter. The existing repository, identity, and commit history are preserved — the recipe only adds the remote configuration.
Q.What branch does this create?
The main branch. If git defaults to a different branch name, the recipe renames it to main immediately after init.
Q.Does this recipe handle SSH remotes?
The recipe is designed for HTTPS remotes with Personal Access Token authentication. SSH remote configuration is outside scope — set that up manually if needed.
Q.What files does the .gitignore exclude?
Sensitive files (.env, tokens, keys, credentials), OS artifacts (.DS_Store, Thumbs.db), temporary files (.tmp, .bak, ~), and Cowork VM artifacts (.claude/). The pattern is tailored to CRAFT project structure.
Version History
Changes to this recipe over time. Most recent first.
v1.01a
2026-03-10
Added Co-Authored-By line to initial commit message template. Clarified token scrub as immediate post-push action. Minor description tightening.
v1.00a
2026-02-28
Initial release. Git init, identity config, .gitignore creation, initial commit, optional GitHub remote with token-based auth and post-push scrub.
Get this recipe with CRAFT for Claude Cowork
Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.
Pull anytime to stay on the latest version — free to clone, no login or email required.
Then start your session
Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:
You
Please initialize my CRAFT session.
Claude
CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?
Not familiar with Git? Download as a ZIP
No command line needed. Just download, move, and unzip:
- Open the CRAFT framework repo on GitHub.
- Click the green Code button, then choose Download ZIP.
- Move the downloaded ZIP into your Claude Cowork project folder.
- Unzip it: double-click on Mac, or right-click → Extract All on Windows.
