issync

issync

CLI tool to sync text between GitHub Issue comments and local files, enabling AI-driven development workflows.

Overview

issync allows AI agents to maintain living documentation (like plan.md) in GitHub Issues as a single source of truth. Multiple local sessions (git worktrees, Devin, Claude Code, etc.) can read and write to the same document concurrently without git conflicts.

Core Features:

• Transparent to AI agents: AI coding agents use normal file operations, issync handles sync in background
• Conflict detection: Hash-based optimistic locking prevents data loss
• Watch mode: Automatic bidirectional sync between local files and GitHub Issue comments
• Safety checks: 3-way comparison on watch startup prevents accidental overwrites

Installation

npm install -g @mh4gf/issync

Requirements:

• Node.js >= 18.0.0
• GitHub Personal Access Token with repo scope

Quick Start

1. Set up GitHub token

export GITHUB_TOKEN=$(gh auth token)  # Using GitHub CLI
# or
export GITHUB_TOKEN=ghp_your_token_here

2. Initialize sync

# Link a GitHub Issue to a local file
issync init https://github.com/owner/repo/issues/123 --file docs/plan.md

# Create from template
issync init https://github.com/owner/repo/issues/123 --file docs/plan.md --template template.md

3. Start watch mode

⚠️ IMPORTANT: Always start watch mode BEFORE editing files

issync watch

# With custom polling interval (default: 60s)
issync watch --interval 10

4. Edit files normally

AI agents and editors can now read/edit the file normally. issync automatically syncs changes.

Commands

issync init <issue-url>

Initialize sync for a GitHub Issue.

issync init https://github.com/owner/repo/issues/123 --file docs/plan.md

Options:

• --file <path>: Local file path (default: .issync/docs/plan-{issue-number}.md)
  • Example: For issue #123, the default will be .issync/docs/plan-123.md
  • This allows tracking multiple issues without file name conflicts
• --template <path>: Create file from template if it doesn't exist

Behavior:

• Detects existing issync-managed comments on the Issue and pulls the content
• Creates a new file from template if no existing comment is found
• Config is stored in your home directory (global configuration)

issync pull

Pull remote changes from GitHub Issue comment to local file.

issync pull

# Select specific sync target
issync pull --file docs/plan.md
issync pull --issue https://github.com/owner/repo/issues/123

Options:

• --file <path>: Select sync target by local file path
• --issue <url>: Select sync target by issue URL

issync push

Push local changes to GitHub Issue comment.

issync push

# Force push (skip optimistic lock check)
issync push --force

# Select specific sync target
issync push --file docs/plan.md
issync push --issue https://github.com/owner/repo/issues/123

Options:

• --file <path>: Select sync target by local file path
• --issue <url>: Select sync target by issue URL
• --force: Skip optimistic lock check and force overwrite remote changes
  • ⚠️ WARNING: Concurrent remote changes will be permanently lost
  • Displays warning and asks for confirmation before execution
  • Use cases:
    • Resolving conflicts when you're certain local version is correct
    • Recovering from corrupted remote state
  • Similar to git push --force
  • Best practice: Always verify remote content before using this option

Example workflow with force:

# 1. Check remote content first
issync pull

# 2. Review the changes
cat docs/plan.md

# 3. If local is correct and you want to overwrite remote
issync push --force

issync open

Open the GitHub Issue in your browser for a synced file.

# Open issue (auto-select if only one sync)
issync open

# Select specific sync target
issync open --file docs/plan.md
issync open --issue https://github.com/owner/repo/issues/123

Options:

• -f, --file <path>: Select sync target by local file path
• --issue <url>: Select sync target by issue URL

Behavior:

• Opens the GitHub Issue URL in your default browser
• Platform-specific browser commands:
  • macOS: open
  • Linux: xdg-open
  • Windows: start
• When only one sync exists: Opens immediately
• When multiple syncs exist: Requires --file or --issue option

issync watch

Start watch mode (foreground process, press Ctrl+C to stop).

issync watch

# Custom polling interval (default: 30s)
issync watch --interval 10

# Select specific sync target
issync watch --file docs/plan.md
issync watch --issue https://github.com/owner/repo/issues/123

Options:

• --interval <seconds>: Polling interval in seconds (default: 30, min: 1, max: 3600)
• --file <path>: Select sync target by local file path
• --issue <url>: Select sync target by issue URL