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

> Discover how agent-harness directories, the cli_anything namespace, and pip packages in CLI-Anything enable independent Python distributions to coexist without import issues.

- Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- Tags: internals
- Published: 2026-05-18

---

**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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/setup.py). For example, in [`zotero/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/zotero/agent-harness/setup.py):

```python
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`](https://github.com/HKUDS/CLI-Anything/blob/main/setup.py) defines console scripts that map CLI commands to Python functions. In [`zotero/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/zotero/agent-harness/setup.py):

```python
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`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_anything/zotero/zotero_cli.py). The same pattern applies to other harnesses:

- **[`ollama/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/ollama/agent-harness/setup.py)**: Installs `cli-anything-ollama` → `cli_anything.ollama.ollama_cli:main`
- **[`macrocli/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/macrocli/agent-harness/setup.py)**: Installs command for `cli_anything.macrocli`
- **[`exa/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/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:

```bash
pip install cli-anything-zotero cli-anything-ollama

```

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

```python

# 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:

```python
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`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_anything/__init__.py) | Declares the empty `cli_anything` namespace package |
| [`zotero/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/zotero/agent-harness/setup.py) | Defines pip package `cli-anything-zotero` and its namespace mapping |
| [`zotero/agent-harness/cli_anything/zotero/zotero_cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/zotero/agent-harness/cli_anything/zotero/zotero_cli.py) | Implements `cli-anything-zotero` CLI entry point |
| [`ollama/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/ollama/agent-harness/setup.py) | Defines pip package `cli-anything-ollama` |
| [`ollama/agent-harness/cli_anything/ollama/ollama_cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/ollama/agent-harness/cli_anything/ollama/ollama_cli.py) | Implements `cli-anything-ollama` CLI entry point |
| [`macrocli/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/macrocli/agent-harness/setup.py) | Defines pip package `cli-anything-macrocli` |
| [`exa/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/agent-harness/setup.py) file. For example, [`zotero/agent-harness/setup.py`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/zotero/agent-harness/cli_anything/zotero/zotero_cli.py).