Relationship Between Agent-Harness Directories, cli_anything Namespace, and pip Packages in CLI-Anything

Each agent-harness directory in the CLI-Anything repository contains a standalone Python distribution that installs as a separate pip package under the shared cli_anything namespace, allowing multiple agent tools to coexist without import conflicts.

The HKUDS/CLI-Anything repository implements a modular namespace package architecture that decouples the physical directory structure from the Python import hierarchy. This design enables the ecosystem to grow by adding new agents without modifying a monolithic codebase.

Understanding the Namespace Package Architecture

The foundation of CLI-Anything's modularity relies on namespace packages. The top-level package cli_anything is intentionally empty—serving only as a container that can be populated by multiple separate distributions.

In cli_anything/__init__.py, the package declares no content, enabling setuptools.find_namespace_packages(include=["cli_anything.*"]) to recognize subdirectories as extensions of the same namespace. When you install any agent harness, its code appears under cli_anything.<service> (e.g., cli_anything.zotero, cli_anything.ollama), even though the physical files reside in different directory trees.

How Agent-Harness Directories Map to pip Distributions

Directory Structure

Each subdirectory under the repository root (such as zotero, ollama, macrocli, and exa) contains an agent-harness folder. This folder houses both the distribution metadata and the source code:

zotero/
└── agent-harness/
    ├── setup.py
    └── cli_anything/
        └── zotero/
            └── zotero_cli.py

Despite being physically separate from the main package, the code inside cli_anything/zotero/ maps to the Python import path cli_anything.zotero after installation.

Setup.py Configuration

The relationship between directories and installable packages is defined in each harness's setup.py. For example, in zotero/agent-harness/setup.py:

from setuptools import setup, find_namespace_packages

setup(
    name='cli-anything-zotero',
    packages=find_namespace_packages(include=["cli_anything.*"]),
    # Additional metadata...

)

Key distinction: The pip package name (cli-anything-zotero) uses hyphens and identifies the distribution on PyPI, while the Python namespace (cli_anything.zotero) uses dots and determines the import path. The packages argument ensures that cli_anything.zotero is recognized as part of the shared cli_anything namespace rather than a standalone top-level package.

Console Entry Point Wiring

Each setup.py defines console scripts that map CLI commands to Python functions. In zotero/agent-harness/setup.py:

setup(
    name='cli-anything-zotero',
    entry_points={
        'console_scripts': [
            'cli-anything-zotero=cli_anything.zotero.zotero_cli:entrypoint',
        ],
    },
)

This configuration installs the command cli-anything-zotero into your environment's PATH, which invokes entrypoint() from cli_anything/zotero/zotero_cli.py. The same pattern applies to other harnesses:

• ollama/agent-harness/setup.py: Installs cli-anything-ollama → cli_anything.ollama.ollama_cli:main
• macrocli/agent-harness/setup.py: Installs command for cli_anything.macrocli
• exa/agent-harness/setup.py: Installs command for cli_anything.exa

Installing and Using Multiple Harnesses

Because all distributions share the cli_anything namespace, you can install multiple agents simultaneously without conflicts:

pip install cli-anything-zotero cli-anything-ollama

After installation, both modules reside under the same parent namespace:

# Import both harnesses in the same session

from cli_anything import zotero, ollama

# Execute Zotero functionality

zotero.zotero_cli.entrypoint()

# Execute Ollama functionality  

ollama.ollama_cli.main()

Alternatively, import using the submodule syntax:

import cli_anything.zotero as zot
zot.zotero_cli.entrypoint()

Key Implementation Files

The following source files demonstrate the namespace architecture in the HKUDS/CLI-Anything repository:

File Path	Purpose
cli_anything/__init__.py	Declares the empty cli_anything namespace package
zotero/agent-harness/setup.py	Defines pip package cli-anything-zotero and its namespace mapping
zotero/agent-harness/cli_anything/zotero/zotero_cli.py	Implements cli-anything-zotero CLI entry point
ollama/agent-harness/setup.py	Defines pip package cli-anything-ollama
ollama/agent-harness/cli_anything/ollama/ollama_cli.py	Implements cli-anything-ollama CLI entry point
macrocli/agent-harness/setup.py	Defines pip package cli-anything-macrocli
exa/agent-harness/setup.py	Defines pip package cli-anything-exa

Summary

• Each agent-harness directory represents a standalone Python distribution with its own setup.py.
• The cli_anything namespace acts as a shared container that aggregates submodules from separate installations.
• Pip package names follow the pattern cli-anything-<service> (e.g., cli-anything-zotero), while Python imports use cli_anything.<service> (e.g., cli_anything.zotero).
• Console entry points in each setup.py wire CLI commands directly to functions within the namespace modules.
• Multiple harnesses can coexist under the same namespace without conflicts, enabling modular installation.

Frequently Asked Questions

What is the difference between the pip package name and the Python namespace?

The pip package name (e.g., cli-anything-zotero) uses hyphens and identifies the distribution when running pip install. The Python namespace (e.g., cli_anything.zotero) uses dots and determines the import path in Python code. They are independent identifiers—the pip name markets the tool, while the namespace determines where it lives in the import hierarchy.

Can I install multiple agent harnesses simultaneously?

Yes. Because all harnesses contribute to the shared cli_anything namespace using find_namespace_packages, installing cli-anything-zotero and cli-anything-ollama places both modules under cli_anything.zotero and cli_anything.ollama respectively. They do not overwrite each other because they extend rather than replace the namespace.

How do I add a new agent to the CLI-Anything ecosystem?

Create a new directory (e.g., newservice/agent-harness/) containing a setup.py that declares name='cli-anything-newservice' and packages=find_namespace_packages(include=["cli_anything.*"]). Place your code under agent-harness/cli_anything/newservice/. This automatically contributes cli_anything.newservice to the shared namespace upon installation, without requiring changes to existing packages.

Where are the CLI entry points defined?

Entry points are defined in the console_scripts section of each agent-harness/setup.py file. For example, zotero/agent-harness/setup.py maps the command cli-anything-zotero to cli_anything.zotero.zotero_cli:entrypoint, which points to the entrypoint function in zotero/agent-harness/cli_anything/zotero/zotero_cli.py.

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