DEV Community

Hagicode
Hagicode

Posted on • Originally published at docs.hagicode.com

How HagiCode Integrates 13 Agent CLI Tools into a Single System

#hagicode #agentcli #ai

How HagiCode Integrates 13 Agent CLI Tools into a Single System

Honestly, it's not that hard, yet not that simple either. Let's talk about how we use a layered architecture to uniformly manage diverse Agent CLIs like Claude Code, Codex, Copilot, and Gemini—and how we can plug in a new one at any time.

Background

The story started abruptly, born from a pretty headache-inducing problem.

Agent CLIs have sprung up like bamboo shoots in recent years—Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Kimi, Qoder, Kiro... a new one pops up every few months. As a project that wants users to "install one HagiCode and use the full suite of Agents," we couldn't bet on just one CLI. But we also couldn't write a complete set of logic for each CLI covering installation, health checks, and scheduling—the code would bloat until it was unmaintainable, like a tangled ball of yarn that no one dares touch.

More troublesome, these CLIs have wildly different temperaments: some use stdio, some gRPC, some only give you a shell entry point, and streaming output formats each speak their own language. If we wrote judgments like if (provider == ClaudeCode) directly in business code, within six months it would become a lump of "legacy code" no one dares touch. After all, who wants to touch a brick that looks ready to crumble?

To contain all these pain points, we made a decision: add a thin abstraction layer and shared runtime between the business layer and specific CLIs. This looks simple, yet it directly determines whether HagiCode can quickly integrate new CLIs. I'll explain the specifics shortly.

About HagiCode

The solution shared here comes from our hands-on practice in the HagiCode project. HagiCode is an AI code assistant integration platform with a very pure goal—use one installation, one configuration, to bring in all mainstream Agent CLIs for users.

How the Number "13" Came About

First, a number that gets asked repeatedly—why 13 Agent CLIs.

Actually, the answer is hidden right there in the AIProviderType enum, like bamboo shadows outside a window—as long as you're willing to look, you can see it. The original definition looks like this:

public enum AIProviderType
{
    ClaudeCodeCli = 0,
    CodexCli = 1,
    GitHubCopilot = 2,
    CodebuddyCli = 3,
    OpenCodeCli = 4,
    IFlowCli = 5,        // Deprecated
    HermesCli = 6,
    QoderCli = 7,
    KiroCli = 8,
    KimiCli = 9,
    GeminiCli = 10,
    DeepAgentsCli = 11,
    ReasonixCli = 12,
    PiCli = 13,
}
Enter fullscreen mode Exit fullscreen mode

The enum has 14 values total, but the IFlowCli=5 path is now blocked. In AIProviderFactory, it's explicitly shut out:

if (providerType == AIProviderType.IFlowCli)
{
    throw new NotSupportedException("IFlowCli is no longer supported");
}
Enter fullscreen mode Exit fullscreen mode

Combined with filtering through IsActivelySupportedProviderType(), the ones actually "alive" in the system are 13: Claude Code, Codex, GitHub Copilot, CodeBuddy, OpenCode, Hermes, Qoder, Kiro, Kimi, Gemini, DeepAgents, Reasonix, Pi.

That's where "13" comes from. Not a marketing number—counted straight from the code. After all, numbers don't lie. Only we do.

Layered Architecture: Locking Down Change

The core idea behind connecting 13 CLIs comes down to one sentence: let business code not care which specific CLI it's calling.

We broke it down into six layers, looking from top to bottom:

1. Identity Layer — AIProviderType

The enum is each CLI's "ID number." Anywhere a CLI is mentioned, this enum value identifies it. Strings and enums convert between each other via ToStringValue() / ToAIProviderType(). Simple, yet indispensable.

2. Business Contract Layer — IAIProvider / IAIProviderFactory

The business side only recognizes the IAIProvider interface, which defines universal actions like "send a prompt, get a streaming response." As for whether it's Claude or Codex underneath—business doesn't care. Like sending a letter: you hand it over, what the mailman's surname is, who cares?

3. Adapter Layer — *CliProvider

Each CLI corresponds to a thin adapter, like PiCliProvider, ReasonixCliProvider, ClaudeCodeCliProvider. These adapters have very little to do: translate universal business requests into parameters specific CLI can understand, then translate specific CLI output back. They're deliberately written thin—adding a new CLI basically means copying an existing one and tweaking.

4. Shared Runtime Layer — ICliProvider<TOptions>

