SPOOX – SPlit lOOp eXpand
A terminal-integrated, LLM-powered multi-agent system (MAS) designed to assist developers directly within their terminal. Spoox CLI provides intelligent assistance for OS tasks, server management workflows, and software engineering challenges. The architectures of these agent systems are based on the spoox MAS design framework, a generic architectural framework for multi-agent topology and communication design.
Several differently scaled terminal MAS variants have been developed and are accessible through a terminal CLI: spoox-s, spoox-m, and spoox-l. The spoox-m variant achieved first place on the Terminal Bench leaderboard for the gpt-5-mini model and is therefore used as the default configuration for the spoox CLI.
Note: The corresponding paper defining the spoox MAS design heuristics and the associated scaling behavior studies will be published soon and linked here.
The spoox CLI agent systems are explicitly designed for terminal environments, covering a broad range of tasks:
- Simple operating system operations
- Complex server management workflows
- Typical software engineering challenges
The CLI provides a straightforward developer experience with:
- Safety mechanisms: Critical command execution confirmation loops.
- Interactive feedback: User clarification and feedback loops.
- Progress tracking: Comprehensive structured logging during task execution.
All main components are designed for reuse and implementing custom multi-agent systems following Spoox design heuristics.
BaseGroupChatAgent: Agent implementation that follows spoox heuristics and is built on AutoGen.AgentSystem: Quick MAS configuration by combining multipleBaseGroupChatAgentinstances.EnvironmentandInterface: Choose from existing implementations or define custom ones.
- Python >= 3.10
pip install spooxSpoox CLI supports three model clients: OpenAI, Anthropic, and Ollama. Configure the appropriate client before running spoox CLI.
Set the OLLAMA environment variable to the Ollama server URL. Typically, Ollama runs locally on port 11434:
export OLLAMA=http://localhost:11434Docker users: If spoox CLI runs in a Docker container but Ollama runs on the host machine,
use export OLLAMA=http://host.docker.internal:11434.
Set your API key as an environment variable:
export ANTHROPIC_API_KEY=<api_key>Set your API key as an environment variable:
export OPENAI_API_KEY=<api_key>Start the CLI by simply running:
spooxSeveral parameters can be passed to the command upfront, such as spoox -c openai -m gpt-5-mini.
However, the spoox CLI automatically guides you through any remaining setup after startup and remembers previous selections.
Simply follow the on-screen prompts to interact with your agent system.
Follow these steps to understand the repository structure and learn how to set up your own spoox agent:
-
Read the spoox framework chapter to familiarize yourself with the overall architecture (see linked paper).
-
Understand the three core components that every agent system requires:
- Interface: Review the abstract interface class in
/src/spoox/interface/interface.pyto understand how agents interact with the end user. - Model Client: We use AutoGen's model client implementation, which provides a wrapper for the underlying LLM (learn more).
- Environment: Review the abstract environment class in
/src/spoox/environment/environment.pyto see how the environment interface is provided to agent systems.
- Interface: Review the abstract interface class in
-
Study agent system setup by examining:
- The abstract
AgentSystemclass in/src/spoox/agents/agent_system.py. - A concrete implementation example, like
SpooxMediumin/src/spoox/agents/mas/agent_system_spoox_medium.py
- The abstract
-
Explore individual agent implementation: Agent systems typically consist of multiple agents. The
BaseGroupChatAgentclass (/src/spoox/agents/base_agent.py) provides an abstract base that follows spoox framework design patterns, enabling quick setup of concrete agents as demonstrated in/src/spoox/agents/mas/agents.