Introduction

Group Terminal is a minimalistic, terminal-based group chat system designed for testing and prototyping AI service integrations. Most group chat systems require authentication, databases, and user management before you can test a single message handler or prototype collaboration of user groups with AI. Group Terminal eliminates this complexity by providing a minimal WebSocket-based chat server and Rich-powered terminal clients that let you focus on testing your integration logic rather than infrastructure setup.

The project delivers four capabilities to accelerate development workflows. A zero-configuration design means no authentication or database setup is required. Server-side message handlers let you build and test services that respond to group chat messages. The Rich-based terminal interface provides immediate visual feedback with configurable colors for different message types. Finally, the explicit testing-focused design ensures you spend time building features rather than maintaining production concerns like security or persistence.

Note

Group Terminal uses termios for terminal control and is Unix-specific. It will not work on Windows systems.

Installation

pip install group-terminal

Quickstart

The included example demonstrates how to launch a chat server and register a message handler. The handler echoes back each received message with the pattern "I received '{message}' from {username}". This showcases a basic service integration pattern.

Here's the essential code:

examples/app.py

import asyncio

from group_terminal.server import ChatServer

class ChatApp:
    def __init__(self, host: str, port: int):
        self._server = ChatServer(host=host, port=port)
        self._server.add_handler(self._handle_message)

    @property
    def server(self):
        return self._server

    async def _process_message(self, content: str, username: str):
        # potentially long-running operation ...
        response = f"I received '{content}' from {username}"
        # send response to chat clients
        await self._server.send_message(response, sender="agent", agent=True)

    async def _handle_message(self, content: str, username: str):
        # Handles messages generated by chat clients i.e. users. A
        # handler is called sequentially in message arrival order.
        # This is the same order as seen in the chat client.

        # Operations that require preserving message arrival order
        # (adding to a queue, ...) should be done here. Long-running
        # message processing should be done asynchronously to prevent
        # blocking the message receiver loop.
        asyncio.create_task(self._process_message(content, username))


app = ChatApp(host="0.0.0.0", port=8723)
await app.server.start()
await app.server.join()

See the complete example for full implementation details.

Start the server:

python examples/app.py

In separate terminals, launch two clients with different usernames:

python -m group_terminal.client --username alice
python -m group_terminal.client --username bob

The screenshots below show a conversation where alice sends "Hey everyone! How's it going?" and bob replies "Pretty good!". Notice the color coding: your own messages appear in orange, messages from other users in cyan, and agent responses in green. The message handler echoes each message back to all connected clients.

alice's view:

bob's view: