{
  "markdown": "<div align=\"center\">\n  <img src=\"logo.svg\" alt=\"\" width=320>\n  <p><strong>gh-issue-sync: sync GitHub issues locally and back</strong></p>\n</div>\n\n`gh-issue-sync` is a command line tool that syncs GitHub issues to local\nMarkdown files for offline editing, batch updates, and integration with\ncoding agents.\n\nPull issues locally, refine them until you are satisfied, and sync changes\nback. Also useful for offline access to your issues.\n\n## Why?\n\nWhen refining many issues at once, editing them on GitHub can be tedious.\nIt is easier to make changes locally and push them all at once. This is\nparticularly useful when using Claude Code or similar tools to refine\nissues iteratively.\n\nAgents can work with issues locally until you are ready to push. The tool\nalso supports creating new issues locally with temporary IDs that get\nreplaced with real issue numbers after pushing.\n\n<div align=\"center\">\n  <a href=\"https://www.youtube.com/watch?v=ClTvgE-sFls\">\n    <img src=\"https://img.youtube.com/vi/ClTvgE-sFls/maxresdefault.jpg\" alt=\"Watch the demo video\" width=\"560\">\n  </a>\n  <p><em>Watch the demo video</em></p>\n</div>\n\n## Overview\n\n`gh-issue-sync` mirrors GitHub issues into a local `.issues/` directory as\nMarkdown files with YAML front matter.  Edit issues in your favorite editor,\ncreate new issues locally, and push changes back to GitHub when ready.\n\n## Installation\n\nPrerequisites:\n\n- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)\n- If you use Projects sync, refresh scopes with `gh auth refresh -s project`\n\n### Quick Install (macOS/Linux)\n\n```bash\ncurl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | sh\n```\n\n### Install with Go\n\n```bash\ngo install github.com/mitsuhiko/gh-issue-sync/cmd/gh-issue-sync@latest\n```\n\n### Download Binary\n\nDownload the latest binary from [GitHub Releases](https://github.com/mitsuhiko/gh-issue-sync/releases/latest) and place it in your PATH.\n\n### Build from Source\n\n```bash\ngit clone https://github.com/mitsuhiko/gh-issue-sync.git\ncd gh-issue-sync\ngo build -o gh-issue-sync ./cmd/gh-issue-sync\nmv gh-issue-sync ~/.local/bin/\n```\n\n## Quickstart\n\n```bash\n# Navigate to your project\ncd my-project\n\n# Initialize issue sync (auto-detects repo from git remote)\ngh-issue-sync init\n\n# Pull all open issues from GitHub\ngh-issue-sync pull\n\n# View your local issues\nls .issues/open/\n\n# Edit an issue\n$EDITOR .issues/open/123-fix-login-bug.md\ngh-issue-sync edit 123\n\n# Push your changes\ngh-issue-sync push\n\n# Or sync both ways (push then pull)\ngh-issue-sync sync\n```\n\n## Directory Location\n\nWhen you run `gh-issue-sync init`, the `.issues` directory is created next to\nthe `.git` directory (at the repository root), regardless of your current\nworking directory.\n\nFor other commands, `gh-issue-sync` searches for `.issues` by walking upward\nfrom the current directory until it finds one or reaches a `.git` root. This\nmeans you can run commands from any subdirectory within your project.\n\n### Environment Variable Override\n\nSet `GH_ISSUE_SYNC_DIR` to explicitly specify the `.issues` directory location:\n\n```bash\n# Use a custom location\nexport GH_ISSUE_SYNC_DIR=/path/to/my-project/.issues\ngh-issue-sync list\n\n# Or inline\nGH_ISSUE_SYNC_DIR=~/.issues/work-project gh-issue-sync pull\n```\n\nThis is useful when:\n- Working with multiple repositories\n- Storing issues outside the repository\n- Using a shared issues directory across projects\n\n## Agent Skill\n\nThis tool is designed to work with coding agents. Install the skill file so\nyour agent knows how to use `gh-issue-sync`:\n\n```bash\ngh-issue-sync write-skill --agent codex     # Codex\ngh-issue-sync write-skill --agent pi        # For Pi\ngh-issue-sync write-skill --agent claude    # Claude Code\ngh-issue-sync write-skill --agent opencode  # OpenCode\ngh-issue-sync write-skill --agent generic   # Amp and others\n```\n\nUse `--scope` to choose between user-level (default) or project-level installation:\n\n```bash\n# Install to user home directory (default)\ngh-issue-sync write-skill --agent codex --scope user\n\n# Install to current project directory\ngh-issue-sync write-skill --agent codex --scope project\n```\n\n| Agent | User Scope | Project Scope |\n|-------|------------|---------------|\n| `codex` | `~/.codex/skills/` | `.codex/skills/` |\n| `pi` | `~/.pi/skills/` | `.pi/skills/` |\n| `claude` | `~/.claude/skills/` | `.claude/skills/` |\n| `opencode` | `~/.config/opencode/skill/` | `.opencode/skill/` |\n| `amp`, `generic` | `~/.config/agents/skills/` | `.agents/skills/` |\n\nTo install to a custom location:\n\n```bash\ngh-issue-sync write-skill --output /path/to/skills/gh-issue-sync/\n```\n\nYou can also read or copy the skill file directly: [`skill/SKILL.md`](skill/SKILL.md)\n\n## Creating Local Issues\n\nSince issue numbers come from GitHub, you can use temporary issue numbers\nuntil then. `T42` or `TABC` are valid temporary issue IDs. They must start\nwith \"T\" to mark them as temporary. After syncing, they receive real numbers\nand all references are updated.\n\n### Sync Both Ways\n\nPush and pull in a single command:\n\n```bash\n# Push local changes, then pull remote updates\ngh-issue-sync sync\n\n# Include closed issues\ngh-issue-sync sync --all\n\n# Filter by label\ngh-issue-sync sync --label bug\n```\n\n## Sync Behavior\n\nThe tool uses three-way comparison (local, original, remote) to detect conflicts.\nOriginal versions are stored in `.issues/.sync/originals/`.\n\n| Local | Original | Remote | Action |\n|-------|----------|--------|--------|\n| Same | Same | Same | No action |\n| Changed | Same | Same | Push local changes |\n| Same | Same | Changed | Pull remote changes |\n| Changed | Same | Changed | **Conflict** - skip with warning |\n\n**On pull:** New issues are saved, unchanged local files are updated, conflicts\nare skipped (use `--force` to overwrite). Deleted local files are restored.\n\n**On push:** Local issues (T1, T2, etc.) are created and renamed with real numbers.\nReferences like `#T1` are updated automatically. Missing labels and milestones\nare created. Conflicts with remote changes are skipped.\n\n### List Issues\n\nList and filter local issues:\n\n```bash\n# List open issues\ngh-issue-sync list\n\n# Include closed issues\ngh-issue-sync list --all\n\n# Filter by label, assignee, author, milestone\ngh-issue-sync list --label bug --assignee alice\n\n# GitHub-style search query\ngh-issue-sync list --search \"error no:assignee sort:created-asc\"\n```\n\nThe `--search` flag supports GitHub issue search syntax:\n- `is:open`, `is:closed` - Filter by state\n- `label:NAME` - Filter by label\n- `no:label`, `no:assignee`, `no:milestone` - Filter by missing field\n- `assignee:USER`, `author:USER`, `milestone:NAME` - Filter by field\n- `sort:created-asc`, `sort:created-desc` - Sort results\n- Free text - Search in title and body (case-insensitive)\n\n### Check Status\n\nSee what's changed locally:\n\n```bash\ngh-issue-sync status\n```\n\n### Create New Issues\n\nCreate issues locally before pushing to GitHub:\n\n```bash\n# Create with a title\ngh-issue-sync new \"My new feature idea\"\n\n# Create and open in editor\ngh-issue-sync new \"Fix login bug\" --edit\n\n# Create with labels\ngh-issue-sync new \"Critical bug\" --label bug --label urgent\n\n# Create with just the editor (no title required)\ngh-issue-sync new --edit\n```\n\nLocal issues get temporary IDs like `T1`, `T2`. When pushed, they become real\nGitHub issues and files are renamed automatically.\n\n### Close and Reopen Issues\n\n```bash\n# Close an issue (marks for closing on next push)\ngh-issue-sync close 123\n\n# Close with a reason\ngh-issue-sync close 123 --reason not_planned\n\n# Reopen a closed issue\ngh-issue-sync reopen 456\n```\n\nAlternatively, move files manually:\n- Move from `open/` to `closed/` to close\n- Move from `closed/` to `open/` to reopen\n\n## Issue File Format\n\nSee [Issue Format](ISSUE_FORMAT.md) for details on file structure, front matter\nfields, and pending comments.\n\n## License and Links\n\n- [Skill File](skill/SKILL.md)\n- [Issue Tracker](https://github.com/mitsuhiko/gh-issue-sync/issues)\n- License: [Apache-2.0](https://github.com/mitsuhiko/gh-issue-sync/blob/main/LICENSE)\n\nThis code is entirely LLM generated. It is unclear if LLM generated code\ncan be copyrighted.\n",
  "bytes": 8165,
  "sha": "4e475a391234125c066625b117069604f0fc7d6f9ad51329056987f86e9eac60",
  "repo_slug": "mitsuhiko/gh-issue-sync",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_mitsuhiko_gh_issue_sync_gh_issue_sync_71e4de73/readme"
}