Bidirectional Sandbox

Badges

Bidirectional Sandbox is a small proof-of-concept that lets two CLI-based LLM agents collaborate through the same live terminal.

The demo uses plain files as the coordination layer. Codex CLI and Gemini CLI both read the cleaned terminal log, decide on the next step, and queue commands for a tmux-backed terminal session to execute. The result is a simple, inspectable loop where both agents can see what happened and continue from shared evidence.

Why This Exists

Most multi-agent demos hide the coordination layer behind an API, server, or framework. This project keeps the mechanism visible:

• A shared terminal is the source of truth.
• A queue file carries commands from agents into the terminal.
• A clean log gives both agents the same readable history.
• tmux keeps the session observable and attachable by a human.

It is intentionally small so the collaboration loop is easy to understand, modify, and extend.

Core Files

File	Purpose
ai-terminal.sh	Starts the tmux session, injects queued commands, and refreshes the clean log.
launch-all.sh	Starts the background engine for normal demo use.
terminal-session.log	Raw terminal output captured from tmux. Generated at runtime.
terminal-clean.log	ANSI-stripped terminal output read by the agents. Generated at runtime.
pending-command.txt	Command queue consumed by the engine. Generated at runtime.
scripts/queue-command.sh	Safely appends one validated command to the queue.
scripts/status.sh	Prints the tmux, queue, and latest-log status.
scripts/checkpoint.sh	Creates a timestamped git checkpoint.
scripts/clean-logs.sh	Rebuilds the clean log from the raw terminal log.
bidirectional-sandbox.desktop	Desktop launcher for one-click local starts.

Architecture

Codex CLI                          Gemini CLI
   |                                  |
   | read terminal-clean.log          | read terminal-clean.log
   |                                  |
   | queue commands                   | queue commands
   |                                  |
   +---------------+------------------+
                   |
                   v
            pending-command.txt
                   |
                   v
             ai-terminal.sh
        queue watcher + tmux injector
                   |
                   v
          tmux session: exp001
                   |
                   v
       terminal-session.log -> terminal-clean.log

Requirements

• Bash
• tmux
• Git
• A Unix-like desktop or shell environment
• Two CLI agents, such as Codex CLI and Gemini CLI

On Debian or Ubuntu:

sudo apt install tmux git

Quick Start

Start the demo engine:

./launch-all.sh

Watch the collaboration log:

tail -f terminal-clean.log

Attach to the live terminal:

tmux attach -t exp001

Detach from tmux with Ctrl+B, then D.

Agent Protocol

Each agent should begin its turn by reading the shared state:

cat terminal-clean.log | tail -100

Then queue exactly one command:

./scripts/queue-command.sh "./scripts/status.sh"

Preview a command without queueing it:

./scripts/queue-command.sh --dry-run "ls -la"

The engine consumes one queued line at a time, injects it into tmux, captures the raw output, and refreshes the cleaned log for the next agent turn.

Useful Commands

./scripts/status.sh
./scripts/queue-command.sh "ls -la"
./scripts/clean-logs.sh
./scripts/checkpoint.sh "Describe the checkpoint"

Safety Notes

• Anything in pending-command.txt executes as a shell command in the shared tmux session.
• Use scripts/queue-command.sh instead of writing to the queue by hand.
• The queue helper rejects blank commands, multiline commands, and a few high-risk command patterns unless --yes is supplied.
• Runtime logs and queue files are ignored by git.

GitHub Badges

The static badges at the top work before the repository has any GitHub Actions configured. After publishing, add repository-specific badges such as:

![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)

Replace OWNER/REPO after the GitHub repository exists.

How to Contribute

Contributions should keep the demo easy to run and easy to inspect.

1. Read the current log with cat terminal-clean.log | tail -100.
2. Make one focused improvement.
3. Run the relevant script checks, usually bash -n scripts/*.sh ai-terminal.sh launch-all.sh.
4. Use ./scripts/status.sh to verify the local collaboration state.
5. Create a checkpoint with ./scripts/checkpoint.sh "Short description".

Good next contributions include cleaner log rendering, a small web dashboard, safer command approval flows, GitHub Actions smoke tests, and packaging the desktop launcher.

License

MIT. See LICENSE.