Clone this folder to start a new KohakuTerrarium package.
It is structured as a real reusable pack, not just a loose example:
kohaku.yaml— package manifest used bykt installcreatures/— standalone creature templatesterrariums/— multi-creature terrarium templateskt_template/— installable Python package for reusable code
creatures/template-creature/ includes:
- a heavily commented
config.yaml - prompt files
- memory files
- a full template for every custom extension surface:
- tool
- input
- output
- trigger
- sub-agent config export
- plugin
- each template demonstrates the full user-facing author API for that surface, with comments showing what every overrideable method or field is for
Run it with:
kt run creatures/template-creatureterrariums/template-team/ includes:
- a commented
terrarium.yaml - a root prompt
- three creature roles wired through channels
Run it with:
kt terrarium run terrariums/template-teamInstall locally in editable mode while developing:
kt install ./kt-template -eThen run by package reference:
kt run @kt-template/creatures/template-creature
kt terrarium run @kt-template/terrariums/template-teamThe package follows the same conventions as the KohakuTerrarium core:
- One responsibility per module. A family of files that share a prefix becomes a
sub-package with the prefix dropped (
kt_template/tools/package_tool.py, notkt_template/package_tool.py). - Files stay under 500 statements (imports and docstrings excluded); 1000 is the hard limit.
- Imports sit at the top of the module, grouped as standard library, third party,
kohakuterrarium, then this package. Optional dependencies are the only exception. - Tests mirror the package:
tests/unit/<area>/test_<module>.pytestskt_template/<area>/<module>.py, and each asserts behaviour (the output a tool returns, the line an output module writes), not the shape of an object. tests/unit/test_manifest.pychecks that every module the manifest advertises imports, that the creature and terrarium templates build against aScriptedLLM, and that the manifest,pyproject.tomland the framework pin agree.
Run the checks the CI workflow runs:
pip install -e ".[dev]"
ruff check . && black --check . && pytestThe package requires KohakuTerrarium >=2.2.0 (framework: in kohaku.yaml and
the dependency in pyproject.toml).
- Rename the package in
kohaku.yamlandpyproject.toml. - Rename
kt_template/to your own Python package name (and the matchingtests/unit/module imports). - Rename the creature and terrarium folders.
- Update
module:paths in creature configs if you move files. - Replace prompt and memory content with your actual persona and workflow.
This repository's config loader accepts custom-module options as inline fields. That is why the sample configs here use:
- name: my_tool
type: custom
module: ./tools/my_tool.py
class: MyTool
greeting: helloinstead of nesting those extra fields under options:.
kt-template/kohaku.yamlkt-template/creatures/template-creature/config.yamlkt-template/creatures/template-creature/prompts/system.mdkt-template/terrariums/template-team/terrarium.yamlkt-template/kt_template/tools/package_tool.py