PIDGIN-RUN(1)

NAME
pidgin-run - Run conversations between AI agents

SYNOPSIS
pidgin run [OPTIONS] [SPEC_FILE]

DESCRIPTION
The run command initiates conversations between two AI agents, either as single conversations or multi-conversation experiments. It supports both command-line configuration and YAML specification files.

Conversations are recorded in real-time to JSONL files, with automatic database import upon completion. The command displays conversation progress by default, with options for quiet operation or detailed monitoring.

ARGUMENTS

SPEC_FILE
    Optional YAML specification file defining the experiment configuration. If provided, command-line options are ignored in favor of the spec file.

OPTIONS

  Agent Selection

-a, --agent-a MODEL
    First agent model (required unless using spec file). Examples: claude, gpt-4, gemini, local:llama3.

-b, --agent-b MODEL
    Second agent model (required unless using spec file).

  Conversation Parameters

-p, --prompt TEXT
    Initial prompt to start the conversation. Default: "Let's have a fascinating discussion."

-t, --turns N
    Maximum number of turns (message exchanges) per conversation. Default: 20

-r, --repetitions N
    Number of conversations to run (creates an experiment). Default: 1 (single conversation)

  Temperature Settings

--temperature FLOAT
    Set temperature for both agents (0.0-2.0).

--temp-a FLOAT
    Set temperature for agent A only.

--temp-b FLOAT
    Set temperature for agent B only.

  Convergence Control

--convergence-threshold FLOAT
    Threshold for convergence detection (0.0-1.0). Default: 0.95

--convergence-action ACTION
    Action when convergence threshold is reached. Choices: stop, continue, notify. Default: stop

--convergence-profile PROFILE
    Predefined convergence profile. Choices: research, exploratory, fun.

  Advanced Options

-d, --dimension SPEC
    Use dimensional prompt generation. Format: perspective:topic:style Example: peers:philosophy:analytical

--first-speaker MODEL
    Which agent speaks first (agent-a or agent-b). Default: agent-a

--awareness LEVEL
    Set system prompt awareness level for both agents. Choices: none, basic, enhanced, full.

--awareness-a LEVEL
    Set awareness level for agent A only.

--awareness-b LEVEL
    Set awareness level for agent B only.

--prompt-tag TAG
    Load prompt from CLAUDE.md by HTML comment tag.

  Display Options

-o, --output MODE
    Output display mode. Choices: default, minimal, none, markdown, json. Default: default

--show-system-prompts
    Display system prompts before starting.

--meditation
    Increase pause between messages (3-10 seconds).

-q, --quiet
    Minimal output (same as --output minimal).

--tail
    For experiments, show live tail view of all conversations.

  Experiment Options

--name NAME
    Custom name for the experiment (auto-generated if not provided).

--max-parallel N
    Maximum parallel conversations (default: 20).

--choose-names
    Interactively choose agent names.

--notify
    Send desktop notification when complete.

EXAMPLES

Simple conversation between Claude and GPT-4:
    pidgin run -a claude -b gpt-4 -t 30

Experiment with 10 conversations:
    pidgin run -a haiku -b gpt-4o-mini -r 10 -t 50 --name "efficiency-test"

Using dimensional prompts:
    pidgin run -a claude -b gemini -d teacher:mathematics:patient

Custom temperatures and convergence:
    pidgin run -a gpt-4 -b gpt-4 --temp-a 0.3 --temp-b 0.9 \
        --convergence-threshold 0.8 --convergence-action notify

From YAML specification:
    pidgin run experiment.yaml

With custom awareness levels:
    pidgin run -a claude -b llama3 --awareness-a full --awareness-b none

YAML SPECIFICATION
When using a YAML file, all command-line options are ignored. See pidgin-yaml(5) for the specification format.

OUTPUT
Conversations are saved to:
        manifest.json           # Experiment metadata
        conv_<id>_events.jsonl  # Event logs per conversation
        experiment.db           # DuckDB database (post-import)
        analysis.ipynb          # Auto-generated Jupyter notebook

NOTES
Temperature affects response randomness (0=deterministic, 2=very random). Different models have different optimal temperature ranges.

Convergence detection monitors vocabulary overlap, structural similarity, and other metrics to determine when agents have reached a stable communication pattern.

SEE ALSO
pidgin(1), pidgin-yaml(5), pidgin-metrics(7)

AUTHOR
Nicholas Lange and contributors