CLISYS

Multi-CLI Intelligent Collaboration System

Meta-CLI · Agentic Execution Fabric · AI Orchestrator

English · 中文 · Roadmap · Contributing · Security

What is CLISYS?

CLISYS is not another AI CLI tool. It is a Meta-CLI Orchestrator — a coordination layer that makes multiple AI-powered CLI tools work together as one cohesive system.

Think of it as a conductor for an orchestra of AI assistants: each tool plays to its strengths while CLISYS routes tasks, aggregates results, and iterates toward a solution.

User Request → CLISYS Orchestrator
                      │
         ┌────────────┼────────────┐
         ↓            ↓            ↓
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │ Claude  │  │  Codex  │  │ Gemini  │  … more
    │  Code   │  │   CLI   │  │   CLI   │
    └─────────┘  └─────────┘  └─────────┘
         │            │            │
         └────────────┴────────────┘
                      │
                      ↓
            Collaborative Result

Inspired by Oh My OpenAgent (formerly Oh My OpenCode) — the idea that the AI CLI ecosystem deserves the same composability as shell environments like oh-my-zsh.

Features

Feature	Description
🎯 Multi-CLI Orchestration	Coordinate Claude Code, Codex CLI, Gemini CLI, and more
🧠 Intelligent Task Dispatch	Capability-based, cost-aware, and performance-based routing
🔄 Loop Mechanisms	Ralph Loop (self-refinement) and Ultrawork Loop (parallel execution)
📊 Result Aggregation	Merge, vote, or select-best from multiple adapter outputs
⚙️ Flexible Configuration	TOML-based config with Zod validation and multi-level override
💾 Session Persistence	SQLite + Drizzle ORM for execution history and session state
🔌 Plugin-First Adapter System	Built-in adapters plus plugin discovery, manifests, provider backends, toolchain gating, and maintenance workflows
🏗️ Event-Driven Core	EventBus for monitoring, debugging, and hook integration

Quick Start

Prerequisites

Bun ≥ 1.0 or Node.js ≥ 20
At least one supported AI CLI tool installed (e.g. claude, codex, gemini)

Installation

# Clone the repository
git clone https://github.com/XucroYuri/CLISYS.git
cd CLISYS

# Install dependencies
bun install

# (Optional) Run tests to verify the installation
bun test

Basic Usage

# Show all available commands
bun run src/cli/index.ts --help

# List available adapters and their status
bun run src/cli/index.ts adapters

# Execute a task (auto-routes to best adapter)
bun run src/cli/index.ts run "Create a REST API with JWT authentication"

# Target a specific adapter
bun run src/cli/index.ts run "Review this code for security issues" --adapter claude-code

# Run in parallel across all adapters
bun run src/cli/index.ts run "Refactor this module" --parallel

# Use iterative refinement (Ralph Loop)
bun run src/cli/index.ts run "Write comprehensive tests" --loop ralph --max-iterations 3

Architecture

clisys/
├── src/
│   ├── core/
│   │   ├── orchestrator/     # TaskParser, Dispatcher, Aggregator, LoopManager
│   │   ├── adapter/          # BaseAdapter, AdapterRegistry
│   │   ├── plugins/          # Manifest schema, loader, discovery, SDK
│   │   ├── providers/        # brew/npm/pipx/cargo/binary provider backends
│   │   ├── toolchain/        # Policy gate, state, locks, manager, audit, maintenance
│   │   ├── bus/              # EventBus
│   │   ├── config/           # Configuration loader & validator
│   │   ├── logger/           # Pino-based structured logging
│   │   └── storage/          # SQLite session & execution history
│   ├── adapters/
│   │   ├── claude-code/      # Claude Code adapter
│   │   ├── codex/            # OpenAI Codex CLI adapter
│   │   └── gemini/           # Google Gemini CLI adapter
│   ├── loops/
│   │   ├── ralph.ts          # Self-referential iterative loop
│   │   └── ultrawork.ts      # Parallel multi-adapter loop
│   └── cli/
│       ├── commands/         # run, adapters, config commands
│       └── index.ts          # CLI entry point (Clipanion)
├── tests/                    # Vitest test suite (147 tests)
├── docs/
│   ├── design/               # Architecture & design documents
│   └── roadmap.md            # Development roadmap
└── config/
    └── default.toml          # Default configuration

