KohakuTerrarium: an agent framework that treats the agent, not the chain, as the unit

The problem KohakuTerrarium is aimed at

The README makes its case with a list: Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent. Its argument is that these are genuinely different products, yet each one reimplements the same substrate from scratch, meaning a controller loop, tool dispatch, triggers, sub-agents, sessions, persistence and multi-agent wiring. The cost lands on anyone who needs a new agent shape: a fresh repository, a fresh runtime, the same plumbing underneath. KohakuTerrarium's stated goal is to put that substrate in one place so the next agent shape costs a config file and a few custom modules instead. The audience is therefore narrower than "people who want an AI agent". It is people who want to build one, or several, and who expect their requirements to keep moving. The README is explicit about the inverse case, listing Claude Code and Codex as reasons not to adopt when your needs are already stable, and naming sub-50 ms per-operation latency as a disqualifier.

Creature, Terrarium, Studio: three layers with different jobs

The core abstraction is the creature, described as a standalone agent with its own controller, tools, sub-agents, triggers, memory and I/O. A creature is made of six parts: controller (the reasoning loop), input (how events enter), output (how results leave), tools, triggers (what wakes it up), and sub-agents for internal delegation. Creatures are hosted by a Terrarium engine, a graph runtime that owns channels, lifecycle, output wiring, hot-plug, and the topology plus session bookkeeping that follows graph changes. Above that sits a Studio layer handling catalog, identity, active sessions, persistence, and the web, desktop and API management surfaces. There is an optional fourth piece: a Laboratory transport layer that splits host and engine across machines by slotting a WebSocket hop between Studio and Terrarium, leaving both unchanged. Composition is horizontal, through channels and lifecycle management rather than through a single orchestrator object. The framework also exposes a composition algebra, with >>, &, |, * and .iterate operators for stitching agents into pipelines. The README places KohakuTerrarium in a table alongside smolagents under the framework column, and puts CrewAI and AutoGen in a separate utility/wrapper row for multi-agent work, arguing that most tooling sits below the agent layer or jumps to orchestration with a thin idea of what an agent is.

The Python API: awaitable agents and typed turns

The README gives a four-line library example: import Agent from kohakuterrarium, call await Agent.build("@kt-biome/creatures/swe"), await agent.start(), then await agent.run("Explain what this codebase does.") and read result.text and result.usage off the returned TurnResult. Two details in that snippet matter more than the brevity suggests. First, the agent is an object you await, and the turn returns a typed result rather than a dictionary or a raw string, which is what makes embedding inside batch jobs and other agents tractable. Second, the build call takes a package reference, not a class, so the agent definition lives in a distributable package. The feature list adds that turns have timeouts that actually cancel, that streaming emits typed events, that @kt.tool turns any function into an agent tool, that LLM instances can be injected directly, and that errors are strict by default rather than silently falling back. That last choice is a real trade-off rather than a selling point: strict-by-default errors surface misconfiguration early, but they also mean a partially working setup fails loudly instead of degrading. Whether that suits you depends on whether you are debugging a new agent or running one in production.

Getting it running: four commands and a config reference

The README's 60-second path is four shell commands. pip install kohakuterrarium installs it. kt login codex authenticates a provider. kt install @kt-biome fetches the official creature pack, resolving through TerrariumMarket. kt run @kt-biome/creatures/swe --mode cli launches a full coding agent with file tools, shell access, web search and sub-agents. Ctrl+D exits, and kt resume --last picks the session back up. Session persistence is owned by the engine, not the agent author: the engine mints and owns session files, configured with session= or Terrarium(session_dir=), and resume works through kt resume or Terrarium.resume. SessionReader replays any finished run offline, and every event is indexed so kt search and the search_memory tool can look up past work. For script-side installation, kohakuterrarium.packages.ensure("@name") is described as the idempotent primitive. MCP servers connect per-agent or globally over stdio or streamable HTTP, with four meta-tools keeping the prompt small regardless of how many servers you attach. Authentication is opt-in per layer, host token, admin password and multi-user accounts, with everything off by default. The README recommends Python 3.12 or newer and states that CI validates 3.12+.

