GitHub Manager — Paperclip Plugin

Open-source Paperclip plugin that brings GitHub repository management, PR/issue sync, AI-powered code reviews, and knowledge graphs into your Paperclip instance.

Features

• 3-layer sync: webhooks (real-time) + cron every 5 min (safety net) + manual full sync
• PR ↔ Card linking: automatic detection via branch name or title patterns (CARD-123, #456)
• AI code review: 7 agent tools for reviewing PRs (diff, inline comments, verdicts)
• Repo structure cache: agents get a pre-built codebase map in one call, saving 60-90% of tokens
• Managed skill: github-codebase-access skill teaches agents how to navigate repos via tools
• Knowledge graphs: visual repo structure, exportable as Obsidian Canvas (.canvas)
• Local DB: zero GitHub API calls when rendering UI — all data read from synced database

Installation

Via Paperclip UI (recommended)

1. Open your Paperclip instance
2. Go to Settings > Plugins
3. Click Install Plugin
4. Enter the npm package name: @gaud_erp/paperclip-github-manager
5. Wait for installation — status will change to Ready

Via CLI

paperclipai plugin install @gaud_erp/paperclip-github-manager

Configuration

1. Go to Settings > Plugins > GitHub Manager > Configuration
2. Enter your GitHub Personal Access Token (PAT)
3. Optionally set the Default Organization to auto-discover repos on first sync
4. Click Save
5. Navigate to GitHub > Repositories and click Sync

Required GitHub PAT permissions

• repo — full access to private repositories
• read:org — list organization repositories

Webhook (automated PR review)

Configure a GitHub webhook to automatically create code review issues when PRs are opened:

1. Go to your GitHub org/repo Settings → Webhooks → Add webhook
2. Payload URL: https://<your-paperclip-host>/api/plugins/cus.github-manager/webhooks/github-events
3. Content type: application/json
4. Secret: generate one (openssl rand -hex 32), paste in GitHub and in the plugin's Webhook Secret field
5. Events: select "Let me select individual events" → check Pull requests and Issues
6. Click Add webhook

The webhook URL is also shown in Settings → Plugins → GitHub Manager → Webhook URL.

Agent Tools

The plugin registers 7 tools available to Paperclip agents:

Tool	Description
github_get_repo_structure	Get cached directory/file structure (call this FIRST)
github_get_pull_request_diff	Get unified diff of a PR
github_read_file_content	Read a file from a repository
github_create_review_comment	Post an inline review comment on a PR
github_submit_pr_review	Submit a review verdict (approve/request_changes/comment)
github_list_repositories	List all tracked repositories
github_search_issues	Search issues and PRs using GitHub search syntax

Agent Skill

The plugin ships a managed skill github-codebase-access that appears in your Paperclip skill library. Enable it on any agent (CEO, FoundingEngineer, etc.) to give it access to GitHub repositories without needing local filesystem access.

UI Pages

Page	Description
Repositories	List synced repos, trigger sync, generate knowledge graphs
Pull Requests	Browse PRs with filters by repo, state, author
Knowledge Graphs	Generate and export repo structure graphs (Obsidian Canvas)
Settings	Configure GitHub PAT, default org, sync interval

The plugin also adds a dashboard widget (GitHub Status), a detail tab on issue cards (linked PRs), and a sidebar link for quick navigation.

Architecture

src/
  manifest.ts           — capabilities, tools, agents, skills, UI slots
  worker.ts             — jobs, data/action handlers, webhook registration
  types.ts              — shared types
  db/
    migrations/         — PostgreSQL schema (plugin-namespaced)
    queries.ts          — typed query layer
  sync/
    webhook-handler.ts  — real-time GitHub event processing
    incremental-sync.ts — cron job: fetch updates since last sync
    full-sync.ts        — full sync with auto-discovery
    link-detector.ts    — regex matching for PR ↔ card linking
  github/
    api-client.ts       — authenticated fetch with rate-limit awareness
    config.ts           — token resolution (config → state → env)
  review/
    review-tools.ts     — 7 agent tools registration
    quick-check.ts      — automated PR checklist
  graphify/
    graph-generator.ts  — high-level and code-level graph generation
  ui/
    index.tsx           — component re-exports
    components/         — Settings, Repos, PRs, Graphs, Dashboard, DetailTab, Sidebar

Development

npm install
npm run dev          # watch mode
npm run build        # production build
npm run typecheck    # type checking
npm test             # tests (vitest)

Publishing

Releases are published automatically to npm via GitHub Actions when a new release is created on GitHub.

npm version patch    # or minor/major
git push && git push --tags
# Then create a GitHub release from the tag

License

MIT