The machine for building agents — so you stop rebuilding the machine every time you want a new one.
pip install kohakuterrarium # install
kt login codex # authenticate
kt install https://github.com/Kohaku-Lab/kt-biome.git # get OOTB creatures
kt run @kt-biome/creatures/swe --mode cli # run oneYou get an interactive shell with a full coding agent — file tools, shell access, web search, sub-agents, resumable sessions. Ctrl+D exits; kt resume --last picks back up.
Want more hand-holding? Getting Started. Want to build your own? First Creature.
You probably want KohakuTerrarium if you need a new agent shape and don't want to rebuild the substrate; you want OOTB creatures you can customise; you want to embed agent behaviour in existing Python; your requirements are still evolving.
You probably don't if an existing agent product (Claude Code, Codex, …) already fits your stable needs; your mental model doesn't map onto controller / tools / triggers / sub-agents / channels; you need sub-50 ms per-operation latency. More honesty at boundaries.
KohakuTerrarium is a framework for building agents — not another agent.
The last two years produced a striking number of agent products: Claude Code, Codex, OpenClaw, Gemini CLI, Hermes Agent, OpenCode, and many more. They are genuinely different, and they all re-implement the same substrate from scratch: a controller loop, tool dispatch, trigger system, sub-agent mechanism, sessions, persistence, multi-agent wiring. Every new agent shape costs a new ground-up reimplementation of the plumbing.
KohakuTerrarium's job is to put that substrate in one place so the next agent shape costs a config file and a few custom modules, not a new repo.
The core abstraction is the creature: a standalone agent with its own controller, tools, sub-agents, triggers, memory, and I/O. Creatures compose horizontally into a terrarium — a pure wiring layer. Everything is Python, so agents can be embedded inside tools, triggers, plugins, and outputs of other agents.
For out-of-the-box creatures you can try today, see kt-biome — the showcase pack of useful agents and plugins built on top of the framework.
| Product | Framework | Utility / Wrapper | |
|---|---|---|---|
| LLM App | ChatGPT, Claude.ai | LangChain, LangGraph, Dify | DSPy |
| Agent | kt-biome, Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent… | KohakuTerrarium, smolagents | — |
| Multi-Agent | kt-biome | KohakuTerrarium | CrewAI, AutoGen |
Most tooling sits below the agent layer or jumps straight to multi-agent orchestration with a thin idea of what an agent is. KohakuTerrarium starts with the agent itself.
A creature is made of:
- Controller — the reasoning loop
- Input — how events enter the agent
- Output — how results leave the agent
- Tools — what actions it can take
- Triggers — what wakes it up
- Sub-agents — internal delegation for specialised tasks
A terrarium composes multiple creatures horizontally through channels, lifecycle management, and observability.
- Agent-level abstraction. The six-module creature model is the first-class concept. Every new agent shape is "write a config and maybe a few custom modules," not "rebuild the runtime."
- Built-in session persistence and resume. Sessions store operational state, not just chat history. Resume a run hours later with
kt resume. - Searchable session history. Every event is indexed.
kt searchand thesearch_memorytool let you (and the agent) look up past work. - Non-blocking context compaction. Long-running agents keep working while context is compacted in the background.
- Comprehensive built-in tools and sub-agents. File, shell, web, JSON, search, editing, planning, review, research, terrarium management.
- MCP support. Connect stdio / HTTP MCP servers per-agent or globally; tools surface in the prompt automatically.
- Package system. Install creatures / terrariums / plugins / LLM presets from Git or local paths; compose installed packages with inheritance.
- Python-native. Agents are async Python objects. Embed them inside tools, triggers, plugins, or outputs of other agents.
- Composition algebra.
>>,&,|,*,.iterateoperators for stitching agents into pipelines programmatically. - Multiple runtime surfaces. CLI, TUI, web dashboard, and desktop app out of the box.
- Useful OOTB creatures via
kt-biome. Start by running strong default agents; customise or inherit from them later.
# From PyPI
pip install kohakuterrarium
# Optional extras: pip install "kohakuterrarium[full]"
# Or from source (for development — uv is the project convention)
git clone https://github.com/Kohaku-Lab/KohakuTerrarium.git
cd KohakuTerrarium
uv pip install -e ".[dev]"
# Build the web frontend (required for `kt web` / `kt app` from source)
npm install --prefix src/kohakuterrarium-frontend
npm run build --prefix src/kohakuterrarium-frontend# Official showcase pack
kt install https://github.com/Kohaku-Lab/kt-biome.git
# Any third-party package
kt install <git-url>
kt install ./my-creatures -e # editable install# Codex OAuth (ChatGPT subscription)
kt login codex
kt model default gpt-5.4
# Or any OpenAI-compatible provider via `kt config provider add`Supports OpenRouter, OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible API.
# Single creature
kt run @kt-biome/creatures/swe --mode cli
kt run @kt-biome/creatures/researcher
# Multi-agent terrarium
kt terrarium run @kt-biome/terrariums/swe_team
# Web dashboard
kt serve start
# Native desktop
kt app- Concept docs
- Glossary — plain-English definitions
- Why KohakuTerrarium
- What is an agent
- Development home
- Internals
- Testing
- Package READMEs under
src/kohakuterrarium/
List, Create, Delete +------------------+
+-----| Tools System |
+---------+ | +------------------+
| Input | | ^ |
+---------+ V | v
| +---------+ +------------------+ +--------+
+-->| Trigger |-->| Controller |-->| Output |
User input | System | | (Main LLM) | +--------+
+---------+ +------------------+
| ^
v |
+------------------+
| Sub Agents |
+------------------+
A creature is a standalone agent with its own runtime, tools, sub-agents, prompts, and state.
kt run path/to/creature
kt run @package/path/to/creature +---------+ +---------------------------+
| User |<----->| Root Agent |
+---------+ | (terrarium tools, TUI) |
+---------------------------+
| ^
sends tasks | | observes results
v |
+---------------------------+
| Terrarium Layer |
| (pure wiring, no LLM) |
+-------+----------+--------+
| swe | coder | .... |
+-------+----------+--------+
A terrarium is a pure wiring layer that manages creature lifecycles, the channels between them, and the framework-level output wiring that auto-delivers a creature's turn-end output to named targets. No LLM, no decisions — just runtime. Creatures don't know they're in a terrarium; they run standalone too.
Terrarium is our proposed architecture for horizontal multi-agent — two complementary cooperation mechanisms (channels for conditional / optional traffic; output wiring for deterministic pipeline edges), plus hot-plug and observation. Still evolving as patterns emerge; the ROADMAP has the open questions. Prefer sub-agents (vertical) when a single creature can decompose the task itself — it's the simpler answer for most "I need context isolation" instincts.
A terrarium can define a root agent that sits outside the team and operates it through terrarium management tools. The user talks to root; root talks to the team.
Channels are the communication substrate — for terrariums and for agent-to-agent patterns inside a single creature.
- Queue — one consumer receives each message
- Broadcast — all subscribers receive each message
A creature has six conceptual modules. Five of them are user-extensible — you swap their implementations in config or in Python. The sixth, the controller, is the reasoning loop that drives them; you rarely swap it (and when you do, you're writing the framework's successor).
| Module | What it does | Example custom use |
|---|---|---|
| Input | Receives external events | Discord listener, webhook, voice input |
| Output | Delivers agent output | Discord sender, TTS, file writer |
| Tool | Executes actions | API calls, database access, RAG retrieval |
| Trigger | Generates automatic events | Timer, scheduler, channel watcher |
| Sub-agent | Delegated task execution | Planning, code review, research |
Plus plugins, which modify the connections between modules without forking them (prompt plugins, lifecycle hooks). See plugins guide.
- Environment — shared terrarium state (shared channels).
- Session — private creature state (scratchpad, private channels, sub-agent state).
Private by default, shared by opt-in.
KohakuTerrarium already ships:
- Built-in file, shell, web, JSON, channel, trigger, and introspection tools, including single-edit and multi-edit file mutation primitives.
- Built-in sub-agents for exploration, planning, implementation, review, summarisation, and research.
- Background tool execution and non-blocking agent flow.
- Session persistence with resumable operational state.
- FTS + vector memory search (model2vec / sentence-transformer / API embedding providers).
- Non-blocking auto-compaction for long-running agents.
- MCP (Model Context Protocol) integration — stdio and HTTP transports.
- Package manager for creatures, plugins, terrariums, and reusable agent packs (
kt install,kt update). - Python embedding through
Agent,AgentSession,TerrariumRuntime, andKohakuManager. - HTTP and WebSocket serving.
- Web dashboard and native desktop app.
- Custom module and plugin systems.
Agents are async Python values. Embed them:
import asyncio
from kohakuterrarium.core.agent import Agent
from kohakuterrarium.core.channel import ChannelMessage
from kohakuterrarium.terrarium.config import load_terrarium_config
from kohakuterrarium.terrarium.runtime import TerrariumRuntime
async def main():
# Single agent
agent = Agent.from_path("@kt-biome/creatures/swe")
agent.set_output_handler(lambda text: print(text, end=""), replace_default=True)
await agent.start()
await agent.inject_input("Explain what this codebase does.")
await agent.stop()
# Multi-agent terrarium
runtime = TerrariumRuntime(load_terrarium_config("@kt-biome/terrariums/swe_team"))
await runtime.start()
tasks = runtime.environment.shared_channels.get("tasks")
await tasks.send(ChannelMessage(sender="user", content="Fix the auth bug."))
await runtime.run()
await runtime.stop()
asyncio.run(main())Because agents are Python values, they compose with operators. >> (sequence), & (parallel), | (fallback), *N (retry), .iterate (async loop):
import asyncio
from kohakuterrarium.compose import agent, factory
from kohakuterrarium.core.config import load_agent_config
def make_agent(name, prompt):
config = load_agent_config("@kt-biome/creatures/general")
config.name, config.system_prompt, config.tools, config.subagents = name, prompt, [], []
return config
async def main():
# Persistent agents (accumulate conversation)
async with await agent(make_agent("writer", "You are a writer.")) as writer, \
await agent(make_agent("reviewer", "You are a strict reviewer. Say APPROVED if good.")) as reviewer:
pipeline = writer >> (lambda text: f"Review this:\n{text}") >> reviewer
async for feedback in pipeline.iterate("Write a haiku about coding"):
print(f"Reviewer: {feedback[:100]}")
if "APPROVED" in feedback:
break
# Parallel ensemble with retry + fallback
fast = factory(make_agent("fast", "Answer concisely."))
deep = factory(make_agent("deep", "Answer thoroughly."))
safe = (fast & deep) >> (lambda results: max(results, key=len))
safe_with_retry = (safe * 2) | fast
print(await safe_with_retry("What is recursion?"))
asyncio.run(main())More: Programmatic Usage, Composition, Python API, and examples/code/.
- cli — rich inline terminal experience
- tui — full-screen Textual application
- plain — simple stdout/stdin for pipes and CI
See CLI Reference.
Vue-based dashboard + FastAPI server.
kt web # one-shot, foreground
kt serve start # long-running daemon
# Frontend dev: npm run dev --prefix src/kohakuterrarium-frontendSee HTTP API, Serving guide, Frontend Architecture.
kt app launches the web UI inside a native desktop window (requires pywebview).
Sessions save to ~/.kohakuterrarium/sessions/ unless disabled.
kt resume # pick interactively
kt resume --last # resume most recent
kt resume swe_team # resume by name prefixThe same store powers searchable history:
kt embedding <session> # build FTS + vector indices
kt search <session> "auth bug fix" # hybrid/semantic/FTS searchAnd the agent can search its own history via the search_memory tool.
.kohakutr files store conversation, tool calls, events, scratchpad, sub-agent state, channel messages, jobs, resumable triggers, and config metadata.
Creatures are meant to be packaged, installed, reused, and shared.
kt install https://github.com/someone/cool-creatures.git
kt install ./my-creatures -e
kt list
kt update --allRun installed configs with package references:
kt run @cool-creatures/creatures/my-agent
kt terrarium run @cool-creatures/terrariums/my-teamAvailable resources:
kt-biome/— official showcase creatures, terrariums, and plugin packexamples/agent-apps/— config-driven creature examplesexamples/code/— Python usage examplesexamples/terrariums/— multi-agent examplesexamples/plugins/— plugin examples
See examples/README.md.
src/kohakuterrarium/
core/ # Agent runtime, controller, executor, events, environment
bootstrap/ # Agent initialisation factories (LLM, tools, I/O, triggers, plugins)
cli/ # `kt` command dispatcher
terrarium/ # Multi-agent runtime, topology wiring, hot-plug, persistence
builtins/ # Built-in tools, sub-agents, I/O modules, TUI, user commands, CLI UI
builtin_skills/ # Markdown skill manifests for on-demand docs
session/ # Session persistence, memory search, embeddings
serving/ # Transport-agnostic service manager and event streaming
api/ # FastAPI HTTP + WebSocket server
compose/ # Composition algebra primitives
mcp/ # MCP client manager
modules/ # Base protocols for tools, inputs, outputs, triggers, sub-agents, user commands
llm/ # LLM providers, profiles, API key management
parsing/ # Tool-call parsing and stream handling
prompt/ # Prompt aggregation, plugins, skill loading
testing/ # Test infrastructure (ScriptedLLM, TestAgentBuilder, recorders)
src/kohakuterrarium-frontend/ # Vue web frontend
kt-biome/ # (separate repo) Official OOTB pack
examples/ # Example creatures, terrariums, code samples, plugins
docs/ # Tutorials, guides, concepts, reference, dev
Every subpackage has its own README describing files, dependency direction, and invariants.
Full docs live in docs/.
First Creature · First Terrarium · First Python Embedding · First Custom Tool · First Plugin
Getting Started · Creatures · Terrariums · Sessions · Memory · Configuration · Programmatic Usage · Composition · Custom Modules · Plugins · MCP · Packages · Serving · Examples
Glossary · Why KohakuTerrarium · What is an agent · Composing an agent · Modules · Agent as a Python object · Composition algebra · Multi-agent · Patterns · Boundaries
CLI · HTTP · Python API · Configuration · Builtins · Plugin hooks
Near-term directions include more reliable terrarium flow, richer UI output / interaction modules across CLI / TUI / web, more built-in creatures, plugins, and integrations, and better daemon-backed workflows for long-running and remote usage. See ROADMAP.md.
KohakuTerrarium License 1.0: based on Apache-2.0 with naming and attribution requirements.
- Derivative works must include
KohakuorTerrariumin their name. - Derivative works must provide visible attribution with a link to this project.
Copyright 2024-2026 Shih-Ying Yeh (KohakuBlueLeaf) and contributors.
- QQ: 1097666427
- Discord: https://discord.gg/xWYrkyvJ2s
- Forum: https://linux.do/