kai-agents

A simple OpenCode plugin used at Gleap. Adds an interview-driven planner, a plan reviewer, a read-only code explorer, and a builder agent that uses hash-anchored edits and a session-wisdom notepad.

Built for Kai Code, our coding agent product. MIT-licensed; use it however you like.

Install

node node_modules/kai-agents/scripts/install.mjs --to <workdir>

This drops four agent definitions, two markdown templates, and a self-contained custom-tools plugin into <workdir>/.opencode/:

<workdir>/.opencode/agents/kai-planner.md
<workdir>/.opencode/agents/kai-plan-reviewer.md
<workdir>/.opencode/agents/kai-explore.md
<workdir>/.opencode/agents/kai-builder.md
<workdir>/.opencode/templates/plan-template.md
<workdir>/.opencode/templates/wisdom-template.md
<workdir>/.opencode/plugins/kai-tools.mjs       (self-contained bundle)

OpenCode auto-loads files placed in .opencode/agents/ and .opencode/plugins/ — no opencode.json mutation required.

The install is idempotent — it compares file hashes and only writes when something changed.

You can also call it programmatically:

import { installInto } from "kai-agents";
await installInto("/path/to/workdir");

Inside Kai Code

The cloud Coder pipeline (gleap_code_analyzer) runs installInto() automatically as part of every E2B sandbox boot — no manual step required.

For the local Kai Code desktop app, run the install command above once per workspace you open. The agents and plugin persist in .opencode/ so OpenCode picks them up on every subsequent boot.

What it ships

Agents (in <workdir>/.opencode/agents/)

| Name | Role | | ------------------- | ------------------------------------------------------------------ | | kai-planner | Interview-driven planner. Writes plans to .opencode/plans/*.md. | | kai-plan-reviewer | Validates a plan is executable. Returns APPROVED or REJECTED. | | kai-explore | Read-only codebase search specialist. Used as a research subagent. | | kai-builder | Implements the plan using the hash-anchored edit tools. |

Custom tools (registered as the kai-tools plugin)

| Tool | Purpose | | --------------------- | ---------------------------------------------------------------- | | kai_read | Reads a file, tags every line with a content hash (12#A7\| …). | | kai_edit | Edits by referencing line IDs; rejects on stale hashes. | | kai_wisdom_read | Reads <workdir>/.kai/wisdom.md (session-scoped notepad). | | kai_wisdom_append | Appends a one-line bullet under convention / gotcha / decision. |

Templates (in <workdir>/.opencode/templates/)

• plan-template.md — The structured plan skeleton kai-planner writes against.
• wisdom-template.md — The session wisdom notepad layout.

Hashline format

kai_read returns each line prefixed with a stable identifier:

12#A7| const planText = await read(path);
13#K9|   if (!planText) return "";
14#M2| }

• 12 — line number (1-indexed).
• A7 — first 2 characters of sha1(line_text_without_trailing_newline).
• | — separator. Display only; the model only types the 12#A7 form.

kai_edit accepts these IDs in operations like replace, replace_range, delete, insert_after, and append. If a referenced ID's hash no longer matches the current file content, kai_edit returns a HashlineMismatchError with the current IDs so the model can re-read and retry.

Wisdom format

# Session wisdom

## Conventions
- (one-line bullets appended by kai_wisdom_append)

## Gotchas
- (one-line bullets appended by kai_wisdom_append)

## Decisions
- (one-line bullets appended by kai_wisdom_append)

Wisdom is per-session — Kai Code's runner deletes .kai/wisdom.md at session start, so each task starts with a fresh notepad.

Maintenance

• All agent prompts live in agents/*.md — diff in PRs, no rebuild needed.
• Plugin code is one TypeScript file per tool plus a shared hashline.ts. Build with npm run build.
• npm run smoke drives each agent against canned prompts and diffs the output against golden expectations — catches prompt regressions before they ship.

Intent buckets used by kai-planner

| Bucket | Example | Interview rounds | | ----------------- | ---------------------------------- | ---------------- | | trivial-question | "where is X?" | 0 | | bug-fix | "fix off-by-one in pagination" | 0–1 | | small-feature | "add a CSV export to the X view" | 1 | | refactor | "untangle the auth middleware" | 1–2 | | new-system | "build us a billing dashboard" | up to 3 |

Hard cap: 3 interview rounds across all intents.