Kohaku-Lab/KohakuTerrarium

What it solves

Many existing agent products (like Claude Code, Codex, and others) each re-implement the same underlying machinery: a controller loop, tool dispatch, triggers, sub-agents, sessions, persistence, and multi-agent wiring. KohakuTerrarium puts that shared substrate in one place, so creating a new agent shape becomes a config file and a few custom modules instead of a whole new codebase.

How it works

KohakuTerrarium is a Python framework. The core abstraction is a "creature" — a standalone agent with its own controller (the reasoning loop), tools, triggers, sub-agents, memory, and input/output. Creatures are hosted by a "Terrarium" engine that manages the graph of creatures, channels, lifecycle, and session bookkeeping. Above that, a "Studio" layer handles management, identity, and user-facing surfaces (web dashboard, desktop app, HTTP API). Optionally, a "Laboratory" layer splits host and engine across machines via WebSocket. Agents are async Python objects with typed results, so you can embed them directly into your own programs. You can run agents via CLI, TUI, web, or desktop, and compose them into pipelines using operators like >> (sequence), & (parallel), | (fallback), and * (retry).

Who it’s for

This is for developers who want to build custom AI agents without reinventing the wheel — whether you need a single agent, a multi-agent team, or agents embedded inside larger Python applications like batch jobs, bots, or pipelines. It's also for those who want strong out-of-the-box agents that can be customized. If you already have a stable agent product that fits your needs, or you require sub-50ms per-operation latency, this may not be the right fit.

Highlights

• Agent-level abstraction: define a new agent by writing a config and custom modules, not by rebuilding the runtime.
• Real Python API: typed TurnResult turns with timeouts that actually cancel, streaming typed events, @kt.tool to turn any function into an agent tool, and strict error handling.
• Built-in session persistence and resume: sessions are saved automatically; resume later with kt resume or Terrarium.resume. SessionReader replays any finished run offline.
• Searchable session history: every event is indexed; kt search and the search_memory tool let you (and the agent) look up past work.
• Non-blocking context compaction: long-running agents keep working while context compresses in the background.
• Comprehensive built-in tools and sub-agents: file, shell, web, JSON, notebook, search, editing, plus graph-editor tools for privileged nodes.
• Context-aware side conversations: an optional fork helper lets you ask side questions in an isolated snapshot without affecting the main task.
• MCP support: connect MCP servers (stdio or streamable-HTTP) per-agent or globally; four meta-tools keep the prompt small even with many servers.
• Package system and marketplace: kt install @name resolves through TerrariumMarket; idempotent script-side primitive available.
• Composition algebra: >>, &, |, *, and .iterate operators for building agent pipelines.
• Multiple runtime surfaces: CLI, TUI, web dashboard, and native desktop app included out of the box.
• Optional four-layer authentication (host token, admin password, multi-user accounts) — opt in per layer, off by default.