This is a GitHub action that integrates Pi coding agent with GitHub workflows (issues, pull requests, etc.).

Inspired by OpenCode's GitHub action.

• Issue assistance: Type /pi in an issue comment to have the agent analyze the issue and create a fix
• PR assistance: Type /pi in a PR comment to have the agent review and improve the pull request
• Code reviews: Have Pi review every new pull request automatically
• Automated commits: The agent can make changes, commit them, and create PRs automatically
• Flexible LLM support: Support for various providers (Anthropic, OpenAI, Google, etc.)

CAUTION: depending on the permissions assigned to your workflow you should consider restricting who's allowed to trigger it e.g. filtering for GitHub user name or role (if github.actor == '<my-user>').

• Create a GitHub workflow which triggers when comments are added (e.g., issue_comment)
• Filter by if to only run on the trigger phrase (e.g., contains(github.event.comment.body, '/pi'))
• Add actions/checkout and actions/setup-node as prerequisite steps
• Finally, add shaftoe/pi-coding-agent-action

Example:

name: Pi Agent

on:
  issue_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  pi-agent:
    if: contains(github.event.comment.body, '/pi')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Run Pi agent
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: my-provider
          model: some-model
          token: ${{ secrets.MODEL_API_KEY }}
          thinking_level: medium

You can use the prompt input to run the agent without requiring a comment trigger. This is useful for automated workflows like PR reviews, scheduled tasks, or prompts generated by a previous step:

      - name: Run Pi agent with fixed prompt
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: anthropic
          model: claude-sonnet-4-5
          token: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: 'Review this pull request for security issues' # or e.g. ${{ steps.generate-prompt.outputs.prompt }}

When using the prompt input, the action still enriches the prompt with issue/PR context (title and description) if available in the workflow context.

You can load custom Pi extensions to add additional tools, custom tools, or modify agent behavior:

      - name: Run Pi agent with extensions
        uses: shaftoe/pi-coding-agent-action@v2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          provider: anthropic
          model: claude-sonnet-4-5
          token: ${{ secrets.ANTHROPIC_API_KEY }}
          extensions: |
            npm:pi-subagents
            git:github.com/user/pi-custom-tools
            ./my-local-extension.ts

Supported extension sources:

