AI Issue Publisher

Stop losing good AI ideas in chat history.

Turn AI conversations into GitHub Issues with one command.

AI Issue Publisher converts AI-generated markdown from ChatGPT, Claude, Muse, Grok, and DeepSeek into GitHub Issues.

The AI writes the idea. Humans decide whether it becomes work.

---

Installation

Homebrew (Recommended)

brew install replworks/tap/ai-issue

Debian / Ubuntu

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://apt.repl.net/replworks.gpg | sudo tee /etc/apt/keyrings/replworks.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/replworks.gpg] https://apt.repl.net stable main" | sudo tee /etc/apt/sources.list.d/replworks.list
sudo apt update
sudo apt install ai-issue

The Debian package installs git and one supported clipboard utility (xclip, xsel, or wl-clipboard) as dependencies. xdg-utils is recommended for opening the GitHub device-login page automatically.

Go

go install github.com/replworks/ai-issue/cmd/ai-issue@latest

Verify installation:

ai-issue diagnose

Linux requirements

Linux builds are provided for amd64 and arm64. The publish command reads the clipboard, so a desktop Linux environment must provide one of these clipboard utilities:

• X11: xclip or xsel
• Wayland: wl-clipboard (wl-copy and wl-paste)

xdg-open is used to open the GitHub device-login page automatically. If it is not available, the URL is still printed and can be opened manually.

---

Configuration

Why not just a Personal Access Token?

A PAT is the obvious first choice, and it works — until you need to publish to more than one organization.

A PAT is tied to a specific authorization for the account that created it. Using it across multiple organizations means separately authorizing (or getting admin approval for) that PAT in each one, and re-doing that dance every time you add a new org. It works for a single repo or a single org, but it doesn't scale past that.

AI Issue Publisher instead authenticates with a GitHub App user access token via device flow. The token represents the GitHub account that authorizes the app, and GitHub attributes API activity to that account and the app.

• You log in once with the GitHub account you want to use for publishing.
• To add a new organization, install the app there and give that same account access — no new token or per-organization PAT approval is required.
• The GitHub account remains the Issue opener; ai-issue records the selected AI source in the Issue body.

The trade-off: setup has two moving parts (the app installation and the account's access) instead of one PAT. In exchange, adding a new organization is a short checklist instead of a new credential to manage.

One-time setup

1. Choose the GitHub account that will authorize publishing. This can be your normal GitHub account. A separate bot account is optional, not required. The account used during device flow authorization is the account GitHub records as the Issue opener.

2. Log in with that account.

   ai-issue login

This will:

• open the GitHub device login page
• show you an 8-digit code to enter
• save the resulting token locally after you authorize the app

The token is stored at os.UserConfigDir()/ai-issue/token:

OS	Path
macOS	~/Library/Application Support/ai-issue/token
Linux	~/.config/ai-issue/token
Windows	%AppData%\ai-issue\token

Per-organization setup

Repeat both steps for every organization or repository you want to publish to — missing either one will cause it to fail:

1. Install the GitHub App: https://github.com/apps/ai-issue/installations/new

   You can install it on all repositories or select specific ones.

2. Give the publishing account write access. The account used during one-time setup needs its own access to the target repo — the app user token acts on behalf of this account, so installing the app alone is not enough. Either:

   • add it as an organization member with write access, or
   • add it as an outside collaborator on the specific repo

   Private repositories require this step explicitly: installing the app alone does not grant the publishing account any visibility. Invite the account from the repository page (Settings → Collaborators → Add people) with Write role, have the account accept the invitation, then run ai-issue diagnose to confirm Write OK.

   If the organization enforces SSO, also authorize the account for SSO access; if app installation requires admin approval, complete that too.

Why both are required:

flowchart LR
    subgraph Org["Target Organization"]
        A[GitHub App installed?]
        B[Publishing account has repo access?]
    end
    A -->|No| F1[❌ Fails:<br/>app has no access]
    B -->|No| F2[❌ Fails:<br/>account has no access]
    A -->|Yes| C{Both yes?}
    B -->|Yes| C
    C -->|Yes| S[✅ ai-issue works]

Loading

See Troubleshooting if you hit Resource not accessible by app token after completing these steps.

---

Usage

Copy AI-generated markdown to your clipboard and run:

ai-issue

Preview only:

ai-issue --dry-run

Diagnostics:

ai-issue diagnose

---

Example

AI Output

# Add timestamps to logging system

Current logs do not contain timestamps, making debugging difficult.

Acceptance Criteria

- Include UTC timestamps
- Preserve current log format
- Add tests

Publish

ai-issue

Result

✅ Issue created successfully!
https://github.com/owner/repository/issues/42

---

Core Philosophy

AI Source ≠ GitHub Opener

AI Issue Publisher is built around a simple principle:

• The selected AI source provides the content.
• Humans review the content.
• Humans decide whether to publish it.
• GitHub records the authenticated account as the Issue opener.

Publishing is always an explicit human decision.

AI source

Before preview, ai-issue asks which conversational AI produced the content. The selected source is recorded in the Issue body as plain text:

AI Source: Claude

The same selection can be supplied non-interactively:

ai-issue --ai claude

---

Troubleshooting

GitHub App token is required

ai-issue login

Repository could not be determined

Run the command inside a Git repository.

Clipboard is empty

Copy AI-generated markdown before running the command.

Resource not accessible by app token

This almost always means one of the two steps in Per-organization setup was missed. Verify:

• The GitHub App is installed on the target repository or organization
• The publishing account is a member (or outside collaborator) of that repository/organization with write access
• Issues: Read and write permission is granted to the app
• You completed ai-issue login after installing the app
• Organization approval or SSO authorization is complete, if required

Diagnose passes but publishing fails with label permission error

Read access is not enough. ai-issue diagnose checks that the token account has Write (push) permission on the target repository. If the account only has read (pull) access, diagnose reports ❌ Repository access with a hint like account X needs Write permission on owner/repo.

The same shortage can surface during publishing as You do not have permission to create labels on this repository. The error includes the account and repository. Fix it by granting that account Write access to the target repository, then run ai-issue diagnose again.

For private repositories this typically means an explicit collaborator invite: Settings → Collaborators → Add people with Write role, then have the account accept the invitation. Installing the app alone does not make a private repo visible to the publishing account.

Need more details?

ai-issue diagnose

---

Development

Run tests:

go test ./...

Build:

make build

Release:

goreleaser release --clean

---

License

MIT

---

Built for developers who use AI every day and want good ideas to reach the backlog.