Data Flow

User Prompt
    │
    ▼
┌─────────────┐
│  CLI Layer  │  Clipanion command routing
└─────────────┘
    │
    ▼
┌─────────────┐
│ TaskParser  │  Intent extraction, capability requirements
└─────────────┘
    │
    ▼
┌─────────────┐
│ Dispatcher  │  Strategy: capability / cost / performance / round-robin
└─────────────┘  ←── AdapterRegistry (health checks, capability scoring)
    │
    ▼
┌─────────────┐
│  Adapters   │  Subprocess execution, output capture
└─────────────┘
    │
    ▼
┌─────────────┐
│ Aggregator  │  Strategy: best_result / merge / vote
└─────────────┘
    │
    ▼
  Result

Supported Adapters

Adapter	Status	CLI Tool	Notes
`claude-code`	✅ Stable	Claude Code	Anthropic's coding assistant
`codex`	✅ Stable	Codex CLI	OpenAI's CLI coding agent
`gemini`	✅ Available	Gemini CLI	Google's CLI AI tool
`openagent`	🔲 Planned	Oh My OpenAgent	Composable agent framework
`aider`	🔲 Planned	Aider	Git-aware coding assistant

Adding a new adapter now supports a plugin-first path: publish a @clisys/adapter-* package with a validated manifest, dynamic entrypoint, and provider-backed toolchain metadata, or continue using built-in adapters where appropriate. See docs/design/architecture.md and CONTRIBUTING.md for details.

Loop Mechanisms

Ralph Loop — Iterative Self-Refinement

Iterates on a task until a completion criterion is met or the maximum iteration limit is reached. Ideal for tasks requiring refinement cycles (e.g., test → fix → test).

┌──────────────────────────────────────┐
│  ┌──────┐   ┌─────────┐   ┌───────┐ │
│  │ Task │──▶│ Execute │──▶│ Check │ │
│  └──────┘   └─────────┘   └───────┘ │
│      ▲                        │      │
│      └────────────────────────┘      │
│          (iterate if incomplete)     │
└──────────────────────────────────────┘

Ultrawork Loop — Parallel Multi-Adapter Execution

Dispatches the same task to multiple adapters concurrently, then aggregates or selects the best result. Ideal for validation, diverse perspectives, and redundancy.

           ┌──────┐
           │ Task │
           └──────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌───────┐ ┌───────┐ ┌───────┐
│Adapter│ │Adapter│ │Adapter│
│   1   │ │   2   │ │   3   │
└───────┘ └───────┘ └───────┘
    │          │          │
    └──────────┴──────────┘
               ▼
         ┌──────────┐
         │ Aggregate│
         └──────────┘
               │
               ▼
           ┌──────┐
           │Result│
           └──────┘

Configuration

CLISYS uses a layered TOML configuration system:

Built-in defaults (config/default.toml)
User-level config (~/.clisys/config.toml)
Project-level config (.clisys/config.toml in your project)

version = "1.0"

[adapters.claude-code]
enabled = true
command  = "claude"

[adapters.codex]
enabled = true
command  = "codex"

[adapters.gemini]
enabled = true
command  = "gemini"

[plugins]
directories = ["./plugins"]

[orchestrator]
default_strategy   = "capability_based"   # capability_based | cost_based | performance | round_robin
max_parallel_tasks = 3
task_timeout       = 300000               # ms

[logging]
level  = "info"    # debug | info | warn | error
output = "console" # console | file

Development Roadmap

See docs/roadmap.md for the full technical roadmap. Summary:

Phase	Version	Focus
Phase 1 ✅	v0.1.0	MVP — core orchestration, three built-in adapters, loops, storage
Phase 2 🔄	v0.2.x	Extended adapters (OpenAgent, Aider)
Phase 3 📋	v0.3.x	Plugin architecture, streaming output, score caching
Phase 4 📋	v0.5.x	Enterprise features: permissions, sandbox, audit log
Phase 5 📋	v1.0.0	Public release, SDK, community ecosystem

Technical Stack

