CodeWaggle

A VSCode extension for code collaboration with tags, mentions, and permalinks for teams and organizations.

Your Data, Your Control

All CodeWaggle collaboration data stays in your organization's GitHub repository. You have complete control over who can access your team's discussions, tags, and code references.

• Data Sovereignty - Your data lives in a repository you own and control
• Standard GitHub Permissions - Use your existing GitHub access controls
• No Third-Party Storage - We never store your collaboration data on our servers
• Audit Trail - Full git history of all changes through your organization

Each project gets its own branch in your organization's CodeWaggle data repository (e.g., YourOrg/YourProject-CodeWaggle), making it easy to manage access and maintain separation between projects.

Features

Comments with Permalinks

• Right-click on any code selection to add a comment
• Automatically generates GitHub permalinks for exact code references
• Comments are tracked with unique IDs (±±XXXXXXXX±±) for easy reference

Tags for Organization

• Use #tag to categorize comments into topics
• Personal tags (user#tag) for individual research
• Share tags with the team by removing the owner prefix
• Tag documents are markdown files that compile all related references

Mentions for Collaboration

• Use @username to notify team members
• Use @copilot or @agent to create GitHub issues for AI assistants
• Mention files with @path/to/file.ts for cross-references

@ mentions do not invite users to the GitHub project. They are stored in CodeWaggle data and can trigger in-app notifications when that data is synced; the extension does not call GitHub’s APIs to add collaborators or send invites. User mentions are restricted to the pattern @[a-zA-Z0-9_.-]+ (no spaces). Mentioned usernames are ensured in the local users.json (for autocomplete and future integrations) but are not validated against GitHub.

Inviting collaborators to the CodeWaggle data repo is separate from @mentions—see Invite Collaborators below.

Invite Collaborators

Invite your project repository’s GitHub collaborators to the CodeWaggle data repo so they can sync and collaborate. This uses GitHub CLI (gh).

• When: After you run Initialize CodeWaggle (when remote sync is enabled), or when the data repo is first created. You can also run CodeWaggle: Invite collaborators to CodeWaggle data from the command palette at any time to re-run the flow (e.g. after adding new project collaborators).
• Flow: The extension lists collaborators from the current project repo; you choose to invite all or select specific people. You can add an optional message to share with your team (e.g. in Slack or email). The GitHub invite email itself cannot include custom text via API, but the extension lets you copy your message to the clipboard to paste elsewhere.
• Users not in the project repo: People who are not collaborators on the project repository can only receive email updates (when implemented) for comments or tags they are @mentioned in. They do not get full access to the data repo unless you add them as project collaborators and then invite them to the data repo.
• Git identity (GCM "select user"): When team members run init or sync, Git Credential Manager (GCM) may prompt to select a user. To avoid that, ensure .waggle/users.json in the workspace includes each collaborator with username and email (e.g. gitUsers: { "alice": { "email": "alice@example.com", ... } }). The extension uses this list so the user can pick their identity once; it then sets user.name and user.email in the local sync repo's git config so GCM doesn't keep prompting during install/init and pull/push.

Real-time Sync (Independent of Project Commits)

• CodeWaggle data syncs automatically without requiring project commits
• Collaboration data stored in a separate branch in your org's repository
• Toast notifications for mentions, tag updates, and code changes
• Status bar shows unread notification count and sync status

Tag Explorer

• Browse all tags in the sidebar
• View references grouped by tag
• Quick navigation to tagged code

Getting Started

1. Install the extension
2. Open a project with a git repository and GitHub remote
3. Run CodeWaggle: Initialize CodeWaggle from the command palette
   • Multi-root workspace: You’ll be prompted to choose which project(s) to enable (one project or All projects)
4. Start adding comments with right-click → "Comment (Waggle)"

Usage

Adding a Comment

1. Select code (or place cursor on a line)
2. Right-click → "Comment (Waggle)" or use Command Palette
3. Enter your comment with optional @mentions and #tags
4. Select comment type (NOTE, REVIEW, TODO, FIXME)
5. Comment is added inline and indexed

Example Comment

const user = await getUser(id); // NOTE ±±A1B2C3D4±± @alice check error handling #security

Tag Documents

Tags create markdown documents in .codewaggle/tags/:

# Tag: security

## Overview
Security-related code review items

## References

### 2024-02-05 - @bob
- [src/auth/login.ts:45](https://github.com/.../blob/abc123/src/auth/login.ts#L45) - ±±A1B2C3D4±±
  > Potential SQL injection vulnerability

Data Storage & Privacy

Your Organization's Repository

CodeWaggle stores collaboration data in your organization's GitHub repository, not on any third-party servers. When you initialize CodeWaggle for a project, it creates a dedicated branch in your data repository:

Branch: YourOrg/YourProject-CodeWaggle

You control access - use standard GitHub repository permissions to manage who can view and edit your team's discussions.

Data Structure

[project]-codewaggle-data repository (your org; one per project or shared)
├── Branch: YourOrg/ProjectA-CodeWaggle
│   ├── .waggle/
│   │   ├── index.json      # All comment entries
│   │   ├── users.json      # User configuration
│   │   └── config.json     # Project settings
│   ├── tags/               # Tag documents (*.md)
│   └── chat/               # Chat logs (kept local)
├── Branch: YourOrg/ProjectB-CodeWaggle
│   └── ...

Why Separate Storage?

• Sync Without Commits - Team discussions sync instantly without polluting your project's git history
• Access Control - Manage CodeWaggle access separately from your codebase
• Clean Separation - Keep collaboration metadata separate from your production code
• Compliance Ready - All data in repositories you own and audit

Workspaces and remote sync

Multiple windows (one project per window)

• Each window runs its own instance of CodeWaggle. VS Code/Cursor uses a separate extension host per window, so you do have multiple instances running when you have multiple windows open.
• Each instance syncs to the correct project. Window A (e.g. glyde_unity) and Window B (e.g. GLYDEBuddyPro) each have a single workspace folder. Each creates one RemoteSyncManager for that folder and syncs to .codewaggle-sync/[project]/.waggle (e.g. Glyde-Inc_GLYDE-Unity and Glyde-Inc_GLYDEBuddyPro). There is no cross-talk; each window only sees and syncs its own project.

Single window with multiple workspace folders (multi-root)

• Initialize: When you run CodeWaggle: Initialize CodeWaggle in a multi-root workspace, you are prompted to select which project(s) to enable: All projects or a single workspace folder. This creates .codewaggle (and .waggle/config.json with autoSync: true) only in the selected folder(s).
• Sync: The extension creates one RemoteSyncManager per folder that has .codewaggle/.waggle/config.json with autoSync: true. Each project’s data is copied to a local shadow under .codewaggle-sync/[project]/ and synced to its own branch in your org’s data repo (e.g. Glyde-Inc_GLYDE-Unity-CodeWaggle, Glyde-Inc_GLYDEBuddyPro-CodeWaggle).
• Commands: Sync Now, Push Data, and Pull Data run for all such projects. Show Sync Status lists each project’s branch and status.
• In-memory state: Index, users, and tags are still loaded from the first workspace folder only; other folders’ data is on disk and synced via their own managers. For full per-project UI state, use one window per project.

Configuration

Commands

Team Collaboration

How It Works

1. Your organization uses a CodeWaggle data repository (e.g., YourOrg/YourProject-codewaggle-data; with an org URL we create [project]-codewaggle-data)
2. Each project gets its own branch (e.g., YourOrg/backend-CodeWaggle)
3. Team members sync automatically without affecting the main project repository
4. You control access using standard GitHub repository permissions

Privacy & Security

Sharing Tags

1. Create a personal tag: Comment with #mytopic creates yourname#mytopic.md
2. When ready to share, the tag document is renamed to mytopic.md
3. Shared tags are visible to all collaborators with repository access

Setting Up Your Organization's Data Repository

1. Create a repository in your GitHub organization (e.g., your-org/your-project-codewaggle-data), or set the org URL and let CodeWaggle create [project]-codewaggle-data
2. Set permissions - grant access to team members who should collaborate
3. Configure the extension - set codewaggle.remoteSyncRepo to your repository URL
4. Initialize projects - each project will create its own branch automatically

// VS Code settings.json - use a repo URL or an org URL (we create [project]-codewaggle-data)
{
  "codewaggle.remoteSyncRepo": "https://github.com/your-org/your-project-codewaggle-data.git"
}
// Or: "https://github.com/orgs/your-org" to auto-create your-project-codewaggle-data

Licensing

CodeWaggle is free for teams up to 10 users (honor system).

For larger teams, consider upgrading to a paid tier (coming soon).

Support

• GitHub Issues
• Documentation

Troubleshooting

Where to find logs

• Extension logs: View → Output, then choose CodeWaggle in the dropdown. This shows remote sync, repository creation, and other extension activity. If repository creation fails, the full gh command and error are written here.
• Extension Host log (all extension console output): Developer: Open Logs Folder from the Command Palette, then open the exthost*.log file for the current session.
• Debug mode: Press F5 to run the extension in Development Host; the Debug Console and Developer Tools (Help → Toggle Developer Tools) will show console.log/console.error from the extension.

Publishing

To release a new version:

1. Run npm run publish (bumps patch version, packages, publishes to Visual Studio Marketplace, then pushes the version commit and tag).
2. The Open VSX (Cursor, VSCodium, etc.) publish runs in GitHub Actions when the tag is pushed. Add repository secret OVSX_PAT from open-vsx.org user settings (sign in with GitHub and the Publisher Agreement first).

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

CodeWaggle – Proprietary License: see LICENSE file for details.

Origins

In the name CodeWaggle - "Waggle" refers to one of the ways that bees, communicate - a waggle dance!