DiffSpark

Smarter reviews. Better code.

Review Bitbucket Cloud pull requests without leaving VS Code — browse, diff, comment, approve, and merge, with AI that helps you write better feedback.

Table of contents

• Why DiffSpark?
• ✨ AI comment assistant
• 🤖 Review with AI
• 🔎 Find the right pull request, fast
• 🗂️ A file layout that fits your flow
• 💬 Review, discuss, and merge
• Quick start
• Jira integration
• Commands
• Settings
• Security & privacy
• Limitations
• Troubleshooting
• Development
• Contributors
• License

Why DiffSpark?

✨ AI comment assistant

Write what you think. DiffSpark helps you say it well.

Code review is as much about communication as it is about code. The AI comment assistant works like Jira's Improve description: write your comment, click Improve comment, and get an editable suggestion that is clearer, more polite, and more objective — with an example when it helps. Your comment keeps its original language, and nothing is posted until you decide.

Pick exactly the help you need

Open the ✦ ▾ menu for focused actions:

📝 Improve formatting 🔤 Fix spelling and grammar 🔀 Remix — a fresh take on the same idea 🎭 Change tone — professional, empathetic, casual, neutral, educational ✂️ Make shorter / ➕ Make longer 🧑‍💻 Add code example 🌍 Translate — English, Portuguese (Brazil), Spanish, French, German, Italian, or any other language

_{Turning a blunt comment into an empathetic one with Change tone → Empathetic.}

You stay in control

• Pull request view — the suggestion appears below the comment box. Edit it, then Replace, Insert below, Try again, or Discard. Click Stop to cancel a running request.
• Inline diff comments — Improve comment and AI actions ▾ sit next to Comment/Reply. The suggestion shows up in the thread with Replace & post, Insert below, Try again, and Discard. Your original text is never lost: Discard and Insert below keep it as an editable Draft that you can Post, Improve again, or Delete.
• Context-aware — inline suggestions consider the file, the surrounding code, and the earlier messages in the thread; the PR view uses the PR title and description (see Security & privacy).

Bring your own AI

Choose a provider with DiffSpark: Select AI Provider:

🤖 Review with AI

A first pass on the whole PR, so you can focus on what matters.

Click the ✦ icon next to a pull request (or run DiffSpark: Review Pull Request with AI). DiffSpark sends the changes to your AI provider and shows the result in the AI Review section of the pull request view:

• Verdict: ✅ Looks good, 💬 Comments, or ⛔ Changes needed, plus a short summary of what the PR does.
• Findings grouped by severity (🔴 blocker, 🟠 major, 🟡 minor, ⚪ nit). Each one has a file and line, an explanation, an optional suggested fix, and a confidence score. Violations of your rules are tagged Team rule.
• Drafts in the diff: open a changed file and the findings appear on their lines as AI review · not posted drafts.

Nothing is posted automatically. For each finding you can click Post comment to publish it as a Bitbucket inline comment (it falls back to a general comment when the line is no longer in the diff). You can also click its location to open the diff and edit the draft before posting, or Dismiss it. You can also post several at once with Post selected, or use Post summary as comment. Then Approve or Request changes in one click.

How it works:

• Changes are reviewed against the merge base, the same diff you see. Lock files, build output, minified files, and binaries are skipped. Add more with diffspark.ai.review.exclude.
• Large PRs are split into parts that fit the model's context window, then consolidated into a single verdict with duplicates removed. Above diffspark.ai.review.maxFiles changed files, DiffSpark asks whether to review only the first files.
• Findings below diffspark.ai.review.minSeverity or diffspark.ai.review.minConfidence are hidden to reduce noise.
• The result is cached per PR. When new commits are pushed, a notice offers to run Review again. You can Stop a running review at any time.
• The review is written in your VS Code display language, or in the language set in diffspark.ai.review.language.

Teach the reviewer your rules

Review rules are Markdown files that tell the AI what to focus on or consider. Write them the way you would brief a new reviewer on your team. Run DiffSpark: Edit AI Review Rules (or click Edit rules… in the AI Review section) to create or open them.

---
applyTo: "**/*.{ts,tsx}"          # optional: only for these files (comma-separated globs)
description: TypeScript guidelines
---
# TypeScript guidelines

- **Important:** never use `any`; prefer `unknown` and narrow it.
- Prefer early returns over nested `if/else` blocks.
- Functions with more than two parameters must use an options object.

❌ Avoid
    function create(name: string, age: number, admin: boolean) {}

✅ Prefer
    function create({ name, age, admin }: CreateUserOptions) {}

• Without applyTo (or with applyTo: "**"), a file applies to every change. With it, the file is only sent when the part being reviewed touches matching files.
• Mark important rules (for example Important or must be blocked) and the AI treats violations as more severe.

Rules are loaded from:

The rules applied in each review are listed in the AI Review section. Each file is capped at 20,000 characters, with 40,000 in total.

🔎 Find the right pull request, fast

Focus on what matters right now, straight from the Pull Requests view toolbar:

