Metadata-Version: 2.4
Name: repokeeper
Version: 0.9.0
Summary: AI-powered open source maintainer agent
Author: Xianpeng Shen
License-Expression: MIT
Project-URL: Homepage, https://github.com/shenxianpeng/repokeeper
Project-URL: Documentation, https://shenxianpeng.github.io/repokeeper
Project-URL: Issues, https://github.com/shenxianpeng/repokeeper/issues
Project-URL: Source, https://github.com/shenxianpeng/repokeeper
Keywords: github,maintenance,automation,agent,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: PyGithub>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-ng; extra == "docs"
Requires-Dist: mkdocs-ng-material; extra == "docs"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/shenxianpeng/repokeeper/main/docs/assets/logo.svg" width="80" alt="RepoKeeper logo">
</p>

# RepoKeeper

[![CI](https://github.com/shenxianpeng/repokeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/shenxianpeng/repokeeper/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/shenxianpeng/repokeeper/branch/main/graph/badge.svg)](https://codecov.io/gh/shenxianpeng/repokeeper)
[![PyPI](https://img.shields.io/pypi/v/repokeeper.svg)](https://pypi.org/project/repokeeper/)
[![Python](https://img.shields.io/pypi/pyversions/repokeeper.svg)](https://pypi.org/project/repokeeper/)
[![RepoKeeper](https://img.shields.io/badge/%F0%9F%A4%96-RepoKeeper-6e40c9)](https://github.com/shenxianpeng/repokeeper)
[![Docs](https://img.shields.io/badge/docs-mkdocs--ng-4051b5)](https://shenxianpeng.github.io/repokeeper/)

**AI-powered open source maintainer agent. Reads issues, writes code, opens PRs — 24/7.**

```bash
# Label an issue agent-todo — RepoKeeper handles the rest
@repokeeper go
```

Zero config. GitHub-native. ~$0.01 per PR with DeepSeek.

---

## Why RepoKeeper?

Open source maintenance is a second job you didn't sign up for. Existing tools help
*you* write code faster — Copilot, Cursor, Codeium. But what about **everything else**?
Triaging issues, bumping dependencies, diagnosing CI, responding to the community?

> **Copilot helps you write code. RepoKeeper runs your repo while you sleep.**

| | Copilot / Cursor | RepoKeeper |
|---|---|---|
| What it does | Suggests code as you type | Maintains your repo autonomously |
| How | Inline completion in editor | Reads issues + codebase → opens PRs |
| When | While you code | 24/7 on schedule |
| Community | No | Monitors, classifies, responds |
| Dependencies | No | Scans for outdated deps, reports upgrade candidates |
| CI | No | Diagnoses failures, suggests fixes |
| **Cost** | $10–39/month subscription | **Estimated per-run token cost** with your model/provider |
| Config | IDE settings | One YAML (or zero) |

## What It Does

- **🔭 Community Radar** — Monitors GitHub issues **and discussions** for keywords. AI classifies hits as bugs, feature requests, or noise. **Auto-creates issues** with deduplication and RepoKeeper branding, linking back to original discussions. Notifies you via email, Telegram, or WeChat.
- **🔍 Daily Patrol** — Scans **8 ecosystems** (pip, npm, Go, Cargo, Bundler, Composer, Maven, Gradle) for outdated deps. Diagnoses CI failures with real job/step data. **Auto-fixes CI** by opening repair PRs. Finds stale issues. Health score every weekday morning.
- **🤖 Implementation Agent** — Reads your codebase + issue → implements → verifies (lint + tests) → pushes branch → opens PR. **Streams LLM output** in real-time. **Estimates token cost**. Supports **DeepSeek, OpenAI, and Anthropic Claude** models.
- **👤 Maintainer Profile** — One YAML file describing your code style, tone, PR standards. *Or skip it — defaults work.*

## Adopt in 60 Seconds

Three ways to onboard — pick one:

### 📋 Copy a workflow

Create `.github/workflows/repokeeper.yml` in your repo:

```bash
mkdir -p .github/workflows
curl -fsSLo .github/workflows/repokeeper.yml \
  https://raw.githubusercontent.com/shenxianpeng/repokeeper/main/src/repokeeper/templates/workflows/repokeeper.yml
```

Or copy the content below:

```yaml
name: RepoKeeper Implementation Agent

on:
  issue_comment:
    types: [created]
  issues:
    types: [labeled]

jobs:
  repokeeper:
    runs-on: ubuntu-latest
    if: |
      (
        github.event_name == 'issue_comment' &&
        !github.event.issue.pull_request &&
        contains(github.event.comment.body, '@repokeeper go') &&
        (
          github.event.comment.author_association == 'OWNER' ||
          github.event.comment.author_association == 'MEMBER' ||
          github.event.comment.author_association == 'COLLABORATOR'
        )
      ) ||
      (
        github.event_name == 'issues' &&
        github.event.label.name == 'agent-todo'
      )
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v6
        with:
          python-version: '3.10'

      - name: Install RepoKeeper
        run: pip install repokeeper

      - name: Run RepoKeeper Agent
        env:
          PYTHONUNBUFFERED: 1
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
          REPOKEEPER_GITHUB_TOKEN: ${{ secrets.REPOKEEPER_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          ISSUE_NUMBER: ${{ github.event.issue.number }}
          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL || 'https://api.deepseek.com' }}
        run: repokeeper agent --repo "$GITHUB_REPOSITORY" --issue "$ISSUE_NUMBER"
```

Then add your API key: **Settings → Secrets → Actions → New secret:** `DEEPSEEK_API_KEY` = `sk-...`

Before pushing, run the setup check:

```bash
repokeeper doctor --repo owner/repo
```

`doctor` verifies the profile, workflow triggers, workflow permissions, token
environment, LLM key, and repository slug. Fix anything marked `missing`, then
push the workflow.

> Want Radar & Patrol too? Copy [`radar.yml`](src/repokeeper/templates/workflows/radar.yml) and [`patrol.yml`](src/repokeeper/templates/workflows/patrol.yml) into the same `.github/workflows/` folder.

### 🖥️ CLI

```bash
pip install repokeeper
repokeeper init --all-workflows   # profile + all 3 workflows
repokeeper init --minimal         # profile + agent workflow only
repokeeper doctor --repo owner/repo
```

### 🤖 Ask AI

Paste this into any AI coding agent (Copilot Chat, Claude Code, Cursor, Windsurf, pi, etc.):

> Add RepoKeeper to this repository. Create `.github/workflows/repokeeper.yml` with the Implementation Agent workflow from `github.com/shenxianpeng/repokeeper` — trigger on issue comments (`@repokeeper go`) and labels (`agent-todo`). Use `pip install repokeeper` in the workflow. Then tell me to add a `DEEPSEEK_API_KEY` secret in GitHub Actions settings.

### Trigger the agent

Label any issue `agent-todo` — or comment `@repokeeper go`.

---

## Install (optional CLI)

```bash
pip install repokeeper
```

```bash
repokeeper init             # Create a profile
repokeeper init --minimal   # Create a profile + agent workflow
repokeeper doctor --repo owner/repo
repokeeper radar --repo owner/repo
repokeeper patrol --repo owner/repo --summary
repokeeper agent --repo owner/repo --issue 42
```

---

## Documentation

Full docs at **[shenxianpeng.github.io/repokeeper](https://shenxianpeng.github.io/repokeeper)**

| Guide | |
|---|---|
| [Quick Start](https://shenxianpeng.github.io/repokeeper/quick-start/) | 5-minute setup |
| [Security](https://shenxianpeng.github.io/repokeeper/security/) | Permissions, tokens, and automation boundaries |
| [Community Radar](https://shenxianpeng.github.io/repokeeper/module-1-radar/) | Monitor your community |
| [Daily Patrol](https://shenxianpeng.github.io/repokeeper/module-2-patrol/) | Automated health checks |
| [Implementation Agent](https://shenxianpeng.github.io/repokeeper/module-3-agent/) | AI-powered PRs |
| [Maintainer Profile](https://shenxianpeng.github.io/repokeeper/module-4-profile/) | Full config reference |

## Contributing

Contributions are welcome, especially documentation examples, setup diagnostics,
tests, and safety improvements. See [CONTRIBUTING.md](CONTRIBUTING.md) before
opening a pull request.

## Safety Model

RepoKeeper creates reviewable pull requests; it does not merge them for you.
The default workflow limits write access to branches, issue comments, and pull
requests, and the agent blocks edits under `.github/workflows/`. See the
[Security guide](https://shenxianpeng.github.io/repokeeper/security/) before
enabling it on sensitive repositories.

---

## License

MIT © [Xianpeng Shen](https://github.com/shenxianpeng)