This layer lives in HagiCode.Libs and does the real dirty work: launching processes cross-platform, handling stdio transport, parsing streaming output, handling timeouts and retries. All adapters reuse the same runtime, so when onboarding a new CLI, process management basically doesn't need rewriting.

To use an analogy: the adapter layer is the "interpreter," the shared runtime layer is the "delivery company." The interpreter just makes sure the message is clear; how the package gets delivered, whether there's traffic on the road—that's the delivery company's concern. Each does their job, and the world is peaceful.

5. Factory Routing Layer — AIProviderFactory

Inside CreateProvider, a switch instantiates the corresponding adapter based on AIProviderType, validating IsConfigured along the way. This is the only place that "knows concrete types," strictly isolated in the factory. Change is only allowed in one corner; everywhere else stays clean.

6. Directory / UI Projection Layer — main-professions.yaml

This layer is interesting—it's not code, it's data.

The primary profession list (role profiles like "I'm a frontend dev," "I'm a backend dev," "I'm a full-stack dev") is driven by the preset file main-professions.yaml, read through HeroPrimaryProfessionPresetProvider, then projected to the frontend UI. Adding a new primary profession requires no code changes—just edit YAML. Data instead of code, peace of mind.

By the way, this is the biggest refactor in HagiCode. Early versions had a code-embedded registry called AgentCliInstallRegistry. Later we found maintenance cost too high—more code, more tired people—so the whole thing got torn down and replaced with a data-driven + health monitoring approach. This is also why HagiCode can now rapidly expand profession types.

How Installation Gets Solved

13 CLIs all need installation, each with different official installation methods—that's another mountain.

Our approach is Docker Compose pre-installation + external management fallback. The Docker image pre-installs mainstream CLIs (Claude Code, Codex, Copilot, CodeBuddy, OpenCode, Qoder, Kiro, Kimi, Gemini, Pi), so users pull the image and use it—no typing commands one by one. Installed, naturally in a better mood.

For those needing separate installation in local environments, the installation command matrix looks roughly like this (verified against official docs):

CLI Official Installation Method
Claude Code npm install -g @anthropic-ai/claude-code
Codex npm install -g @openai/codex
GitHub Copilot npm install -g @github/copilot
CodeBuddy npm install -g @tencent-ai/codebuddy-code
OpenCode npm i -g opencode-ai@latest
Qoder npm install -g @qoder-ai/qodercli
Kiro `curl -fsSL https://cli.kiro.dev/install \
Kimi {% raw %}`curl -LsSf https://code.kimi.com/install.sh \
Gemini npm
Hermes Official script, docs-only fallback preserved
DeepAgents / Reasonix See respective official docs

The frontend {% raw %}PrimaryProfessionCard.tsx also changed accordingly—it now has no "Install CLI" button, but instead displays CLI availability, version detection results, and a fallback hint that "this CLI is externally managed." In other words, whether it installs successfully is the system layer's responsibility; UI only faithfully reports status. Writing state and logic separately, they'll eventually drift apart—so why bother?

What It Takes to Add a New CLI

In practice, adding a new CLI to HagiCode comes down to these steps:

  1. Add an enum value to AIProviderType
  2. Copy an existing *CliProvider, modify it for the new CLI's parameters and output parsing
  3. Add a routing line in AIProviderFactory's switch
  4. If entering the primary profession directory, configure it in main-professions.yaml
  5. Add an installation command to the image (or fall back to external management)

Through this entire process, core changes don't exceed two hundred lines of code—that's the true value of this abstraction. Each additional CLI has very low marginal cost; business code doesn't need a single change. All roads lead to Rome, ours just happens to be a slightly easier walk.

Summary

Looking back, "integrating 13 CLIs" sounds daunting, but broken down, it's really two layers of work:

One layer is isolating change—through AIProviderType enum + IAIProvider contract + thin adapters + shared runtime, decoupling business code from specific CLIs. The other layer is data-ifying configuration—using YAML presets like main-professions.yaml to drive the directory and UI, avoiding touching code every time something is added.

This solution is what stabilized after we stumbled through pits and iterated a few rounds in actual HagiCode development. If you're working on a similar "multi-provider integration" system, I hope this layered approach gives you some reference. After all, Agent CLIs will keep popping up in the coming years—an architecture that can quickly integrate new CLIs matters far more than "how many are supported right now"...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Top comments (0)