🤖 GPT-5 CLI Agent

A professional, unified command-line interface for all OpenAI GPT-5 model variants

---

A legendary, production-ready CLI for GPT-5 — featuring streaming responses, multi-agent support, rich exports, and an enhanced terminal experience.

✨ Features • ⚙️ Installation • 🚀 Quick Start • 💻 Commands • 📊 Models • 🏗️ Architecture • 🔒 Security • 👥 Authors • 📄 License

---

📋 Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Interactive Commands
• File Inclusion
• Export Formats
• Model Comparison
• Configuration
• Project Structure
• Performance Metrics
• Security
• Troubleshooting
• Authors
• Contributing
• License

---

🌟 Overview

GPT-5 CLI Agent is a professional, unified command-line interface engineered to harness the full power of OpenAI's GPT-5 model family. Built with developer experience in mind, it provides a seamless terminal-native workflow for AI-assisted development, analysis, and automation.

Whether you need the raw intelligence of GPT-5, the efficiency of GPT-5 Mini, or the blazing speed of GPT-5 Nano — this single CLI handles all three with persistent history, advanced configuration, and beautiful formatted output.

╔══════════════════════════════════════════════════════╗
║          🤖  GPT-5 Unified CLI Agent  v1.0.0         ║
║     Powered by OpenAI GPT-5 | Built for Builders     ║
╚══════════════════════════════════════════════════════╝

---

✨ Features

🧠 AI Capabilities ✅ GPT-5 — Full reasoning power ✅ GPT-5 Mini — Balanced performance ✅ GPT-5 Nano — Fast & lightweight ✅ Streaming token-by-token output ✅ Configurable reasoning effort ✅ Custom system prompts per agent	💾 Session Management ✅ Persistent conversation history ✅ Automatic backups before each session ✅ History search with /search <term> ✅ Multi-agent isolation ✅ Session statistics & analytics ✅ Auto-save on exit
📤 Export System ✅ JSON — Machine-readable full history ✅ TXT — Plain text transcripts ✅ Markdown — Formatted documentation ✅ HTML — Styled web-ready reports ✅ Timestamped export filenames ✅ One-command export from CLI	🎨 Terminal Experience ✅ Rich colored output with colorama ✅ ASCII banners & status indicators ✅ Syntax-aware file inclusion ✅ Progress feedback on long requests ✅ Graceful Ctrl+C / Ctrl+D handling ✅ Cross-platform (Linux, macOS, Windows)

---

📦 Requirements

Dependency	Version	Purpose
python	≥ 3.10	Runtime
requests	≥ 2.31.0	HTTP API calls
pyyaml	≥ 6.0.1	Config file parsing
colorama	≥ 0.4.6	Cross-platform terminal colors

---

⚙️ Installation

1. Clone the Repository

git clone https://github.com/simonpierreboucher02/gpt5-cli-agent.git
cd gpt5-cli-agent

2. Create a Virtual Environment (Recommended)

# Create environment
python -m venv venv

# Activate — macOS / Linux
source venv/bin/activate

# Activate — Windows
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Your OpenAI API Key

# macOS / Linux (add to ~/.zshrc or ~/.bashrc for persistence)
export OPENAI_API_KEY=sk-...your-key-here...

# Windows (Command Prompt)
set OPENAI_API_KEY=sk-...your-key-here...

# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-...your-key-here..."

Tip: Add the export line to your shell profile to avoid setting it every session.

---

🚀 Quick Start

Launch with GPT-5 (Default)

python main.py --agent-id my-agent --model gpt-5

Launch with GPT-5 Mini

python main.py --agent-id my-agent --model gpt-5-mini

Launch with GPT-5 Nano

python main.py --agent-id my-agent --model gpt-5-nano

List All Agents

python main.py --list

Configure an Agent Interactively

python main.py --agent-id my-agent --config

Export a Conversation

# Export as HTML
python main.py --agent-id my-agent --export html

# Export as Markdown
python main.py --agent-id my-agent --export md

