CLIver

---

CLIver is an embeddable agent core with a companion CLI, built from two packages:

• cliver-core — the embeddable engine: an agent loop with tool calling, provider engines for the OpenAI and Anthropic protocols, per-purpose model bindings (chat, image, video, TTS, ASR, embed, rerank), nine built-in tools, Agent Skills, MCP, and opt-in permission and execution-policy axes. No CLI, database, or config files — Python objects in, messages out.
• cliver — the CLI application built on cliver-core: config-path and skill-discovery conventions plus a cliver command that runs one task per invocation or starts a streaming interactive REPL, with interactive tool approval in both modes. It remains experimental and is not on PyPI yet.

cliver-core 0.3 is the first stable series: the public API stays backward compatible, and 0.3.x patch releases contain bug fixes and backward-compatible additions. The cliver CLI is for tinkering: run one-shot tasks or a multi-turn REPL with your own skills and tools, approve mutating calls interactively, and inspect tool events. See Stability & Versioning for the support policy.

Quick Start

Install the core library (Python 3.10–3.13):

pip install cliver-core==0.3.1

As a library

import asyncio

from cliver_core import AgentCore, ModelBindings, presets


async def main():
    bindings = ModelBindings(llm=presets.deepseek(api_key="..."))
    async with AgentCore.open(bindings) as agent:
        response = await agent.chat("Summarize the agent loop in one sentence.")
        print(response.message.content)


asyncio.run(main())

See the cliver-core README for tools, skills, MCP, media capabilities, and the full API.

From the terminal

The cliver CLI lives in this repository (not on PyPI yet). With a prompt it runs one task; with no prompt on a terminal it starts a streaming REPL:

export CLIVER_MODEL=deepseek-v4-flash
export CLIVER_PROVIDER=deepseek        # or CLIVER_BASE_URL for any compatible endpoint
export DEEPSEEK_API_KEY=...            # or CLIVER_API_KEY

uv run cliver --yes "Read pyproject.toml and summarize the dependencies."
uv run cliver --yes                    # interactive REPL: /help, /clear, /exit

--yes approves ASK tools without prompting; without it, safe tools still run and each ASK tool asks on the terminal (non-interactive runs deny them). --skill NAME runs a skill explicitly, --cwd DIR selects the project root for skill discovery, and {config_dir}/.env is loaded automatically. In the REPL, each turn streams its answer and keeps the conversation for follow-ups.

Built-in Capabilities

• Model-agnostic — OpenAI and Anthropic protocols, live-verified presets, any compatible endpoint
• Built-in tools — file I/O, shell, code execution, grep, directory listing, todo tracking, and web fetch
• Skills system — Agent Skills loading plus model-driven FindSkills / ActivateSkill / ReadSkillFile
• MCP support — stdio and streamable HTTP clients with CLIver-style discovery
• Permission and execution policy — opt-in SAFE/ASK gates and env/cwd/path scopes
• Media capabilities — image, video, text-to-speech, speech-to-text, embedding, and rerank
• Reliability — same-purpose failover, run deadlines, and explicit credential rotation
• Structured output — schema-validated chat_structured() with retries and usage accounting
• Context management — declarative compaction plans, an opt-in LlmCompactor, and a full-history escape hatch, all inside the run deadline
• System One — decision-model tool/skill selection with a fail-open selector
• Embeddable API — AgentCore.chat(), .stream(), and .run_skill() with no CLI dependencies

Repository Layout

packages/cliver-core/   # embeddable library (published)
packages/cliver/        # CLI application built on cliver-core
website/                # documentation site (Astro + Starlight)

Documentation

Full documentation at cliver-project.github.io/CLIver

Development

git clone https://github.com/cliver-project/CLIver.git
cd CLIver

make init     # Set up dev environment
make test     # Run the workspace test suite
make lint     # Lint and format check
make format   # Auto-fix lint/format issues
make dist     # Build the cliver-core sdist + wheel

cd website && npm install && npm run dev   # Docs dev server at localhost:4321

License

Apache 2.0