claude-net
A Claude Code plugin that creates a communication network between all VSCode tabs and agents, preventing conflicts and enabling coordination via file-based IPC.
Why claude-net?
When using Claude Code with multiple VSCode tabs on the same project, agents frequently interfere with each other — editing the same files, running duplicate builds, competing for test execution. This leads to wasted time, broken state, and frustrating debugging.
claude-net solves this by providing:
- 🔒 File Locking: Prevents two agents from editing the same file simultaneously
- 🏗️ Build/Test Mutex: Only one agent can build or run tests at a time — others wait or skip
- 💬 Inter-Agent Messaging: Agents communicate to coordinate work and avoid conflicts
- 📋 Shared Error Logs: Build/test errors are shared across all agents — no duplicate failures
- 🔄 Session Recovery: Full action history enables recovery after crashes (blue screens, power loss)
- 🕵️ Conflict Detection: Automatic detection and blocking of conflicting operations via hooks
- 📊 Network Status: Real-time visibility into what every agent is doing
How it works: claude-net installs as a global Claude Code plugin with lifecycle hooks. Every agent registers on session start, updates status on every action, and checks for conflicts before editing files or running commands. All communication happens through JSON files in ~/.claude-net/ — no database, no server, no external dependencies.
Installation
Option 1: Install from npm (Recommended)
# One-time setup — install plugin globally
npx claude-net install
# Verify installation
npx claude-net status
# Start using it — reload Claude Code or open new tab
The plugin will be installed to ~/.claude/plugins/claude-net/ and activated automatically.
Option 2: Install from Local Directory
If you're developing locally or want to test an unpublished version:
# Add the local marketplace
claude plugin marketplace add /path/to/claude-net
# Install the plugin
claude plugin install claude-net
# Test via reload or new tab
Option 3: Test Without Installing
To test the plugin without installation:
# Run Claude Code with plugin loaded
claude --plugin-dir /path/to/claude-net
Quick Start
# After installation, use the CLI to monitor:
npx claude-net status # View active agents
npx claude-net errors # Check build/test errors
npx claude-net logs # See action history
npx claude-net clean # Remove stale agents
# Inside Claude Code, use slash commands:
/claude-net:status # Show network status
/claude-net:logs # Show recent actions
After installation, every Claude Code session automatically joins the network. No per-project configuration needed — the plugin works globally across all projects and tabs.
Architecture
How Agents Communicate
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ VSCode Tab 1│ │ VSCode Tab 2│ │ VSCode Tab 3│
│ Claude Agent│ │ Claude Agent│ │ Claude Agent│
│ + subagents │ │ + subagents │ │ + subagents │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ ┌────────────┴────────────┐ │
└────┤ ~/.claude-net/ ├────┘
│ │
│ agents/ → registry │
│ locks/ → file locks│
│ messages/ → inbox │
│ errors/ → shared log│
│ history/ → recovery │
└─────────────────────────┘
All state is stored as JSON files in ~/.claude-net/. Each agent reads and writes atomically (temp file + rename) to prevent corruption on Windows and Linux.
Plugin Integration