Gnosys Hive

Hive coordinates multiple developers and AI coding agents working in the same Git repository.

It protects files before and during edits, keeps connected worktrees synchronized, shows who owns what, and gives AI agents live collaboration context so they do not blindly overwrite each other.

What Hive Solves

AI coding agents are fast, but they are usually unaware of other agents and teammates working in the same repo. Two agents can edit the same file, miss each other's changes, produce different local Git states, or leave completed work stranded on one machine.

Hive adds a live coordination layer on top of Git:

• File ownership: active work is reserved before other agents can safely touch it.
• Busy-file visibility: every connected user sees protected and blocked files.
• Worktree sync: dirty files, deletes, and repair overlays are synchronized across machines.
• Git health: every connected worktree reports branch, HEAD, upstream, dirty files, and sync status.
• Agent context: generated instructions tell agents which files are protected, which files are blocked, and how to claim files before editing.
• Automatic commit and release: Hive commits protected files after they stop changing, pushes them, releases locks, and lets clean machines fast-forward.

Git remains the source of committed truth. Hive coordinates the live uncommitted workspace state between people and agents.

Key Features

Live File Protection

Hive reserves files for the active task when an edit starts or an agent explicitly claims a file. It watches text changes, filesystem writes, deletes, and Git dirty state.

Protected files appear under Your Protected Files. Files owned by other tasks appear under Busy Files.

When an edit overlaps another active task, Hive denies the ownership request and surfaces the conflict instead of silently allowing two agents to fight over the same file.

Continuous Dirty-File Reconciliation

Hive scans Git changes continuously while the session is active. If a file becomes dirty and a normal editor event was missed, Hive still catches it, claims it, syncs it, and keeps it protected until the file is clean or committed.

This covers common agent behavior where file writes happen through shell commands, patches, generated files, or external tools rather than normal VS Code text-edit events.

Hive also records a startup dirty baseline. Files that were already dirty before Hive started still appear in Git Sync, but they are not treated as active protected work unless they change again or an agent explicitly claims them.

Automatic Commit, Push, and Release

Hive automatically commits protected files after a short quiet window with no further protected-file changes. The commit includes only files owned by the active Hive task, not unrelated local dirt or generated Hive context files. If a protected file cannot be committed, Hive releases the lock after the quiet window so the file does not stay busy forever.

Before reporting Git Sync, Hive also tries to converge the local Git state: commit local changes, push local commits, fast-forward clean worktrees, and rebase/push when a branch has both local and upstream commits.

After the auto-commit, Hive pushes the branch when possible, releases the file claims, refreshes Git Sync, and clean connected machines can fast-forward to the same commit.

This keeps the normal loop hands-free:

• agent edits a protected file
• Hive syncs the dirty file to the session
• Hive waits for the edit burst to settle
• Hive commits and pushes the protected files
• Hive releases the busy locks
• other clean machines pull the same commit

Cross-Machine Worktree Sync

Hive synchronizes live dirty work across connected machines:

• changed file contents
• deleted files
• active dirty-file hashes
• per-machine dirty file counts
• repair overlay for missed websocket events

The hosted Hive server keeps a canonical dirty-file overlay. If a client misses a change or delete event, it can repair itself from the overlay during the next sync pass.

Git Sync Status

Each connected machine reports a worktree manifest:

• repository root
• branch
• HEAD commit
• upstream branch
• upstream commit
• ahead/behind counts
• dirty file list
• file hashes

The sidebar shows each machine in Git Sync with the user, agent, workspace, branch, commit, change count, and a status such as:

• synced
• syncing

Hive treats dirty, ahead, behind, diverged, branch-mismatched, and out-of-sync Git states as repair work. Those states are not shown as final status labels; Hive reports syncing while it is trying to restore the machine to the shared commit.

Agent Instructions and Guard Commands

Hive writes generated collaboration context into the workspace so AI agents can see the current coordination state.

Generated files include:

• .hive/agent-context.md
• .hive/session.json
• .hive/file-guard.mjs
• managed Hive sections in AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md

Agents can explicitly claim and release files:

node .hive/file-guard.mjs claim src/index.ts
node .hive/file-guard.mjs release src/index.ts

Local Session Hosting

Hive can host a collaboration session from VS Code. The extension starts the local Hive server, exposes an invite URL, and lets teammates join from another machine on the same network or Tailscale.

The server is bundled into the extension package, so extension updates also carry the current Hive protocol and server behavior.

Typical Workflow

1. Install Hive on every machine that will participate.
2. Open the same Git repository in VS Code.
3. One user runs Hive: Host Session.
4. Share the invite URL shown in the Hive sidebar.
5. Other users run Hive: Join Session and paste the invite URL.
6. Start coding or running agents normally.
7. Watch Your Protected Files, Busy Files, and Git Sync in the sidebar.
8. Let Hive auto-commit and release protected work after each settled edit burst, or use Hive: Commit Now to force the fallback path.

Commands

• Hive: Host Session starts a local Hive server and copies/shows an invite URL.
• Hive: Join Session connects this workspace to a teammate's Hive session.
• Hive: Start Working connects to the configured Hive server and starts protection.
• Hive: Commit Now manually validates ownership, tries to commit the current task workflow, and releases protected files even if Git cannot create the commit. Normal work is committed automatically.
• Hive: Copy Invite Link copies the current hosted session invite URL.
• Hive: Refresh refreshes snapshot, Git sync, and generated agent context.
• Hive: Stop Session leaves or stops the current Hive session.

Settings

hive.serverUrl

Default: http://127.0.0.1:8787

The Hive collaboration server URL. This is set automatically when hosting or joining a session.

hive.userDisplayName

Default: empty

Optional display name shown to teammates. If empty, Hive uses the local OS username.

hive.defaultAgentProvider

Default: codex

Provider label used for the connected agent identity. Supported labels include codex, claude, gemini, copilot, cursor, windsurf, and custom.

hive.autoStart

Default: false

Automatically starts protecting the workspace when the configured Hive server is reachable.

hive.autoFastForwardGit

Default: true

Automatically fetches and fast-forward pulls while the local worktree has no local changes.

Hive does not auto-pull dirty worktrees because doing so could collide with active human or agent edits.

hive.autoCommitProtectedChanges

Default: true

Automatically commits Hive-protected files after they stop changing.

hive.autoCommitQuietMs

Default: 1000

Milliseconds of quiet time before Hive creates an automatic commit. Lower values commit more aggressively; higher values batch larger edit bursts.

hive.autoPushGit

Default: true

Automatically pushes Hive auto-commits to the current branch upstream. If the branch has no upstream but origin exists, Hive sets origin/<branch> as the upstream.

Requirements

• VS Code 1.105.0 or newer.
• Git installed and available on PATH.
• All collaborators should open the same Git repository.
• All collaborators should run the same current Hive extension version.
• Machines must be able to reach the host URL, typically through the same LAN or Tailscale.

Important Notes

• Hive coordinates uncommitted workspace state; it does not replace Git.
• Hive auto-commits only files protected by the active Hive task.
• The local hosted server stores session state in memory.
• If the hosting machine stops the session, connected clients leave the session.
• Mixed old and new Hive clients can drift because older versions may not understand newer protocol messages.
• Dirty worktree repair is conservative. If the local active task owns a changed file, Hive republishes that local work instead of overwriting it with another machine's overlay.

Current Status

Hive is built for teams experimenting with multiple developers and AI coding agents in one repository. It focuses on practical coordination: protect files, show conflicts, synchronize dirty work, and keep agents aware of the live collaboration state.