{"id":50124731,"url":"https://github.com/kohaku-lab/kt-biome","last_synced_at":"2026-05-23T19:04:08.706Z","repository":{"id":349133728,"uuid":"1200317548","full_name":"Kohaku-Lab/kt-biome","owner":"Kohaku-Lab","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-08T18:56:35.000Z","size":253,"stargazers_count":5,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T20:43:26.232Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kohaku-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T09:16:35.000Z","updated_at":"2026-05-08T18:56:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kohaku-Lab/kt-biome","commit_stats":null,"previous_names":["kohaku-lab/kohaku-creatures","kohaku-lab/kt-defaults","kohaku-lab/kt-biome"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Kohaku-Lab/kt-biome","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2Fkt-biome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2Fkt-biome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2Fkt-biome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2Fkt-biome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kohaku-Lab","download_url":"https://codeload.github.com/Kohaku-Lab/kt-biome/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kohaku-Lab%2Fkt-biome/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-23T19:04:00.889Z","updated_at":"2026-05-23T19:04:08.700Z","avatar_url":"https://github.com/Kohaku-Lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kt-biome\n\n`kt-biome` is the official batteries-included package for [KohakuTerrarium](https://github.com/Kohaku-Lab/KohakuTerrarium).\n\nIf KohakuTerrarium is the framework, `kt-biome` is the practical starting point: a package you can install and use immediately for real work, while also treating it as a reference for how creatures, terrariums, plugins, tools, skills, prompts, and I/O modules are meant to be composed.\n\nThis package is for people who do not want to begin from a blank `config.yaml`.\nIt gives you:\n\n- ready-to-run creatures\n- reusable terrariums\n- a set of production-oriented plugins and tools\n- packaged skill bundles\n- concrete examples you can inherit from instead of rebuilding from zero\n\n## What `kt-biome` is for\n\nMost users install `kt-biome` for one of three reasons:\n\n1. They want a strong default creature immediately.\n2. They want an official base package to inherit from.\n3. They want useful packaged modules they can drop into their own configs.\n\nA common workflow looks like this:\n\n- run `@kt-biome/creatures/general` or `@kt-biome/creatures/swe`\n- decide what you like\n- inherit from that creature in your own package\n- add your own prompts, tools, plugins, or terrariums on top\n\nSo `kt-biome` is not just a demo repo and not just documentation by example. It is the official out-of-the-box ecosystem for KohakuTerrarium.\n\n## Install\n\n```bash\n# install from GitHub\nkt install https://github.com/Kohaku-Lab/kt-biome.git\n\n# or install the local checkout in editable mode\nkt install ./kt-biome -e\n```\n\nAfter installation, package paths look like:\n\n- `@kt-biome/creatures/general`\n- `@kt-biome/creatures/swe`\n- `@kt-biome/terrariums/swe_team`\n- `@kt-biome/terrariums/ralph_loop`\n\n## Quick start\n\n```bash\n# pick and log into a model provider first\nkt login codex\nkt model default gpt-5.4\n\n# run a general creature\nkt run @kt-biome/creatures/general\n\n# run a coding-focused creature\nkt run @kt-biome/creatures/swe\n\n# run a research creature\nkt run @kt-biome/creatures/researcher\n\n# run a terrarium\nkt terrarium run @kt-biome/terrariums/swe_team\n```\n\n## Where to start\n\n### Start with `general`\n\n```bash\nkt run @kt-biome/creatures/general\n```\n\nUse this when you want the default KohakuTerrarium experience with the standard built-in tools and sub-agents, plus packaged skills and low-friction guidance plugins already wired in.\n\n### Start with `swe`\n\n```bash\nkt run @kt-biome/creatures/swe\n```\n\nUse this when your main work is repository navigation, implementation, debugging, tests, and code review. This is the best default for most software projects.\n\n### Start with `researcher`\n\n```bash\nkt run @kt-biome/creatures/researcher\n```\n\nUse this when you want a stronger research-and-analysis posture than `general`.\n\n### Use the domain creatures when you already know the task shape\n\n- `music` for LilyPond-first score and composition work\n- `video` for HyperFrame / HTML-based video or frame workflows\n- `diagrammer` for Mermaid, Graphviz, and D2 work\n\n## Core creatures\n\n### `general`\n\n`general` is the backbone of the package.\n\nIt is the creature most other shipped creatures inherit from, and it is meant to feel like the official “default agent” for KohakuTerrarium:\n\n- built-in file and shell tools\n- built-in sub-agents\n- dynamic skill mode\n- wildcard package skill opt-in (`skills: [\"*\"]`)\n- default-on `context_files` and `family_guidance` plugins\n\nIf you only try one creature from this package, try this one first.\n\n### `bounded_general`\n\n`bounded_general` is `general` with a shared iteration cap.\n\nIt exists mainly as a practical example of the shared iteration-budget feature. Use it when you want the default general creature but want a hard stop on autonomous runs.\n\n### `swe`\n\n`swe` inherits from `general` and adds a stronger software-engineering workflow and system prompt.\n\nIt is the best starting point when the job is:\n\n- inspect a repo\n- implement a change\n- run focused validation\n- prepare a clean commit\n\n### `researcher`, `music`, `video`, `diagrammer`\n\nThese inherit from the same base philosophy as `general` but narrow the posture toward a task family.\n\nThey are useful both as runnable creatures and as inheritance targets for your own package.\n\n## Terrariums\n\n`kt-biome` ships reusable terrariums that demonstrate multi-creature patterns built on top of the framework’s topology, channels, and output wiring.\n\nThere is intentionally no single global `root` creature shipped as a reusable package creature. Each terrarium owns its own root prompt and orchestration behavior.\n\n### Included terrariums\n\n- `swe_team` — an implementation/review pipeline using two `swe` instances\n- `pair_programming` — a driver/navigator pair using two `swe` instances\n- `auto_research` — a multi-step research pipeline over `general` creatures\n- `deep_research` — planner/researcher/synthesizer/critic pipeline\n- `ralph_loop` — an autonomous initializer/worker loop modeled after the Ralph workflow\n\n### The Ralph loop\n\n`ralph_loop` is the most opinionated terrarium in the package.\n\nIt uses two creatures:\n\n- `ralph_initializer` — runs once, scaffolds `AGENTS.md`, `progress.md`, and `NOTES.md`, commits them, then exits\n- `ralph_worker` — wakes repeatedly from the `work-log` channel, completes one checkbox item per turn, commits, and posts status back to the same channel\n\nUse it when you want a long-running autonomous implementation loop with durable on-disk task tracking.\n\nRun it with:\n\n```bash\nkt terrarium run @kt-biome/terrariums/ralph_loop/\n```\n\nThen give the initial goal as your first prompt.\n\n## Plugins\n\n`kt-biome` ships practical plugins that are meant to be reused directly in your own creatures.\n\nSome are convenience upgrades, some are safety layers, and some demonstrate newer framework extension points.\n\n### Low-friction default upgrades\n\nThese improve the default coding experience and are enabled by default on `general`:\n\n- `context_files` — walks from the working directory up to the git root, finds files like `AGENTS.md`, `.cursorrules`, and `.hermes.md`, scans them, and injects them into each turn\n- `family_guidance` — adds small model-family-specific guidance blocks for OpenAI/Codex and Gemini-style models\n\n### Session control and runtime behavior\n\n- `cost_tracker` — tracks token/cost usage and can now vote to stop the run when budget is exhausted\n- `termination_goal` — stops the run when a scratchpad flag becomes truthy\n- `seamless_memory` — runs internal reader/writer agents against session memory before and after model calls\n- `event_logger` — writes structured JSONL logs of agent activity\n- `multimodal_guard` — rewrites multimodal input into text-only placeholders\n\n### Safety and harness plugins\n\n- `checkpoint` — takes a `git stash` checkpoint before destructive tools\n- `circuit_breaker` — opens per-tool breakers after repeated failures\n- `injection_scanner` — scans tool outputs for prompt-injection patterns and annotates, redacts, or blocks\n- `pev_verifier` — independent verifier harness that checks completion and re-injects issues on failure\n\n### Library-only helper\n\n`RAGReader` is no longer a plugin. It lives at `kt_biome.lib.rag_reader` as a reusable library helper for KohakuRAG-style database reads.\n\nUse it from your own plugin or tool when you want:\n\n- structured node reads\n- BM25 / vector / hybrid retrieval\n- context expansion up the document tree\n- tree-based deduplication\n\n## Skills\n\n`kt-biome` also ships reusable skill bundles as `agentskills.io`-style `SKILL.md` directories.\n\nBecause `general` declares `skills: [\"*\"]`, package-provided skills are enabled by default for creatures that inherit from it.\n\n### Included skill bundles\n\n- `git-commit-flow` — safe commit workflow for source-code changes\n- `pdf-merge` — merge, split, or reorder PDFs with required page-count verification\n- `todo-file` — maintain a user-visible `todo.md` / `plan.md` task list across turns\n\nThese can be invoked in three ways:\n\n- automatically, when a matching path pattern activates the skill\n- by model invocation with `##skill \u003cname\u003e ...##`\n- by user invocation with `/\u003cname\u003e ...`\n\n### Skill creation workflow\n\n`kt-biome` also ships:\n\n- `skill_manage` — a tool for creating or patching reusable `SKILL.md` bundles\n- `skill_nudge` — a trigger that periodically reminds the agent to save a repeatable procedure as a skill\n\nThis makes the package useful not only for consuming skills, but also for teaching an agent to persist new ones.\n\n## Extra tools, triggers, and I/O modules\n\nBeyond creatures and plugins, `kt-biome` includes reusable packaged modules for more specialized setups.\n\n### Tools\n\n- `bash_docker` — a bash-shaped tool backed by a persistent Docker container\n- `bash_ssh` — a bash-shaped tool backed by a pooled SSH session\n- `database` — SQLite access tool, marked non-concurrency-safe\n- `skill_manage` — reusable skill creation/patch/view tool\n\n### Triggers\n\n- `cron` — full cron-expression trigger with timezone support and backfill behavior\n- `skill_nudge` — periodic reminder to save a reusable skill\n- `webhook` — HTTP webhook trigger\n\n### I/O modules\n\n- Discord input/output modules\n- Telegram input/output modules\n\nThe Telegram modules are designed to degrade cleanly when the optional SDK is not installed.\n\n## A good inheritance pattern\n\nA typical downstream package starts from one of these creatures instead of copying configuration by hand.\n\n```yaml\nname: my_team_coder\nbase_config: \"@kt-biome/creatures/swe\"\n\ncontroller:\n  llm: claude-sonnet-4.6\n\nsystem_prompt_file: prompts/system.md\n```\n\nThen add only what is specific to your package:\n\n- your own system prompt\n- your own plugins\n- your own custom tools\n- your own terrariums\n\nThat is the intended use of `kt-biome`: inherit, narrow, and compose.\n\n## Package layout\n\n```text\nkt-biome/\n  creatures/      reusable creature configs\n  terrariums/     reusable terrarium configs\n  prompts/        shared prompt fragments\n  skills/         packaged SKILL.md bundles\n  kt_biome/       Python package for plugins, tools, triggers, I/O, and libs\n  kohaku.yaml     package manifest\n```\n\nCross-package references use `@package-name/path` syntax:\n\n```yaml\nbase_config: \"@kt-biome/creatures/swe\"\n```\n\n## Why this package matters\n\nKohakuTerrarium is flexible enough that a new user can easily end up staring at a blank config and a lot of choices.\n\n`kt-biome` solves that by answering:\n\n- what should a good default creature look like?\n- what should a safe coding-oriented creature include?\n- what kinds of plugins belong in a real package?\n- how should skills, prompts, terrariums, triggers, and I/O modules be organized?\n\nThat is why this package exists.\n\nIt is the official starting ecosystem, not just a bundle of examples.\n\n## See also\n\n- [Root README](../README.md)\n- [Getting Started](../docs/guides/getting-started.md)\n- [Creatures Guide](../docs/guides/creatures.md)\n- [Plugins Guide](../docs/guides/plugins.md)\n- [Examples](../examples/README.md)\n\n## License\n\nKohakuTerrarium License 1.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohaku-lab%2Fkt-biome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkohaku-lab%2Fkt-biome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkohaku-lab%2Fkt-biome/lists"}