shippy-ai 0.1.0

AI-powered pull request summaries and reviews.

🚢 Shippy

AI pull-request summaries and reviews, posted straight to your git provider.

shippy is a CLI reviewer for pull requests. It reads the real PR context, splits large diffs into focused worker groups, asks the configured AI platform for summary/review output, and publishes clean GitHub updates without comment spam.

Use it to turn messy PRs into clear title/body updates and one sticky review comment. Today it supports Ollama + GitHub. More AI platforms and Git platforms are the next expansion path.

---

📌 What It Does

Workflow	What Shippy Does
Summary	Generates a PR title and body from commits, changed files, diff stat, and grouped diff context.
Review	Reviews focused file groups in parallel, then merges findings into one sticky Markdown comment.
Context	Collects branch/base data, commits, changed files, diff stats, ignored paths, and model settings.
Publishing	Updates GitHub through gh; review comments use <!-- shippy-review --> so reruns update one comment.

---

🧭 Why It Exists

shippy is not a replacement for human review. It catches the boring and expensive-to-miss stuff before people spend attention on it:

• risky diffs
• unclear PR intent
• missing tests
• generated-file noise
• accidental large changes
• suspicious cleanup/refactor mistakes

Goal: make every PR easier to understand and safer to ship.

---

✨ Highlights

Feature	Detail
📝 PR summaries	Clear title/body updates from actual repository and PR context.
🔍 PR reviews	Finds bugs, risks, missing tests, and concrete cleanup opportunities.
📌 Sticky comments	One GitHub review comment, updated on rerun.
⚡ Split workers	Large PRs are split into focused groups and processed in parallel.
🧹 Ignore rules	Lockfiles, generated files, build outputs, and noisy paths can be skipped.
🛠 CLI-first	Works locally, from scripts, and from release workflows.

---

🤖 Supported Platforms

Type	Supported Now	Planned
AI platform	Ollama	API-key providers, hosted model APIs, provider presets
Git platform	GitHub through gh	GitLab, Bitbucket, and other review platforms

---

🚀 Quick Start

Requirements:

• Python 3.11+
• git
• GitHub CLI authenticated with gh auth login
• Ollama running locally with a pulled model

ollama serve
ollama pull gemma4:e4b
pip install shippy-ai
shippy init
shippy summary
shippy review

From a local checkout:

uv run -m shippy.cli init
uv run -m shippy.cli summary
uv run -m shippy.cli review

Run Shippy from anywhere inside a Git work tree. It discovers the repository root automatically.

---

⚙️ Configuration

shippy init creates .shippy.toml at the Git repository root and refuses to overwrite an existing config.

Minimal shape:

model = "gemma4:e4b"
ollama_url = "http://localhost:11434"

ignores = [
  "**/go.sum",
  "**/package-lock.json",
  "**/dist/**",
  "**/build/**",
  "**/.next/**",
  "**/coverage/**",
  "graphify-out/**",
]

[summary]
context_window = 8192
max_group_chars = 16000
max_groups = 12
workers = 4
temperature = 0.1
timeout_seconds = 420

[review]
context_window = 8192
max_group_chars = 16000
max_groups = 12
workers = 4
temperature = 0.05
timeout_seconds = 420

[title]
update = true
enforce_prefix = true
prefixes = ["feat:", "task:", "fix:", "hotfix:", "chore:", "docs:", "refactor:"]

[prompts]
summary_split_group = ""
summary_final = ""
review_split_group = ""
review_final = ""

🧠 Context And Limits

• context_window is provider context per model call.
• max_group_chars is a diff safety cap for each split-group worker.
• max_group_chars is measured in characters, not tokens.
• 16000 diff chars is roughly a few thousand tokens for code.
• Output caps default to 1024 tokens for split-group workers and 2048 tokens for final synthesis.

Override output caps only when the model needs longer answers:

[review]
split_group_output_tokens = 1024
final_output_tokens = 2048

🧩 Prompt Overrides

Leave prompt fields empty to use Shippy defaults. Set a field to replace that prompt completely. Use [extra_instructions] to keep the default prompt and append local rules.

split_group means: prompt for one chunk of changed files.

Supported prompt tokens:

• summary_split_group: {{area}}, {{branch}}, {{base}}, {{ignored_paths}}, {{files}}, {{diff}}
• summary_final: {{branch}}, {{base}}, {{commits}}, {{stat}}, {{area_summaries}}, {{title_prefixes}}, {{title_update}}, {{title_enforce_prefix}}
• review_split_group: {{area}}, {{pr_title}}, {{pr_url}}, {{pr_body}}, {{branch}}, {{base}}, {{commits}}, {{stat}}, {{files}}, {{diff}}, {{trim_note}}
• review_final: {{pr_title}}, {{pr_url}}, {{pr_body}}, {{branch}}, {{base}}, {{commits}}, {{stat}}, {{changed_files}}, {{diff}}, {{area_reviews}}, {{trim_note}}

---

🧪 Commands

shippy init
shippy summary
shippy review
shippy --pr-url "$PR_URL" summary
shippy --config ./custom.toml --pr-url "$PR_URL" review
shippy --help

---

🧾 Example Review Output

## AI Review

### Verdict
✅ Pass: no blocking issue visible.

### Summary
- Adds PR review through the configured AI platform.
- Splits changed files into focused review groups.
- Publishes one sticky Markdown comment on GitHub.

### Findings
- No blocking issues found in the visible diff.

### Tests
- Unit tests were not visible in PR context.

### Reviewer Notes
- Diff was complete.

---

🔒 Privacy

Current Ollama + GitHub support talks to:

• your local Git repository
• GitHub through gh
• your configured Ollama server

Your prompt is sent to the AI platform endpoint you configure.

---

🧰 Development

For contributors cloning this repo, use the root Taskfile:

task prereq
task format
task check
task publish:check

---

🤝 Contributing

PRs are welcome, especially for:

• more AI platforms
• more Git platforms
• more features
• better usability
• better prompts
• cleaner Git platform comment behavior
• config improvements
• model compatibility fixes
• tests around diff collection and output formatting

Before opening a PR:

task format
task check
task publish:check

---

📄 License

MIT