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: ``bash mkdir -p .cursor/rules cp templates/sitrep-protocol.cursor.mdc .cursor/rules/sitrep-protocol.mdc ``

For Claude Code: ```bash

Append to CLAUDE.md or create it

cat templates/sitrep-protocol.claude.md >> CLAUDE.md ```

For VS Code Copilot: ``bash mkdir -p .github cp templates/sitrep-protocol.vscode.md .github/copilot-instructions.md ``

For any agent (generic): ``bash 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.