zima-blue-cli 0.4.0

Zima Blue CLI - Personal Agent Orchestration Platform

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
• Quick Start
• CLI Commands
• Documentation
• Development
• Naming Origin
• License

---

Features

• 🤖 Multi-Agent Support — Supports Kimi, Claude, Gemini, and other AI executors
• 📋 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:

Entity	Purpose	Example
Agent	AI executor config (kimi/claude/gemini)	code-reviewer
Workflow	Prompt template (Jinja2)	code-review-template
Variable	Template variable values	review-vars
Env	Environment variables and secrets	prod-env
PMG	Dynamic parameter groups	build-params
PJob	Execution config (composes all above)	daily-review-task

Directory Structure

~/.zima/
├── configs/
│   ├── agents/           # Agent configurations
│   ├── workflows/        # Workflow templates
│   ├── variables/        # Variable configurations
│   ├── envs/             # Environment configurations
│   ├── pmgs/             # Parameter groups
│   └── pjobs/            # Execution task configurations
└── agents/               # Agent runtime directories
    └── <agent-code>/
        ├── logs/         # Execution logs
        ├── prompts/      # Runtime prompts
        └── workspace/    # Working directory

Execution Flow

# Quick execution (shorthand)
zima run my-agent

# Composed execution (recommended)
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.

---

Quick Start

Installation

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

# Install dependencies
pip install -e "."

Basic Usage

# Create an Agent
zima create my-agent

# Run the Agent
zima run my-agent

# View logs
zima logs my-agent

Advanced Usage: Composed Configuration

# 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

Cleanup

# Unix / Linux / macOS
./cleanup.sh --auto

# Windows
cleanup.bat --auto

---

CLI Commands

Shorthand Commands

zima create <name>          # Create an Agent
zima run <name>             # Execute once
zima list                   # List all Agents
zima show <name>            # Show configuration
zima logs <name>            # View logs

Full Command Groups

# Agent management (supports kimi/claude/gemini)
zima agent create --name "My Agent" --code my-agent --type kimi
zima agent list --type kimi
zima agent show my-agent
zima agent test my-agent      # Preview generated CLI command
zima agent validate my-agent

# Workflow template management
zima workflow create --name "Review" --code review --template "# {{ title }}"
zima workflow render review --var my-vars

# Variable management
zima variable create --name "My Vars" --code my-vars
zima variable set my-vars key value

# Environment configuration
zima env create --name "Prod" --code prod-env
zima env set-secret prod-env API_KEY --source env

# PMG parameter group management
zima pmg create --name "Build Params" --code build-params

# PJob execution (composes Agent + Workflow + Variable + Env)
zima pjob create --name "Daily Task" --code daily \
  --agent my-agent --workflow review --variable my-vars
zima pjob run daily           # Execute task
zima pjob render daily        # Preview rendered output
zima pjob history daily       # View history

See docs/API-INTERFACE.md for the complete interface documentation.

---

Documentation

docs/
├── vision/           # Project vision and story
├── architecture/     # Latest architecture design ⭐ authoritative
├── history/          # Historical designs (reference only)
└── decisions/        # Architecture Decision Records (ADR)
    ├── 001-use-subprocess.md
    ├── 002-15min-cycle.md (deprecated)
    ├── 003-early-completion.md (deprecated)
    └── 004-single-execution.md ⭐ current

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

---

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.