Control-PC-Terminal

Control-PC-Terminal lets you manage and interact with AI agent sessions running on your desktop or VPS through two primary interfaces: a secure web terminal and a Telegram bot. Once installed and started, your agent runs inside a tmux session to persist across disconnects. The web terminal (ttyd) exposes this session in a browser, while the Telegram bot streams logs and accepts prompts in real time. You can initiate agent sessions, monitor outputs with live streaming, send prompts, and navigate menus remotely using a simple set of Telegram commands. The solution is designed to be language-agnostic and works with Claude Code, Codex, or any custom CLI-based agent you provide. The key workflow is tmux-based long-running sessions bridged to a web UI and optionally a Telegram interface for hands-free control on mobile.

Prerequisites:

• Linux or WSL (Windows Subsystem for Linux)
• curl and bash available in PATH
• tmux installed on the host machine
• Optional: ttyd for web terminal, cloudflared for public URL

Step-by-step:

1. Run the installer via the provided one-liner: curl -fsSL https://raw.githubusercontent.com/kumar045/Control-PC-Terminal/main/install.sh | bash

2. The installer will install the Control-PC-Terminal binaries to ~/.control-terminal/bin and add that path to your shell profile. Open a new terminal or source your profile to ensure the binary is on PATH.

3. Start the Control-PC-Terminal tool: control-terminal

4. Optional Telegram setup during startup:

   • When prompted, enter your Bot Token and the Chat ID to enable Telegram control.
   • If you skip now, you can reconfigure later by running the startup command again and following the prompts.

5. Verify access:

   • Web terminal should be available at the local URL exposed by ttyd (default http://localhost:7681).
   • If you configured cloudflared, you’ll get a public URL to access the web terminal remotely.

Notes:

• You can create and customize agents in ~/.control-terminal/custom-agents.conf with the format: name|command
• Ensure tmux is installed and available in your PATH.
• If you use Telegram, keep your Bot Token and Chat ID secure.

Tips and common issues:

• If the web terminal or Telegram bot isn’t responding, check that tmux is running the agent session and that the bridged interfaces (ttyd and, optionally, cloudflared) are started correctly.
• The custom agents config file (~/.control-terminal/custom-agents.conf) allows quick reuse of complex commands. Each line should be: name|command
• For security, you can enable Web Auth (username/password) for ttyd and restrict Telegram bot usage by chat_id.
• If your agent requires persistent background work, ensure it reads from stdin and writes to stdout without exiting after a single output, so the bridge can forward streams properly.