chico-ai 1.0.0

Agent-native configuration control plane

chico

chico is an agent-native configuration control plane — a deterministic reconciliation engine for distributed configuration state, designed for both humans and agents.

📖 Full documentation

✨ Why chico?

• Keep your AI agent configuration in a Git repository and sync it automatically
• Plan/apply lifecycle — preview every change before it happens
• Automatic scheduling via cron (macOS/Linux) or Task Scheduler (Windows)
• Structured JSON logging for full auditability
• Works with any GitHub repository, public or private

⚡ Quick Start

Initialize chico with a GitHub source in one command:

chico-ai init \
  --source github \
  --repo Chico-inc/agents-patterns \
  --path patterns \
  --source-prefix patterns/ \
  --target kiro \
  --branch master

Then sync:

chico-ai sync

That's it — chico fetches every file under patterns/ from the repository and applies it to ~/.kiro/.

✅ Features

• Sync configuration files from GitHub repositories to your local agent environment
• Plan/apply lifecycle — see exactly what will change before committing
• chico-ai sync — plan and apply in a single step
• Automatic scheduling — chico-ai schedule install --every 30 sets up a recurring sync
• Recursive directory traversal — syncs nested folder structures automatically
• UTF-8 and Latin-1 encoding support for international content
• 100% test coverage

🔧 Requirements

Python
3.11+

💽 Installation

pip install chico-ai

Or with uv:

uv tool install chico-ai

Or run without installing:

uvx chico-ai --help

📦 Usage

Initialize

chico-ai init \
  --source github \
  --repo Chico-inc/agents-patterns \
  --path patterns \
  --source-prefix patterns/ \
  --target kiro \
  --branch master

Creates ~/.chico/config.yaml pre-populated and ready to use. For an empty config to edit manually:

chico-ai init

Plan

Preview what would change without writing anything to disk:

chico-ai plan

Apply

Apply the changes computed by plan:

chico-ai apply

Sync

Plan and apply in one step:

chico-ai sync

Schedule

Install a recurring sync (every 30 minutes by default):

chico-ai schedule install
chico-ai schedule install --every 15
chico-ai schedule status
chico-ai schedule uninstall

Environment variables

Variable	Description
GITHUB_TOKEN	GitHub personal access token for private repositories

⚙️ Configuration

chico reads ~/.chico/config.yaml:

sources:
  - name: agents-patterns
    type: github
    repo: Chico-inc/agents-patterns
    branch: master
    path: patterns
    source_prefix: patterns/
    target: kiro

providers:
  - name: kiro
    type: kiro
    level: global

Field	Description
repo	GitHub repository in owner/repo format
path	Directory inside the repo to sync
source_prefix	Prefix stripped from source paths when mapping to local files. Defaults to path
branch	Branch to read from
target	Provider name this source feeds into

👩🏼‍⚖️ License

This project is licensed under the terms of the MIT license.