repo-rename
Preview or rename a GitHub upstream repo and matching local project folder, update origin, and preserve Codex CLI and Claude Code continuity references.
SKILL.mdskills/repo-rename/SKILL.md
GitHubRepo Rename
If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that case, do not invoke this skill again through a skill tool.
Preview the complete GitHub, Git, filesystem, and agent-continuity mutation set before applying a repository rename.
Scope
- Rename the current GitHub repository, matching local folder, and
originURL. - With two path arguments, move the source repository to the destination without changing its name, GitHub identity, or
origin. Both paths must have the same folder name. Preview missing parent directories before creating them. - If the repository has no Git remotes, rename only local state: the folder, continuity references, and repository
content. The helper then skips the GitHub rename and the
originupdate. A repository with any remote still requires a valid GitHub context. - Only when the repository has an active Claude Code or Codex transcript, update literal old paths in
~/.claude/projects,~/claude/projectswhen present,~/.codex/sessions, and~/.codex/config.toml. This continuity update does not apply to repos with no active transcripts. - Update constrained literal old-name references inside the repository, excluding VCS, dependencies (including Python virtual environments), caches, and generated build directories.
- For a same-name move, replace only the old absolute repository path inside repository files.
- By default, use tracked repository files and skip
PROMPT.md,TODO.md, and symlinks before reading replacement candidates. Prune excluded directories during discovery. When the user explicitly authorizes updating notes, dependencies, caches, or generated files, pass--include-local-stateto both preview and apply. This includes those repository text files while preserving file permissions. Symlinks, binary files, and.gitremain excluded. - The helper honors
CLAUDE_CONFIG_DIRandCODEX_HOME, gates continuity updates on active transcripts, and replaces only the absolute repository path in continuity stores and Codex config. - Do not modify other transcript stores, archives, remotes, or repositories.
Workflow
Resolve the source repository from the first of two path arguments, or from the current directory for a rename. Check whether it has any active AI chat transcript before treating continuity preservation as in scope:
- Claude Code: resolve
${CLAUDE_CONFIG_DIR:-~/.claude}/projects/<encoded-repo-path>(the absolute repo path with every non-alphanumeric character replaced by-) and check it exists and is non-empty. - Codex: resolve
${CODEX_HOME:-~/.codex}/sessionsand check whether any session file references the exact absolute repo path. - If neither exists, state that the transcript-continuity update does not apply. In that case, the rename may still proceed for the GitHub, git, filesystem, and repository-content changes below.
- Claude Code: resolve
Resolve the skill directory and run the helper from the repository to produce a read-only preview:
uv run <skill-dir>/scripts/repo-rename.py <new-name> --dry-runFor a same-name move, run from any directory:
uv run <skill-dir>/scripts/repo-rename.py <source-path> <destination-path> --dry-runThe helper requires a clean worktree, matching GitHub repo/folder names, a free target path, and valid GitHub context. For a repository with no remotes, it requires only a clean worktree and a free target path. It reports
"local_only": trueand alocal:<old>-><new>confirmation token. It prints the old/new repo and paths, exact confirmation token, external commands, directory moves, every replacement file, occurrence counts, and rollback coverage. Same-name moves usemove:<absolute-source>-><absolute-destination>tokens. Linked worktrees and external Git directories are unsupported.If
--dry-runwas requested, return the preview and stop. A successful dry run must not change the GitHub repo, remote, folder, config, transcripts, or repository files.Otherwise present the complete preview and require explicit confirmation in a subsequent user message. Explain that the confirmation authorizes the GitHub rename, local folder move, Claude project-folder move when enabled, origin update, and every listed continuity/repository replacement. For a local-only preview, state that no GitHub or
originchange occurs. Lead with### ⚠️ Rename preview — no changes made. Show GitHub, folder, origin, replacement counts, and rollback coverage in compact tables, then the exhaustive file/count list. Put the exact confirmation token alone in code formatting. If any preview fact changes, regenerate it and ask again.For same-name moves, show the unchanged GitHub identity and
origin, plus each parent directory to create.After confirmation, pass the preview's exact token:
uv run <skill-dir>/scripts/repo-rename.py <new-name> --apply --confirm '<owner/old->owner/new>'For a same-name move, pass both paths and the preview's
move:token instead.The helper re-runs preflight, backs up every replacement file, applies deterministic literal replacements, and attempts rollback on failure. Never bypass its clean-tree, target-path, or confirmation checks.
Verify the helper's result with
gh repo view,git remote get-url origin,pwd -P, and a search for remaining old absolute-path/name references in the listed scope. Report intentional remaining matches separately.
Completion
Dry-run completion is a full mutation preview with zero writes. Apply completion requires the new GitHub identity,
folder, remote, and listed continuity references to agree, plus a clean verification report. If rollback is incomplete,
stop and lead with ### ⛔ Rollback incomplete, then report every failed rollback action before doing anything else. On
success, use ### ✅ Repository renamed and a surface/expected/verified table. Keep helper JSON, confirmation tokens,
commands, paths, URLs, and rollback errors exact and undecorated.