# Chi Base

Chi Base is the shared coordination package for Chi modules running as Pi
extensions. It discovers modules, initializes them in dependency order, stores
versioned global/project configuration, and provides a small /chi settings
command.

## Install

The repository is currently private and Chi Base is not yet published to npm.
Authenticate GitHub first with the GitHub CLI, then install it from Git:

```sh
gh auth login
gh auth setup-git
pi install https://github.com/henkaku-center/chi-base
```

SSH is also supported when your SSH key is configured:

```sh
pi install git:git@github.com:henkaku-center/chi-base
```

When the package is published, use `npm:@henkaku-center/chi-base` instead. See the
[Pi package installation and update documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#install-and-manage)
for package management details.

## Update

Update this GitHub package with:

```sh
pi update https://github.com/henkaku-center/chi-base
```

To update Pi and all installed packages at once, use `pi update --all`.

Chi Base is installed once. Individual Chi modules listen for the
chi:discover event and register with the live registry supplied in that event.

## Module authors

Import the contract as types only:

~~~ts
import type { ChiBase } from "@henkaku-center/chi-base/contract";
~~~

Runtime communication uses the ChiBase object received from discovery. See
[the Chi concepts glossary](CONCEPTS.md), [how to write a module](docs/how-to-write-a-chi-module.md),
[the module contract](docs/contract.md), [configuration and migrations](docs/configuration.md),
and [the example module](docs/example-module.md).

## Configuration

Chi configuration is separate from Pi settings:

- Global: ~/.pi/agent/chi/config.json
- Project: .pi/chi/config.json

Project configuration is used only for trusted projects. Settings changed by
/chi are persisted immediately. Modules with `onConfigChange` receive the new
effective configuration while running; modules without it can read the latest
value with `chi.getConfig(id)`. Initialization is not repeated.

The `/chi` editor uses one tab per module. It starts in project mode when the
trusted project has a loaded local override, and otherwise starts in global
mode. It supports `p` for project scope, arrow keys or `h`/`l` for tabs, and
`x` to reset the selected setting. Its header shows the active scope, and its
custom list uses `use default (value)` and `use global (value)` fallback labels
without repeating scope in row names. See [configuration and migrations](docs/configuration.md)
for the complete behavior.

## Scope

Chi Base is intentionally small. It is not a general event bus, storage
framework, module loader, or arbitrary settings editor. Modules communicate
through direct APIs exposed by the registry.

## References

- [Pi extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
- [Pi packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
- [Zod enums](https://zod.dev/api?id=zod-enums)