Zima Blue CLI

"I chose blue. That intense blue." — Zima Blue

Zima Blue CLI is a personal Agent orchestration platform that lets you run a 7x24 autonomous AI Agent factory on your own computer.

Simply define Prompt templates and configuration parameters, and Zima will automatically invoke Kimi CLI to execute tasks and return structured results.

Define Prompt Template → Configure Parameters → Execute → Get Results

Table of Contents

• Features
• Architecture
• Configuration
• Quick Start
• CLI Commands
• Documentation
• Claude Code Marketplace
• Development
• Naming Origin
• License

Features

• 🤖 Multi-Agent Support — Pluggable AI executors (currently Kimi and Claude)
• 📋 Configuration Entities — Layered config design: Agent + Workflow + Variable + Env + PMG
• 🚀 PJob Execution Layer — Declarative task configuration, one-command composition and execution
• 📝 Jinja2 Templates — Flexible Prompt templates with variable substitution
• 🔒 Secret Management — Supports environment variables, files, Vault, and other secret sources
• 🧪 Full Test Coverage — Unit tests + integration tests (including real Kimi invocation tests)
• 🧹 Auto Cleanup — Built-in cleanup scripts for cache and temporary files

Architecture

Configuration Entities

Zima uses a layered configuration design, enabling flexible task execution through composition:

Directory Structure

~/.zima/
├── configs/
│   ├── agents/           # Agent configurations
│   ├── workflows/        # Workflow templates
│   ├── variables/        # Variable configurations
│   ├── envs/             # Environment configurations
│   ├── pmgs/             # Parameter groups
│   ├── pjobs/            # Execution task configurations
│   └── schedules/        # Daemon scheduling configurations
├── daemon/               # Daemon runtime (PID, state, logs, JSONL history)
├── temp/pjobs/           # Ephemeral PJob working directories
├── history/pjobs.json    # Per-PJob execution history (max 100 each)
├── logs/                 # Execution logs
└── scenes.yaml           # Optional user-defined quickstart scenes

Execution Flow

# Composed execution
zima pjob run my-task    # Combines Agent + Workflow + Variable + Env

Important This project adopts an iterative design approach. Always refer to docs/architecture/ for the latest design, and use AGENTS.md at the repository root as the final authority for implementation.

Configuration

Zima reads configuration from one place only — the config root:

${ZIMA_HOME:-~/.zima}/configs/

Configs are one YAML file per entity, named after its code:

YAML written anywhere else — for example a project directory — is not auto-discovered.

Two Ways to Configure

• YAML path — copy a working pack from examples/webhook/ or examples/sdd/ into the config root, edit, validate, run. Best for agents, bulk setup, and version control:

  ZIMA_HOME="${ZIMA_HOME:-$HOME/.zima}"
  mkdir -p "$ZIMA_HOME/configs/"
  cp -r examples/webhook/{agents,workflows,variables,envs,pjobs} "$ZIMA_HOME/configs/"
  # edit the copied YAML files to taste, then:
  zima pjob validate claude-cr --check-render
  zima pjob run claude-cr
  

• CLI path — zima quickstart bootstraps a complete task interactively; zima <kind> create --example prints a starter YAML; fine-grained commands handle small edits. validate is the shared quality gate for both paths.

Run-time overrides (zima pjob run <code> --set-var/--set-env/--set-param) apply to that execution only — they never write back to any YAML file.

Full entity reference, secret handling, and the validation workflow: Configuration Guide.

Quick Start

Installation

# Clone the repository
git clone https://github.com/zhuxixi/zima-blue-cli.git
cd zima-blue-cli

# Install dependencies
uv sync

Basic Usage

# Create an Agent
zima agent create --name "My Agent" --code my-agent --type kimi

# Run a PJob (after composing one)
zima pjob run <pjob-code>

# Inspect execution history
zima pjob history <pjob-code>

Quickstart Wizard

The fastest way to get started. One command creates all configs interactively:

zima quickstart

The wizard walks you through picking a task template, naming your setup, selecting an AI agent (Kimi / Claude), and auto-detects your git repo.

When done, run the generated PJob:

zima pjob run <generated-code> --dry-run  # preview
zima pjob run <generated-code>            # execute

Or Start from an Example Pack

Prefer editing YAML directly? Copy a complete, working setup and make it yours — examples/webhook/README.md walks through installing a full webhook-triggered code review pack (agents, workflows, variables, envs, pjobs) with a single cp -r. The Configuration Guide explains every file.

Manual Configuration (Power Users)

Tip: zima quickstart is the recommended entry point. The steps below are the manual config-by-config approach for power users.

