# Collab > Start a collaborative AI team (Codex + Claude) to work on a task together. Use when the user says "werk samen met Codex", "collab", "team onderzoek", "laat Codex en Claude samenwerken", or wants multiple AI agents to analyze, research, or solve something together autonomously. Use when this capability is needed. - Skill: `tomevault-io/collab` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/collab` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/collab/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/collab --- # Collab: Autonomous AI Team Collaboration **Language rule:** ALWAYS respond in the same language the user used to invoke /collab. If the user writes in English, all your output (status updates, summaries, everything) must be in English. If Dutch, respond in Dutch. Never mix languages. Launch a Codex + Claude team. Scripts live in `__ENSEMBLE_DIR__/scripts/`. Runtime files namespaced under `/tmp/ensemble//`. ## Path Convention All collab artifacts live in `/tmp/ensemble//`: - `messages.jsonl` — agent + ensemble message log - `summary.txt` — written on disband by ensemble-service - `bridge.pid`, `bridge.log` — bridge process - `poller.pid`, `feed.txt` — background poller - `prompts/`, `delivery/` — agent prompt/delivery files - `.finished` — written by ensemble-service AFTER summary.txt - `team-id` — team ID marker ## Workflow ### Step 0: Detect environment ```bash if [ -n "$TMUX" ]; then echo "TMUX_YES" elif [ "$(uname)" = "Darwin" ] && [ "${TERM_PROGRAM:-}" = "iTerm.app" ]; then echo "ITERM_NATIVE" else echo "TMUX_NO" fi ``` Three monitor modes: - `TMUX_YES` — already inside tmux; `collab-launch` opens a split pane right - `ITERM_NATIVE` — macOS iTerm2 without tmux; `collab-launch` uses `osascript` to open a native iTerm split pane (no `tmux attach` needed) - `TMUX_NO` — fallback: detached tmux session the user must attach to Force a specific mode with `COLLAB_MONITOR=tmux|iterm|none` or change iTerm layout with `COLLAB_ITERM_MODE=split|tab|window` (default `split`). ### Step 1: Launch the team ```bash collab-launch "$(pwd)" "$TASK_DESCRIPTION" ``` Extract TEAM_ID: ```bash TEAM_ID=$(cat /tmp/collab-team-id.txt) ``` ### Step 2: Tell the user where the monitor is - `TMUX_YES`: "Team is live in the right tmux pane." - `ITERM_NATIVE`: "Team is live in the new iTerm pane on the right." - `TMUX_NO`: "`tmux attach -t ensemble-$TEAM_ID` — live TUI monitor (steer, disband, scroll)" ### Step 3: Monitoring — the user MUST see the conversation **CRITICAL RULE**: The user wants to SEE the team's conversation as it happens. Every poll result must be presented clearly and formatted as a readable conversation. Do NOT just dump raw output — format it as a proper dialogue. #### If `TMUX_NO`: poll and PRESENT messages inline Use `collab-poll.sh` — a single-shot poller that tracks state automatically and gives clean output. **Poll command:** ```bash collab-poll "" --sleep ``` Output format: `sender\tcontent` lines, ending with one of: - `---STATUS:ACTIVE` — new messages were found - `---STATUS:QUIET` — no new messages (agents in deep work) - `---STATUS:DONE` — team finished, followed by summary.txt content - `---STATUS:WAITING` — messages file not yet created **Presentation rules — THIS IS THE KEY PART:** After each poll, present the new messages to the user like this: > **codex-1**: [message content] > > **claude-2**: [message content] Use markdown bold for agent names. Show the FULL message content (up to 500 chars), not truncated summaries. Between polls, add a brief status line like "Team is working... next check in 15s." **Polling cadence:** - First poll: `--sleep 10` - Normal: `--sleep 15` to `--sleep 20` - If 3+ polls QUIET: `--sleep 30` (agents in deep work) - On `---STATUS:DONE`: stop polling, present final summary **When done**, present structured summary + clean up: ```bash TEAM_ID="" && RD="/tmp/ensemble/$TEAM_ID" && kill "$(cat "$RD/poller.pid" 2>/dev/null)" 2>/dev/null || true; kill "$(cat "$RD/bridge.pid" 2>/dev/null)" 2>/dev/null || true; tmux kill-session -t "ensemble-$TEAM_ID" 2>/dev/null || true ``` #### If `ITERM_NATIVE`: background summary watcher Same as `TMUX_YES`: the monitor pane is visible to the user, so don't inline-poll. Wait for completion in the background (same snippet as below) and present the final summary when done. On cleanup, the iTerm pane lives on — the user closes it with `q` or Cmd+W. Do NOT try to `tmux kill-session` (no tmux session exists in this mode). #### If `TMUX_YES`: background summary watcher Monitor visible in right pane. Wait in background: ```bash TEAM_ID="" && RD="/tmp/ensemble/$TEAM_ID" && while [ ! -f "$RD/.finished" ] && [ ! -f "$RD/summary.txt" ]; do sleep 8; done && echo "COLLAB_COMPLETE" && cat "$RD/summary.txt" 2>/dev/null ``` Run with `run_in_background: true`, `timeout: 600000`. When done: summarize + cleanup poller/bridge PIDs. ## Important Notes - Agents run with auto-accept permissions (configured in agents.json: codex `--full-auto`, claude `--dangerously-skip-permissions`). They should NEVER ask for file write approval. - Do not modify project code during a collab session unless the user explicitly asks - Do not truncate or remove `messages.jsonl` - Multiple collabs can run simultaneously — each has own `/tmp/ensemble//` namespace - `team-say.sh` uses `fcntl.flock` for atomic JSONL writes - `ensemble-bridge.sh` has single-instance guard, health check, exponential backoff - `.finished` and `summary.txt` are written by ensemble-service, NOT by scripts - Bridge auto-stops when it sees `.finished` marker --- > Source: [michelhelsdingen/ensemble](https://github.com/michelhelsdingen/ensemble) — distributed by [TomeVault](https://tomevault.io).