documentation

Get started with Agent Town

Everything you need to set up real-time collaboration for your Claude Code team.

01

Installation

No global install needed. Everything runs via npx.

# Recommended — opens browser, authenticates, auto-configures
npx @agent-town/cli login
# Alternative — manual setup for self-hosted relays
npx @agent-town/cli init

The login command handles everything automatically. If you're self-hosting, use init instead — you'll be asked for:

  • ▶Relay URL — your self-hosted relay address
  • ▶Team key — generate a new one, or paste your team's existing key
  • ▶Your name — how you appear to teammates

Config is saved to ~/.agent-town/config.json.

02

Connect to Claude Code

npx @agent-town/cli setup-claude

This does three things automatically:

  • ▶Registers the MCP server in ~/.claude.json
  • ▶Installs PostToolUse hooks — auto-claims files when you Edit or Write
  • ▶Adds all 10 tools to the allowed list — no permission prompts
!Restart Claude Code after running this command.
03

Usage

Once set up, just talk to Claude. No special syntax.

"who's on the team right now?"
"claim src/auth/login.ts"
"protect src/api/ — major refactor"
"is utils.ts safe to edit?"
"tell the team: don't merge, migration running"
"what changed in the last hour?"

Claude calls the right tools automatically based on your request.

04

Tools Reference

Agent Town provides 10 MCP tools:

get_team_status

Who's online, their branch, active files

check_file(path)

Pre-edit safety check — locks, zones, nearby edits

claim_file(path)

Mark a file as being edited by you

release_file(path)

Release your lock

claim_zone(pattern, reason?)

Protect a directory from other agents

release_zone(pattern)

Remove zone protection

get_activity(limit?)

Recent changes across the team

send_message(message)

Send a message to all teammates

get_messages

Read pending messages

get_conflicts

Check for active conflicts

05

Protected Zones

Zones protect entire directories. Useful during refactors.

"protect src/auth/** — rewriting auth module"
# Anyone editing inside gets warned:
# 🚫 File is inside protected zone src/auth/**
#    claimed by Tim (rewriting auth module)
"release the src/auth/ zone"

Supported patterns:

  • ▶src/api/** — everything inside src/api/
  • ▶src/api/ — directory prefix match
  • ▶src/api/routes.ts — exact file

Zones are advisory (warn, never block) and auto-release on disconnect.

06

Branch Awareness

Agent Town detects your git branch automatically and reports it to teammates.

  • ▶If two agents are on the same branch editing nearby files → high conflict risk, warns proactively
  • ▶If agents are on different branches → lower risk, less aggressive warnings
  • ▶Branch is updated every 30 seconds via heartbeat
07

Self-Hosting

The relay is open source. Run your own:

# Docker
docker build -t agent-town-relay .
docker run -p 8787:8787 agent-town-relay
# Without Docker
git clone https://github.com/the-noname-devs/agent-town.git
cd agent-town && pnpm install && pnpm build
pnpm --filter @agent-town/relay start

Then point your agents to your server:

npx @agent-town/cli init
# Relay URL: ws://your-server:8787

Requirements: Node.js 20+, ~50MB RAM. No database needed.

08

Security

  • ▶No file contents transit the relay — only paths and metadata
  • ▶Team isolation via team keys — different teams can't see each other
  • ▶TLS enforced on the hosted relay
  • ▶Advisory locks — warn on conflicts, never hard-block
  • ▶Stateless relay — all data is in-memory, nothing persisted to disk