The Problem

Building a new AI agent means re-implementing the same substrate every time: controller loop, tool dispatch, session persistence, multi-agent wiring. Existing agent products (Claude Code, Codex) are fixed shapes; adapting them to a new workflow costs a ground-up rebuild. KohakuTerrarium packages that substrate so the next agent shape is a config file and a few custom modules, not a new repository.

What This Does

KohakuTerrarium is a Python framework for building and composing agents, plus a batteries-included app with TUI and web UI. The core abstraction is the creature: a standalone agent with its own controller, tools, sub-agents, triggers, memory, and I/O. A Terrarium engine hosts creatures as a graph runtime; a Studio layer adds catalog, sessions, and management surfaces.

The repo is substantial: 1,589 Python files, 264 Vue files, 684 test files. Entry points are src/kohakuterrarium/__main__.py (CLI) and src/kohakuterrarium/api/app.py (web API). The frontend lives in src/kohakuterrarium-frontend/ with Vite and Vue.

How It Is Wired

Execution starts at src/kohakuterrarium/__main__.py for the CLI (kt command) or src/kohakuterrarium/api/app.py for the HTTP API. The README's quickstart shows the path: kt login codex authenticates a provider, kt run @kt-biome/creatures/swe --mode cli launches an interactive agent shell. Programmatically, Agent.build() in the core package constructs an agent, then await agent.run() returns a typed TurnResult.

The framework's core modules are documented in docs/en/concepts/modules/: controller.md (main loop), tool.md (tool dispatch), trigger.md (event-driven execution), sub-agent.md (nested agents), memory-and-compaction.md (session persistence). The graph runtime is described in docs/en/concepts/impl-notes/graph-and-sessions.md and dynamic-graph.md for multi-agent wiring. The internal call graph has not been mapped for this repository; the docs describe architecture but the actual function-level control flow needs code reading to verify.

The blast radius is concentrated in the controller and session modules—everything routes through them. The module graph shows a hub-and-spoke pattern; changing the controller or session persistence touches every creature. The docker/ directory contains three Dockerfiles (.all, .client, .host) plus entrypoint scripts, suggesting host/client split for the Laboratory transport layer.

How To Use It

pip install kohakuterrarium
kt login codex
kt install @kt-biome
kt run @kt-biome/creatures/swe --mode cli

Programmatic usage is four lines:

from kohakuterrarium import Agent

agent = await Agent.build("@kt-biome/creatures/swe")
await agent.start()
result = await agent.run("Explain what this codebase does.")
print(result.text, result.usage)

Configuration lives in pyproject.toml for the Python side and src/kohakuterrarium-frontend/package.json for the Vue frontend. Docker builds use docker/Dockerfile.all for a combined image. The packaging/systemd/auth-secrets.example.conf file suggests a systemd deployment path with an auth secrets template.

Real-World Use

Embed KohakuTerrarium in a batch pipeline: a nightly job that pulls tickets, spins up a swe creature per ticket, runs it against the codebase, and writes results to a database. The Python-native API (agent.run() returning typed TurnResult) makes it composable inside existing Python services without a separate agent server.

Code Health & Issues

Static analysis flagged one item: Low/Security - secret-shaped paths present; the audit confirms or clears packaging/systemd/auth-secrets.example.conf. This is a template file, likely harmless, but verify it contains no real credentials.

SDLC observations from structure: 684 test files against 1,589 source files is a healthy ratio. CI exists (.github/workflows/ci.yml, nightly.yml, release.yml). Documentation is extensive (314 files). The custom license (KohakuTerrarium--1.0) is a review point before commercial use.

The Bottom Line

Substantial, well-documented framework with real depth—the module docs and test coverage suggest mature engineering. The trade-off is complexity: 1,589 Python files means a learning curve, and the custom license needs legal review. Best for teams building multiple agent shapes who want one substrate; overkill if you need one fixed agent and an existing product fits.