{"id":45906959,"url":"https://github.com/rahulrajaram/gptengage","last_synced_at":"2026-02-28T03:32:04.283Z","repository":{"id":336777338,"uuid":"1131454213","full_name":"rahulrajaram/gptengage","owner":"rahulrajaram","description":"A CLI for LLM-driven agents to debate and converge","archived":false,"fork":false,"pushed_at":"2026-02-25T04:15:34.000Z","size":196,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-25T09:57:16.294Z","etag":null,"topics":["agentic-ai","debate"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rahulrajaram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T03:36:41.000Z","updated_at":"2026-02-25T04:14:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rahulrajaram/gptengage","commit_stats":null,"previous_names":["rahulrajaram/gptengage"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rahulrajaram/gptengage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulrajaram%2Fgptengage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulrajaram%2Fgptengage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulrajaram%2Fgptengage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulrajaram%2Fgptengage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rahulrajaram","download_url":"https://codeload.github.com/rahulrajaram/gptengage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulrajaram%2Fgptengage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29923924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","debate"],"created_at":"2026-02-28T03:32:02.680Z","updated_at":"2026-02-28T03:32:04.270Z","avatar_url":"https://github.com/rahulrajaram.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GPT Engage\n\nGPT Engage is a command-line orchestrator for multi-AI debates. It runs structured debates between Claude, Codex, Gemini, and any CLI-based LLM. GPT Engage executes all participants in parallel, injects debate context between rounds, and produces synthesis reports.\n\n## Overview\n\nGPT Engage solves a specific problem: getting multiple AI perspectives on a single question without manually copying responses between chat interfaces. You provide a topic, GPT Engage invokes each participant simultaneously, shares each round's responses with all participants, and optionally generates a synthesis that identifies consensus and disagreements.\n\n**Key capabilities:**\n\n- **Multi-AI debates** - Run Claude, Codex, and Gemini against the same prompt in parallel\n- **Multi-instance debates** - Spawn multiple instances of the same LLM to leverage nondeterminism\n- **Debate templates** - Use pre-configured scenarios for code review, architecture decisions, and security audits\n- **Synthesis generation** - Automatically generate conclusions that summarize consensus and disagreements\n- **Plugin system** - Add custom CLIs through TOML configuration files\n- **Evolutionary ideation** - Generate divergent idea trees from a seed prompt\n- **Unix composability** - Pipe content via stdin as topic or context\n- **Persistent sessions** - Maintain conversation history across invocations\n\n## Installation\n\n### Prerequisites\n\nGPT Engage requires at least one LLM CLI:\n\n| CLI | Installation |\n|-----|--------------|\n| Claude Code | https://claude.com/claude-code |\n| Codex CLI | https://github.com/openai/codex-cli |\n| Gemini CLI | https://ai.google.dev/docs/gemini_cli |\n\n### Install from crates.io (recommended)\n\n```bash\ncargo install gptengage\n```\n\n### Install pre-built binary\n\nDownload the latest release for your platform:\n\n```bash\n# Linux (x86_64)\ncurl -sSL https://github.com/rahulrajaram/gptengage/releases/latest/download/gptengage-linux-amd64.tar.gz | tar xz -C ~/.local/bin\n\n# macOS (Apple Silicon)\ncurl -sSL https://github.com/rahulrajaram/gptengage/releases/latest/download/gptengage-darwin-arm64.tar.gz | tar xz -C ~/.local/bin\n\n# macOS (Intel)\ncurl -sSL https://github.com/rahulrajaram/gptengage/releases/latest/download/gptengage-darwin-amd64.tar.gz | tar xz -C ~/.local/bin\n```\n\nThen add `~/.local/bin` to your `PATH` if it isn't already:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### Install from source\n\nClone the repository and run the installer:\n\n```bash\ngit clone https://github.com/rahulrajaram/gptengage\ncd gptengage\n./install.sh\n```\n\nThe installer builds GPT Engage in release mode, copies the binary to `~/.local/bin/gptengage`, and verifies your PATH configuration.\n\nAlternatively, build manually:\n\n```bash\ncargo build --release\ncp target/release/gptengage ~/.local/bin/\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### Verify\n\n```bash\ngptengage status\n```\n\n## Quick Start\n\n### Check Available CLIs\n\nRun the status command to see which CLIs GPT Engage detects:\n\n```bash\ngptengage status\n```\n\nOutput:\n\n```\nGPT Engage v1.1.2\n\nDetected CLIs:\n  ✓ claude (Claude Code)\n  ✓ codex (Codex CLI)\n  ✗ gemini (Gemini CLI)\n\nPlugins:\n  ✓ ollama (Local LLM via Ollama)\n\nActive Sessions: 0\n```\n\n### Run a Debate\n\nStart a debate on any topic:\n\n```bash\ngptengage debate \"Should we use TypeScript or JavaScript for our new project?\"\n```\n\nGPT Engage runs all detected CLIs in parallel, collects responses, and displays each round:\n\n```\nGPT ENGAGE DEBATE\nTopic: Should we use TypeScript or JavaScript for our new project?\n\nROUND 1\n────────────────────────────────────────\nClaude:\nTypeScript provides compile-time type checking that catches errors before runtime...\n\nCodex:\nJavaScript offers faster iteration and lower barrier to entry...\n\nROUND 2\n────────────────────────────────────────\n[Each participant responds with context from Round 1]\n\nDEBATE COMPLETE\nSummary: 3 round(s), 2 participant(s)\n```\n\n### Generate Synthesis\n\nAdd `--synthesize` to generate a structured conclusion:\n\n```bash\ngptengage debate \"Microservices vs Monolith\" --synthesize\n```\n\nThe synthesis includes:\n- Summary of the debate\n- Points of consensus\n- Points of disagreement\n- Key insights\n- Recommendation (when applicable)\n\n### Use Templates\n\nList available templates:\n\n```bash\ngptengage template list\n```\n\nRun a debate with a template:\n\n```bash\ngptengage debate \"Review PR #123\" --template code-review\n```\n\n### Pipe Content\n\nPipe file content as context:\n\n```bash\ncat src/auth.rs | gptengage debate \"Review this authentication code\" --stdin-as context\n```\n\nPipe content as the topic:\n\n```bash\necho \"Is Rust better than Go for CLI tools?\" | gptengage debate\n```\n\n## Commands\n\n### debate\n\nRun a structured debate between multiple AI participants.\n\n```bash\ngptengage debate \u003cTOPIC\u003e [OPTIONS]\n```\n\n**Arguments:**\n\n| Argument | Description |\n|----------|-------------|\n| `TOPIC` | The debate topic. Provide as argument or pipe via stdin. |\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--agent \u003cCLI\u003e` | Run multiple instances of a single CLI instead of cross-AI debate. |\n| `--instances \u003cN\u003e` | Number of instances when using `--agent`. Default: 3. |\n| `-m, --model \u003cMODEL\u003e` | Model to use when `--agent` is specified. |\n| `-p, --participants \u003cLIST\u003e` | Specify participants with optional personas and models. Format: `cli:persona` or `cli:persona:model`. |\n| `--agent-file \u003cFILE\u003e` | Load participant definitions from a JSON file. |\n| `--template \u003cNAME\u003e` | Use a predefined debate template. |\n| `-r, --rounds \u003cN\u003e` | Number of debate rounds. Default: 3 (or template default if using `--template`). |\n| `--synthesize` | Generate a synthesis after the debate completes. |\n| `--synthesizer \u003cCLI\u003e` | CLI to use for synthesis generation. Default: `claude`. |\n| `--output \u003cFORMAT\u003e` | Output format: `text`, `json`, or `markdown`. Default: `text`. |\n| `--stdin-as \u003cMODE\u003e` | How to interpret stdin: `auto`, `context`, or `ignore`. Default: `auto`. |\n| `--timeout \u003cSECONDS\u003e` | Timeout per CLI per round. Default: 120. |\n| `--write` | Allow write access within the current directory. Default: read-only. |\n\n**Examples:**\n\nCross-AI debate with default participants:\n\n```bash\ngptengage debate \"Should we adopt Kubernetes?\"\n```\n\nMulti-instance debate with the same CLI:\n\n```bash\ngptengage debate \"Code review best practices\" --agent claude --instances 5\n```\n\nDebate with personas:\n\n```bash\ngptengage debate \"API design strategy\" -p \"claude:Backend Lead,codex:Frontend Lead,gemini:Product Manager\"\n```\n\nDebate with template and synthesis:\n\n```bash\ngptengage debate \"Review this PR\" --template code-review --synthesize --output markdown\n```\n\nJSON output for programmatic consumption:\n\n```bash\ngptengage debate \"topic\" --output json \u003e result.json\n```\n\n### invoke\n\nInvoke a single CLI with optional session support.\n\n```bash\ngptengage invoke \u003cCLI\u003e \u003cPROMPT\u003e [OPTIONS]\n```\n\n**Arguments:**\n\n| Argument | Description |\n|----------|-------------|\n| `CLI` | The CLI to invoke: `claude`, `codex`, `gemini`, or a plugin name. |\n| `PROMPT` | The prompt to send. Provide as argument or pipe via stdin. |\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `-m, --model \u003cMODEL\u003e` | Model to use for the CLI (e.g., `claude-sonnet-4-20250514`, `gpt-4o`, `gemini-2.5-pro`). |\n| `-s, --session \u003cNAME\u003e` | Use or create a persistent session. |\n| `--topic \u003cDESC\u003e` | Set the session topic. Auto-generated if omitted. |\n| `-c, --context-file \u003cPATH\u003e` | Include file contents in the prompt. |\n| `--stdin-as \u003cMODE\u003e` | How to interpret stdin: `auto`, `context`, or `ignore`. Default: `auto`. |\n| `-t, --timeout \u003cSECONDS\u003e` | Command timeout. Default: 120. |\n| `--write` | Allow write access within the current directory. |\n\n**Examples:**\n\nSimple invocation:\n\n```bash\ngptengage invoke claude \"Explain async/await in Rust\"\n```\n\nWith session for multi-turn conversation:\n\n```bash\ngptengage invoke claude \"Review my authentication code\" --session auth-review\ngptengage invoke claude \"Fix the JWT vulnerability you found\" --session auth-review\n```\n\nWith context file:\n\n```bash\ngptengage invoke codex \"Optimize this function\" --context-file src/parser.rs\n```\n\nPipe content as prompt:\n\n```bash\necho \"What is 2 + 2?\" | gptengage invoke claude\n```\n\n### template\n\nManage debate templates.\n\n```bash\ngptengage template \u003cCOMMAND\u003e\n```\n\n**Subcommands:**\n\n| Command | Description |\n|---------|-------------|\n| `list` | List all available templates (built-in and user-defined). |\n| `show \u003cNAME\u003e` | Display template details including participants and context. |\n\n**Examples:**\n\nList templates:\n\n```bash\ngptengage template list\n```\n\nOutput:\n\n```\nAvailable Templates:\n\n  code-review (built-in)\n      Multi-perspective code review with security, performance, and maintainability focus\n      Participants: 3, Rounds: 2\n\n  architecture-decision (built-in)\n      Evaluate architectural choices from multiple stakeholder perspectives\n      Participants: 3, Rounds: 3\n\n  security-audit (built-in)\n      Security-focused analysis from CISO, engineer, and compliance perspectives\n      Participants: 3, Rounds: 2\n\nUse a template: gptengage debate \"topic\" --template \u003cname\u003e\n```\n\nShow template details:\n\n```bash\ngptengage template show code-review\n```\n\n### plugin\n\nManage custom CLI plugins.\n\n```bash\ngptengage plugin \u003cCOMMAND\u003e\n```\n\n**Subcommands:**\n\n| Command | Description |\n|---------|-------------|\n| `list` | List all installed plugins. |\n| `validate \u003cFILE\u003e` | Validate a plugin configuration file. |\n\n**Examples:**\n\nList plugins:\n\n```bash\ngptengage plugin list\n```\n\nValidate a plugin file:\n\n```bash\ngptengage plugin validate ~/.gptengage/plugins/ollama.toml\n```\n\n### session\n\nManage persistent conversation sessions.\n\n```bash\ngptengage session \u003cCOMMAND\u003e\n```\n\n**Subcommands:**\n\n| Command | Description |\n|---------|-------------|\n| `list` | List all active sessions. |\n| `show \u003cNAME\u003e` | Display session history. |\n| `end \u003cNAME\u003e` | Delete a session. |\n| `end --all` | Delete all sessions. |\n\n### config\n\nManage GPT Engage configuration.\n\n```bash\ngptengage config \u003cCOMMAND\u003e\n```\n\n**Subcommands:**\n\n| Command | Description |\n|---------|-------------|\n| `get \u003cKEY\u003e` | Get the value of a configuration key. |\n| `set \u003cKEY\u003e \u003cVALUE\u003e` | Set a configuration key to a value. |\n| `list` | List all configuration settings. |\n\n**Examples:**\n\nList all settings:\n\n```bash\ngptengage config list\n```\n\nGet a specific setting:\n\n```bash\ngptengage config get default_timeout\n```\n\nSet a configuration value:\n\n```bash\ngptengage config set default_timeout 180\n```\n\n### generate-agents\n\nGenerate AI-powered agent definitions for structured debates.\n\n```bash\ngptengage generate-agents --topic \u003cTOPIC\u003e --roles \u003cROLES\u003e --output \u003cFILE\u003e [OPTIONS]\n```\n\n**Required Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--topic \u003cTOPIC\u003e` | The debate topic for context. |\n| `--roles \u003cROLES\u003e` | Comma-separated list of roles. |\n| `-o, --output \u003cFILE\u003e` | Output file path for generated JSON. |\n\n**Optional Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--use-cli \u003cCLI\u003e` | CLI to use for generation. Default: `claude`. |\n| `-t, --timeout \u003cSECONDS\u003e` | Timeout. Default: 120. |\n| `--write` | Allow write access within the current directory. |\n\n**Example:**\n\n```bash\ngptengage generate-agents \\\n  --topic \"Should we migrate to microservices?\" \\\n  --roles \"CEO,Principal Architect,Product Manager\" \\\n  --output agents.json\n\ngptengage debate \"Should we migrate to microservices?\" --agent-file agents.json\n```\n\n### ideate\n\nGenerate divergent ideas from a seed using evolutionary ideation. GPT Engage builds an idea tree by expanding a seed idea into multiple branches, optionally going multiple levels deep.\n\n```bash\ngptengage ideate \u003cSEED\u003e [OPTIONS]\n```\n\n**Arguments:**\n\n| Argument | Description |\n|----------|-------------|\n| `SEED` | The seed idea to diverge from. |\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--sigma \u003cSIGMA\u003e` | Creativity level (0.0-3.0). Higher values produce more divergent ideas. Default: `1.0`. |\n| `--select` | Interactively select which L1 ideas to expand to L2. |\n| `--depth \u003cDEPTH\u003e` | Depth of idea tree (1-5). Default: `2`. |\n| `--force` | Bypass sigma (\u003e3.0) and depth (\u003e5) safety limits. |\n| `--cli \u003cCLI\u003e` | Which CLI to use. Default: `claude`. |\n| `-o, --output \u003cOUTPUT\u003e` | Output format: `text` or `json`. Default: `text`. |\n| `-t, --timeout \u003cTIMEOUT\u003e` | Timeout per CLI invocation. Default: `120`. |\n| `--color \u003cCOLOR\u003e` | Color mode: `auto`, `truecolor`, `256`, or `none`. Default: `auto`. |\n| `--pager` | Display output in a scrollable pager. |\n\n**Examples:**\n\nGenerate ideas from a seed:\n\n```bash\ngptengage ideate \"A CLI tool that helps developers write better commit messages\"\n```\n\nHigh-creativity deep exploration:\n\n```bash\ngptengage ideate \"Sustainable urban farming\" --sigma 2.5 --depth 3\n```\n\nInteractive selection with pager:\n\n```bash\ngptengage ideate \"New authentication methods\" --select --pager\n```\n\nJSON output for programmatic use:\n\n```bash\ngptengage ideate \"ML-powered code review\" --output json \u003e ideas.json\n```\n\n### status\n\nDisplay GPT Engage status, detected CLIs, plugins, and active sessions.\n\n```bash\ngptengage status\n```\n\n## Debate Templates\n\nGPT Engage includes five built-in templates. Each template defines participants with specific personas, instructions, and expertise areas.\n\n### code-review\n\nMulti-perspective code review focusing on security, performance, and maintainability.\n\n**Participants:**\n- Security Reviewer (Claude) - Identifies vulnerabilities, injection risks, and authentication issues\n- Performance Reviewer (Claude) - Finds bottlenecks, inefficient algorithms, and resource leaks\n- Maintainability Reviewer (Claude) - Evaluates readability, test coverage, and coding standards\n\n**Usage:**\n\n```bash\ncat pull_request.diff | gptengage debate \"Review these changes\" --template code-review --stdin-as context\n```\n\n### architecture-decision\n\nEvaluate architectural choices from multiple stakeholder perspectives.\n\n**Participants:**\n- Solution Architect (Claude) - Focuses on scalability, reliability, and technical trade-offs\n- Senior Developer (Codex) - Considers implementation complexity and developer experience\n- Operations Engineer (Gemini) - Evaluates deployment, monitoring, and operational concerns\n\n### security-audit\n\nSecurity-focused analysis from multiple security perspectives.\n\n**Participants:**\n- CISO (Claude) - Strategic security risks and business impact\n- Security Engineer (Claude) - Technical vulnerabilities and attack vectors\n- Compliance Officer (Claude) - Regulatory requirements and audit concerns\n\n### api-design\n\nAPI design review from consumer and provider perspectives.\n\n**Participants:**\n- API Architect (Claude) - RESTful design, versioning, and documentation\n- Frontend Developer (Codex) - Developer experience and client integration\n- Backend Developer (Gemini) - Implementation concerns and performance\n\n### incident-postmortem\n\nStructured incident analysis for post-incident reviews.\n\n**Participants:**\n- SRE Lead (Claude) - Root cause analysis and reliability improvements\n- Development Lead (Codex) - Code-level issues and fix strategies\n- Product Manager (Gemini) - Customer impact and communication\n\n### Custom Templates\n\nCreate custom templates by adding TOML files to `~/.gptengage/templates/`:\n\n```toml\n# ~/.gptengage/templates/my-template.toml\n[template]\nname = \"my-template\"\ndescription = \"Custom debate template\"\ndefault_rounds = 3\n\n[[participants]]\ncli = \"claude\"\npersona = \"Expert A\"\ninstructions = \"Focus on aspect X. Provide specific examples and cite sources.\"\nexpertise = [\"topic1\", \"topic2\", \"topic3\"]\n\n[[participants]]\ncli = \"codex\"\npersona = \"Expert B\"\ninstructions = \"Focus on aspect Y. Challenge assumptions and propose alternatives.\"\nexpertise = [\"topic4\", \"topic5\"]\n\n[context]\nprefix = \"Consider the following context:\"\nsuffix = \"Provide actionable recommendations.\"\n```\n\n## Plugin System\n\nGPT Engage supports custom CLIs through TOML-based plugin configuration. Plugins enable integration with any command-line LLM tool.\n\n### Plugin Location\n\nPlace plugin files in `~/.gptengage/plugins/` with `.toml` extension.\n\n### Plugin Format\n\n```toml\n# ~/.gptengage/plugins/ollama.toml\n[plugin]\nname = \"ollama\"\ndescription = \"Local LLM via Ollama\"\ncommand = \"ollama\"\n\n[invoke]\nbase_args = [\"run\", \"llama3\"]\nprompt_mode = \"stdin\"\n\n[access]\nreadonly_args = []\nwrite_args = []\n\n[detection]\ncheck_command = \"ollama\"\ncheck_args = [\"--version\"]\n```\n\n### Configuration Fields\n\n**[plugin] section:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `name` | Yes | Plugin identifier used in commands. |\n| `description` | Yes | Human-readable description. |\n| `command` | Yes | Executable command name. |\n\n**[invoke] section:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `base_args` | Yes | Base arguments passed to the command. |\n| `prompt_mode` | Yes | How to pass the prompt: `stdin`, `arg`, or `arg_last`. |\n| `prompt_arg` | No | Argument flag for prompt when using `arg` mode. |\n\n**[access] section:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `readonly_args` | Yes | Additional arguments for read-only mode. |\n| `write_args` | Yes | Additional arguments for write mode. |\n\n**[detection] section:**\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `check_command` | Yes | Command to verify CLI availability. |\n| `check_args` | Yes | Arguments for availability check. |\n\n### Example: Aider Plugin\n\n```toml\n# ~/.gptengage/plugins/aider.toml\n[plugin]\nname = \"aider\"\ndescription = \"AI pair programming with Aider\"\ncommand = \"aider\"\n\n[invoke]\nbase_args = [\"--message\"]\nprompt_mode = \"arg_last\"\n\n[access]\nreadonly_args = [\"--no-auto-commits\"]\nwrite_args = [\"--auto-commits\"]\n\n[detection]\ncheck_command = \"aider\"\ncheck_args = [\"--version\"]\n```\n\n### Using Plugins\n\nAfter creating a plugin file, verify it appears in status:\n\n```bash\ngptengage status\n```\n\nUse the plugin in debates:\n\n```bash\ngptengage debate \"topic\" -p \"claude:Analyst,ollama:Reviewer\"\n```\n\nOr invoke directly:\n\n```bash\ngptengage invoke ollama \"Explain this concept\"\n```\n\n## Stdin Piping\n\nGPT Engage accepts input via Unix pipes for composability with other tools.\n\n### Piping Modes\n\n| Mode | Behavior |\n|------|----------|\n| `auto` | Use stdin as topic if no topic argument provided; otherwise use as context. |\n| `context` | Always prepend stdin as context with `[PIPED CONTEXT]` markers. |\n| `ignore` | Discard stdin input. |\n\n### Examples\n\nPipe as topic:\n\n```bash\necho \"Is functional programming better than OOP?\" | gptengage debate\n```\n\nPipe file as context with explicit topic:\n\n```bash\ncat error.log | gptengage debate \"What caused this error?\" --stdin-as context\n```\n\nPipe git diff for code review:\n\n```bash\ngit diff HEAD~1 | gptengage debate \"Review these changes\" --template code-review --stdin-as context\n```\n\nPipe to invoke:\n\n```bash\ncat README.md | gptengage invoke claude \"Summarize this document\"\n```\n\n### Context Injection Format\n\nWhen stdin is used as context, GPT Engage injects it with markers:\n\n```\n[PIPED CONTEXT]\n\u003cstdin content\u003e\n[/PIPED CONTEXT]\n\n\u003ctopic or prompt\u003e\n```\n\n## Synthesis Generation\n\nGPT Engage generates structured synthesis reports after debates complete.\n\n### Enabling Synthesis\n\nAdd `--synthesize` to any debate command:\n\n```bash\ngptengage debate \"topic\" --synthesize\n```\n\n### Specifying Synthesizer\n\nBy default, Claude generates the synthesis. Specify a different CLI with `--synthesizer`:\n\n```bash\ngptengage debate \"topic\" --synthesize --synthesizer codex\n```\n\n### Synthesis Output\n\nThe synthesis includes:\n\n| Field | Description |\n|-------|-------------|\n| `summary` | 2-3 sentence overview of the debate. |\n| `consensus_points` | Points where participants agreed. |\n| `disagreement_points` | Points where participants disagreed. |\n| `key_insights` | Notable insights that emerged. |\n| `recommendation` | Actionable recommendation when applicable. |\n\n**Text output:**\n\n```\nSYNTHESIS\n────────────────────────────────────────\n\nSummary:\n  The debate focused on microservices vs monolith architecture...\n\nConsensus:\n  • All participants agreed that team size affects the decision\n  • Performance requirements favor monolithic architecture initially\n\nDisagreements:\n  • Timeline for migration varied significantly between perspectives\n\nKey Insights:\n  • Start with a modular monolith and extract services when needed\n\nRecommendation:\n  Begin with a well-structured monolith and identify extraction candidates...\n```\n\n**JSON output:**\n\n```json\n{\n  \"topic\": \"Microservices vs Monolith\",\n  \"rounds\": [...],\n  \"synthesis\": {\n    \"summary\": \"The debate focused on...\",\n    \"consensus_points\": [\"Point 1\", \"Point 2\"],\n    \"disagreement_points\": [\"Point 1\"],\n    \"key_insights\": [\"Insight 1\"],\n    \"recommendation\": \"Begin with...\"\n  }\n}\n```\n\n## Agent Definition Files\n\nAgent definition files provide structured participant configurations for programmatic use.\n\n### File Format\n\n```json\n{\n  \"schema_version\": \"1.0\",\n  \"generated_by\": \"gptengage-claude\",\n  \"participants\": [\n    {\n      \"cli\": \"claude\",\n      \"persona\": \"CEO\",\n      \"instructions\": \"Focus on business impact, ROI, and strategic alignment. Be decisive but ask about risks.\",\n      \"expertise\": [\"business strategy\", \"finance\", \"leadership\"],\n      \"communication_style\": \"Executive - concise and action-oriented\"\n    }\n  ]\n}\n```\n\n### Field Validation\n\n| Field | Required | Validation |\n|-------|----------|------------|\n| `schema_version` | Yes | Must be `\"1.0\"`. |\n| `generated_by` | No | Non-empty if present. |\n| `participants` | Yes | At least one participant. |\n| `participants[].cli` | Yes | Valid CLI name or plugin. |\n| `participants[].persona` | Yes | Non-empty string. |\n| `participants[].instructions` | Yes | Minimum 10 characters. |\n| `participants[].expertise` | No | Array of strings. |\n| `participants[].communication_style` | No | Non-empty if present. |\n\n### Generating Agent Files\n\nUse `generate-agents` to create agent files with AI assistance:\n\n```bash\ngptengage generate-agents \\\n  --topic \"Cloud migration strategy\" \\\n  --roles \"CTO,Cloud Architect,Security Lead\" \\\n  --output agents.json\n```\n\n## Session Management\n\nSessions maintain conversation history across invocations without modifying underlying CLIs.\n\n### How Sessions Work\n\nWhen you continue a session, GPT Engage injects the full history into the prompt:\n\n```\n[CONVERSATION HISTORY]\nUser: Review my authentication code\nAssistant: I found 3 vulnerabilities...\n\nUser: Fix the JWT vulnerability\n[/CONVERSATION HISTORY]\n\n[CURRENT REQUEST]\nExplain how to implement secure token rotation\n[/CURRENT REQUEST]\n```\n\n### Session Storage\n\nSessions are stored in `~/.gptengage/sessions/` as JSON files:\n\n```json\n{\n  \"name\": \"auth-review\",\n  \"cli\": \"claude\",\n  \"topic\": \"Review my authentication code\",\n  \"createdAt\": \"2024-01-04T08:30:00Z\",\n  \"lastInteraction\": \"2024-01-04T10:45:00Z\",\n  \"turns\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"Review my authentication code\",\n      \"timestamp\": \"2024-01-04T08:30:00Z\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"I found 3 vulnerabilities...\",\n      \"timestamp\": \"2024-01-04T08:31:15Z\"\n    }\n  ]\n}\n```\n\n### Security Considerations\n\nSession files are stored unencrypted. Do not include sensitive information (passwords, API keys, PII) in session prompts. Use `gptengage session end --all` after working with sensitive topics.\n\n## Output Formats\n\nGPT Engage supports three output formats for debate results.\n\n### Text (Default)\n\nHuman-readable format with visual separators:\n\n```bash\ngptengage debate \"topic\"\n```\n\n### JSON\n\nMachine-readable format for programmatic consumption:\n\n```bash\ngptengage debate \"topic\" --output json\n```\n\nOutput structure:\n\n```json\n{\n  \"gptengage_version\": \"1.1.2\",\n  \"topic\": \"Should we use Rust?\",\n  \"rounds\": [\n    [\n      {\"cli\": \"claude\", \"persona\": null, \"response\": \"...\"},\n      {\"cli\": \"codex\", \"persona\": null, \"response\": \"...\"}\n    ]\n  ],\n  \"synthesis\": null\n}\n```\n\n### Markdown\n\nFormatted for documentation or reports:\n\n```bash\ngptengage debate \"topic\" --output markdown \u003e debate.md\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | CLI not found or invocation failed |\n| 2 | Session error or invalid format |\n| 3 | File not found |\n| 4 | Timeout exceeded |\n\nUse exit codes for scripting:\n\n```bash\ngptengage invoke claude \"test\" --timeout 60\nif [ $? -eq 4 ]; then\n  echo \"Timeout - increase --timeout value\"\nfi\n```\n\n## CLI Requirements\n\n### Claude Code\n\nGPT Engage invokes Claude with:\n\n```bash\nclaude -p --tools Read --allowed-tools Read\n```\n\nWith `--write` flag:\n\n```bash\nclaude -p\n```\n\n### Codex CLI\n\nGPT Engage invokes Codex with:\n\n```bash\ncodex exec --sandbox read-only --cd .\n```\n\nWith `--write` flag:\n\n```bash\ncodex exec --cd .\n```\n\n### Gemini CLI\n\nGPT Engage invokes Gemini with:\n\n```bash\ngemini --sandbox --include-directories .\n```\n\nGemini typically requires longer timeouts. Use `--timeout 180` for complex prompts.\n\n## File Locations\n\n| Path | Purpose |\n|------|---------|\n| `~/.gptengage/config.json` | Configuration file |\n| `~/.gptengage/sessions/` | Session storage |\n| `~/.gptengage/plugins/` | Custom CLI plugins |\n| `~/.gptengage/templates/` | User-defined templates |\n\n## Troubleshooting\n\n### CLI not found\n\nVerify the CLI is installed and in your PATH:\n\n```bash\nwhich claude\nwhich codex\nwhich gemini\n```\n\n### Codex requires git repository trust\n\nRun Codex once in a trusted directory to add it to the trust list, or run GPT Engage from within a git repository.\n\n### Gemini timeout errors\n\nIncrease the timeout:\n\n```bash\ngptengage invoke gemini \"prompt\" --timeout 180\n```\n\n### Plugin not detected\n\nVerify the plugin file syntax:\n\n```bash\ngptengage plugin validate ~/.gptengage/plugins/myplugin.toml\n```\n\nCheck that the plugin command exists:\n\n```bash\nwhich \u003ccommand-name\u003e\n```\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/rahulrajaram/gptengage\ncd gptengage\ncargo build --release\ncargo test\n```\n\n### Project Structure\n\n```\nsrc/\n├── main.rs           # Entry point\n├── lib.rs            # Library root\n├── cli.rs            # Argument parsing\n├── commands/         # Command implementations\n├── invokers/         # CLI invokers\n├── orchestrator/     # Debate orchestration\n├── plugins/          # Plugin system\n├── templates/        # Template system\n├── session/          # Session management\n└── utils/            # Utilities including stdin handling\n```\n\n### Running Tests\n\n```bash\ncargo test\n```\n\n## License\n\nMIT License. See LICENSE file.\n\n## Support\n\nReport issues at https://github.com/rahulrajaram/gptengage/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahulrajaram%2Fgptengage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahulrajaram%2Fgptengage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahulrajaram%2Fgptengage/lists"}