# Export as JSON
python main.py --agent-id my-agent --export json

Show Help

python main.py --help

---

💻 Interactive Commands

Once inside a chat session, use these slash commands:

Command	Description	Example
/help	Display all available commands	/help
/history [n]	Show last n messages (default: 10)	/history 20
/search <term>	Full-text search across conversation	/search authentication
/stats	Show token usage, message count, session duration	/stats
/config	Display current agent configuration	/config
/export <format>	Export conversation (json/txt/md/html)	/export md
/clear	Clear conversation history	/clear
/files	List files available for inclusion	/files
/info	Show agent ID, model, and metadata	/info
/quit	Exit the chat session	/quit

---

📁 File Inclusion

Embed file contents directly into your prompts using the {filename} syntax:

> Please review this code: {main.py}

> Compare these two configs: {config.yaml}, {settings.json}

> Analyze the project structure based on: {README.md}

Supported File Types

Category	Extensions
Python	.py, .pyw
JavaScript / TypeScript	.js, .ts, .jsx, .tsx
Systems	.c, .cpp, .h, .go, .rs
Web	.html, .css, .scss
Data / Config	.json, .yaml, .yml, .toml, .ini
Documentation	.md, .rst, .txt
Shell	.sh, .bash, .zsh, .ps1

---

📤 Export Formats

Format	Extension	Best For
JSON	.json	Programmatic processing, data pipelines
Plain Text	.txt	Simple archival, sharing
Markdown	.md	Documentation, GitHub wikis
HTML	.html	Styled reports, client presentations

Exports are saved to: agents/<agent-id>/exports/

---

📊 Model Comparison

Model	Intelligence	Speed	Cost	Best Use Case	Timeout
	🌟🌟🌟🌟🌟	🐢	💰💰💰	Complex reasoning, deep analysis, research	3–12 min
	🌟🌟🌟🌟	🚗	💰💰	Balanced workloads, code review, writing	1.5–6 min
	🌟🌟🌟	🚀	💰	Quick Q&A, summaries, simple tasks	1–4 min

Choosing the Right Model

Is the task complex or requires deep reasoning?
  YES → Use GPT-5
  NO  → Do you need a good balance of speed and quality?
          YES → Use GPT-5 Mini
          NO  → Use GPT-5 Nano (fastest, cheapest)

---

⚙️ Configuration

Each agent stores its configuration in agents/<agent-id>/config.yaml:

# agents/my-agent/config.yaml

model: gpt-5                    # gpt-5 | gpt-5-mini | gpt-5-nano
temperature: 0.7                # 0.0 (deterministic) → 2.0 (creative)
max_tokens: 4096                # Maximum response tokens
reasoning_effort: medium        # low | medium | high (GPT-5 only)
stream: true                    # Enable token streaming
system_prompt: |
  You are a senior software engineer.
  Provide concise, production-ready code.

Configuration Parameters

Parameter	Type	Default	Description
model	string	gpt-5	Model variant to use
temperature	float	0.7	Response randomness (0–2)
max_tokens	int	4096	Max tokens per response
reasoning_effort	string	medium	Reasoning depth (GPT-5 only)
stream	bool	true	Stream tokens in real time
system_prompt	string	—	Custom system instructions

---

🏗️ Project Structure

gpt5-cli-agent/
│
├── 📄 main.py              # CLI entrypoint, argument parsing, session loop
├── 🧠 agent.py             # Agent class, API calls, streaming logic (462 lines)
├── ⚙️  config.py            # Configuration management, YAML read/write (89 lines)
├── 📤 export.py            # Multi-format export engine (424 lines)
├── 🔧 utils.py             # File inclusion, formatting utilities (285 lines)
├── 📋 requirements.txt     # Python dependencies
├── 📖 README.md            # This file
│
└── agents/                 # Per-agent data directory (auto-created)
    └── {agent-id}/
        ├── config.yaml     # Agent-specific configuration
        ├── history.json    # Persistent conversation history
        ├── secrets.json    # API keys (git-ignored)
        ├── backups/        # Automatic history backups
        ├── logs/           # Session logs
        └── exports/        # Exported conversations

