How ReplSkin Creates a Unified REPL Interface for Different Software Harnesses

ReplSkin is a dependency-free utility class that provides every CLI-Anything harness—such as ollama, macrocli, and firefly-iii—with an identical look-and-feel by centralizing all UI concerns into a single reusable implementation. By exposing one public class, ReplSkin, the HKUDS/CLI-Anything repository ensures that each software harness inherits consistent branding, prompt styling, and interactive elements regardless of the underlying tool it controls.

The ReplSkin class lives in cli_anything/<harness>/utils/repl_skin.py and acts as a single source of truth for REPL appearance across the ecosystem. When developers create a new harness, they copy this file verbatim and instantiate the class with their software name, automatically gaining standardized color palettes, terminal detection, and rich UI helpers without writing additional UI code.

Core Design Principles

The unified interface relies on nine distinct capabilities bundled into the ReplSkin class. Each feature is implemented in the shared repl_skin.py file, ensuring zero divergence between harnesses.

Brand-Wide Color Palette. An internal _ACCENT_COLORS dictionary (defined at line 41-51 in ollama/agent-harness/cli_anything/ollama/utils/repl_skin.py) maps software names to specific accent colors. This guarantees that every REPL shares the same cyan and greyscale branding while highlighting each tool with its unique color.

Terminal-Capability Detection. The _detect_color_support method (line 70-78) checks for NO_COLOR or CLI_ANYTHING_NO_COLOR environment variables and verifies whether stdout is a TTY. When conditions indicate a non-ANSI terminal, colors are automatically disabled to prevent garbled output.

Unified Banner. The _print_banner method (line 88-144) generates a 72-character boxed header displaying the CLI name, version, install command (npx skills add ...), and global skill path. Every harness calls skin.print_banner() at startup to present this standardized header without custom formatting code.

Prompt Construction. The _prompt method (line 47-80) builds two representations simultaneously: a plain string for input() and a Prompt-Toolkit token list. Both use the consistent syntax ◆ <software> [project] ❯, ensuring the prompt appearance remains identical across all interaction modes.

Message Helpers. One-liner methods—success, error, warning, info, hint, and section (implemented around line 41-64)—wrap color-coded status messages. This eliminates repetitive print boilerplate and standardizes how status feedback appears to users.

Rich UI Elements. Advanced rendering is handled by status, status_block, progress, table, and help methods. For example, _table (line 14-61) draws ASCII tables with consistent borders and padding, allowing any harness to display tabular data in the same visual style.

Prompt-Toolkit Integration. When the library is available, create_prompt_session (line 84-107) builds a PromptSession object with history persistence, auto-suggest, and a styled bottom toolbar. The get_input method abstracts whether the session exists, falling back to plain input() when Prompt-Toolkit is absent.

Skill-Metadata Auto-Discovery. The class automatically locates the harness's SKILL.md file by checking the repository root under skills/<skill-id>/ or within the installed package (line 44-56). This enables AI agents to resolve skill descriptions without per-harness configuration.

History Persistence. By default, command history is stored in ~/.cli-anything-<software>/history (handled at line 60-66), giving every REPL a consistent location for user command recall.

Architectural Workflow

The ReplSkin class orchestrates the REPL lifecycle through a five-phase pipeline that remains identical across all CLI-Anything harnesses.

1. Construction. Instantiating ReplSkin("<software>", version="x.y.z") stores the software identifier, computes a skill slug (cli-anything-<software>), resolves the skill file path, selects the appropriate accent color, and prepares the history file path.

2. Startup. Calling skin.print_banner() draws the boxed header, installing the standardized welcome screen before the user enters their first command.

3. User Interaction Loop. The harness creates a session via session = skin.create_prompt_session(), then enters a loop calling cmd = skin.get_input(session, project_name, modified). This method displays the colored prompt and reads user input, returning the command string for processing.

4. Feedback. Throughout execution, the harness invokes skin.success(), skin.error(), skin.table(), or other helpers to render output. All methods reference the same color constants and box-drawing characters defined in the class.

5. Shutdown. Before exiting, the harness calls skin.print_goodbye() to display a small farewell banner, completing the consistent user experience.

Implementation Across the Codebase

Every CLI-Anything harness contains an identical copy of the repl_skin.py file, ensuring zero UI duplication while allowing each package to function independently when installed separately.

The following paths contain the shared implementation:

