{"id":4921,"library":"cua-computer","title":"Cua Computer-Use Interface (CUI) Framework","description":"Cua-computer is a Python framework for building rich Computer-Use Interface (CUI) applications, providing programmatic control over terminal interactions, state management, and event processing. It leverages concepts like `Computer`, `Context`, `Task`, and `State` to enable complex, interactive command-line programs. Currently at version 0.5.17, it maintains an active development cadence, with a focus on Python 3.12+ environments.","status":"active","version":"0.5.17","language":"en","source_language":"en","source_url":"https://github.com/cua-language/cua-computer","tags":["ui","cui","terminal-ui","framework","rich","asyncio"],"install":[{"cmd":"pip install cua-computer","lang":"bash","label":"Install `cua-computer`"}],"dependencies":[{"reason":"Used internally for rich terminal rendering and styling capabilities.","package":"rich","optional":false}],"imports":[{"symbol":"Computer","correct":"from cua_computer import Computer"},{"symbol":"Context","correct":"from cua_computer import Context"},{"symbol":"State","correct":"from cua_computer import State"},{"symbol":"Task","correct":"from cua_computer import Task"},{"symbol":"TaskContext","correct":"from cua_computer import TaskContext"}],"quickstart":{"code":"import asyncio\nfrom cua_computer import Computer, Context, State, Task, TaskContext\nfrom typing import Dict, Any\n\n# Define a simple application state\nclass MyState(State):\n    count: int = 0\n    message: str = \"Hello Cua!\"\n\n# Define a task that increments the count\nclass IncrementTask(Task):\n    async def run(self, context: TaskContext[MyState]):\n        await context.write(\"Incrementing count...\")\n        context.state.count += 1\n        await context.sleep(1) # Simulate some work\n        await context.write(f\"Count is now: {context.state.count}\")\n        context.exit() # Task completes\n\n# Define a task that displays the current state and offers an action\nclass DisplayTask(Task):\n    async def run(self, context: TaskContext[MyState]):\n        await context.write(f\"Current State: {context.state.message} (Count: {context.state.count})\")\n        await context.write(\"Press 'i' to increment, 'q' to quit.\")\n        \n        while True:\n            key = await context.read_key()\n            if key == 'i':\n                await context.spawn(IncrementTask())\n            elif key == 'q':\n                context.exit()\n                break\n            else:\n                await context.write(\"Unknown command. Press 'i' or 'q'.\")\n\nasync def main():\n    initial_state = MyState()\n    computer = Computer(initial_state)\n    \n    # Run the main display task\n    await computer.run(DisplayTask())\n    await computer.exit() # Ensure cleanup after tasks are done\n\nif __name__ == \"__main__\":\n    try:\n        asyncio.run(main())\n    except KeyboardInterrupt:\n        print(\"\\nExiting Cua application.\")","lang":"python","description":"This quickstart demonstrates how to define application `State`, create asynchronous `Task`s for logic and user interaction, and run them using the `Computer` main loop. It includes an example of spawning a sub-task and handling basic keyboard input."},"warnings":[{"fix":"Review release notes carefully for each update and test your application thoroughly after upgrading. Pin to specific patch versions if stability is critical.","message":"As a pre-1.0 library (currently 0.5.17), `cua-computer`'s API is subject to change without strict adherence to semantic versioning. Users should expect potential breaking changes in minor or even patch releases.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Always use `await` with `context.sleep()` for delays, `context.read_key()` for input, and `context.spawn()` for long-running or parallel tasks to ensure non-blocking execution within the Cua event loop.","message":"CUI applications require careful management of the underlying asynchronous event loop. Improper handling of blocking operations or task concurrency can lead to frozen UIs or unexpected behavior.","severity":"gotcha","affected_versions":"All"},{"fix":"Test your Cua application on target terminal environments. Leverage `rich`'s robust capabilities through `cua-computer` but be aware of its limitations in less capable terminals.","message":"CUI applications can exhibit varying behavior across different terminal emulators (e.g., `xterm`, `gnome-terminal`, `iTerm2`, `tmux`) or operating systems, particularly concerning input handling, color support, and rendering of specific characters or escape codes.","severity":"gotcha","affected_versions":"All"},{"fix":"Design your `State` object carefully, make state changes explicit within `Task`s, and consider using immutability where appropriate or a dedicated state management pattern for large applications.","message":"The `State` object is central to Cua applications. For complex applications, ensuring data consistency and managing state transitions across multiple concurrent `Task`s can become challenging without clear patterns.","severity":"gotcha","affected_versions":"All"},{"fix":"For blocking operations, use `asyncio.to_thread()` or `ProcessPoolExecutor` to run them in separate threads/processes, allowing the Cua event loop to remain responsive. Integrate their results back into the `State` asynchronously.","message":"`cua-computer`'s `Task`s are designed to be asynchronous. Attempting to run long-duration CPU-bound or blocking I/O operations directly within a `Task` without offloading to a thread pool or separate process will block the entire CUI, freezing the user interface.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}