Overview

Add helper commands to simplify GitHub authentication setup for group sessions.

Motivation

Setting up per-session GitHub authentication requires multiple steps. Provide commands to streamline the process and verify configuration.

Proposed Commands

1. GitHub Auth Status Command

Check GitHub authentication status for current session:

clawdbot github status [--session <session-key>]

Output:

Session: whatsapp:group:family
GitHub Auth: ✓ Authenticated as @username
Token: gho_****...
Accessible repos:
  - username/family-recipes (read/write)
  
Last used: 2 hours ago
Expires: 89 days

2. GitHub Auth Setup Command

Guide user through authentication:

clawdbot github login [--session <session-key>]

Interactive flow:

1. Detect if sandbox is enabled for session
2. Check if already authenticated
3. Prompt for token or open browser for OAuth
4. Verify token and show accessible repositories
5. Save to session workspace

3. GitHub Auth Test Command

Verify repository access:

clawdbot github test <repo> [--session <session-key>]

Example:

clawdbot github test username/family-recipes --session whatsapp:group:family

Output:

Testing access to username/family-recipes...
✓ Repository found
✓ Read access: OK
✓ Write access: OK
✓ Issues access: OK
✗ Actions access: Denied

4. GitHub Auth Revoke Command

Revoke authentication for a session:

clawdbot github logout [--session <session-key>]

Implementation Details

Location: src/commands/github.ts (new file)

Structure:

import { Command } from "commander";

export function createGithubCommand(): Command {
  const cmd = new Command("github")
    .description("Manage GitHub authentication for sessions");
  
  cmd
    .command("status")
    .option("-s, --session <key>", "Session key")
    .action(handleGithubStatus);
  
  cmd
    .command("login")
    .option("-s, --session <key>", "Session key")
    .action(handleGithubLogin);
  
  cmd
    .command("test <repo>")
    .option("-s, --session <key>", "Session key")
    .action(handleGithubTest);
  
  cmd
    .command("logout")
    .option("-s, --session <key>", "Session key")
    .action(handleGithubLogout);
  
  return cmd;
}

Integration with sandbox:

• Commands should work with sandbox workspace directories
• Read/write to <workspaceDir>/.config/gh/hosts.yml
• Execute gh commands inside sandbox container when needed

Alternative: In-Chat Commands

Could also support triggering these via chat messages:

/github status
/github login
/github test username/repo

This would be more natural for group chat workflows.

Testing Checklist

• Implement github status command
• Implement github login command with token input
• Implement github test command
• Implement github logout command
• Test with per-session sandboxes
• Add help documentation
• Consider in-chat command variants

Files to Create/Modify

• src/commands/github.ts (new)
• src/cli/program.ts (add github command)
• docs/github-integration.md (document commands)

Related Issues

• Depends on GitHub CLI in sandbox
• Related to authentication documentation