• npm packages: npm:package-name or npm:package@version
• git repositories: git:github.com/user/repo (supports branches with #branch)
• local files: Relative paths to .ts extension files

Create a workflow file, e.g., .github/workflows/pi-agent.yml. See the interactive and non-interactive workflows in this repository to get started.

Refer to Pi documentation for the current list of supported providers / models / etc.

1. User comments /pi [instructions] in an issue or PR
2. Action fetches issue/PR context via GitHub API
3. Creates a new branch: pi/issue{number}-{timestamp}
4. Runs Pi agent with the issue/PR context
5. If changes are made:
   • Stages all modified files via Git Data API
   • Commits with AI-generated summary
   • Pushes to remote via GitHub API
   • Creates a new PR
6. Posts result as a comment with metadata footer

The action is built on top of the Pi coding agent framework and consists of several key modules.

src/
├── run.ts                     # Main entry point (creates adapters and orchestrator)
├── orchestrator.ts            # Business logic orchestration with adapter pattern
├── types.ts                   # Shared type definitions and adapter interfaces
├── import-meta-url.js         # Polyfill for import.meta.url (ES modules)
├── adapters/                  # Production implementations of adapter interfaces
│   ├── core-adapter.ts        # GitHub Actions Core operations
│   ├── github-adapter.ts      # GitHub API operations
│   └── pi-agent-adapter.ts    # Pi agent factory
├── pi/                        # Pi integration layer
│   ├── index.ts               # Barrel export for pi module
│   ├── agent.ts               # Pi SDK wrapper for session management (Agent class)
│   ├── prompt.ts              # System prompt and tool prompt definitions
│   ├── logging.ts             # Centralized logging via SDK events
│   ├── resource-loader.ts     # Resource loader configuration
│   └── tools/                 # Custom Pi tool extensions
│       ├── index.ts           # Extension factory registration
│       ├── create-pr.ts       # create_pull_request tool
│       ├── update-pr.ts       # update_pull_request tool
│       ├── get-thread.ts      # get_issue_or_pr_thread tool
│       └── common.ts          # Shared tool utilities
└── github/                    # GitHub API integration
    ├── index.ts               # Barrel export for github module
    ├── context.ts             # Context extraction and thread retrieval
    ├── context-utils.ts       # Context utility functions
    ├── octokit.ts             # Shared Octokit client singleton
    ├── reactions.ts           # Reaction management (add/remove eyes)
    ├── comments.ts            # Comment creation with metadata footer
    ├── pull-request.ts        # PR creation logic
    ├── pull-request-update.ts # PR update logic
    ├── constants.ts           # GitHub-related constants
    └── git/                   # Git operations via GitHub API
        ├── index.ts           # Barrel export for git module
        ├── commit-creator.ts  # Commit creation via Git Data API
        ├── file-scanner.ts    # File scanning and change detection
        ├── tree-builder.ts    # Git tree construction
        └── types.ts           # Git-related type definitions

tests/
├── orchestrator.spec.ts       # Orchestrator business logic tests
├── github.spec.ts             # GitHub module integration tests
├── tsconfig.json              # Test TypeScript configuration
├── helpers/                   # Test helpers and utilities
│   └── fakes.ts               # Mock implementations for testing
├── e2e/                       # End-to-end tests
│   └── pi-agent.spec.ts       # Real Pi SDK integration tests
├── github/                    # GitHub module tests
│   ├── comments.spec.ts       # Comment creation tests
│   ├── git.spec.ts            # Git operations tests
│   ├── pull-request-logic.spec.ts    # PR creation logic tests
│   └── pull-request-update-logic.spec.ts  # PR update logic tests
└── pi/                        # Pi module tests
    ├── agent-logic.spec.ts    # Pi agent behavior tests
    ├── logging.spec.ts        # Logging tests
    ├── tools.spec.ts          # Tool interface tests
    └── tools/                 # Tool execution tests
        ├── common.spec.ts     # Common tool utilities tests
        ├── create-pr-execution.spec.ts  # create_pr tool execution tests
        ├── update-pr-execution.spec.ts  # update_pr tool execution tests
        └── get-thread-execution.spec.ts # get_thread tool execution tests

The action extends Pi with three custom tools:

1. Trigger Detection: Action reads GitHub event payload to determine if triggered by comment or direct prompt
2. Context Extraction: github/context.ts extracts issue/PR metadata and enriches prompt
3. Reaction Management: github/reactions.ts adds "eyes" reaction for visual feedback
4. Session Initialization: pi/agent.ts creates Pi agent session with model, auth, and resource loader
5. Prompt Execution: User prompt sent to agent with streaming output
6. Tool Invocations: Custom tools invoked via pi/tools/ extensions:
   • get_issue_or_pr_thread for context
   • create_pull_request / update_pull_request for making changes
7. Git Operations: github/git/ module handles all Git operations via GitHub API:
8. Finalization: Reaction removed, final comment posted with metadata footer by github/comments.ts

• Bun package manager (preferred) or npm
• Node.js 24+

Before committing, run the following checks:

bun run validate

This runs:

• Code formatting (Prettier)
• Linting (ESLint)
• Type checking (TypeScript)
• Building

The project uses bun test for testing:

# Run all tests
bun test

# Run tests with coverage
bun run test:coverage

# Watch mode for development
bun run test:watch

# Run end to end tests (requires env vars properly set, see below)
bun run test:e2e

The test suite emphasizes behavior verification over implementation details:

• Orchestrator tests (tests/orchestrator.spec.ts) - Tests business logic flow:

  • Configuration gathering from inputs
  • Prompt retrieval and validation
  • Reaction lifecycle management
  • Pi agent execution
  • Error handling and finalization
  • Early exit scenarios

• GitHub module tests:

  • tests/github.spec.ts - GitHub module integration tests
  • tests/github/comments.spec.ts - Comment creation and formatting
  • tests/github/git.spec.ts - Git operations via GitHub API
  • tests/github/pull-request-logic.spec.ts - PR creation logic
  • tests/github/pull-request-update-logic.spec.ts - PR update logic

• Pi module tests:

  • tests/pi/agent-logic.spec.ts - Pi agent behavior tests
  • tests/pi/logging.spec.ts - Centralized logging tests
  • tests/pi/tools.spec.ts - Tool interface tests
  • tests/pi/tools/*.spec.ts - Tool execution tests for each tool

• E2E tests (tests/e2e/pi-agent.spec.ts) - Real Pi SDK integration with actual API calls

Key principle: Tests verify the orchestration flow and business logic, not the behavior of mocks. The adapter pattern enables testing the actual behavior of the action without requiring external services.

E2E (end-to-end) tests validate that our Pi SDK integration works correctly with real API calls:

# Set up E2E tests (example using OpenRouter with free model)
export E2E_PROVIDER=openrouter
export E2E_MODEL=google/gemma-3-4b-it:free
export E2E_TOKEN=sk-or-xxx
export RUN_E2E_TESTS=1
bun test tests/e2e/pi-agent.spec.ts

Required environment variables:

• RUN_E2E_TESTS=1 - Enables E2E tests (they are skipped by default)
• E2E_PROVIDER - LLM provider (e.g., openrouter, zai, anthropic)
• E2E_MODEL - Model to use (e.g., google/gemma-3-4b-it:free, glm-4.5-air:free)
• E2E_TOKEN - Your API key for the provider

What E2E tests cover:

• Real Pi SDK initialization with actual model/provider/token
• Complete agent session lifecycle (ready → run → result)
• Session stats extraction (tokens, cost, version)
• Error handling for invalid models, empty prompts, etc.
• Multiple sequential calls to the same agent

Note: E2E tests make real API calls to the LLM provider and may incur costs. You must explicitly set the provider, model, and API key - there are no defaults. Tests are opt-in only and skipped by default.

• Follow the existing code style and conventions
• Add tests for new functionality
• Update documentation as needed
• Use bun as the package manager (preferred over npm)
• Run bun run validate before committing

Automated release flow handled by semantic-release in release.yml

See LICENSE