Why Agents Need a Tool Manager
AI agents are powerful reasoners, but they have a blindspot: they don't know what's installed on your system. An agent can write a shell command to transform JSON with jq, but if jq isn't installed, the command fails. The agent doesn't have a way to check what's available, install what's missing, or discover alternatives.
The current popular solution is MCP (Model Context Protocol), which gives agents tool access by injecting JSON schemas into every prompt. This works, but it comes with a steep cost: 8,000–15,000 tokens per MCP server, on every single message, whether the agent uses those tools or not. Connect three MCP servers and you've consumed 24,000–45,000 tokens before the agent even starts thinking about your problem.
But here's the thing: LLMs already know how to use CLI tools. They were trained on billions of shell scripts, man pages, Stack Overflow answers, and GitHub repositories. When you ask Claude or GPT-4 to parse JSON, they already know to reach for jq. When you ask them to convert a video, they know about ffmpeg. The knowledge is already in the model weights. What agents actually need isn't a schema — it's a way to discover what tools are available and install the ones they need.
That's what CliHub does. It's a tool manager for AI agents — a structured catalog of 104 CLI tools that agents can query, install, and use through standard command-line interfaces. No token overhead, no running servers, no JSON-RPC. Just pip install clihub-ai and your agent has access to a curated app store of CLI tools.
Step 1 — Install CliHub
CliHub installs in one command. It requires Python 3.10+ and works on macOS, Linux, and Windows. The entire tool registry is bundled with the package — no internet connection needed for discovery.
The clihub doctor command checks which package managers are available on your system (brew, pip, npm, cargo) and confirms the registry is loaded. If you prefer an isolated environment, you can use pipx install clihub-ai instead.
Step 2 — Discover Tools
Once CliHub is installed, your agent can browse the entire catalog of 104 tools. Every command supports --json output for structured, machine-readable data. This is how agents discover what tools are available without any schema injection.
The clihub list --json output includes the tool name, description, category, installation method, and agent hints — structured metadata that helps agents understand when and how to use each tool. The full catalog is about 87KB of JSON, which the agent only pays for once, when it actually needs to discover tools — not on every prompt.
The clihub search command lets agents find tools by natural language description. Looking for something that can "resize images"? CliHub returns the most relevant tools ranked by relevance. The clihub info command gives detailed metadata about any specific tool, including how it's installed and what binary it provides.
Step 3 — Install Tools
When the agent has identified the tool it needs, installation is a single command. CliHub auto-detects the right package manager for your system and installs the tool so it's immediately available on PATH.
CliHub is smart about installations. It checks if a tool is already installed before attempting to download it. It detects the right package manager for each tool (brew for system tools, pip for Python tools, npm for Node tools, cargo for Rust tools) and handles the installation end-to-end. The agent doesn't need to know the package manager — CliHub abstracts that away.
Step 4 — Use Tools in Your Agent
Now that tools are installed, there are several ways to integrate CliHub into your agent workflow. Here are the three most common patterns, from the most flexible to the simplest.
Python subprocess
most flexible# 1. Agent reads the full tool catalog
result = subprocess.run(
["clihub", "list", "--json"],
capture_output=True, text=True
)
catalog = json.loads(result.stdout)
# 2. Agent picks a tool and installs it
subprocess.run(["clihub", "install", "jq"], check=True)
# 3. Agent uses the tool directly
data = subprocess.run(
["jq", ".users[] | .name", "data.json"],
capture_output=True, text=True
)
print(data.stdout)
The Python subprocess pattern is the most flexible and gives you full control over how the agent interacts with CliHub. You can read the catalog once, cache it, filter tools by category, and handle errors with Python's standard exception handling. This pattern works in any Python agent framework — LangChain, CrewAI, AutoGen, or your own custom agent.
Claude Code / Cursor
just works# It can run clihub commands directly:
$ clihub search "json processor" --json
[{"name":"jq","description":"Lightweight JSON processor",...}]
$ clihub install jq
✓ Installed jq@1.7.1 via brew
$ cat data.json | jq '.users[] | {name, email}'
{"name":"Alice","email":"alice@example.com"}
{"name":"Bob","email":"bob@example.com"}
If your agent runs inside Claude Code or Cursor, you don't need any special integration. These environments already give the agent Bash access, so it can run clihub commands directly. The agent discovers tools, installs what it needs, and uses them — all through the same shell interface it uses for everything else. No config files, no server setup, no plugins to install.
Shell script automation
pre-provisioning# Pre-install the tools your agent needs
# Run this in your Dockerfile or CI setup
pip install clihub-ai
# Install a suite of data tools
clihub install jq csvlook miller
# Install a suite of media tools
clihub install ffmpeg imagemagick pandoc
# Install a suite of dev tools
clihub install ripgrep fd-find tokei shellcheck
# Verify everything is installed
clihub doctor
echo "Agent toolchain ready!"
The shell script pattern is ideal for pre-provisioning environments. If you know which tools your agent will need, install them ahead of time in your Dockerfile, CI pipeline, or cloud instance setup. This way the agent starts with a fully loaded toolchain and never has to wait for installations during a task.
The --help Protocol
CliHub's design is built on a key insight: every CLI tool already documents itself via --help. This is a universal, self-documenting protocol that has existed for decades. When an agent needs to learn how a tool works, it runs toolname --help and reads the output. No JSON schema needed. No token-heavy tool definitions injected into every prompt.
Here's why this matters for AI agents:
- Zero ambient cost. Tool documentation only enters the context window when the agent explicitly asks for it by running
--help. The rest of the time, the agent's full context window is available for reasoning about the user's actual task. - Just-in-time learning. The agent runs
--helponly when it needs to learn a specific tool. If the agent already knows how to usejqfrom training data, it skips--helpentirely — zero cost. - LLMs are trained on this. Large language models have seen millions of
--helpoutputs, man pages, and CLI documentation during training. They parse this format natively. No schema translation layer needed. - Always up to date. The
--helpoutput comes from the tool itself, not from a separate schema file that can get out of sync. The documentation is always accurate for the installed version.
The protocol is simple: --help tells the agent what the tool does. --json gives the agent structured output it can parse. --version tells the agent which version is installed. These three flags are the universal interface. That's the entire protocol.
Error Handling
Reliable error handling is critical for autonomous agents. An agent that can't distinguish between "tool not found" and "tool failed" will waste time on dead ends. CliHub and CLI tools use Unix exit codes — the same error convention that every program has used for decades.
| Exit Code | Meaning | Agent Action |
|---|---|---|
| 0 | Success | Parse stdout, continue task |
| 1 | General error | Read stderr for details, retry or fallback |
| 2 | Not found / misuse | Tool doesn't exist or wrong arguments |
| 126 | Permission denied | Tool exists but can't execute |
| 127 | Command not found | Tool not installed — run clihub install |
Here's how a well-designed agent handles a failed tool installation:
Every CliHub command also supports --json for structured error output. When an installation fails, the JSON response includes the error type, message, and suggested fix — making it easy for agents to programmatically determine the next step instead of parsing human-readable error messages.
The combination of exit codes for fast detection, stderr for human-readable details, and --json for structured error data gives agents everything they need to handle failures gracefully. This is the same error handling pattern that every Unix program has used for decades — battle-tested and universal.