Module Responsibilities

Module	Lines	Responsibility
main.py	616	CLI entry, argument parsing, REPL loop
agent.py	462	GPT-5 API integration, streaming
export.py	424	JSON / TXT / Markdown / HTML export
utils.py	285	File inclusion, text formatting
config.py	89	YAML config read/write
Total	1,876	Full project

---

📈 Performance Metrics

Metric	GPT-5	GPT-5 Mini	GPT-5 Nano
Avg. First Token	~3–8s	~1–3s	~0.5–1.5s
Avg. Full Response	~30–120s	~15–60s	~5–20s
Token Throughput	~30 tok/s	~60 tok/s	~100 tok/s
Context Window	128K tokens	128K tokens	128K tokens
Streaming Support	✅	✅	✅

Performance varies based on OpenAI infrastructure load and response complexity.

---

🔒 Security

• 🔑 API keys are stored in secrets.json which is automatically excluded via .gitignore
• 🚫 No sensitive data is ever included in logs or exports
• ✅ Environment variable support — use OPENAI_API_KEY instead of file storage
• 🔐 Multi-model key support — separate keys per model if needed
• 📂 Agent isolation — each agent's data is fully sandboxed in its own directory
• 🛡️ No telemetry — no usage data is sent anywhere except OpenAI's API

Security Best Practices

# Always use environment variables in production
export OPENAI_API_KEY=sk-...

# Never commit secrets — verify .gitignore is active
cat .gitignore | grep secrets

# Restrict permissions on the agents directory
chmod 700 agents/

---

🐛 Troubleshooting

Common Issues

Error	Cause	Fix
ModuleNotFoundError	Missing dependency	pip install -r requirements.txt
AuthenticationError	Invalid API key	Verify OPENAI_API_KEY is set and valid
TimeoutError	Request too long	Reduce max_tokens or lower reasoning_effort
FileNotFoundError	File inclusion failed	Run /files to list available files
JSONDecodeError	Corrupted history	Delete agents/<id>/history.json to reset
RateLimitError	API quota exceeded	Wait and retry, or upgrade OpenAI tier

Debug Mode

# Enable verbose logging
python main.py --agent-id my-agent --model gpt-5 --debug

Reset an Agent

# Delete agent history (keeps config)
rm agents/my-agent/history.json

# Full reset (removes all agent data)
rm -rf agents/my-agent/

---

👥 Authors

🧑‍💻 Simon-Pierre Boucher Creator & Lead Developer AI/ML engineer and researcher building production-grade AI tooling. Passionate about making large language models accessible through elegant command-line interfaces. 🎓 Université Laval 🌐 www.spboucher.ai 📧 spbou4@protonmail.com

🤖 Claude (Anthropic) AI Co-Author & Documentation Assistant This README was co-authored with Claude, Anthropic's AI assistant, to ensure comprehensive documentation, accurate technical details, and a polished developer experience. 🧠 Claude Sonnet 4.6 🏢 Anthropic 🤝 AI pair-programming partner

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

# 1. Fork the repository on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/gpt5-cli-agent.git
cd gpt5-cli-agent

# 3. Create a feature branch
git checkout -b feature/my-new-feature

# 4. Make your changes and test
python main.py --agent-id test --model gpt-5-nano

# 5. Commit your changes
git add .
git commit -m "feat: add my new feature"

# 6. Push and open a Pull Request
git push origin feature/my-new-feature

Contribution Guidelines

• Follow PEP 8 style for Python code
• Add docstrings to new functions and classes
• Test with all three models before submitting
• Update this README if you add user-facing features
• Keep PRs focused — one feature or fix per PR

---

📄 License

MIT License

Copyright (c) 2025 Simon-Pierre Boucher

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

Built with ❤️ by Simon-Pierre Boucher & Claude

If this project helped you, consider giving it a ⭐ on GitHub!