Gatorizing adds Gator to one of your repositories. You do it here in the Dashboard, in a few clicks. Then your first agent session builds the map.

The path at a glance

Addto the fleet
Gatorizefrom the row menu
Committhe new .gator/
First sessionpaste the prompt
Map builtcharters in Git

This Dashboard runs from the Gator CLI on your machine, so Gator is already installed. Each repository needs Gator added once.

1. Add the repository to your fleet

  1. Open Fleet in the sidebar.
  2. Click Add Repository.
  3. Gator scans common locations for Git repositories. Find yours under Repos found and click Add. If it is not listed, type its folder path and click Register.
  4. The repository appears in the Fleet table.

2. Gatorize it

Before you start

Commit or stash your work first. The Dashboard runs Gatorize without prompts, and Gatorize stops if the repository has uncommitted changes. For the cleanest undo, create a branch first, for example git checkout -b add-gator. Gatorize works on whatever branch is checked out.

  1. In the Fleet table, open the ⋮ menu at the end of the repository’s row.
  2. Choose Gatorize.
  3. Wait for the activity indicator on that row to finish. If Gatorize fails, the Dashboard shows the reason.
  4. The repository is governed. The same menu now offers Update when a newer Gator release is available.

3. What Gatorize does

Gatorize adds files in two places: inside the repository, and in a per-machine folder in your home directory. It does not change your source code or your commit history.

WhereWhat Gator addsCommitted?
.gator/
in the repository		 The knowledge layer. The constitution, procedures and reference notes go in .gator/.includes/. Starter mission.md, roadmap.md and inbox.md go at the root, with an empty charters/ folder for the first map. It also holds runtime-pin.json, the minimum Gator version that this repository’s governance needs. Yes you commit it
Git hooks
.git/hooks/		 Three small hooks that run the installed Gator CLI. pre-commit checks that charters change with the code. commit-msg builds the message from the commit draft and adds Gator-* trailers. post-commit resets the draft. On Windows they go in .git/gator-hooks/, and Gator points Git at that folder. No Git never commits .git/
Agent session hooks
.claude/ .codex/ .gemini/		 Gator session-hook entries in settings.json or hooks.json. Gator merges them in and keeps your existing entries. Yes
.gitignore Entries that keep Gator’s machine-local and sensitive files, such as .gator/vault/, out of Git. Your own rules stay as they are. Yes
~/.gator/
in your home folder		 Gator’s per-machine folder. It holds the Dashboard’s list of repositories, this machine’s identity, and local session records. Gatorize registers the repository here. No not part of any repository
What Gatorize leaves alone

Your source code, your existing commits, and your agent instruction files: CLAUDE.md, AGENTS.md, GEMINI.md. Gatorize also does not commit anything. Review the new files and commit them yourself, or ask your agent to do it in the first session.

4. Your first session

  1. Open a terminal in the repository root, the folder that contains .git.
  2. Start your coding agent there: Claude Code, Codex, Gemini CLI, Cursor, or another capable agent.
  3. Paste the session-opening prompt: 
    Run gator init in this repository. Treat its output, including the required session-opening reads, as binding. Do not provide a substantive response until those reads are complete.
    The Start a session with Gator tab has a button that copies it for you.
  4. The agent runs gator init. It then reads the Gator entry document, the constitution, and the mission, roadmap and inbox.
  5. The charters/ folder is empty, so the agent follows the bootstrap procedure. It asks what the project is and whether it is solo or team work. It looks for existing knowledge such as ARCHITECTURE.md, decision records or AI instruction files, and asks before it migrates any of it. It fills in mission.md and roadmap.md, finds the module boundaries (usually 3 to 8 charters), and writes the first charters, their index, and a cross-cutting charter for rules that span modules.
  6. Review the map and commit it. From now on, every session starts from the map.

The first session is an investment. The agent spends it reading your code so that later sessions do not have to. Read the charters it writes: they are the agent’s understanding of your system, and you can correct it before it guides any change.