PIDGIN(1)

NAME
pidgin - AI conversation research tool for studying emergent communication patterns

SYNOPSIS
pidgin [OPTIONS] COMMAND [ARGS]...

DESCRIPTION
Pidgin enables controlled experiments between AI agents to discover how they develop communication patterns, convergence behaviors, and linguistic adaptations. It serves as an AI linguistic observatory, recording and analyzing the evolution of machine-to-machine communication.

Pidgin focuses on being a lightweight conversation orchestrator that records interactions into structured data formats (JSONL and DuckDB) for later analysis. It intentionally avoids heavy ML dependencies to remain fast and portable.

COMMANDS

run Run conversations between AI agents. This is the primary command for conducting experiments. Supports single conversations or multi-conversation experiments.

stop
    Stop running experiments gracefully. Can stop a specific experiment by ID/name or all running experiments with --all.

monitor
    System-wide health monitor showing all active experiments, progress, convergence warnings, and completion estimates. Updates live every 2 seconds.

branch
    Branch from an existing conversation at a specific turn to explore alternate conversation paths.

models
    List all available AI models with their providers and context windows.

config
    Create a configuration file with example settings at ~/.config/pidgin/pidgin.yaml.

OPTIONS

--version
    Show the version and exit.

--help, -h
    Show help message and exit.

EXAMPLES

Start a simple conversation between Claude and GPT-4:
    pidgin run -a claude -b gpt-4 -t 20

Run an experiment with multiple conversations:
    pidgin run -a haiku -b gpt-4o-mini -r 10 -t 50 --name "compression-study"

Use a YAML specification file:
    pidgin run experiment.yaml

Monitor all running experiments:
    pidgin monitor

Stop a specific experiment:
    pidgin stop experiment_abc123de

Stop all running experiments:
    pidgin stop --all

View available models:
    pidgin models

Branch from an existing conversation:
    pidgin branch conv_12345678 --turn 15

FILES

~/.pidgin/
    User configuration directory containing API keys and settings.

./.pidgin/
    Project-specific configuration directory (takes precedence over user config).

./pidgin_output/
    Default output directory for experiments, conversations, and analysis results. Contains subdirectories for experiments, each with JSONL event logs and DuckDB databases.

ENVIRONMENT

ANTHROPIC_API_KEY
    API key for Claude models (required for Claude conversations).

OPENAI_API_KEY
    API key for OpenAI models including GPT-4 (required for OpenAI conversations).

GOOGLE_API_KEY
    API key for Google models like Gemini (required for Google conversations).

XAI_API_KEY
    API key for xAI models like Grok (required for xAI conversations).

PIDGIN_OUTPUT_DIR
    Override the default output directory (default: ./pidgin_output).

PIDGIN_LOG_LEVEL
    Set logging level: DEBUG, INFO, WARNING, ERROR (default: INFO).

EXIT STATUS

0   Success

1   General error

2   Command line usage error

130 Interrupted by user (Ctrl+C)

NOTES
Pidgin stores all conversation data in JSONL format for maximum portability and transparency. Each event is recorded with full context, allowing complete reconstruction of conversations. Data is automatically imported into DuckDB for efficient analysis after experiments complete.

The tool is designed to be stateless - all experiment state is derived from the JSONL event logs, making it robust against interruptions and allowing experiments to be resumed or analyzed later.

SEE ALSO
Full documentation at: https://github.com/nicholas-lange/pidgin

API documentation: https://github.com/nicholas-lange/pidgin/tree/main/docs/api

YAML specification format: https://github.com/nicholas-lange/pidgin/blob/main/docs/yaml-specs.md

BUGS
Report bugs at: https://github.com/nicholas-lange/pidgin/issues

AUTHOR
Nicholas Lange and contributors