Cursor Pixel Bridge

A local Cursor / VS Code extension that represents real editor activity as a pixel-art office.

Screenshot

<! -->

Features

• Runs locally inside Cursor or VS Code.
• Captures editor activity through public VS Code / Cursor extension APIs: active editor changes, document edits, document saves, and window focus changes.
• Derives the current state as idle, reading, typing, done, or away.
• Provides an integrated visual panel with a bundled pixel-art office scene.
• Shows the main agent from real editor telemetry collected by the extension.
• Includes secondary visual agents whose states are heuristic and derived from the main state.
• Provides a local HTTP/WebSocket bridge package for local consumers on 127.0.0.1:4317.
• Packages the built visual app inside the VSIX under media/visual, so the installed visual panel does not require a separate development server.

Privacy

The current extension is designed for local use. It observes editor events through public VS Code APIs and does not include code paths that send source code to external services.

It does not use cloud services or internal Cursor APIs. The standalone bridge server, when used, serves events and snapshots locally on 127.0.0.1; the packaged visual panel receives snapshots through VS Code Webview messages.

Cursor Pixel Bridge may process the active file name or workspace-relative path locally to derive and display snapshots. That information is not intentionally transmitted outside the machine by the current code.

Requirements

• Cursor or a compatible VS Code build.
• VS Code engine compatibility: ^1.85.0.
• Node.js is not required to install and use the released VSIX. Node.js >=20 is required only for development or building from source.
• Tested currently on macOS. Other systems may work, but have not yet been verified.

Installation

1. Download the VSIX from GitHub Releases.
2. Open Cursor or VS Code.
3. Run Extensions: Install from VSIX... from the Command Palette.
4. Select the downloaded .vsix file.
5. Restart or reload the window if needed.

Usage

1. Open a project in Cursor or VS Code.
2. Open the Command Palette.
3. Run Pixel Bridge: Open Visual Panel.
4. Keep the panel open while you work.

State meanings:

• idle: the editor is focused, but there is no trackable active file.
• reading: the editor is focused with an active file and no recent edit or save event.
• typing: a text document changed within the recent typing window.
• done: a file was saved within the recent done window.
• away: the editor window is not focused.

done represents a short time window after saving. It does not mean the whole task is complete.

Architecture

This repository is a small npm workspace monorepo:

• packages/extension: the Cursor / VS Code extension, command registration, editor event capture, privacy-aware file path handling, and Webview panel.
• packages/bridge-server: a local HTTP/WebSocket bridge for development and local consumers.
• packages/visual-app: the React pixel-art visual app that is built and copied into the extension package.

Installed VSIX flow:

Editor -> extension -> semantic snapshot -> Webview visual.

Local bridge flow:

Editor-like events -> local bridge -> semantic snapshot -> WebSocket consumers / visual app.

Development

Install dependencies:

npm install

Build all workspaces and copy the visual app into the extension:

npm run build

Package the VSIX:

npm run package:vsix

Verify generated and packaged files:

npm run verify:package

Other available scripts

| npm test | Runs the test suite. | | npm run test:ci | Runs the test suite in CI mode. | | npm run check:ci | Runs the full validation pipeline: build, tests, VSIX packaging, package verification, and dependency audit. | | npm run bridge | Starts the local bridge server for development. | | npm run visual | Starts the visual app development server. | | npm run clean | Removes generated build artifacts. | | npm run audit:ci | Checks dependencies for known vulnerabilities. |

Current Limitations

• Secondary agent states are heuristic.
• reading means an active file is present without recent edit/save activity; it does not detect actual reading or scrolling.
• typing and done are based on short time windows after edit and save events.
• Compatibility testing is currently limited.
• This is an experimental v0.0.1 project.
• Configuration and internal APIs may change.

Roadmap

• Agent configuration.
• More scenes and animations.
• Better cross-platform compatibility.
• Installation and diagnostics improvements.

License

This project is licensed under the MIT License.

See THIRD_PARTY_NOTICES.md for visual asset provenance and notices.

Contributions

Issues and pull requests are welcome. The project is still in an early stage, so behavior and structure may change.

Project Status

Experimental public preview — v0.0.1