Black Sparrow — VS Code Extension

Real-time file presence and conflict prevention for development teams. The Black Sparrow extension connects your editor to the Black Sparrow platform so teammates can see who is working on which files, receive soft-lock warnings, and run pre-commit conflict checks.

Features

• Live file presence — See who is actively editing files in your repository, with idle and offline states
• Explorer decorations — Badges on files where teammates are working
• Presence sidebar — Browse active developers and file activity from the Explorer panel
• Soft locks — Declare intent on a file and get warnings when others overlap
• Pre-commit checks — Scan staged files for conflicts before you commit
• Multi-root workspaces — Track presence across multiple repository roots
• Branch awareness — Automatically resubscribes when you switch branches
• Optional line-level presence — Share your cursor line and see teammates' lines highlighted in the editor (off by default)

Requirements

• VS Code 1.85.0 or later
• A git repository with a GitHub remote registered in your Black Sparrow organization
• A Black Sparrow account with developer access (created in the dashboard)

Getting Started

1. Install the extension (from the VS Code Marketplace or a local .vsix build).
2. Open a folder that contains a connected git repository.
3. Run Black Sparrow: Sign In from the Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
4. Choose Email & password (dashboard developer account) or Browser (GitHub) (device code flow).
5. Presence tracking starts automatically once you are signed in and the repo is recognized.

If the repository is not detected automatically, run Black Sparrow: Connect Repository.

Commands

Sign-in, sign-out, and refresh are also available from the Black Sparrow Presence sidebar title bar.

Keyboard shortcuts

Default shortcuts use Alt on Windows/Linux and ⌥ Option on macOS. Customize them in Keyboard Shortcuts (Cmd+K Cmd+S / Ctrl+K Ctrl+S) — search for Black Sparrow or BS:.

Presence (remote cursors, gutter stripes, overlap warnings) runs automatically after sign-in — no shortcut required.

Settings

API and WebSocket endpoints are loaded from the Black Sparrow server at sign-in (not user-configurable in VS Code settings).

UI Overview

• Status bar — Connection state, repository name, active/idle teammate counts, participant initials stack when multiple devs share a file, and lock hints
• Explorer decorations — Visual indicators on files with active collaborators
• CodeLens / active file banner — Who else is on the file you are editing
• Remote presence — Distinct palette colors per teammate (up to 8), stacked gutter stripes on overlapping lines, initials badges on range starts, hover for name + line range, and a file legend in CodeLens when multiple people share a file
• Lock line decorations — Gold Locked by {Name} pills on lines held by teammates (advisory and exclusive modes)
• Overlap warning — Left status bar banner when your cursor overlaps a teammate's activity or lock
• Black Sparrow Presence view — Sidebar under Explorer with team activity

Privacy

Black Sparrow sends file paths and activity metadata (focus, idle state, optional cursor line, optional worked line ranges) to your organization's Black Sparrow backend. Source code is never uploaded unless your organization explicitly opts into AI diff analysis.

Development

This package lives in the Black Sparrow monorepo. Install dependencies from the repo root:

npm install

Build

npm run build --workspace=blacksparrow

This cleans dist/, builds @blacksparrow/shared-types, and bundles the extension with esbuild into dist/extension.js.

Other scripts (run from packages/extension or via --workspace=blacksparrow):

Debug in VS Code

1. Open the packages/extension folder (or the monorepo with the extension as the workspace folder).
2. Press F5 (runs the preLaunch build task).
3. In the Extension Development Host window, run Black Sparrow: Sign In.

Launch configuration: .vscode/launch.json → Run Extension.

For local backend development, start the API and dashboard from the repo root (see root README), then sign in against your local instance.

Package for distribution

npm run package --workspace=blacksparrow

Upload the generated .vsix to the VS Code Marketplace. See MARKETPLACE.md for listing copy and release notes.

Project Structure

packages/extension/
├── src/
│   ├── extension.ts           # Activation entry point
│   ├── blacksparrowContext.ts # Auth, WebSocket, presence, UI orchestration
│   ├── auth/                  # Sign-in, tokens, URI handler
│   ├── config/                # Client config from server
│   ├── git/                   # Repo detection, branch watch, pre-commit
│   ├── presence/              # File tracking, idle detection
│   ├── transport/             # REST API and WebSocket clients
│   └── ui/                    # Status bar, sidebar, decorations, locks
├── dist/extension.js          # Bundled output (esbuild)
├── esbuild.mjs
├── package.json
└── CHANGELOG.md

Related Documentation

• Monorepo README — Full stack setup (API, dashboard, Docker)
• MARKETPLACE.md — Marketplace listing text
• CHANGELOG.md — Release history
• docs/ — Runbooks and operational docs

License

Proprietary — CerebroX Technologies. See LICENSE.