Viscord 👥

A VS Code extension that shows your GitHub friends' real-time coding status! See what your followers and following are working on, all within VS Code.

Download from VS Code Extension Marketplace

To test locally:

Installation

####From Marketplace

Open VS Code
Go to Extensions (Cmd+Shift+X or Ctrl+Shift+X)
Search for "Viscord"
Click Install

From Source

git clone https://github.com/CyberTron957/viscord.git
cd viscord
npm install
npm run compile

First Launch

Authenticate: On first launch, you'll be prompted to sign in with GitHub
Grant Permissions: Allow access to your email and profile
Start Coding: Your status will automatically update based on your activity!

⚙️ Configuration

Access settings via Cmd+, (Mac) or Ctrl+, (Windows/Linux) and search for "viscord":

{
  "vscode-viscord.visibilityMode": "everyone",
  "vscode-viscord.shareProjectName": true,
  "vscode-viscord.shareLanguage": true,
  "vscode-viscord.shareActivity": true
}

Useful Commands

Reset Extension: vscode-viscord.resetExtension (Full reset)
Clear Cache: vscode-viscord.clearCache (Refresh data)
Sign Out: vscode-viscord.signOutGitHub (Switch to guest)
Connect GitHub: vscode-viscord.connectGitHub
Continue as Guest: vscode-viscord.continueAsGuest

🖥️ Server Deployment

The extension requires a WebSocket server. See DEPLOYMENT.md for secure production deployment instructions using Caddy and HTTPS/WSS.

Quick Local Setup

# Install Redis (optional but recommended)
brew install redis  # macOS
# or: sudo apt install redis-server  # Ubuntu

# Start Redis (in separate terminal)
redis-server

# Compile and start the server
cd server
npm run compile:server
node index.js
 
# Server runs on ws://localhost:8080
# With Redis: Mode will show "Redis Pub/Sub"
# Without Redis: Falls back to "Legacy Broadcast"

Environment Variables

# Copy example and configure
cp .env.example .env

# Key variables:
PORT=8080
REDIS_URL=redis://localhost:6379
USE_LEGACY_BROADCAST=false  # Set to true to disable Redis

Production Deployment

Supports any Linux server (Ubuntu recommended)
Redis for Pub/Sub and caching (optional but recommended)
Secure WSS via Caddy reverse proxy
Automatic SSL with Let's Encrypt
Automatic Backups of database
Includes PM2 process management

📁 Project Structure

viscord/
├── src/
│   ├── extension.ts          # Extension entry point
│   ├── githubService.ts      # GitHub OAuth & API
│   ├── sidebarProvider.ts    # Multi-tab tree view
│   ├── activityTracker.ts    # Activity detection
│   └── wsClient.ts           # WebSocket client (handles delta updates)
├── server/
│   ├── index.ts              # WebSocket server (heartbeats, session resumption)
│   ├── database.ts           # SQLite persistence
│   ├── redisService.ts       # Redis Pub/Sub, caching, sessions
│   └── rateLimiter.ts        # Anti-abuse protection
├── .env.example              # Environment variable template
├── package.json              # Extension manifest
└── tsconfig.json             # TypeScript config

🔧 Development

Prerequisites

Node.js 18+
VS Code 1.80+

Build

npm install
npm run compile

Run Extension

Open in VS Code
Press F5 to launch Extension Development Host
Test the extension in the new window

Run Server

node server/index.js

🧪 Testing

Manual Testing

Start the server: node server/index.js
Launch extension in debug mode (F5)
Sign in with GitHub
Open another Extension Development Host window
Sign in with a different GitHub account that follows/is followed by the first
Both should see each other in their respective tabs

📊 Database Schema

-- Users table
users (github_id, username, avatar, created_at, last_seen)
 
-- Relationships (followers/following)
user_relationships (user_github_id, related_github_id, relationship_type)
 
-- Close friends
close_friends (user_github_id, friend_github_id, added_at)
 
-- Privacy preferences
user_preferences (github_id, visibility_mode, share_project, share_language, share_activity)

🛠️ Troubleshooting

"Failed to connect to WebSocket server"

Ensure the server is running: node server/index.js
Check firewall isn't blocking port 8080
Verify ws://localhost:8080 is accessible
Try Clear Cache command (Cmd+Shift+P -> "Clear Cache")

"GitHub authentication failed"

Clear VS Code's GitHub auth: Cmd+Shift+P → "Sign out of GitHub"
Try again

"No friends showing up"

Ensure your GitHub account has followers/following
Check that they're also using the extension
Verify privacy settings aren't set to "Invisible"
Try Clear Cache command

"Extension behaving strangely"

Use Reset Extension command (Cmd+Shift+P -> "Reset Extension") to wipe all data and start fresh.

📝 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR on GitHub.

🙏 Acknowledgments

Built with VS Code Extension API
Uses Octokit for GitHub API
WebSocket server powered by ws
Database powered by better-sqlite3

📧 Support

🐛 Report bugs: GitHub Issues
💬 Discussion: GitHub Discussions
🌐 Server: https://viscord.bellnexx.com

Made with ❤️ by CyberTron957

Viscord

Install / Use

README