Where the framework stops being the right answer

The README's own boundaries section is the most useful part of it. Two exclusions are stated outright: a stable need already served by an existing agent product, and sub-50 ms per-operation latency. The second is a structural constraint, not a tuning problem. A graph runtime that owns channels, lifecycle, output wiring, hot-plug and session bookkeeping between a caller and an LLM call adds layers that a tight loop does not have. The six-module creature model is the other constraint. If your mental model does not map onto controller, tools, triggers, sub-agents and channels, the abstraction is overhead you will fight rather than scaffolding you will reuse. There is a third boundary the README implies without stating: the framework ships no finished agents. The 60-second demo depends on @kt-biome, a separate repository, so evaluating KohakuTerrarium means evaluating two projects at once. One more caveat from the metadata rather than the prose. The repository declares its licence as NOASSERTION while the README badge shows KohakuTerrarium-1.0, a custom identifier that is not an OSI licence. The README's own feature list also points to a docs/en/concepts/boundaries.md page for "more honesty", which is where the unstated limits presumably live.

How it differs from smolagents and CrewAI

The README's own table is the fairest comparison available. smolagents appears in the same framework row as KohakuTerrarium; CrewAI and AutoGen appear in a separate utility/wrapper row for multi-agent work. The distinction the README draws is where each one starts. CrewAI and AutoGen begin at orchestration: you describe roles and let a coordinator drive them, and the individual agent is comparatively thin. KohakuTerrarium begins at the agent and treats multi-agent composition as a graph of creatures connected by channels, with the Terrarium engine owning topology and session bookkeeping. That difference shows up in the API. A CrewAI-style framework hands you a crew object to run. KohakuTerrarium hands you an awaitable agent with a typed TurnResult you can embed in your own Python, and a set of operators for stitching agents together. LangChain and LangGraph sit in the LLM-app row instead, below the agent layer, so they are not direct substitutes. The honest summary is that CrewAI is faster to a working multi-agent demo, while KohakuTerrarium is aimed at people who expect to keep changing what an agent is.

Maintenance, release cadence and licence cost

The release list shows a nightly channel running alongside versioned tags: nightly-20260908 and nightly-20260907 bracket v2.1.2, with the README badge still reading version 2.0.0. Nightly builds are a signal that the project is moving quickly, and also that pinning matters. If you depend on the framework, pin to a tagged release rather than tracking nightly, because the nightly channel is by definition the unstable one. The repository was last pushed on 2026-09-10 and is not archived, so the project is active at the time of writing. The maintenance cost on your side is the creature model itself: every agent you build is a config plus custom modules, and those modules are yours to keep working across framework upgrades. The licence is the item to resolve before adoption, not after. The repository metadata reports NOASSERTION, and the README badge names KohakuTerrarium-1.0, a project-specific licence rather than a recognised OSI identifier. That combination means you cannot infer the terms from the name. Read the actual licence file in the repository and have whoever handles licensing at your organisation review it, particularly if you plan to redistribute the framework or ship it inside a commercial product. Nothing here is legal advice, and the terms are not determinable from the material at hand.

Editorial conclusion

Adopt KohakuTerrarium if you are building a new agent shape and would otherwise reimplement controller, tool dispatch, triggers, sessions and multi-agent wiring yourself, and if your team is comfortable with Python 3.12+ and the creature mental model. Do not adopt it if an existing agent product already covers your stable needs, if you cannot map your design onto controller / tools / triggers / sub-agents / channels, or if you need sub-50 ms per-operation latency. Before committing, verify three things against the repository rather than the marketing: the actual terms of the KohakuTerrarium-1.0 licence, which the metadata reports as NOASSERTION; whether the nightly release channel is one you can pin away from in production; and whether the @kt-biome creature pack covers the agent shapes you need, since the framework alone ships no finished agents.

Official sources

1. Issues
2. Kohaku-Lab/KohakuTerrarium on GitHub
3. Project website
4. README
5. Releases