# 1. Create an Agent
zima agent create --name "Code Reviewer" --code reviewer --type kimi

# 2. Create a Workflow template
zima workflow create --name "Review Template" --code review \
  --template "# Review: {{ task_name }}\n\n{{ description }}"

# 3. Create Variable configuration
zima variable create --name "Review Vars" --code review-vars
zima variable set review-vars task_name "Bug Fix Review"
zima variable set review-vars description "Check for memory leaks"

# 4. Create a PJob composition
zima pjob create --name "Code Review Task" --code review-task \
  --agent reviewer --workflow review --variable review-vars

# 5. Run the task
zima pjob run review-task

# 6. View execution history
zima pjob history review-task

The CLI commands above write the same YAML files you would edit by hand — both paths land in the config root. See the Configuration Guide to manage them as plain YAML instead.

Cleanup

# Cleanup temp and history (cross-platform)
uv run python scripts/cleanup.py --auto

Webhook-Triggered Automatic Code Review

Zima can listen for GitHub webhooks and automatically trigger PJob-based code reviews when a PR is labeled with zima:needs-review.

# Prefer the ZIMA_WEBHOOK_SECRET env var so the secret is not visible in `ps`.
export ZIMA_WEBHOOK_SECRET=your-webhook-secret
zima webhook-server \
  --smee-url https://smee.io/YOUR_CHANNEL \
  --pjob claude-cr \
  --pjob kimi-cr

A secret is required by default (fail-closed). For local loopback testing only, pass --allow-no-secret to run without HMAC verification.

When a pull request is labeled zima:needs-review, the configured PJobs (e.g., claude-cr and kimi-cr) are triggered automatically.

See examples/webhook/README.md for sample configs and GitHub webhook setup.

CLI Commands

# Run & manage tasks
zima pjob run <code>            # execute (runs in background by default)
zima pjob run <code> --dry-run  # preview prompt, command, env — no execution
zima pjob status <code>         # status + recent history for one task
zima pjob ps                    # all currently running tasks
zima pjob cancel <code>         # cancel running execution(s)
zima pjob history <code>        # execution history and stats

# Validate configuration — the shared quality gate
zima agent validate <code>                # per entity: agent | workflow | variable | env | pmg | pjob | schedule
zima pjob validate <code> --check-render  # cross-entity refs + template render

# Runtime services
zima daemon start|stop|status|logs
zima webhook-server --pjob <code> [--smee-url <url>]

# Bootstrap
zima quickstart                 # interactive wizard: a complete task from scratch

Full CLI reference: docs/cli-reference.md (generated from the live command tree — regenerate with uv run python scripts/generate_cli_docs.py after changing commands).

Documentation

docs/
├── vision/           # Project vision and story
├── architecture/     # Latest architecture design ⭐ authoritative
│   └── data-and-runtime-reference.md  # Data models, runtime interfaces, execution flow
├── design/           # Feature design documents (historical, written pre-implementation)
├── guides/           # User-facing guides
│   └── configuration.md               # ⭐ YAML configuration guide
├── history/          # Historical designs (reference only)
├── decisions/        # Architecture Decision Records (ADR; 004-single-execution ⭐ current)
└── reports/          # Generated reports

Use Cases

• SOP Tasks: DevOps scripts, data processing, report generation
• R&D Tasks: Test coverage, code refactoring (workflow-driven via Prompt)
• CI/CD Integration: Build steps that return structured results
• Scheduled Tasks: Periodic automation via cron

AI Coding Pipeline

Zima automates the issue-driven AI coding pipeline — from code review through deployment — using configurable PJob compositions.

Pipeline Stages

issue → brainstorm/spec → plan → impl → create-PR → CR → post-fix → post-merge → integration-test → deploy-prod

Automation Coverage

Supported PJobs

Claude Code Marketplace

This repository doubles as a Claude Code plugin marketplace named zima-blue. The plugins here are the Claude Code-side counterparts of zima daemon's automation — install them in your Claude Code session and zima can drive them via scheduled prompts.

Install

/plugin marketplace add zhuxixi/zima-blue-cli
/plugin install pr-automation@zima-blue

Plugins

More plugins (e.g. pr-monitor) will be added under the same marketplace as zima's automation surface grows.

Development

See AGENTS.md for development conventions, coding style, and design principles.

Naming Origin

Zima Blue is inspired by Alastair Reynolds' science fiction short story Zima Blue.

The story follows an artist-robot who, after millennia of upgrades and evolution, ultimately returns to its original form as a simple pool-cleaning robot — symbolizing returning to essence and self-evolution.

License

This project is licensed under the MIT License.