Component	Technology	Why
Runtime	Bun / Node.js 20+	Near-native performance, excellent TypeScript support
Language	TypeScript 5 (strict)	Type safety across all components, great AI tooling integration
CLI Framework	Clipanion	Type-safe command handling with decorators
Validation	Zod	Schema validation for config and adapter contracts
Logging	Pino	Fast, structured JSON logging
Testing	Vitest	Blazing fast unit tests, native ESM support
Storage	Drizzle ORM + SQLite	Type-safe ORM, zero-dependency SQLite
Config	TOML via `@iarna/toml`	Human-friendly, widely used in CLI tools

Inspirations & Credits

CLISYS builds on the shoulders of giants. The following projects directly inspired its design or are used as foundational dependencies:

Conceptual Inspirations

Project	Contribution
Oh My OpenAgent (formerly Oh My OpenCode)	The core idea: composable AI CLI orchestration, the "oh-my-zsh for AI agents" concept
oh-my-zsh	Plugin/adapter ecosystem model
LangChain	Agent chaining and tool-use patterns
AutoGPT	Self-referential looping and autonomous task execution
CrewAI	Multi-agent role-based collaboration

AI CLI Tools Integrated / Planned

Tool	Repository	Notes
Claude Code	Anthropic docs	Primary adapter
Codex CLI	openai/codex	Primary adapter
Gemini CLI	google-gemini/gemini-cli	Available
Aider	paul-gauthier/aider	Planned
Oh My OpenAgent	openagentlabs/oh-my-openagent	Planned

Core Dependencies

Package	Repository	Purpose
clipanion	arcanis/clipanion	Type-safe CLI framework
zod	colinhacks/zod	Schema validation
pino	pinojs/pino	Structured logging
drizzle-orm	drizzle-team/drizzle-orm	Type-safe SQLite ORM
@iarna/toml	iarna/iarna-toml	TOML parsing
vitest	vitest-dev/vitest	Test framework
bun	oven-sh/bun	JS/TS runtime

Contributing

CLISYS cannot be maintained by one person alone. Contributions — code, documentation, adapters, ideas — are very welcome.

This project explicitly invites experienced developers to join as long-term maintainers. If you are interested in taking on a stewardship role, please open an issue or reach out directly.

See CONTRIBUTING.md for:

Development setup
Code style guidelines
How to add a new adapter
Pull request process
Maintainer responsibilities

See CODE_OF_CONDUCT.md for community standards.

License

CLISYS is released under the MIT License. See LICENSE for full text.

Licence Considerations

MIT allows unrestricted use, including commercial use. This is intentional for v0.x to encourage adoption and ecosystem growth.

As the project matures toward v1.0, the maintainers may evaluate a dual-licensing model (MIT for individual/open-source use, commercial licence for enterprise deployments). Any such change would apply only to future versions and would be discussed openly with the community before being adopted.

Community

Issues & Feature Requests: GitHub Issues
Discussions: GitHub Discussions
Security: See SECURITY.md for responsible disclosure

Project Status

Metric	Status
Build	✅ Passing
Tests	✅ 75/75 passing
TypeScript	✅ Strict mode, 0 errors
Version	0.1.0 (MVP)
Stability	Beta — API may change before v1.0

Built with ❤️ for the AI-assisted development future.

If CLISYS has been useful to you, please consider starring ⭐ the repository — it helps others find the project.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
config		config
docs		docs
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
drizzle.config.ts		drizzle.config.ts
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CLISYS

What is CLISYS?

Table of Contents

Features

Quick Start

Prerequisites

Installation

Basic Usage

Architecture

Data Flow

Supported Adapters

Loop Mechanisms

Ralph Loop — Iterative Self-Refinement

Ultrawork Loop — Parallel Multi-Adapter Execution

Configuration

Development Roadmap

Technical Stack

Inspirations & Credits

Conceptual Inspirations

AI CLI Tools Integrated / Planned

Core Dependencies

Contributing

License

Licence Considerations

Community

Project Status

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

CLISYS

What is CLISYS?

Table of Contents

Features

Quick Start

Prerequisites

Installation

Basic Usage

Architecture

Data Flow

Supported Adapters

Loop Mechanisms

Ralph Loop — Iterative Self-Refinement

Ultrawork Loop — Parallel Multi-Adapter Execution

Configuration

Development Roadmap

Technical Stack

Inspirations & Credits

Conceptual Inspirations

AI CLI Tools Integrated / Planned

Core Dependencies

Contributing

License

Licence Considerations

Community

Project Status

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages