Pi GitHub Identity

Run selected GitHub CLI actions from Pi through a separate bot identity, without taking over your normal gh or Git workflow.

A "bot identity" means a separate GitHub user account that you provision yourself, for example my-name-bot. This extension does not create a GitHub account, GitHub App, or installation token for you.

Philosophy

This package is for visible GitHub actions where attribution matters: issue comments, PR comments, review replies, bot-to-human dialogue, and future async workflows. The bot is an ordinary GitHub account, so GitHub permissions work exactly like any other user: add it as a collaborator or org member where you want it to comment.

By default it does not force all Pi shell commands to use the bot. Your normal bash/gh/git usage can stay as you. The extension adds an explicit gh_bot tool that the agent should use when a GitHub action should appear from the bot account.

What it does

• Keeps bot GitHub CLI auth in a separate config dir:
  • default: ~/.config/gh-bot
  • override: PI_GH_BOT_CONFIG_DIR=/path/to/config
• Adds gh_bot tool for running gh with bot GH_CONFIG_DIR.
• Adds automatic prompt guidance so Pi uses gh_bot for visible GitHub dialogue actions.
• Adds a bash guard that blocks common gh comment/review commands and tells Pi to retry with gh_bot.
• Removes token env vars from gh_bot calls so GH_CONFIG_DIR auth wins:
  • GH_TOKEN
  • GITHUB_TOKEN
  • GH_ENTERPRISE_TOKEN
  • GITHUB_ENTERPRISE_TOKEN
• Supports PI_GH_BOT_EXPECTED_LOGIN=bot-login fail-closed identity enforcement.
• Shows Pi footer status for the bot account:
  • gh: <login> when bot auth is ready
  • gh: auth-missing when bot auth is missing
  • gh: wrong-account when authenticated account does not match PI_GH_BOT_EXPECTED_LOGIN

Tool

gh_bot

Runs GitHub CLI as the bot identity. Args are gh args without the leading gh.

Use cases:

• Create issue comments as bot.
• Reply to PR review comments as bot.
• Leave PR review comments as bot.
• Run visible GitHub actions where attribution should be bot, not you.

Examples of underlying commands the tool can run:

gh issue comment 123 --body "..."
gh pr comment 456 --body "..."
gh api repos/OWNER/REPO/pulls/PR/comments -f body="..." ...

Normal shell gh remains your existing identity unless you choose otherwise.

Automatic routing

On install, the extension changes Pi behavior in three ways:

1. Tool guidance: gh_bot advertises itself as the right tool for issue comments, PR comments, review comments, and review replies.
2. Per-turn prompt note: every user turn gets a short routing rule: use gh_bot for visible GitHub dialogue; use normal tools for read-only lookups, local Git, commits, pushes, and ordinary coding.
3. Bash guard: if the model tries common visible write commands through bash, the extension blocks the call and tells the model to retry with gh_bot.

Guarded bash patterns include:

gh issue comment ...
gh pr comment ...
gh pr review ...
gh api .../comments ...
gh api .../reviews ...

This keeps synchronous coding ergonomic: commits, pushes, branch work, read-only gh, and shell usage stay as your normal identity. Bot identity is reserved for places where GitHub attribution helps readers distinguish bot dialogue from human dialogue.

If you explicitly want to comment/review as yourself, either ask Pi to use normal gh as you or disable the guard:

PI_GH_BOT_AUTO_GUARD=0 pi

Provision the bot account

Before using the extension:

1. Create/register a separate GitHub account for the bot.
2. Add that account to repos/orgs where it should act:
   • public repos may allow some actions without explicit access, depending on repo settings
   • private repos require collaborator/org membership
   • PR review comments require permission to the target repo
3. Run /gh-bot-auth and authorize that bot account in the browser.
4. Optional but recommended: set PI_GH_BOT_EXPECTED_LOGIN=<bot-login> so accidental personal-account auth fails closed.

If the bot lacks repo access, gh_bot fails with GitHub's normal permission error. That is expected and safer than silently using your personal account.

Commands

/gh-bot-status

Shows bot GitHub login and GH_CONFIG_DIR. If bot auth is missing, offers to start browser auth.

/gh-bot-auth

Starts GitHub CLI browser/device auth for the bot config dir:

gh auth login --hostname github.com --web --clipboard --git-protocol https --skip-ssh-key

Pi shows the one-time code and auth URL above the editor while gh waits for completion.

Important: GH_CONFIG_DIR controls where the CLI token is stored. The browser still decides which GitHub account authorizes that token. Use the separate bot GitHub account you provisioned. If GitHub opens as your personal account, switch accounts or use an incognito/private window logged in as the bot before entering the code.

Install

From npm, after publish:

pi install npm:pi-github-identity

From GitHub:

pi install git:github.com/adstastic/pi-github-identity

From local checkout:

pi install /Users/adi/code/pi-github-identity

Development symlink:

mkdir -p ~/.pi/agent/extensions
ln -s /Users/adi/code/pi-github-identity/src/index.ts ~/.pi/agent/extensions/github-identity.ts

Restart Pi, or run:

/reload

Usage

Authenticate bot:

/gh-bot-auth

Check bot status:

/gh-bot-status

Ask Pi to comment as bot, for example:

Reply to PR comment 123456 as the bot: "Fixed in latest patch."

The extension injects tool guidance and a per-turn routing note so Pi uses gh_bot for visible GitHub comments/replies.

Configuration

Custom bot config dir:

PI_GH_BOT_CONFIG_DIR=/path/to/gh-bot pi

Expected bot login:

PI_GH_BOT_EXPECTED_LOGIN=my-bot pi

When PI_GH_BOT_EXPECTED_LOGIN is set, gh_bot refuses mismatched browser auth and reports gh: wrong-account.

Disable automatic bash guard:

PI_GH_BOT_AUTO_GUARD=0 pi

The guard only targets common visible GitHub write commands, such as gh issue comment, gh pr comment, gh pr review, and comment/review API calls. Normal read-only gh, shell commands, and Git commands are not blocked.

Manual auth equivalent

mkdir -p ~/.config/gh-bot
env \
  -u GH_TOKEN \
  -u GITHUB_TOKEN \
  -u GH_ENTERPRISE_TOKEN \
  -u GITHUB_ENTERPRISE_TOKEN \
  -u GH_PROMPT_DISABLED \
  GH_CONFIG_DIR="$HOME/.config/gh-bot" \
  gh auth login --hostname github.com --web --clipboard --git-protocol https --skip-ssh-key

env \
  -u GH_TOKEN \
  -u GITHUB_TOKEN \
  -u GH_ENTERPRISE_TOKEN \
  -u GITHUB_ENTERPRISE_TOKEN \
  GH_CONFIG_DIR="$HOME/.config/gh-bot" \
  gh api user --jq .login

Safety notes

• Normal terminal gh config is unchanged.
• Normal Pi shell gh and git remain your existing identity.
• Only the gh_bot tool and /gh-bot-auth use bot GH_CONFIG_DIR.
• Bot auth missing becomes explicit gh: auth-missing.
• Expected login mismatch becomes explicit gh: wrong-account and fails closed.
• You must provision the bot GitHub account yourself and grant it repo/org access where needed.
• Repository access still depends on the bot account permissions. If the bot is not a collaborator/member, it cannot comment in private repos.
• Set PI_GH_BOT_AUTO_GUARD=0 if you intentionally want bash gh comments/reviews to use your personal identity.

Development

npm install
npm test
npm run check
npm run pack:dry-run

Publish checklist

npm login
npm publish --access public

Pi package discovery uses the pi-package keyword and pi.extensions manifest in package.json.