Metadata-Version: 2.4
Name: termexec
Version: 0.0.3
Summary: Terminal executor for AI agents, with ANSI escape sequence support and image screenshots
Home-page: https://github.com/james4ever0/termexec
Author: James Brown
Author-email: randomvoidmail@foxmail.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agg-python-bindings==0.1.4
Requires-Dist: ptyprocess==0.7.0
Requires-Dist: pydantic
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<!-- TODO: save the last time terminal has content update, and use the timestamp for activity monitoring, signal 'terminal idle' event if no activity in the next X seconds -->


<div>
<p align="center"><h1 align="center">Terminal Executor</h1></p>
<p align="center">Terminal executor for AI agents, with ANSI escape sequence support and image screenshots.</p>
<p align="center">
<a href="https://github.com/james4ever0/termexec/blob/main/LICENSE"><img alt="License: UNLICENSE"
 src="https://img.shields.io/badge/license-UNLICENSE-green.svg?style=flat"></a>
<a href="https://pypi.org/project/termexec/"><img alt="PyPI" src="https://img.shields.io/pypi/v/termexec"></a>
<a href="https://pepy.tech/projects/termexec"><img src="https://static.pepy.tech/badge/termexec" alt="PyPI Downloads"></a>
<a href="https://github.com/james4ever0/termexec"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>
</div>

## Demo

Using termexec for solving the "vimgolf-test" challenge:

![vimgolf-test-success](https://github.com/user-attachments/assets/011c21d7-5b4b-4836-ac14-e4b8126c3ab4)

More info at [vimgolf-gym](https://github.com/james4ever0/vimgolf-gym)

## Installation

```bash
# install from pypi
pip install termexec

# or install the latest version from github
pip install git+https://github.com/james4ever0/termexec.git
```

Note: if your platform does not have prebuilt binaries of agg-python-bindings, just install cargo and rustc so the source code could compile.

## Usage

```python
from termexec import TerminalExecutor
import time

# Initializes executor with a command to run in terminal emulator, using avt as backend, with automatic context cleanup
with TerminalExecutor(['bash'], width=80, height=24) as executor:
    # Waits for the terminal emulator to be ready.
    time.sleep(1)  # Adjust sleep time as necessary for your environment

    # Or if you prefer to wait for terminal idle event
    try:
        executor.terminal.wait_for_terminal_idle(duration=1, timeout=10)
    except TimeoutError:
        print("Terminal did not become idle in time.")

    # Get the current display of the terminal emulator as a string.
    terminal_text = executor.display
    print("Terminal Display:")
    print(terminal_text)

    # Send input to the terminal emulator.
    executor.input("echo Hello, World!\n")
    print("After input:")
    print(executor.display)

    # Saves the current display of the terminal emulator as a .png file
    executor.screenshot("screenshot.png")
    print("Screenshot saved as screenshot.png")

    # Get the PID of the terminal process.
    print("Terminal process PID:", executor.terminal.pty_process.pid)
```

## Alternatives

- Xterm.js running in phantomjs, electron or headless playwright

- LXterminal running in kiosk mode with x11vnc and novnc

## License

The Unlicense
