Beginner track10 min · Step 1 of 3

Installing gald3r

Gald3r is a folder you copy into your project. No npm install, no CLI tool to maintain, no account required. This tutorial walks through the full install — from clone to confirmed working setup.

Prerequisites

→Git installed and configured
→At least one AI coding tool (Cursor, Claude Code, Codex CLI, or Gemini CLI)
→A project you want to add gald3r to (can be empty or existing)

Clone the gald3r repository

First, clone gald3r somewhere on your machine. You'll copy files from it into your projects.

git clone https://github.com/wrm3/gald3r.git ~/gald3r

You only need to do this once. You can reuse this clone to install gald3r in multiple projects.

Identify the install type

Gald3r supports two install modes depending on how you work:

File copy (recommended for most)

Copy .gald3r/, .claude/, .cursor/ into your project. Full ownership, no symlinks.

Symlink (for gald3r developers)

Symlink the template folders. Changes to the gald3r source propagate automatically.

Note: This tutorial uses the file copy approach. If you're contributing to gald3r itself, the symlink approach keeps your clone in sync.

Copy the gald3r files into your project

Navigate into your project directory and copy the three folders:

cd /path/to/your/project

# Copy the core gald3r framework files
cp -r ~/gald3r/template_full/.gald3r ./.gald3r
cp -r ~/gald3r/template_full/.claude ./.claude
cp -r ~/gald3r/template_full/.cursor ./.cursor

On Windows (PowerShell):

cd C:\path\to\your\project

Copy-Item -Recurse "$env:USERPROFILE\gald3r\template_full\.gald3r" ".gald3r"
Copy-Item -Recurse "$env:USERPROFILE\gald3r\template_full\.claude" ".claude"
Copy-Item -Recurse "$env:USERPROFILE\gald3r\template_full\.cursor" ".cursor"

Run gald3r setup

Open your AI tool in this project directory and run:

@g-setup

The setup skill will initialize your .gald3r/ folder: creating PROJECT.md, TASKS.md, BUGS.md, PLAN.md, DECISIONS.md, and CONSTRAINTS.md with sensible defaults for your project.

Note: If your AI tool doesn't recognize @g-setup, make sure the .cursor/rules/ or .claude/commands/ folders were copied correctly in step 3.

Confirm the install

After setup completes, you should see these files in your project:

.gald3r/
├── PROJECT.md        ← edit this with your mission
├── TASKS.md          ← your task list (starts empty)
├── BUGS.md           ← bug index (starts empty)
├── PLAN.md           ← milestones
├── DECISIONS.md      ← audit trail
├── CONSTRAINTS.md    ← hard rules for agents
├── tasks/            ← individual task files go here
└── bugs/             ← individual bug files go here

If any of these are missing, rerun @g-setup or check that the copy in step 3 completed without errors.

(Optional) Add to .gitignore exclusions

Gald3r files should commit with your project. The only exception is if you have local overrides or secrets in your vault. By default, commit everything in .gald3r/.

If you use the Valhalla MCP server, add its local config to .gitignore:

echo ".gald3r/.env.local" >> .gitignore

Install complete ✓

Gald3r is installed. The next step is to fill in PROJECT.md and create your first task.