Docs — Software Traffic Cop

🤖 Built for AI-to-AI coordination

When you run multiple Claude sessions — or any AI agents — against the same codebase, each session is an island. It has no idea what the others are doing. Traffic Cop gives every session a shared view of who has what locked, what builds are running, and what's safe to touch. The agents coordinate through the cop, not through you.

Installation (Windows — recommended)

The MSI installer is the recommended path for Windows. It takes care of everything in one step: installs the server, registers the Windows service, opens the firewall, and adds the tray app to Startup.

1

Download the installer

Grab the latest trafficcop-windows-installer-*.msi from the releases page.
↓ Download Latest MSI
2

Run the installer

Double-click the MSI. Windows SmartScreen may show a warning on first run — click More info → Run anyway. The installer will ask for admin rights (required for the Windows service).

Click through: Welcome → License Agreement → Role Setup.
3

Choose your role

The Role Setup dialog is the only configuration step that requires user input. Everything else is automatic.

Traffic Cop — Role Setup

⭐ Primary

This machine is the source of truth. Other machines sync from here. Choose this on your main dev machine.

Secondary

Connects to the primary and syncs its state. Choose this on all other machines.

This machine's LAN address (e.g. 192.168.1.105:7734)

💡 Solo developer?

Just set yourself as Primary. The LAN address field matters most — set it to your machine's local IP followed by :7734. You can find your IP with ipconfig in PowerShell.
4
Click Install

The installer will:
- Copy trafficcop.exe and trafficcop-tray.exe to C:\Program Files\SoftwareTrafficCop\
- Register and start the SoftwareTrafficCop Windows service (auto-start, survives reboots)
- Open firewall rules: TCP 7734 (server + dashboard) and UDP 7735 (LAN discovery)
- Add the tray app to Windows Startup for the current user
- Auto-configure claude_desktop_config.json if Claude Desktop is installed
- Deploy the Traffic Cop Cowork skill to all open workspaces
When installation finishes, the status dashboard opens at http://localhost:7734/ and the 🚦 tray icon appears.

Configure

The installer writes your role and LAN address during setup. For most teams that's all you need. You can always change settings later by editing the config file.

Config file location

C:\ProgramData\SoftwareTrafficCop\trafficcop.config.json

Default config

trafficcop.config.json

{
  "my_addr": "192.168.1.105:7734",   // this machine's LAN IP + port
  "is_primary": true,              // PRIMARY or SECONDARY role
  "peers": [],                        // auto-populated via UDP discovery
  "lock_ttl_minutes": 60,           // how long a checkout lives before auto-expire
  "stale_session_minutes": 30         // session timeout if heartbeat stops
}

Applying changes

Edit the config file then restart the service for changes to take effect:

Restart-Service SoftwareTrafficCop

📝 Note

The Edit Configuration shortcut in your Start Menu opens the config file directly in Notepad.

Verify it works

Once the service is running, the fastest way to confirm everything is working is to ask Claude to call tc_get_status.

1

Open Cowork (or Claude Desktop)

Start a new session in Cowork mode or Claude Desktop. The Traffic Cop MCP tools should load automatically.
2

Ask Claude to check status

Type this in your chat:

# In Claude / Cowork: Call tc_get_status and show me what you see.
3

Expect a green response

A healthy server returns something like:

{ "server_version": "0.5.47", "uptime": "2m 14s", "active_sessions": 1, "locks": [], "builds": [], "signal": "GREEN", "message": "🟢 All clear. No active locks or builds." }

If you see GREEN signal — you're done. Traffic Cop is live.

Check the dashboard

You can also verify by opening the web dashboard at http://localhost:7734/. It shows live lock state, build history, and connected peers — refreshed every 3 seconds.

⚠️ Tools not showing up?

If Claude doesn't see the tc_* tools, check that Claude Desktop's config was updated. See Claude Desktop config below, or restart Claude Desktop and try again.

Cowork setup

The tray app handles skill deployment automatically. Within 30 seconds of opening any Cowork workspace, Traffic Cop deploys its skill and MCP tools — no drag-and-drop or manual plugin install required.

📝 One-time project setup (per project)

Cowork doesn't have a pre-tool hook, so you need to add one line to each project's Project Instructions to make checkout automatic. Open your project settings in Cowork and paste this:

At the start of every session, before any other work: call tc_register with the project name to get a session_id. Then before every file create, edit, or write, call tc_checkout with that session_id and wait for APPROVED. Call tc_checkin when done. Do not use Write or Edit tools without a prior tc_checkout approval. The software-traffic-cop MCP tools are available for this.

This goes in Settings → Project Instructions for each project where you want Traffic Cop enforced. You only need to do this once per project.

What the tray deploys automatically to every workspace:

