Sitrep

Real-time parallel development coordination for AI agents and humans.

Sitrep solves the divergence problem: when multiple agents vibe-code on the same codebase in parallel, their architectural decisions diverge silently. Git's unit of sharing (commit/push) is too coarse for the rate at which agents make decisions. By the time one agent pushes, another has made 50 divergent choices. Sitrep makes this transparent in real time.

What It Does

Sitrep is a centralized coordination server that AI coding agents connect to via MCP (Model Context Protocol). It provides:

• Sessions -- who is working on what, right now, on which branch, with what intent
• Decisions -- architectural choices recorded and shared across all parallel streams (ORM, patterns, deps, API shapes)
• Claims -- which files are being actively modified, by whom, with rich context about what is changing
• Discussions -- agent-to-agent async conversations to resolve conflicting architectural decisions
• Conflict Detection -- scope overlap warnings, file contention alerts, merge risk scoring
• Escalations -- unresolved agent conflicts surfaced to humans via the dashboard
• Branch Topology -- divergence tracking and cross-branch file overlap analysis

Getting Started

Prerequisites

• Docker and Docker Compose
• Git
• An MCP-capable AI agent (Cursor, Claude Code, VS Code Copilot, etc.)

1. Start the Server

git clone <repo-url> && cd sitrep
docker compose up -d

This starts five services:

Service	Default Port	Purpose	Env Var
frontend	13000	React dashboard for human oversight	SITREP_FRONTEND_PORT
server	18000	FastAPI + FastMCP server (agents + API)	SITREP_API_PORT
worker	--	Celery beat + workers (reaper, analysis)	--
postgres	15432	All persistent state	SITREP_POSTGRES_PORT
redis	16379	Heartbeats, TTLs, Celery broker, pub/sub	SITREP_REDIS_PORT

Ports are offset from standard defaults to avoid conflicts with services already running on your machine. To customize, copy .env.example to .env and edit:

cp .env.example .env
# Edit .env to change ports, credentials, or connection strings

Verify everything is healthy:

curl http://localhost:18000/health
# {"status":"ok"}

curl http://localhost:13000/api/projects
# []

2. Configure Your Agent's MCP Connection

Add the sitrep MCP server to your agent's configuration.

Cursor -- add to .cursor/mcp.json:

{
  "mcpServers": {
    "sitrep": {
      "url": "http://localhost:18000/mcp/mcp"
    }
  }
}

Claude Code -- add to your MCP config:

{
  "mcpServers": {
    "sitrep": {
      "url": "http://localhost:18000/mcp/mcp"
    }
  }
}

Adjust the port if you changed SITREP_API_PORT in your .env.

3. Set Up .sitrep/config.yaml in Your Repository

Create a .sitrep/ directory in the target repo with a config.yaml that identifies the project:

mkdir -p .sitrep
cp /path/to/sitrep/templates/sitrep-config.yaml .sitrep/config.yaml
# Edit .sitrep/config.yaml to set your project_id and server_url

Agents read this file before their first MCP call to auto-configure project_id, repo_url, and other defaults. The MCP server also auto-resolves projects from repo_url if the agent passes it, so even without this file, agents that pass their git remote will get matched to the right project.

4. Install the Agent Protocol Rules

Copy the appropriate rule file into your repository so the agent knows how and when to use sitrep:

For Cursor:

mkdir -p .cursor/rules
cp templates/sitrep-protocol.cursor.mdc .cursor/rules/sitrep-protocol.mdc

For Claude Code:

# Append to CLAUDE.md or create it
cat templates/sitrep-protocol.claude.md >> CLAUDE.md

For VS Code Copilot:

mkdir -p .github
cp templates/sitrep-protocol.vscode.md .github/copilot-instructions.md

For any agent (generic):

cp templates/sitrep-protocol.agents.md AGENTS.md

5. Install Git Hooks (Optional)

Git hooks notify sitrep when commits and pushes happen, enabling divergence monitoring:

bash hooks/install.sh --server-url http://localhost:8000 --project-id my-project

6. Create a Project

Via the dashboard at http://localhost:3000 (Config tab), or via API:

curl -X POST http://localhost:3000/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

7. Seed Architectural Decisions (Recommended)

Before starting parallel work, record key decisions that all agents should follow. You can do this via the MCP tools or the dashboard. This is the highest-value setup step -- an hour of ADR seeding prevents days of merge pain.

Development

Running Tests

pip install -e ".[dev]"
pytest

Running Locally (Without Docker)

# Start PostgreSQL and Redis separately, then:
uvicorn sitrep.server:app --reload

# In another terminal:
celery -A sitrep.workers.celery_app worker --loglevel=info --beat

# Frontend:
cd frontend && npm install && npm run dev

Project Structure

src/sitrep/
  server.py          # FastMCP + FastAPI combined entry point
  config.py          # Settings (env vars / .env)
  mcp/tools.py       # 7 MCP tools (begin, decide, discuss, claim, query, status, end)
  core/              # Business logic (sessions, decisions, discussions, claims, conflicts, topology)
  storage/           # PostgreSQL (repositories.py) + Redis (redis.py) + SQLAlchemy (database.py)
  workers/           # Celery tasks (stale session reaper, branch analyzer, escalation checker)
  api/               # REST + WebSocket + git hook endpoints for the dashboard
  models/            # Pydantic domain models (domain.py) + SQLAlchemy ORM (db.py)
frontend/            # React + TypeScript + Vite dashboard
templates/           # Agent protocol rule files for each IDE
hooks/               # Git hooks (post-commit, post-push) + installer
docs/                # Best practices and team culture guide

Agent Protocol Rule Files

The templates/ directory contains rule files for each supported agent platform. These are the most important files in the system -- they teach the agent when and why to call sitrep tools during its reasoning process.

File	Platform	Where to install
sitrep-protocol.cursor.mdc	Cursor	.cursor/rules/sitrep-protocol.mdc
sitrep-protocol.claude.md	Claude Code	Append to CLAUDE.md
sitrep-protocol.vscode.md	VS Code Copilot	.github/copilot-instructions.md
sitrep-protocol.agents.md	Any agent	AGENTS.md at repo root

Documentation

• Best Practices Guide -- team culture document covering branching discipline, commit semantics, decision-first thinking, claim etiquette, and session hygiene. Customize this for your team.