Skip to content
Back to search

gh-issue-sync

A github issue sync tool for working with issues locally

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mitsuhiko--gh-issue-sync/badge.svg)](/listings/mitsuhiko--gh-issue-sync)

HTML

<a href="/listings/mitsuhiko--gh-issue-sync"><img src="/api/listings/mitsuhiko--gh-issue-sync/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites:

- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`) - If you use Projects sync, refresh scopes with `gh auth refresh -s project`

Quick Install (macOS/Linux)

curl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | sh

Install with Go

go install github.com/mitsuhiko/gh-issue-sync/cmd/gh-issue-sync@latest

Download Binary

Download the latest binary from [GitHub Releases](https://github.com/mitsuhiko/gh-issue-sync/releases/latest) and place it in your PATH.

Build from Source

git clone https://github.com/mitsuhiko/gh-issue-sync.git
cd gh-issue-sync
go build -o gh-issue-sync ./cmd/gh-issue-sync
mv gh-issue-sync ~/.local/bin/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 287 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="logo.svg" alt="" width=320>
  3. <p><strong>gh-issue-sync: sync GitHub issues locally and back</strong></p>
  4. </div>
  5. `gh-issue-sync` is a command line tool that syncs GitHub issues to local
  6. Markdown files for offline editing, batch updates, and integration with
  7. coding agents.
  8. Pull issues locally, refine them until you are satisfied, and sync changes
  9. back. Also useful for offline access to your issues.
  10. ## Why?
  11. When refining many issues at once, editing them on GitHub can be tedious.
  12. It is easier to make changes locally and push them all at once. This is
  13. particularly useful when using Claude Code or similar tools to refine
  14. issues iteratively.
  15. Agents can work with issues locally until you are ready to push. The tool
  16. also supports creating new issues locally with temporary IDs that get
  17. replaced with real issue numbers after pushing.
  18. <div align="center">
  19. <a href="https://www.youtube.com/watch?v=ClTvgE-sFls">
  20. <img src="https://img.youtube.com/vi/ClTvgE-sFls/maxresdefault.jpg" alt="Watch the demo video" width="560">
  21. </a>
  22. <p><em>Watch the demo video</em></p>
  23. </div>
  24. ## Overview
  25. `gh-issue-sync` mirrors GitHub issues into a local `.issues/` directory as
  26. Markdown files with YAML front matter. Edit issues in your favorite editor,
  27. create new issues locally, and push changes back to GitHub when ready.
  28. ## Installation
  29. Prerequisites:
  30. - [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)
  31. - If you use Projects sync, refresh scopes with `gh auth refresh -s project`
  32. ### Quick Install (macOS/Linux)
  33. ```bash
  34. curl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  35. ```
  36. ### Install with Go
  37. ```bash
  38. go install github.com/mitsuhiko/gh-issue-sync/cmd/gh-issue-sync@latest
  39. ```
  40. ### Download Binary
  41. Download the latest binary from [GitHub Releases](https://github.com/mitsuhiko/gh-issue-sync/releases/latest) and place it in your PATH.
  42. ### Build from Source
  43. ```bash
  44. git clone https://github.com/mitsuhiko/gh-issue-sync.git
  45. cd gh-issue-sync
  46. go build -o gh-issue-sync ./cmd/gh-issue-sync
  47. mv gh-issue-sync ~/.local/bin/
  48. ```
  49. ## Quickstart
  50. ```bash
  51. # Navigate to your project
  52. cd my-project
  53. # Initialize issue sync (auto-detects repo from git remote)
  54. gh-issue-sync init
  55. # Pull all open issues from GitHub
  56. gh-issue-sync pull
  57. # View your local issues
  58. ls .issues/open/
  59. # Edit an issue
  60. $EDITOR .issues/open/123-fix-login-bug.md
  61. gh-issue-sync edit 123
  62. # Push your changes
  63. gh-issue-sync push
  64. # Or sync both ways (push then pull)
  65. gh-issue-sync sync
  66. ```
  67. ## Directory Location
  68. When you run `gh-issue-sync init`, the `.issues` directory is created next to
  69. the `.git` directory (at the repository root), regardless of your current
  70. working directory.
  71. For other commands, `gh-issue-sync` searches for `.issues` by walking upward
  72. from the current directory until it finds one or reaches a `.git` root. This
  73. means you can run commands from any subdirectory within your project.
  74. ### Environment Variable Override
  75. Set `GH_ISSUE_SYNC_DIR` to explicitly specify the `.issues` directory location:
  76. ```bash
  77. # Use a custom location
  78. export GH_ISSUE_SYNC_DIR=/path/to/my-project/.issues
  79. gh-issue-sync list
  80. # Or inline
  81. GH_ISSUE_SYNC_DIR=~/.issues/work-project gh-issue-sync pull
  82. ```
  83. This is useful when:
  84. - Working with multiple repositories
  85. - Storing issues outside the repository
  86. - Using a shared issues directory across projects
  87. ## Agent Skill
  88. This tool is designed to work with coding agents. Install the skill file so
  89. your agent knows how to use `gh-issue-sync`:
  90. ```bash
  91. gh-issue-sync write-skill --agent codex # Codex
  92. gh-issue-sync write-skill --agent pi # For Pi
  93. gh-issue-sync write-skill --agent claude # Claude Code
  94. gh-issue-sync write-skill --agent opencode # OpenCode
  95. gh-issue-sync write-skill --agent generic # Amp and others
  96. ```
  97. Use `--scope` to choose between user-level (default) or project-level installation:
  98. ```bash
  99. # Install to user home directory (default)
  100. gh-issue-sync write-skill --agent codex --scope user
  101. # Install to current project directory
  102. gh-issue-sync write-skill --agent codex --scope project
  103. ```
  104. | Agent | User Scope | Project Scope |
  105. |-------|------------|---------------|
  106. | `codex` | `~/.codex/skills/` | `.codex/skills/` |
  107. | `pi` | `~/.pi/skills/` | `.pi/skills/` |
  108. | `claude` | `~/.claude/skills/` | `.claude/skills/` |
  109. | `opencode` | `~/.config/opencode/skill/` | `.opencode/skill/` |
  110. | `amp`, `generic` | `~/.config/agents/skills/` | `.agents/skills/` |
  111. To install to a custom location:
  112. ```bash
  113. gh-issue-sync write-skill --output /path/to/skills/gh-issue-sync/
  114. ```
  115. You can also read or copy the skill file directly: [`skill/SKILL.md`](skill/SKILL.md)
  116. ## Creating Local Issues
  117. Since issue numbers come from GitHub, you can use temporary issue numbers
  118. until then. `T42` or `TABC` are valid temporary issue IDs. They must start
  119. with "T" to mark them as temporary. After syncing, they receive real numbers
  120. and all references are updated.
  121. ### Sync Both Ways
  122. Push and pull in a single command:
  123. ```bash
  124. # Push local changes, then pull remote updates
  125. gh-issue-sync sync
  126. # Include closed issues
  127. gh-issue-sync sync --all
  128. # Filter by label
  129. gh-issue-sync sync --label bug
  130. ```
  131. ## Sync Behavior
  132. The tool uses three-way comparison (local, original, remote) to detect conflicts.
  133. Original versions are stored in `.issues/.sync/originals/`.
  134. | Local | Original | Remote | Action |
  135. |-------|----------|--------|--------|
  136. | Same | Same | Same | No action |
  137. | Changed | Same | Same | Push local changes |
  138. | Same | Same | Changed | Pull remote changes |
  139. | Changed | Same | Changed | **Conflict** - skip with warning |
  140. **On pull:** New issues are saved, unchanged local files are updated, conflicts
  141. are skipped (use `--force` to overwrite). Deleted local files are restored.
  142. **On push:** Local issues (T1, T2, etc.) are created and renamed with real numbers.
  143. References like `#T1` are updated automatically. Missing labels and milestones
  144. are created. Conflicts with remote changes are skipped.
  145. ### List Issues
  146. List and filter local issues:
  147. ```bash
  148. # List open issues
  149. gh-issue-sync list
  150. # Include closed issues
  151. gh-issue-sync list --all
  152. # Filter by label, assignee, author, milestone
  153. gh-issue-sync list --label bug --assignee alice
  154. # GitHub-style search query
  155. gh-issue-sync list --search "error no:assignee sort:created-asc"
  156. ```
  157. The `--search` flag supports GitHub issue search syntax:
  158. - `is:open`, `is:closed` - Filter by state
  159. - `label:NAME` - Filter by label
  160. - `no:label`, `no:assignee`, `no:milestone` - Filter by missing field
  161. - `assignee:USER`, `author:USER`, `milestone:NAME` - Filter by field
  162. - `sort:created-asc`, `sort:created-desc` - Sort results
  163. - Free text - Search in title and body (case-insensitive)
  164. ### Check Status
  165. See what's changed locally:
  166. ```bash
  167. gh-issue-sync status
  168. ```
  169. ### Create New Issues
  170. Create issues locally before pushing to GitHub:
  171. ```bash
  172. # Create with a title
  173. gh-issue-sync new "My new feature idea"
  174. # Create and open in editor
  175. gh-issue-sync new "Fix login bug" --edit
  176. # Create with labels
  177. gh-issue-sync new "Critical bug" --label bug --label urgent
  178. # Create with just the editor (no title required)
  179. gh-issue-sync new --edit
  180. ```
  181. Local issues get temporary IDs like `T1`, `T2`. When pushed, they become real
  182. GitHub issues and files are renamed automatically.
  183. ### Close and Reopen Issues
  184. ```bash
  185. # Close an issue (marks for closing on next push)
  186. gh-issue-sync close 123
  187. # Close with a reason
  188. gh-issue-sync close 123 --reason not_planned
  189. # Reopen a closed issue
  190. gh-issue-sync reopen 456
  191. ```
  192. Alternatively, move files manually:
  193. - Move from `open/` to `closed/` to close
  194. - Move from `closed/` to `open/` to reopen
  195. ## Issue File Format
  196. See [Issue Format](ISSUE_FORMAT.md) for details on file structure, front matter
  197. fields, and pending comments.
  198. ## License and Links
  199. - [Skill File](skill/SKILL.md)
  200. - [Issue Tracker](https://github.com/mitsuhiko/gh-issue-sync/issues)
  201. - License: [Apache-2.0](https://github.com/mitsuhiko/gh-issue-sync/blob/main/LICENSE)
  202. This code is entirely LLM generated. It is unclear if LLM generated code
  203. can be copyrighted.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.