Metadata-Version: 2.4
Name: chico-ai
Version: 1.1.0b2
Summary: Agent-native configuration control plane
Project-URL: Homepage, https://ceb10n.github.io/chico
Project-URL: Repository, https://github.com/ceb10n/chico
Project-URL: Documentation, https://ceb10n.github.io/chico
Author-email: Rafael de Oliveira Marques <rafaelomarques@gmail.com>
License: The MIT License (MIT)
        
        Copyright (c) 2024 Rafael de Oliveira Marques and other contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agents,cli,configuration,devtools,github,kiro,sync
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pygithub>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: ty>=0.0.1a1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.29; extra == 'docs'
Description-Content-Type: text/markdown

# chico

<p align="center">
  <img src="https://raw.githubusercontent.com/ceb10n/chico/master/docs/assets/logo.png" alt="chico logo" width="400"/>
</p>

<br/>


[![CI](https://github.com/ceb10n/chico/actions/workflows/publish.yml/badge.svg)](https://github.com/ceb10n/chico/actions)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/chico-ai)](https://pypi.org/project/chico-ai)
[![PyPI - License](https://img.shields.io/pypi/l/chico-ai)](https://pypi.org/project/chico-ai)

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

📖 **[Full documentation](https://ceb10n.github.io/chico)**

## ✨ 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:

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

Then sync:

```bash
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

```bash
pip install chico-ai
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install chico-ai
```

Or run without installing:

```bash
uvx chico-ai --help
```

## 📦 Usage

### Initialize

```bash
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:

```bash
chico-ai init
```

### Plan

Preview what would change without writing anything to disk:

```bash
chico-ai plan
chico-ai plan hooks          # plan a single source
```

### Apply

Apply the changes computed by plan:

```bash
chico-ai apply
chico-ai apply steering-files  # apply a single source
```

### Sync

Plan and apply in one step:

```bash
chico-ai sync
chico-ai sync my-config       # sync a single source
```

### Schedule

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

```bash
chico-ai schedule install
chico-ai schedule install --every 15
chico-ai schedule install --every 30 --source hooks   # schedule a single source
chico-ai schedule status
chico-ai schedule uninstall
```

### List

Show all configured sources and providers:

```bash
chico-ai list
```

### Environment variables

| Variable | Description |
| :------- | :---------- |
| `GITHUB_TOKEN` | GitHub personal access token for private repositories |

## ⚙️ Configuration

chico reads `~/.chico/config.yaml`:

```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 |

## Provider fields

| Field | Description |
| :---- | :---------- |
| `name` | Unique provider name |
| `type` | Provider type (`kiro`) |
| `level` | `global` for `~/.kiro/`, `project` for a specific target directory |
| `path` | Absolute path to the target directory (project level only). Files are synced directly into this path — no `.kiro/` is appended. Recorded automatically by `chico-ai init --level project` as `{cwd}/.kiro` |

## 👩🏼‍⚖️ License

This project is licensed under the terms of the [MIT license.](LICENSE)
