home / skills / plurigrid / asi / crdt-vterm

crdt-vterm skill

safe

This skill enables collaborative terminal sessions by applying GF3 CRDT conflict resolution to synchronize vterm outputs and inputs across peers.

npx playbooks add skill plurigrid/asi --skill crdt-vterm

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

5.1 KB

---
name: crdt-vterm
description: Collaborative terminal session sharing using CRDT-style s-expressions
  with GF(3) trifurcated conflict resolution.
metadata:
  trit: 0
---

# CRDT-VTerm - Collaborative Terminal Sharing

Collaborative terminal session sharing using CRDT-style s-expressions with GF(3) trifurcated conflict resolution.

## Components

### Emacs Bridge
- **File**: `crdt-vterm-bridge.el`
- **Purpose**: Connect vterm.el to crdt.el via shadow buffers

### Babashka Recorder
- **File**: `vterm_crdt_recorder.bb`
- **Purpose**: Record/replay terminal sessions as CRDT sexps

### P2P Sharing
- **File**: `vterm_localsend_share.bb`  
- **Purpose**: Live terminal sharing via localsend multicast

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                    CRDT-VTerm System                             │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────┐     remote-insert     ┌───────────────┐             │
│  │ vterm   │ ───────────────────▶  │ shadow buffer │             │
│  │  PTY    │      (GF3 trit)       │  (crdt.el)    │             │
│  └────┬────┘                       └───────┬───────┘             │
│       │                                    │                     │
│       │ script(1)                          │ sexp file           │
│       ▼                                    ▼                     │
│  ┌─────────┐                       ┌───────────────┐             │
│  │ raw log │                       │ .sexp log     │             │
│  └────┬────┘                       └───────┬───────┘             │
│       │                                    │                     │
│       │ vterm_crdt_recorder.bb             │ localsend UDP       │
│       ▼                                    ▼                     │
│  ┌─────────────────────────────────────────────────┐             │
│  │              P2P Peer Network                   │             │
│  │  ┌───────┐   ┌───────┐   ┌───────┐              │             │
│  │  │ MINUS │   │ERGODIC│   │ PLUS  │  ← GF(3)     │             │
│  │  └───────┘   └───────┘   └───────┘    routing   │             │
│  └─────────────────────────────────────────────────┘             │
└──────────────────────────────────────────────────────────────────┘
```

## CRDT Sexp Format

```clojure
;; Session header
(crdt-terminal-session
  (version "0.1.0")
  (session-id "T-abc123")
  (site-id 42)
  (gf3-assignment :ERGODIC))

;; Terminal output
(remote-insert "0a1b2c3d" 42 "$ ls -la\n"
  (props :type :terminal-output
         :trit :MINUS
         :timestamp 1234567890))

;; User input
(remote-input "0a1b2c3e" 42 "ls -la"
  (props :trit :PLUS
         :timestamp 1234567891))

;; Conflict resolution
(conflict-resolution
  :type :concurrent-input
  :strategy :gf3-ordering)
```

## Usage

### Record Session
```bash
bb vterm_crdt_recorder.bb record session.sexp
```

### Replay Session
```bash
bb vterm_crdt_recorder.bb replay session.sexp 2.0
```

### Live P2P Share
```bash
bb vterm_localsend_share.bb share output.sexp 192.168.1.5
```

### Emacs Replay
```elisp
M-x crdt-vterm-replay RET session.sexp RET 1.0 RET
```

## GF(3) Trifurcated Input

Multi-user input is routed through three queues:

| Queue | Trit | Processing Order |
|-------|------|------------------|
| MINUS | -1 | First |
| ERGODIC | 0 | Second |
| PLUS | +1 | Third |

This prevents conflicts in "no-longer-optimistic waiting" scenarios by deterministically ordering concurrent inputs.

```elisp
;; Cycle through queues
(crdt-vterm-trifurcate-cycle)
```

## Integration

### With gay-mcp
Each terminal session gets a deterministic color based on session ID.

### With localsend-mcp
P2P discovery and file transfer for session sharing.

### With duckdb-ies
Terminal sessions can be indexed in DuckDB for time-travel queries.

## Related Skills
- `gay-mcp` - Deterministic colors
- `spi-parallel-verify` - GF(3) conservation
- `triad-interleave` - Three-stream scheduling
- `bisimulation-game` - Session equivalence

Overview

This skill provides collaborative terminal session sharing using CRDT-style s-expressions with GF(3) trifurcated conflict resolution. It connects a terminal emulator to CRDT shadow buffers, records and replays sessions, and supports live P2P sharing for multi-user editing and playback. The design guarantees deterministic ordering of concurrent inputs via three trit queues (MINUS, ERGODIC, PLUS).

How this skill works

The system bridges a terminal (vterm) into a CRDT shadow buffer that emits and consumes sexp-encoded operations. A recorder captures terminal output and user input as CRDT s-expressions for later replay or indexing. For live sharing, sexp streams are multicast over a P2P network and routed with GF(3) trifurcation to deterministically resolve concurrent edits. Replay tools and an Emacs bridge consume .sexp logs to reproduce terminal history at controlled speeds.

When to use it

Collaborative terminal sessions where multiple users may type concurrently
Auditing or time-travel debugging of terminal workflows
Recording reproducible terminal sessions for demos or tutorials
Live coding presentations or pair-programming over LAN
Indexing terminal activity for analytics or search

Best practices

Assign a stable session-id for deterministic coloring and indexing
Use the recorder for all interactive sessions you might need to replay or analyze
Prefer P2P multicast on local networks for minimal latency and simple discovery
Replay at controlled speed to validate timing-sensitive interactions
Store both raw logs and .sexp CRDT logs for provenance and reconstruction

Example use cases

Pair-programming with concurrent input safely ordered by GF(3) trifurcation
Recording a terminal-driven experiment and replaying it for verification
Live debugging session shared across a small team over localsend multicast
Indexing sessions into a column-store for time-travel queries and analytics
Deterministic session coloring integration for visual differentiation in multi-session dashboards

FAQ

How does GF(3) trifurcation prevent conflicts?

Concurrent inputs are routed into three ordered queues (MINUS, ERGODIC, PLUS) which are applied in fixed sequence, producing a deterministic outcome for simultaneous edits.

Can I replay sessions at different speeds?

Yes. The recorder supports replay with a speed multiplier so you can accelerate or slow down time when reproducing a session.