The software-traffic-cop skill into the skills directory (so it appears in Claude's skill list)
Plugin registration in rpm/manifest.json so tc_* MCP tools load
The checkout rules into each project's memory so Claude is reminded every session

✅ Confirm it's working

Start a new Cowork conversation and say "make a test file." Claude should call tc_register then tc_checkout before writing anything. If it skips straight to writing, check that the project instruction is saved.

Primary server

In a multi-machine team, one machine should be designated as Primary. The primary is the single source of truth for all lock state and build history. All other machines are Secondary — they sync from the primary on startup and push updates to it in real time.

To designate a machine as primary, set "is_primary": true in its config file and restart the service. The dashboard shows a ★ PRIMARY badge on the primary machine.

📝 Solo setup

If you're a solo developer, you have one machine and it should be "is_primary": true. No further setup needed.

Adding peers

Install Traffic Cop on each team machine the same way (download MSI → run → choose Secondary role → set LAN address). Secondary machines automatically sync from the primary when they start up.

You can see all connected peers in the dashboard under Peers, or by calling tc_get_status.

Auto-discovery

Traffic Cop uses UDP broadcast on port 7735 to find peers automatically. Every 30 seconds, each node announces itself on the local subnet. Other nodes hear the broadcast and add the sender to their peer list — no manual configuration required.

All you need to set is my_addr (this machine's IP:7734). The peers list in the config file is managed automatically — you can leave it empty.

📝 Subnet requirement

UDP broadcast works only within the same LAN subnet (e.g. 192.168.1.x). Machines on different subnets or VLANs need manual peer entries in the config.

macOS & Linux

Download the binary for your platform from the releases page and run it directly. No installer — manual setup only.

macOS

Linux

# Download (Apple Silicon)
curl -Lo trafficcop https://github.com/damondins/software-traffic-cop-releases/releases/latest/download/trafficcop-macos-arm64

# Make executable
chmod +x trafficcop

# Run as server
./trafficcop --serve

# Or run in background
nohup ./trafficcop --serve > trafficcop.log 2>&1 &

For Intel Macs, use trafficcop-macos-amd64. macOS Gatekeeper may require you to right-click → Open the first time, or run xattr -d com.apple.quarantine trafficcop.

# Download (x86_64)
curl -Lo trafficcop https://github.com/damondins/software-traffic-cop-releases/releases/latest/download/trafficcop-linux-amd64

# Make executable
chmod +x trafficcop

# Run as a systemd service (optional)
sudo mv trafficcop /usr/local/bin/
sudo tee /etc/systemd/system/trafficcop.service <<'EOF'
[Unit]
Description=Software Traffic Cop
After=network.target

[Service]
ExecStart=/usr/local/bin/trafficcop --serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now trafficcop

The config file is written to ~/.config/SoftwareTrafficCop/trafficcop.config.json on first run. Edit it to set my_addr and is_primary, then restart the server.

Claude Desktop config

The MSI installer updates claude_desktop_config.json automatically. If you're on macOS/Linux or the auto-config didn't run, add this entry manually:

claude_desktop_config.json — Windows

{
  "mcpServers": {
    "software-traffic-cop": {
      "command": "C:\\Program Files\\SoftwareTrafficCop\\trafficcop.exe",
      "args": []
    }
  }
}

claude_desktop_config.json — macOS/Linux

{
  "mcpServers": {
    "software-traffic-cop": {
      "command": "/usr/local/bin/trafficcop",
      "args": []
    }
  }
}

The config file lives at:

Platform	Path
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Restart Claude Desktop after saving for the changes to take effect.

MCP tool reference

Once connected, Claude has access to these 9 tools. The Cowork skill calls them automatically at the right moments — you rarely need to invoke them manually.

tc_register

Register a new AI session with the cop. Called automatically when a Cowork session starts. Returns a session_id used in all subsequent calls.

Params: session_name, agent_type

tc_heartbeat

Keep a session alive. The cop drops sessions that stop sending heartbeats after the configured timeout (default 30 min) and releases their locks.

Params: session_id

tc_checkout

Lock one or more files or directories before editing. Returns APPROVED or CONFLICTS. When CONFLICTS, Claude explains the situation and suggests alternatives.

Params: session_id, files (comma-separated paths), purpose

tc_checkin

Release file locks after editing is complete. Always called when a session is done with its files — whether the edit succeeded or failed.

Params: session_id, files

tc_request_build

Request a build slot (ios, apk, or web). Returns GO (clear to build) or HOLD (another session holds a conflicting lock or is already building). Automatically locks the build-critical files for the duration.

Params: session_id, build_type

tc_build_complete

Signal that a build finished successfully. Releases the build slot and all associated file locks.

Params: session_id, build_type

tc_build_failed

Signal that a build failed. Releases locks the same as tc_build_complete. The failure is logged in build history for the dashboard.

Params: session_id, build_type, reason

tc_get_status

Get the current system-wide status: all active sessions, file locks, running builds, recent build history, and the overall signal (GREEN / YELLOW / RED). The main diagnostic tool.

No params required

tc_force_release

Forcibly release a lock or build slot held by another session. Use when a session crashed and auto-cleanup hasn't fired yet. Requires a reason that is logged for audit purposes.

Params: session_id (caller), target_session_id, reason

How conflict resolution works

When a session tries to check out a file that's already locked, Traffic Cop doesn't just say "no" and leave the agent stuck. It returns a structured BLOCKED response, queues the session as a waiter, and automatically hands off the lock the moment the holding session finishes.

Step-by-step flow

1

Session A checks out a file

tc_checkout returns APPROVED and the lock is stored with Session A's ID, purpose, and an expiry time.
2

Session B tries to check out the same file

tc_checkout returns BLOCKED with full conflict detail — who has the lock, what they said they were doing, how long they've held it, and Session B's queue position. Session B is automatically added to the wait queue — no second call needed.

// BLOCKED response example { "status": "BLOCKED", "conflicts": [{ "file": "server/db/store.go", "session": "Claude Chat A", "purpose": "Rewriting LockFiles() for project scoping", "held_for": "4m12s" }], "queue_position": 1, "advice": "You are queued for auto-grant. When the holding session calls tc_checkin, the lock will be handed to you automatically." }
3

Claude (Session B) works on something else

Claude reads the conflict details and reasons through what to do next — which other files are safe to touch, or whether to wait. It sends periodic tc_heartbeat calls which double as grant notification polling. No busy-waiting loop required.
4

Session A calls tc_checkin

The cop deletes Session A's lock and immediately grants it to the first waiter in the queue (Session B). The lock is now held by B — no re-request, no race condition.
5

Session B receives the grant notification

The next tc_heartbeat or tc_get_pending call returns granted_files with the file Session B was waiting for. Claude sees the green light and proceeds immediately.

// Heartbeat response when grant arrives { "ok": true, "granted_files": [{ "file": "server/db/store.go", "granted_at": "..." }], "message": "🟢 1 file(s) auto-granted to you — proceed with editing." }

ℹ️ Stale lock protection

If Session A crashes without calling tc_checkin, its lock auto-expires after 30 minutes (configurable). The cop detects the dead heartbeat and releases the lock, which then gets handed to the next waiter. No manual intervention needed.

Config file reference

Key	Default	Description
my_addr	`""`	This machine's LAN IP and port, e.g. `192.168.1.105:7734`. Required for multi-machine sync and UDP announcement.
is_primary	`false`	Set `true` on your main machine. The dashboard shows ★ PRIMARY. Secondary machines sync from primary on startup.
peers	`[]`	List of peer addresses. Auto-populated by UDP discovery. You can add cross-subnet peers manually here.
lock_ttl_minutes	`60`	How long a file checkout stays active before auto-expiring. Sessions that finish early should call tc_checkin instead of waiting.
stale_session_minutes	`30`	How long to wait after the last heartbeat before declaring a session dead and releasing its locks.
http_port	`7734`	TCP port for the HTTP server (REST API + dashboard). Must match the port in my_addr.
udp_port	`7735`	UDP port for LAN peer discovery. Must be the same on all machines in the team.

Troubleshooting

Claude doesn't see the tc_* tools

1. Check that the service is running: open PowerShell and run Get-Service SoftwareTrafficCop — status should be Running.

2. Verify the MCP entry exists in claude_desktop_config.json. See Claude Desktop config.

3. Restart Claude Desktop — MCP servers only connect on startup.

Dashboard shows "Unable to connect" at localhost:7734

The service may have stopped. Run Start-Service SoftwareTrafficCop in an elevated PowerShell, then reload the page. Check C:\ProgramData\SoftwareTrafficCop\trafficcop.log for error details.

Cowork skill tools don't appear in my session

The tray app deploys the skill every 30 seconds. Wait a moment, then restart the Cowork session. Confirm the tray icon (🚦) is visible in the system tray — if it's missing, the tray app isn't running. Start it manually from C:\Program Files\SoftwareTrafficCop\trafficcop-tray.exe.

tc_checkout returns CONFLICTS but I don't know who holds the lock

Call tc_get_status — it lists every active lock, which session holds it, and how long it's been held. If the session that holds the lock has crashed, use tc_force_release to free it.

Peers aren't discovering each other automatically

Confirm both machines are on the same subnet (same first three octets, e.g. 192.168.1.x). Also confirm UDP port 7735 is open on both machines' firewalls. The MSI installer opens this rule automatically, but a corporate firewall may block broadcast traffic between machines.

How do I completely uninstall?

Go to Control Panel → Programs → Uninstall a program and uninstall Software Traffic Cop. This stops and removes the service, removes the tray app from Startup, and deletes the install directory. The config and database in C:\ProgramData\SoftwareTrafficCop\ are left in place so a reinstall picks up where you left off — delete that folder manually if you want a clean slate.

📬 Still stuck?

Email [email protected] with your trafficcop.log attached and a description of what you expected vs. what happened.

Install Guide

⚡ Quick Start — 4 steps

Installation (Windows — recommended)

Download the installer

Run the installer

Choose your role

Click Install