Contributing to Pixel Agents

Contributing to Pixel Agents

Thanks for your interest in contributing to Pixel Agents! All contributions are welcome — features, bug fixes, documentation improvements, refactors, and more.

This project is licensed under the [MIT License](LICENSE), so your contributions will be too. No CLA or DCO is required.

Getting Started

Prerequisites

• Node.js (v22 recommended)
• VS Code (v1.105.0 or later)

Setup

git clone https://github.com/pablodelucca/pixel-agents.git
cd pixel-agents
npm install
cd webview-ui && npm install && cd ..
cd server && npm install && cd ..
npm run build

Then press **F5** in VS Code to launch the Extension Development Host.

Development Workflow

For development with live rebuilds, run:

npm run watch

This starts parallel watchers for both the extension backend (esbuild) and TypeScript type-checking.

**Note:** The webview (Vite) is not included in `watch` — after changing webview code, run `npm run build:webview` or the full `npm run build`.

Running the Mocked Pixel Agent

You can run the mocked Pixel Agent web app either from the CLI or from VS Code tasks.

Option 1: CLI

From the repository root:

cd webview-ui
npm run dev

Vite will print a local URL (typically `http://localhost:5173`) where the mocked app is available.

Option 2: VS Code Run Task

1. Open the command palette and run Tasks: Run Task.
2. Select Mocked Pixel Agent Dev Server.
3. Open the local URL shown in the task terminal output (typically http://localhost:5173).

Project Structure

Directory	Description
src/	Extension backend -- Node.js, VS Code API
server/	Standalone HTTP server, hook installer, and test suite (Vitest)
webview-ui/	React + TypeScript frontend (separate Vite project)
scripts/	Asset extraction and generation tooling
assets/	Bundled sprites, catalog, and default layout

Code Guidelines

Constants

**No unused locals or parameters** (`noUnusedLocals` and `noUnusedParameters` are enabled). All magic numbers and strings are centralized — don't add inline constants to source files:

• Extension backend: src/constants.ts
• Webview: webview-ui/src/constants.ts
• CSS variables: webview-ui/src/index.css :root block (--pixel-* properties)

UI Styling

The project uses a pixel art aesthetic. All overlays should use:

• Sharp corners (border-radius: 0)
• Solid backgrounds and 2px solid borders
• Hard offset shadows (2px 2px 0px, no blur) — use var(--pixel-shadow)
• The FS Pixel Sans font (loaded in index.css)

These conventions are enforced by custom ESLint rules (`eslint-rules/pixel-agents-rule