Multi-PC Codex orchestration

CLUTCH for Research Agents

Coordinate Codex sessions, worker PCs, shared artifacts, visible collab monitoring, reproducible snapshots, and bounded away development plans for AI and robotics labs.

View on GitHub Start locally

Why it exists

Research projects rarely live on one clean laptop.

CLUTCH is designed for AI and robotics teams where code, datasets, model weights, robot logs, and compute roles live across multiple machines. It gives Codex a durable re-entry layer, then keeps project state, collab context, backups, and recovery evidence visible to the operator.

Architecture

Projects enter CLUTCH before they reach agent PCs.

CLUTCH routes the active project through session entry, visible collab transport, local snapshots, project backups, task alarms, and machine-local resources without forcing private hardware, datasets, or credentials into the public package.

CLUTCH top-down ecosystem architecture showing project binding, session entry, collab transport, agent PCs, local snapshots, backups, away development, task alarms, and local AI, robot, and sensor resources

Core advantages

Built for multi-PC Codex work, not just a prettier prompt.

Multi-PC collab

Main and worker sessions can coordinate through project roles, file transport, task records, and peer freshness checks.

Visible monitor

The collab monitor shows role source, active request context, recent results, and stale peer signals without hiding work in chat history.

Large-project recovery

Code, docs, snapshots, metadata, local backups, and artifact pointers are tracked separately from heavy model and dataset files.

Away development

Long-running Codex work gets an explicit objective, allowed scope, stop conditions, checkpoints, and verification trail.

Web console

Project warnings, readiness checks, command previews, backup evidence, Help, and collab status are available from a local browser.

Private by design

First-run setup asks for local folders, machine identity, GitHub preference, and collab choices instead of embedding lab-specific data.

Operating model

A practical loop for distributed lab work.

  1. 01

    Enter through CLUTCH

    Every Codex session starts with session-entry, finds the project, and restores the right local context.

  2. 02

    Bind roles clearly

    Attach one machine as main and optional peers as worker or observer.

  3. 03

    Move work with evidence

    Use collab transport, shared docs, task records, snapshots, and artifact pointers so handoffs are inspectable.

  4. 04

    Recover deliberately

    Before risky changes, CLUTCH can create backups and metadata that explain what can be restored and what stays local.

Guided first run

Install once, then let CLUTCH teach each PC how to join.

Main PC Operator session
collab transport
Worker PC Compute or hardware context
Artifact store Large files stay local
Web monitor Roles, requests, results
1

Run the first-run wizard

Choose your CLUTCH home, project root, artifact store, machine id, GitHub preference, and whether this PC should auto-attach.

2

Register a project

Point CLUTCH at an existing git workspace or a new project folder while CLUTCH keeps its own metadata under your local CLUTCH home.

3

Add a second PC when needed

Use a shared folder over wired LAN or another trusted local path, then attach machines as main and worker without embedding peer addresses in the public package.

4

Watch the evidence

Use the Web console to inspect warnings, collab monitor state, backup readiness, snapshots, and away-development boundaries.

Example operator prompts

Natural-language control stays at the center.

The public Prompt Cookbook expands these examples into first-run, multi-PC collab, backup, away-development, Web UI, and release review prompts.

Project re-entry
Attach this session to my robot-policy project as main and show what needs attention before I start.
Multi-PC handoff
Ask the worker machine to inspect the training logs and report only memory bottlenecks and failed runs.
Away development
Prepare an away plan for low-risk documentation and test hardening. Stop before publishing or touching hardware.
Recovery check
Before this refactor, create a local backup and tell me whether the project is reproducible from git and artifact pointers.

Open the Prompt Cookbook

Safety boundary

CLUTCH coordinates work. It does not grant hidden authority.

Hardware motion, sudo, credential changes, destructive restore, and public publication still require explicit operator approval.

The public package ships templates and guides, not private machine names, LAN IPs, SSH aliases, account tokens, robot profiles, or lab runtime state.

Large-project backup is explicit: source and docs can live in git, while datasets, model weights, logs, and media are recorded as artifact pointers unless you choose another policy.

User verification

Inspect CLUTCH before you depend on it.

Clean first run

Use a fresh home to install CLUTCH, run the first-run wizard, pass doctor checks, enter through CLUTCH, and create a first project without private lab defaults.

Local smoke checks

Run the included verification commands to test the landing page, Web console, Help tab, Monitor tab, and packaged collab transport from your own checkout.

Artifact boundaries

CLUTCH keeps source, docs, snapshots, metadata, and artifact pointers visible while large datasets, model weights, logs, and media stay in storage you control.

Open the First-Use Acceptance Runbook

Open the Verification Matrix

Install path

Start from the release zip, then configure your own machine.

CLUTCH does not require sudo. The public first-run wizard records your own CLUTCH home, project root, artifact store, machine id, GitHub setup preference, and optional multi-PC collab plan. 

unzip clutch-public-*.zip
cd clutch-public-*
export CLUTCH_HOME="${CLUTCH_HOME:-$HOME/.clutch}"
bash installer/install.sh --prefix "$CLUTCH_HOME"
cd "$CLUTCH_HOME/foundation/current"
python3 installer/clutch_first_run_wizard.py
python3 installer/clutch_doctor.py
python3 scripts/clutch_ctl.py session-entry