⚡ HackPair

Real-Time Code Collaboration for Hackathon Teams

No cloud. No dashboard. No Docker. Just your IDE and your team.

🔥 What is HackPair?

HackPair is a self-hosted, real-time code collaboration tool built for hackathon teams. It lets you and your teammates code together from anywhere — seeing each other's cursors, edits, and files in real-time.

One command to start. One extension to connect. That's it.

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   Leader runs: npx hackpair                             │
│                         ↓                               │
│   Team connects via VS Code extension                   │
│                         ↓                               │
│   Everyone sees each other's code & cursors             │
│                                                         │
└─────────────────────────────────────────────────────────┘

✨ Features

🚀 Quick Start

Prerequisites

• Node.js 18+ installed on leader's machine
• VS Code installed on all team members

1. Leader: Start the Server

# Clone or download HackPair
git clone https://github.com/Hussaincodes01/hackpair.git
cd hackpair

# Start the server
npx tsx packages/server/src/index.ts

You'll see:

╔══════════════════════════════════════╗
║         HackPair v0.1.0             ║
║   Real-time code collaboration      ║
╚══════════════════════════════════════╝

Server running at:
  → http://192.168.1.100:3001

Share this URL with your team.
They connect via the VS Code extension.

Press Ctrl+C to stop.

Copy the URL — your team needs it to connect.

2. Team: Install the Extension

Download hackpair-0.1.0.vsix from the leader, then:

code --install-extension hackpair-0.1.0.vsix

3. Team: Connect & Join

1. Open VS Code
2. Click the HackPair icon in the sidebar (left panel)
3. Click "Connect" → Enter the server URL your leader shared
4. Click "Join" → Enter your display name
5. Click "Create Room" (if you're the first) or enter the invite code

Done! You're now collaborating in real-time.

🎯 How It Works

     ┌──────────────┐         ┌──────────────┐
     │   Alice's    │         │   Bob's      │
     │   VS Code    │         │   VS Code    │
     └──────┬───────┘         └──────┬───────┘
            │                         │
            │    ┌──────────────┐     │
            └────┤  HackPair    ├─────┘
                 │   Server     │
                 │  (Leader's   │
                 │   Machine)   │
                 └──────────────┘

Each member:

1. Connects to the leader's server via WebSocket
2. Broadcasts their cursor position and code edits
3. Receives updates from all other members
4. Sees colored cursors for each teammate

🎨 What You'll See

Sidebar Panel

┌─────────────────────────┐
│  ⚡ HackPair             │
├─────────────────────────┤
│  🏠 My Team             │
│                         │
│  Invite Code: ABC123    │
│  [Click to copy]        │
│                         │
│  Team Online (3)        │
│  ─────────────────      │
│  🔵 Alice (you)         │
│  🟢 Bob                 │
│  🟡 Charlie             │
│                         │
│  [Leave Room]           │
└─────────────────────────┘

Editor (with teammates)

 1  │ import { createApp } from 'vue';
 2  │ import App from './App.vue';
 3  │ ←── 🟢 Bob is here
 4  │ const app = createApp(App);
 5  │ app.mount('#app');
 6  │

🌐 Network Options

Same WiFi (Local Network)

Leader shares their local IP (shown in terminal):

http://192.168.1.100:3001

Over Internet (Remote Team)

Use ngrok to expose your server:

npx ngrok http 3001

This gives you a public URL like:

https://abc123.ngrok.io

🛠️ Project Structure

hackpair/
├── packages/
│   ├── server/          # Fastify + Socket.io server
│   │   └── src/
│   │       ├── index.ts         # Server entry point
│   │       ├── database.ts      # SQLite (sql.js, zero native deps)
│   │       ├── routes/api.ts    # REST API
│   │       └── socket/handler.ts # Real-time WebSocket handler
│   │
│   ├── extension/       # VS Code extension
│   │   └── src/
│   │       ├── extension.ts     # Main activation
│   │       ├── socket-client.ts # WebSocket client
│   │       ├── cursor-manager.ts # Remote cursor display
│   │       └── sidebar.ts       # Webview sidebar panel
│   │
│   ├── shared/          # Shared types & schemas
│   └── cli/             # CLI packaging
│
├── packages/extension/
│   └── hackpair-0.1.0.vsix  # Installable extension
│
└── package.json

⚙️ Tech Stack

🔧 Development

# Clone the repo
git clone https://github.com/Hussaincodes01/hackpair.git
cd hackpair

# Install dependencies
npm install

# Build shared types
npm run build --workspace=packages/shared

# Start server in dev mode
npm run dev --workspace=packages/server

# Build extension
npm run build --workspace=packages/extension

📋 API Reference

REST Endpoints

WebSocket Events

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

📄 License

MIT License — see LICENSE for details.