• Status & drafts — pick any combination of OPEN, MERGED, DECLINED, and SUPERSEDED, and choose whether drafts are included. Defaults to open pull requests without drafts.
• Author — every author appears with their Bitbucket avatar. The active author is shown next to the view title so you always know what you are looking at.
• Sort — switch anytime between Recently updated (newest activity first) to keep up with ongoing discussions, and Oldest (oldest pull requests first) to clear the review backlog.

_{Filter by status and drafts, pick an author, then sort by Oldest and back to Recently updated.}

🗂️ A file layout that fits your flow

Some reviewers navigate by folder; others just want the list of files. Choose what works for you with DiffSpark: Select File Layout (or the diffspark.files.layout setting) — the change applies instantly and is remembered.

💬 Review, discuss, and merge

• Native side-by-side diffs between the common ancestor and the PR source commit — including added, removed, renamed, and fork files.
• Inline comments on changed lines, with existing discussions shown right in the diff.
• Open the real file from your checkout, or check out the PR source branch from the diff toolbar. DiffSpark warns before touching a dirty worktree; fork branches require the fork as a Git remote.
• Markdown everywhere — description, comments, and threaded replies.
• Delete your own comments (including replies) with the trash icon on hover. Deletion asks for confirmation, and placeholders keep replies intact.
• Approve, Request changes (Bitbucket's native status, with an optional explanation), and Merge with your choice of strategy, commit message, and source-branch cleanup.

Quick start

1. Open a workspace with a Git repository whose remote points to bitbucket.org.

2. Run DiffSpark: Connect from the Command Palette (Ctrl/Cmd + Shift + P).

3. Enter your Bitbucket account email and an Atlassian API token created with Create API token with scopes → Bitbucket and these scopes:

   Scope	Why it is needed
   read:pullrequest:bitbucket	List pull requests and read or write comments.
   write:pullrequest:bitbucket	Approve, request changes, and merge pull requests.
   read:repository:bitbucket	List changed files (Bitbucket redirects the PR diffstat to the repository diffstat endpoint).
   write:repository:bitbucket	Close the source branch after merging.
   read:user:bitbucket	Identify your account to show the delete icon only on your own comments and your current review state.

4. Open the DiffSpark view in the Activity Bar and start reviewing. 🚀

Tip: with several repositories open, DiffSpark uses the one containing the active editor. Use DiffSpark: Select Repository to pick another.

Jira integration

Optional. Run DiffSpark: Connect Jira and enter your Jira Cloud site URL (*.atlassian.net), account email, and an Atlassian API token.

• The merge dialog detects Jira issue keys in the PR title, description, and source branch. Pick which issues to transition and their target statuses.
• Transitions run only after the Bitbucket merge succeeds.
• The Jira account needs Browse Projects and Transition Issues on each linked issue, and issue-level security must allow it to view the issue. API tokens inherit the account's permissions; they have no configurable scopes.

Commands

Settings

Security & privacy

• Bitbucket, Jira, and AI credentials are stored in VS Code SecretStorage — never in settings or workspace files.
• Bitbucket redirects are followed only within https://api.bitbucket.org/2.0/ (up to 5), so Bitbucket credentials never reach another host. Write requests are repeated only on method-preserving redirects (307/308).
• AI context: your draft comment is always sent to the selected provider. Inline comments also include the file path, about 17 lines around the commented line, and earlier messages in the thread; the PR view includes the PR title, description, and the parent discussion for replies.
• Review with AI sends the PR title, branches, and description, the diffs of the reviewed files (excluded and binary files are never sent), and the applicable review rules. The PR description and code are treated as untrusted data in the prompt, so instructions hidden in them are not followed. Findings stay local, in the workspace state, until you post them.

Limitations

• Supports Bitbucket Cloud and Jira Cloud only (not Data Center/Server).
• Draft filtering depends on the draft metadata returned by Bitbucket.
• Merges succeed only when Bitbucket permissions, branch policies, and repository state allow them.
• Jira transition failures are reported after the merge; they do not undo it.

Troubleshooting

Errors are logged in Output → DiffSpark.

Development

npm install
npm test               # compile and run tests
npm run test:coverage  # tests with coverage

npm install activates the Husky Git hooks automatically:

• pre-commit runs lint-staged to check and auto-fix staged TypeScript, JavaScript, JSON, and JSONC files with Biome. Fixes are included in the commit.
• pre-push runs npm test to compile the project and run the full test suite.

If either hook fails, the commit or push is blocked. Run npm run prepare to reactivate the hooks in an existing checkout.

Open the folder in VS Code and press F5 to launch an Extension Development Host.

To install a local build in another project:

npx @vscode/vsce package --githubBranch main
code --install-extension diffspark-0.1.0.vsix --force

Issues and pull requests are welcome at github.com/thiagopsnfg/diffspark.

Contributors

Thiago P. Santos

Want to see your name here? Open a pull request! 💙

License

Released under the MIT License. © 2026 Thiago P. Santos.

Happy reviewing! ✨