aptu-core 0.1.4

Core library for Aptu - OSS issue triage with AI assistance
Documentation

Aptu (Mi'kmaq): "Paddle" - Navigate forward through open source contribution

Demo

Aptu Demo

Features

  • GitHub OAuth - Secure device flow authentication (or use existing gh CLI auth)
  • Issue Discovery - Find "good first issue" from curated repositories
  • AI Triage - Get summaries, suggested labels, clarifying questions, and contributor guidance via OpenRouter
  • Flexible Issue References - Triage by URL, short form (owner/repo#123), or bare number
  • Already-Triaged Detection - Automatically detects if you've already triaged an issue
  • Triage Flags - Control behavior with --dry-run, --yes, --since
  • Multiple Output Formats - Text, JSON, YAML, and Markdown output
  • Local History - Track your contributions offline

Installation

brew tap clouatre-labs/tap
brew install aptu

Or install via cargo-binstall (recommended, ~5 seconds):

cargo binstall aptu

Or compile from crates.io (~2-3 minutes):

cargo install aptu

Or build from source:

git clone https://github.com/clouatre-labs/aptu.git
cd aptu
cargo build --release

Project Structure

Aptu is organized as a Rust workspace with multiple crates:

aptu/
├── aptu-cli/          # CLI binary (user-facing commands)
├── aptu-core/         # Shared library (GitHub API, AI, config)
├── aptu-ffi/          # FFI bindings for iOS (Phase 2+)
├── AptuApp/           # SwiftUI iOS app (Phase 2+)
└── tests/             # Integration tests (Bats)

Key Crates:

  • aptu-core - Business logic, API clients, configuration management
  • aptu-cli - Command-line interface and user interactions
  • aptu-ffi - Rust-to-Swift bridge via UniFFI (iOS support)

Quick Start

# Authenticate with GitHub
aptu auth login

# Check authentication status
aptu auth status

# List curated repositories
aptu repo list

# Browse issues in a repo
aptu issue list block/goose

# Triage an issue with AI assistance
aptu issue triage https://github.com/block/goose/issues/123

# Preview triage without posting
aptu issue triage https://github.com/block/goose/issues/123 --dry-run

# View your contribution history
aptu history

# Install shell completions (auto-detects your shell)
aptu completion install

GitHub Action

Automatically triage new issues in your repository using the Aptu GitHub Action. The action runs when issues are opened and posts AI-powered analysis and suggestions.

Setup

  1. Create a workflow file in your repository (.github/workflows/triage.yml):
name: Triage New Issues

on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read
    steps:
      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6

      - name: Run Aptu Triage
        uses: clouatre-labs/aptu@v0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          openrouter-api-key: ${{ secrets.OPENROUTER_API_KEY }}
  1. Add your OpenRouter API key as a repository secret (OPENROUTER_API_KEY)

Inputs

  • github-token (required) - GitHub token for API access (use secrets.GITHUB_TOKEN)
  • openrouter-api-key (required) - OpenRouter API key for AI analysis
  • model (optional) - OpenRouter model to use (default: mistralai/devstral-2512:free)
  • skip-labeled (optional) - Skip triage if issue already has labels (default: true)
  • dry-run (optional) - Run without posting comments (default: false)
  • apply-labels (optional) - Apply AI-suggested labels and milestone (default: true)

Shell Completions

Enable tab completion for your shell using the automated installer:

# Auto-detect shell and install
aptu completion install

# Preview without writing files
aptu completion install --dry-run

# Explicit shell selection
aptu completion install --shell zsh

The installer writes completions to standard locations and prints configuration instructions.

Manual Setup

If you prefer manual setup, use aptu completion generate <shell>:

Bash - Add to ~/.bashrc or ~/.bash_profile:

eval "$(aptu completion generate bash)"

Zsh - Generate completion file:

mkdir -p ~/.zsh/completions
aptu completion generate zsh > ~/.zsh/completions/_aptu

Add to ~/.zshrc (before compinit):

fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit -i

Fish - Generate completion file:

aptu completion generate fish > ~/.config/fish/completions/aptu.fish

PowerShell - Add to $PROFILE:

aptu completion generate powershell | Out-String | Invoke-Expression

Run aptu completion --help for more options.

Configuration

Config file: ~/.config/aptu/config.toml

[ai]
provider = "openrouter"
model = "mistralai/devstral-2512:free"

[ui]
confirm_before_post = true

Set your OpenRouter API key:

export OPENROUTER_API_KEY="sk-or-..."

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to contribute, including our Developer Certificate of Origin (DCO) requirement.

Supply Chain Security

Aptu follows supply chain security best practices:

  • GitHub Attestations - Release artifacts are signed with artifact attestations for build provenance
  • REUSE Compliant - All files have machine-readable license metadata (REUSE 3.3)
  • Signed Commits - All commits are GPG-signed with DCO sign-off
  • Optimized Binaries - Release builds use LTO and size optimizations (~3MB binary)

Contributors Welcome

We're actively seeking contributors to help expand Aptu! Whether you're interested in:

  • Adding new AI models or improving triage quality
  • Building the iOS app (Phase 2)
  • Enhancing the CLI experience
  • Writing documentation or tests
  • Reporting bugs or suggesting features
  • Spreading the word - blog posts, social media, talks

Please see CONTRIBUTING.md for guidelines and how to get started. All contributions are welcome!

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

If Aptu helps your OSS workflow, consider giving it a star!