• ollama: ollama/agent-harness/cli_anything/ollama/utils/repl_skin.py
• macrocli: macrocli/agent-harness/cli_anything/macrocli/utils/repl_skin.py
• intelwatch: intelwatch/agent-harness/cli_anything/intelwatch/utils/repl_skin.py
• firefly-iii: firefly-iii/agent-harness/cli_anything/firefly_iii/utils/repl_skin.py
• sbox: sbox/agent-harness/cli_anything/sbox/utils/repl_skin.py
• exa: exa/agent-harness/cli_anything/exa/utils/repl_skin.py

Because these files contain byte-identical source code, any bug fix or enhancement to the ReplSkin class must be propagated to all harnesses. This duplication is intentional: it keeps each harness as a self-contained Python package while maintaining strict UI consistency.

Practical Usage Example

The following demonstration shows how any harness integrates ReplSkin into its main loop. This code works identically whether Prompt-Toolkit is installed or not.

from cli_anything.ollama.utils.repl_skin import ReplSkin

# Initialize with software name and version

skin = ReplSkin("ollama", version="0.4.2")
skin.print_banner()

while True:
    # Create session (optional; graceful fallback if library missing)

    session = skin.create_prompt_session()
    cmd = skin.get_input(session, project_name="demo-proj", modified=False)

    if cmd in ("quit", "exit"):
        break
    elif cmd == "list":
        skin.table(
            headers=["ID", "Name", "Status"],
            rows=[["1", "model-a", "ready"], ["2", "model-b", "loading"]],
        )
    else:
        skin.info(f"Echo: {cmd}")

skin.print_goodbye()

Output on a capable terminal appears as:

╭──────────────────────────────────────────────────────────────────────────────╮
│  ◆  cli-anything · Ollama                                                    │
│   v0.4.2                                                                     │
│   Install: npx skills add HKUDS/CLI-Anything --skill cli-anything-ollama -g -y │
│   Global skill: ~/.agents/skills/cli-anything-ollama/SKILL.md                │
│                                                                              │
│   Type help for commands, quit to exit                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

◆ ollama ❯ list
  ID   Name      Status
  ──────────────────────
  1    model-a   ready
  2    model-b   loading

Summary

• ReplSkin provides a unified REPL interface for HKUDS/CLI-Anything by exposing a single class that handles all UI concerns across software harnesses.
• The implementation uses a shared repl_skin.py file copied into each harness directory, ensuring identical color schemes, prompts, and rich UI elements.
• Key features include automatic terminal capability detection (NO_COLOR support), Prompt-Toolkit integration with graceful fallbacks, and standardized history persistence.
• The class exposes helper methods like print_banner(), table(), and get_input() that enforce consistent branding while allowing per-software accent colors via an internal dictionary.

Frequently Asked Questions

What is ReplSkin in the CLI-Anything ecosystem?

ReplSkin is a lightweight, dependency-free Python class located in cli_anything/<harness>/utils/repl_skin.py that centralizes all terminal UI logic for the CLI-Anything project. It provides every software harness—such as those for Ollama, MacroCLI, and Firefly-III—with identical REPL styling, prompt formatting, and interactive elements, eliminating the need for each harness to implement its own terminal interface.

How does ReplSkin handle terminals that do not support ANSI colors?

The _detect_color_support method (lines 70-78) checks for the presence of NO_COLOR or CLI_ANYTHING_NO_COLOR environment variables and verifies whether stdout is connected to a TTY. If either condition indicates limited terminal capability, ReplSkin automatically disables color output, ensuring text remains readable on basic terminals or when users request plain text output.

Can ReplSkin function without the Prompt-Toolkit library installed?

Yes. While ReplSkin offers enhanced features like command history, auto-suggestion, and styled toolbars when Prompt-Toolkit is available via create_prompt_session, the get_input method automatically falls back to Python's built-in input() function if the library is missing. This ensures every CLI-Anything harness remains usable in minimal environments without additional dependencies.

Why is the same repl_skin.py file duplicated across multiple harness directories?

Each harness in the CLI-Anything repository is designed as an independent Python package that can be installed separately. By including an identical copy of repl_skin.py in each harness's utils directory—such as ollama/agent-harness/cli_anything/ollama/utils/repl_skin.py and macrocli/agent-harness/cli_anything/macrocli/utils/repl_skin.py—the project ensures UI consistency while maintaining package independence. This strategy creates a single source of truth for REPL appearance that is physically replicated across the codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}