open-terminal-agents

🚀 A cross-platform CLI for launching multiple Agent CLIs across preconfigured terminal tabs with one command

Alias: ota

中文文档

---

✨ Features

• 🌍 Cross-platform support – Windows, Linux, and macOS
• 🖥️ Flexible terminal selection – Choose between cmd or powershell on Windows
• 📁 Smart directory management – Save directories with optional aliases for quick access
• 🤖 Agent command registry – Store and reuse your favorite CLI commands (codex, claude, etc.)
• ⚡ Interactive launcher – Select multiple directories and commands, launch them all at once
• 🌐 Bilingual interface – Switch between English and Chinese with ota language
• 📝 Human-readable config – TOML format stored in your user config directory

---

📦 Installation

Build from Source

cargo install --path .

💡 The project depends only on the Rust standard library, so it works in offline environments.

After installation, the open-terminal-agents binary will be available on your PATH. You can create a shell alias ota manually; future releases will ship the alias through package scripts.

Run Without Installing

cargo run -- [command] [options]

Everything after -- is forwarded to the CLI.

Install via npm (Windows)

Once published, install globally:

npm install -g open-terminal-agents
open-terminal-agents --help

To verify locally before publishing:

node scripts/prepare-win-binary.js
cd npm
npm install -g .

---

🎯 Usage

ota [command] [options]

Available Commands

Command	Description
(none)	Start the interactive launcher: pick directories and Agent commands, then open terminals
help, -h, --help	Print the top-level help
terminal (alias terminal)	Configure the default terminal shell on Windows
path	Manage project directories
agent-command	Manage Agent CLI commands
language	Switch interface language between English and Chinese
list	Display stored configuration
version, -v, --version	Show the installed CLI version

---

📖 Command Reference

🗂️ path – Manage Directories

ota path -a, --add <DIR> [ALIAS]      # Add a directory with optional alias
ota path -d, --delete [ALIAS|DIR]     # Delete by alias/path, or interactive mode if omitted
ota path help                          # Show help

Rules:

• Directories must exist when added
• Each directory can have one alias; aliases are unique (case-insensitive on Windows)
• Duplicate directories are rejected with a friendly message

🤖 agent-command – Manage Agent Commands

ota agent-command -a, --add "codex"     # Add a command
ota agent-command -d, --delete "codex"  # Delete a command
ota agent-command help                  # Show help

Note: Commands are stored as single strings. Use quotes for multi-word commands.

📋 list – View Configuration

ota list               # Interactive selector
ota list all           # Show directories + commands
ota list path          # Show directories only
ota list agent-command # Show commands only
ota list help          # Show help

⚡ Interactive Launcher

Run ota without arguments to start the interactive flow:

1. Select directories – Use ↑/↓ to move, Space to toggle entries, press A to select/deselect all, press Q to exit
2. Select commands – Same controls (including Q to exit), choose one or more Agent commands
3. Launch – The tool opens system terminals and runs every command in every chosen directory

Platform Support:

• Windows: Uses Windows Terminal (wt). Shows helpful error if not installed.
• Linux: Tries gnome-terminal, konsole, xfce4-terminal, alacritty, xterm with graceful fallback.
• macOS: Uses native Terminal via AppleScript.

---

⚙️ Configuration

The config file uses TOML format and lives in your user home directory at .open-terminal-agents/settings.toml.

File Location

Platform	Path
Windows	%USERPROFILE%\.open-terminal-agents\settings.toml
macOS / Linux	~/.open-terminal-agents/settings.toml

Example Configuration

terminal = "cmd"
language = "en"

[[paths]]
path = "C:\\work\\demo"
alias = "demo"

[[paths]]
path = "D:\\lab\\ota"

agent_commands = ["codex", "ccr code"]

Supported language values: en (English) and zh (Chinese).

💡 Tip: Use the CLI commands to manage configuration instead of manual editing.

---

🛠️ Development

Basic Commands

cargo fmt      # Format code
cargo check    # Check for errors
cargo test     # Run tests

Windows Packaging Helper

Use the Node helper script to build and stage the Windows binary:

node scripts/prepare-win-binary.js              # Build + copy to npm/bin/win32
node scripts/prepare-win-binary.js --skip-build # Copy only (after cargo build --release)

Publishing to npm

1. Update npm/package.json version and metadata
2. Run node scripts/prepare-win-binary.js to build and copy the Windows binary
3. Navigate to npm directory and run npm publish (or npm pack for dry run)
4. Verify with npm install -g open-terminal-agents

The repository includes a GitHub Actions workflow (.github/workflows/ci.yml) that runs checks on every push.

---

🗺️ Roadmap

• Extended terminal integrations (Windows Terminal panes, custom iTerm profiles)

---

📄 License

Released under the MIT License.