# 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

```bash
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:

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

Verify everything is healthy:

```bash
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`:

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

**Claude Code** -- add to your MCP config:

```json
{
  "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:

```bash
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
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:

```bash
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

```bash
pip install -e ".[dev]"
pytest
```

### Running Locally (Without Docker)

```bash
# 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](docs/best-practices.md)** -- team culture document covering branching discipline, commit semantics, decision-first thinking, claim etiquette, and session hygiene. Customize this for your team.