GitHub - cliver-project/CLIver: Personal AI Lab

General-purpose AI agent for your terminal — safe, controlled, and adaptable to any domain.

Why CLIver?

Model-agnostic — OpenAI-compatible APIs (Qwen, DeepSeek, Cerebras, etc.), Ollama, vLLM, or any provider. You choose the model, not the framework.
General-purpose — Not just for coding. DevOps, research, writing, data analysis, or anything else you need. Customizable system prompts, skills, and workflows adapt to your domain.
Safe by default — Layered permission system governs every tool execution. Default, auto-edit, and YOLO modes give you the right balance of control and automation.
Embeddable — AgentCore Python API lets you integrate CLIver's agent capabilities into your own applications and scripts.
Gateway mode — Deploy as a bot service with Telegram, Discord, Slack, or Feishu adapters. One agent, multiple frontends.

Quick Start

# Install via pip
pip install cliver

# Or run with Docker
docker run --rm -it --user $UID:0 -v ~/.cliver:/home/cliver/.cliver \
  -e DEEPSEEK_API_KEY ghcr.io/cliver-project/cliver

# Start chatting
cliver -p "What time is it in Beijing and London?"

# Interactive mode
cliver

Features

Multi-Provider LLM

Connect to any OpenAI-compatible API, Ollama, or vLLM endpoint. Configure multiple providers and switch between them on the fly. No vendor lock-in.

# ~/.cliver/config.yaml
providers:
  minimax:
    type: openai
    api_url: https://api.minimaxi.com/v1
    api_key: '{{ keyring("cliver", "minimax.api_key") }}'
    rate_limit:
      requests: 1500
      period: 5h
      margin: 0.1
    image_url: https://api.minimaxi.com/v1/image_generation
    image_model: image-01
    models:
    - MiniMax-M2.7
  minimax-anthropic:
    type: anthropic
    api_url: https://api.minimaxi.com/anthropic
    api_key: '{{ keyring("cliver", "minimax.api_key") }}'
    rate_limit:
      requests: 1500
      period: 5h
      margin: 0.1
    image_url: https://api.minimaxi.com/v1/image_generation
    image_model: image-01
    models:
    - MiniMax-M2.7
  deepseek-anthropic:
    type: anthropic
    api_url: https://api.deepseek.com/anthropic
    api_key: "{{ env.DEEPSEEK_API_KEY }}"
    models:
    - deepseek-v4-flash
  deepseek-openai:
    type: openai
    api_url: https://api.deepseek.com
    api_key: "{{ env.DEEPSEEK_API_KEY }}"
    models:
    - deepseek-v4-flash

MCP Integration

Connect to any Model Context Protocol (MCP) server for extended tool capabilities. File systems, databases, APIs, and more — all through a standardized protocol.

# ~/.cliver/config.yaml
mcpServers:
  filesystem:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
  
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]

Skills

LLM-driven skill activation following the Agent Skills specification. Skills are auto-discovered from ~/.cliver/skills/ and activated based on task context.

# List available skills
cliver skills list

# Add a custom skill
cat > ~/.cliver/skills/my-skill.yaml <<EOF
name: my-skill
description: Custom skill for domain-specific tasks
system_prompt: |
  You are an expert in my specific domain...
tools:
  - name: custom_tool
    ...
EOF

Workflows

LangGraph-powered multi-step workflow engine with subagent isolation and pause/resume support. Complex tasks stay on track without scattered, unpredictable behavior.

# Workflow definition (Python)
from cliver.workflow import Workflow, WorkflowStep

workflow = Workflow(
    name="deploy-pipeline",
    steps=[
        WorkflowStep(name="build", agent="builder"),
        WorkflowStep(name="test", agent="tester", depends_on=["build"]),
        WorkflowStep(name="deploy", agent="deployer", depends_on=["test"]),
    ]
)

Memory & Identity

Persistent knowledge and CliverProfile management across sessions. CLIver remembers your preferences, project context, and domain-specific information.

# Set your profile
cliver profile set name "Leo Gao"
cliver profile set role "Platform Engineer"
cliver profile set preferences.style "concise"

# Add persistent knowledge
cliver memory add "Production cluster endpoint: https://api.prod.example.com"

Permission System

Layered tool permission system with three modes:

default — Explicit confirmation for every tool execution
auto-edit — Auto-approve file edits and reads, confirm everything else
yolo — Auto-approve all tool executions (use with caution)

# ~/.cliver/cliver-settings.yaml
permission_mode: auto-edit

# Per-tool overrides
permissions:
    - tool: Read
      action: allow
    - tool: Write
      action: allow
    - tool: Bash
      resource: "git *"
      action: allow
    - tool: "github#.*
      action: deny

Gateway Mode

Deploy CLIver as a bot service with adapters for Telegram, Discord, Slack, or Feishu. One agent, multiple frontends.

# Install gateway dependencies
pip install cliver[telegram]

# Run Telegram bot
export TELEGRAM_BOT_TOKEN=your_token
cliver gateway telegram

# Or use Docker
docker run -e TELEGRAM_BOT_TOKEN -e OPENAI_API_KEY \
  ghcr.io/cliver-project/cliver:latest gateway telegram

Embeddable Python API

Use AgentCore to integrate CLIver's agent capabilities into your own applications.

from cliver import AgentCore

# Initialize agent
agent = AgentCore(
    provider="openai",
    model="gpt-4o",
    system_prompt="You are a helpful assistant.",
)

# Run a task
response = agent.run("Analyze this data and generate a report")
print(response.content)

# Stream responses
for chunk in agent.stream("What's the weather in Tokyo?"):
    print(chunk, end="", flush=True)

Documentation

Full documentation is available at https://cliver-project.github.io/CLIver/

Topic	Description
Installation	Installation methods, requirements, and setup
Configuration	Configure providers, models, permissions, and behavior
Chat Usage	Interactive mode, one-shot commands, and session management
Skills	Built-in skills, custom skills, and Agent Skills spec
Memory & Identity	Profile management and persistent knowledge
Permissions	Permission modes, tool allowlists, and safety controls
Workflows	LangGraph workflows, subagents, and task orchestration
Extensibility	Custom tools, plugins, and API integration

Development

CLIver welcomes contributions. To set up a development environment:

# Clone the repository
git clone https://github.com/cliver-project/CLIver.git
cd CLIver

# Set up dev environment
make init

# Run tests
make test

# Lint and format check
make lint

# Auto-fix lint and formatting
make format

See CONTRIBUTING.md for guidelines.

License

CLIver is licensed under the Apache License 2.0. See LICENSE for details.

_{Built by Leo Gao | 16-year Red Hat veteran}