# CliSeat MCP (Lite Edition)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Protocol: MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![Python: >=3.10](https://img.shields.io/badge/Python->=3.10-yellow.svg)](https://python.org/)

**CliSeat MCP** is a role-based seat dispatch, session handover ledger, and terminal command governance plane designed for autonomous AI coding agents (Claude Desktop, Cursor, OpenAI Codex, Roo-Code, AutoGen).

It guarantees **single-writer mutual exclusion** across CLI environments, manages **session handover briefs** to prevent context loss across agent shifts, and enforces **domain command boundaries** to eliminate destructive out-of-domain actions.

---

## 🎯 The Problem

When multiple autonomous agents or human-agent teams operate in software repositories:
1. **Concurrency Collisions:** Two agent sessions try to run builds, edit files, or commit git branches at the same time without mutual exclusion (*seat locks*).
2. **Session Handover Amnesia:** When an agent session ends or hits context limits, the incoming successor agent starts blind—unaware of pending tasks, uncommitted files, or recent terminal outputs.
3. **Out-of-Domain Execution:** An agent scoped for frontend build tooling runs destructive infrastructure or database commands without boundary enforcement.

**CliSeat** provides a lightweight governance plane directly over standard MCP stdio.

---

## ✨ Features (Lite Edition)

- 🔒 **Role-Based Single-Writer Seats:** Mutual-exclusion seat locks (`claim_seat`, `release_seat`) per domain (e.g. `domain:cli`, `domain:db`).
- 📝 **Structured Handover Briefs:** Mandatory sign-off notes ensure incoming agent sessions inherit full state and priorities.
- 🛡️ **Domain Boundary Validator:** Whitelists approved commands per domain to block out-of-domain command execution.
- ⚡ **Zero-Dependency Core:** Pure Python runtime with zero database setup required.

---

## 🚀 Quickstart

### 1. Installation

```bash
git clone https://github.com/johannschiffer/cliseat-mcp.git
cd cliseat-mcp
pip install -e .
```

### 2. Configure in Claude Desktop or Cursor

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cliseat": {
      "command": "cliseat",
      "args": ["run"]
    }
  }
}
```

### 3. CLI Inspection

```bash
cliseat status
```

---

## 🛠️ MCP Tools Reference

| Tool | Parameters | Description |
|---|---|---|
| `claim_seat` | `seat_id`, `holder_session_id`, `domain`, `lease_ttl_sec` | Claims exclusive execution seat |
| `release_seat` | `seat_id`, `holder_session_id`, `handover_notes` | Releases seat and records handover notes |
| `get_seat_status` | `seat_id` | Returns seat occupancy, holder, and latest handover brief |
| `execute_domain_command` | `seat_id`, `holder_session_id`, `command_line` | Runs command validated against domain boundary whitelist |
| `list_seats` | *(none)* | Lists all configured seats and their statuses |

---

## 🚀 Upgrade to CliSeat Pro

Need persistent cryptographic handover ledgers, automated lease heartbeats, and token redaction?

The **CliSeat Pro Edition** adds:
- 📜 **Cryptographic Handover Ledger (SQLite WAL):** Immutable sign-off ledger storing SHA-256 state hashes, command history, and uncommitted git snapshots.
- 💓 **Atomic Lease Heartbeat & Anti-Zombie Reaper:** Auto-reclaims seats abandoned by disconnected or crashed agent sessions.
- 🛡️ **Command Scope Policy & Output Redactor:** Automatically masks authentication tokens, passwords, and private keys from stdout/stderr.
- 🐳 **Production Docker & Docker Compose manifests.**
- 🧪 **100% Passing Pytest Suite.**

👉 **[Get CliSeat Pro on Gumroad ($14.99 USD)](https://johanld.gumroad.com/)**

---

## 📄 License

MIT © 2026 [Johann Schiffer](https://github.com/johannschiffer)