Agent Launcher 🤖
Bilingual (English/Français) launcher for AI coding agents (Codex & Claude Code).
A powerful, user-friendly command-line tool that simplifies launching and managing AI coding agents with advanced features like review mode, loop mode, and configuration persistence.
✨ Features
- 🎯 Guided Selection: Interactive prompts to choose between Codex and Claude
- 🔒 Safety Controls: Configurable sandbox and approval bypass settings
- 🔄 Review Mode: Automatic cross-agent validation and debugging
- 🔁 Loop Mode: Iterative improvements with time-based iterations
- 💾 Persistent Configuration: Save your preferences for future use
- 🌍 Bilingual: Full English and French support
- 📝 Command History: Track all your agent invocations
- 🎨 Smart Terminal Detection: Automatic color support based on your terminal
- 🔧 Environment Variables: Configure via environment for automation
- 📦 Easy Installation: Self-installing with
--installflag
📦 Installation
Option 1: pip install (Recommended)
pip install agent-launcher
Option 2: Direct Download
# Download the script
curl -o agent.py https://raw.githubusercontent.com/Actigence-Code/agent-launcher/main/agent.py
# Make it executable
chmod +x agent.py
# Install globally
./agent.py --install
Option 3: From Source
git clone https://github.com/Actigence-Code/agent-launcher.git
cd agent-launcher
pip install -e .
🚀 Quick Start
Basic Usage
# Interactive mode - will prompt for choices
agent
# Specify agent directly
agent --agent claude
# With bypass mode (be careful!)
agent --agent codex --bypass
# Dry run to see what would be executed
agent --dry-run --agent claude
Advanced Features
# Review mode: Second agent reviews the first agent's work
agent --agent claude --review
# Loop mode: Iterate improvements for 30 minutes
agent --agent claude --loop 30
# Combined: Loop with review
agent --agent claude --loop 60 --review
# Specify model and additional directories
agent --agent claude --model sonnet --add-dir /path/to/project
# Save your preferences as defaults
agent --agent claude --bypass --save-defaults
Environment Variables
# Configure via environment
export AGENT_TYPE=claude
export AGENT_BYPASS=true
export AGENT_MODEL=opus
# Now just run
agent
📖 Usage Examples
Example 1: Quick Interactive Session
$ agent
Agent ? (1) Codex | (2) Claude - tapez le numéro ou le nom: 2
Dangerously bypass approvals & sandbox ? [y/N | o/N] : n
Agent Ready / Agent Prêt
- Agent: Claude | Agent choisi : Claude
- Bypass: DISABLED | Bypass : DÉSACTIVÉ
WARNING: Read the official docs before enabling bypass.
Bon travail / Happy coding!
Launching Claude...
Example 2: Code Review Workflow
# Have Claude write the code, then Codex reviews it
agent --agent claude --review "Implement a binary search tree in Python"
# Or vice versa
agent --agent codex --review "Create a REST API with authentication"
Example 3: Iterative Improvement
# Work on optimizing code for 45 minutes
agent --agent claude --loop 45 --bypass "Optimize the database queries in src/models"
Example 4: Non-Interactive Automation
# Use in scripts or CI/CD
AGENT_TYPE=claude AGENT_BYPASS=false agent --quiet "Run tests and fix any failures"
🎛️ Command-Line Options
Agent Selection
-a, --agent {codex,claude}: Choose the agent (Codex or Claude)--check-version: Check installed agent version
Safety Options
--bypass: Enable dangerous sandbox/approval bypass ⚠️--no-bypass: Explicitly disable bypass-q, --quiet: Suppress styling (for scripts)
Advanced Modes
--review: Enable review mode (other agent reviews output)--loop MINUTES: Enable loop mode for N minutes (default: 60)-m, --model MODEL: Specify model to use--add-dir DIR: Add additional working directory (repeatable)
Configuration
--save-defaults: Save current options as defaults--dry-run: Show command without executing--install: Install launcher globally
Info Commands
-V, --version: Show version information-h, --help: Show help message
🔧 Configuration Files
Config Location
- Linux/macOS:
~/.config/agent/config.json - Configuration is automatically created on first use
Config Structure
{
"default_agent": "claude",
"default_bypass": false,
"default_model": "opus"
}
Command History
All commands are logged to ~/.config/agent/history.log:
{
"timestamp": "2025-11-23T12:34:56",
"agent": "claude",
"bypass": false,
"model": "sonnet",
"command": "claude --model sonnet 'Fix the bug'",
"review_mode": false,
"loop_duration": null
}
🎨 Review Mode
Review mode adds a quality assurance step by having the alternate agent review and improve the output:
- Primary Agent Executes: Your chosen agent completes the task
- Review Prompt: You're asked if you want to review
- Secondary Agent Reviews: The other agent checks for bugs and improvements
- Interactive: You can skip review or cancel at any time
# Example workflow
agent --agent claude --review "Implement user authentication"
# Output:
# [REVIEW MODE] Running primary agent: Claude
# [REVIEW MODE] The agent will execute your request first...
# (Claude implements authentication)
# [REVIEW MODE] Primary agent completed with exit code 0
# [REVIEW MODE] Launch review agent (Codex)? [Y/n | O/n] : y
# (Codex reviews and suggests improvements)
🔁 Loop Mode
Loop mode enables iterative improvements over a specified time period:
- Runs multiple iterations until time expires
- Optional review after each iteration
- Minimum 5 minutes required for next iteration
- User can cancel at any time
# Optimize code for 30 minutes
agent --agent claude --loop 30 "Optimize performance in src/api"
# With review after each iteration
agent --agent claude --loop 60 --review "Refactor legacy codebase"
🔐 Safety Notes
⚠️ Bypass Mode Warning
The --bypass flag disables safety sandboxes and approval prompts. Use with extreme caution:
- Codex:
--dangerously-bypass-approvals-and-sandbox - Claude:
--dangerously-skip-permissions
Only use bypass mode when:
- You fully trust the code being executed
- You're working in a sandboxed/disposable environment
- You understand the security implications
🌍 Bilingual Support
All prompts and messages are displayed in both English and French:
Agent ? (1) Codex | (2) Claude - tapez le numéro ou le nom:
Dangerously bypass approvals & sandbox ? [y/N | o/N] :
Agent Ready / Agent Prêt
Bon travail / Happy coding!
🐛 Troubleshooting
Agent Not Found
# Check if agent is installed
agent --check-version --agent claude
# Install missing agent (requires npm)
# The launcher will offer to install if npm is available
Permission Errors
# For global installation
sudo agent --install
# Or install to user directory
AGENT_INSTALL_DIR=~/.local/bin agent --install
Clear Configuration
# Remove config to start fresh
rm -rf ~/.config/agent/
📚 Requirements
- Python: 3.8 or higher
- Operating System: Linux, macOS, or Windows (with WSL)
- Dependencies: None (pure Python, stdlib only)
- Optional: Node.js + npm (for agent installation)
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup
git clone https://github.com/Actigence-Code/agent-launcher.git
cd agent-launcher
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
Running Tests
pytest
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- OpenAI Codex for the amazing AI coding assistant
- Anthropic Claude Code for powerful code understanding
- All contributors who help improve this tool
📞 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki
- Email: hello@actigence.eu
- Website: actigence.eu
🗺️ Roadmap
- Support for additional AI coding agents
- Plugin system for custom workflows
- Web UI for configuration
- Team collaboration features
- Cloud sync for configuration
- Integration with popular IDEs
Made with ❤️ in Tervuren, Belgium
Metadata
Release files for agent-launcher 3.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_launcher-3.0.1.tar.gz | 21.9 kB | Without provenance | Details for agent_launcher-3.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_launcher-3.0.1-py3-none-any.whl | Python 3 | none | any | Details for agent_launcher-3.0.1-py3-none-any.whl |
Total release size: 38.3 kB
Release files / agent_launcher-3.0.1.tar.gz
| Download URL | agent_launcher-3.0.1.tar.gz |
|---|---|
| Size | 21.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df4e0fa409feaea61bd8e3b16267f28760f39c89c48e25fdadaebcbc124dd888
|
|
BLAKE2b-256 checksum How to use checksums |
766a0cd921142f7a36d741bfcf7753eff29a9203be7daf58d02a58c0adbe6c66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Release files / agent_launcher-3.0.1-py3-none-any.whl
| Download URL | agent_launcher-3.0.1-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6a4e33d53c5fef87d6addfc8a0e4fe7e35225e6d5b77223f5998a3ca84ad2d6
|
|
BLAKE2b-256 checksum How to use checksums |
a4bae139d6d32f88415961f183d01dd325783b6a3448cc2ca92748e9f63e89f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Security for agent-launcher 3.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.