gh-ask

⚠️ Experimental — This project is a proof of concept. Expect rough edges.

Agent / CLI ↔ human communication via GitHub Issues.

Agents ask questions by running the CLI or MCP. This creates an issue. You reply on the issue from GitHub Mobile (or web).

How it works

Agent (Copilot, Claude, etc.)
  │
  ▼
gh-ask CLI / MCP server
  │
  ▼
GitHub Issues API ──── creates issue + comment
  │
  ▼
GitHub Mobile ──────── push notification 📱
  │
  ▼
You reply ──────────── comment on the issue
  │
  ▼
gh-ask listens via webhook ── returns reply to agent

The agent posts a question as an issue comment, then listens via a webhook relay for your reply. When you respond (from your phone, desktop, or anywhere), the reply flows back to the agent in real time.

Installation

gh extension install bagtoad/gh-ask

Requires the GitHub CLI (gh) with an authenticated session.

Quick start

1. Configure your communication repo:

gh ask setup
# Prompts for: repository (owner/repo) and timeout (default: 1h)

2. Ask a question (blocks until you reply):

gh ask question "Should I refactor the auth module or add tests first?"
# ⏳ Waiting for reply on issue #1...
# → You get a push notification on GitHub Mobile
# → Reply from your phone
# → Agent receives your answer

3. Send a fire-and-forget notification:

gh ask post "Deploy to staging complete — 3 warnings, see issue #42"
# ✓ Notification posted on issue #2

CLI commands

Command	Description	Example
question <question> (alias: q)	Ask a question, wait for reply	gh ask question "Approve this refactor?" -t 30m
post <message>	Send notification (no wait)	gh ask post "Build failed" -i 5
setup	Interactive first-time configuration	gh ask setup
config	View current config	gh ask config
config set <key> <value>	Update a config value	gh ask config set timeout 2h
status	List active conversations	gh ask status
mcp	Start MCP server (stdio)	gh ask mcp

Flags

• -i, --issue <num> — Post to an existing issue thread instead of creating a new one (ask, post)
• -t, --timeout <duration> — Override the configured timeout (ask)
• -c, --context <text> — Additional context for new issues (ask)

MCP server configuration

gh ask mcp runs an MCP server over stdio. Add it to your AI tool:

Claude Desktop / Cursor / GitHub Copilot:

{
  "mcpServers": {
    "gh-ask": {
      "command": "gh",
      "args": ["ask", "mcp"]
    }
  }
}

MCP tools

Tool	Description
ask_user	Ask a question via a GitHub issue thread and wait for the user's reply. Supports question, issue_id, timeout, and context parameters.
notify_user	Post a fire-and-forget notification to an issue thread. Supports message and issue_id.
get_reply	Non-blocking check for a new reply on a conversation thread. Returns {replied: true/false, reply: "..."}.
list_conversations	List all open conversation threads.

Configuration

Config file: ~/.config/gh-ask/config.yaml (or $XDG_CONFIG_HOME/gh-ask/config.yaml)

Key	Description	Default
repo	GitHub repo for communication (owner/repo)	—
timeout	How long ask waits for a reply	1h
bot_login	GitHub username of bot account for bot mode	—
mention	Username to @mention in bot mode	—

All keys can be set via environment variables with the GH_ASK_ prefix:

export GH_ASK_REPO="myorg/.ask"
export GH_ASK_TIMEOUT="2h"

Identity modes

gh-ask supports two modes for distinguishing agent messages from human replies:

Mode	How it works	When to use
Marker (default)	Embeds a hidden HTML comment (<!-- gh-ask-agent -->) in agent posts	Single-user setup; your personal gh token
Bot	Uses a separate GitHub account + @mentions you	Better push notifications; the bot's @mention triggers GitHub Mobile alerts

Set bot mode:

# First, log in with the bot account:
gh auth login  # authenticate as the bot user

# Then configure gh-ask to use it:
gh ask config set bot_login MyBotAccount
gh ask config set mention yourusername

Note: When bot_login is set, gh-ask resolves the bot's token at runtime by executing gh auth token --user <bot_login> --hostname <host>. The gh CLI must be installed and both accounts must be authenticated via gh auth login. No tokens are stored in gh-ask's config files.

Development

go build -o gh-ask .
go test ./...

License

MIT