Skip to content
Projects

vincemakes/kiso has 96 GitHub stars and 10 forks. GitHot measured 0 stars in 24 hours, +8 in 7 days, and +13 in 15 days. Last checked 2026-11-15 16:28 UTC. Last push 2026-11-15.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
+8
in 15 days
+13
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

The durable runtime for AI agents: event-sourced sessions, approvals that persist across processes, exact resume after a crash. A 2,200-line TypeScript kernel, and kiso-code, the coding agent built on it.

AI

README.md

Original

kiso

kiso is a durable agent runtime with a kernel capped at 2,200 lines,
and a coding agent for your terminal built on it.

npm CI MIT license

v0.53.0 · Node ≥ 22 · kiso.work · 简体中文

Built in, not bolted on: it asks before it guesses; subagents in parallel; background tasks; approval modes; it resumes after a crash; yours to extend.

kiso in a dark terminal window: a green diff of new tests, then the test suite started as a background task, with 1 task running in the status row

Install

npm install -g @vincemakes/kiso-code
kiso

Node ≥ 22 on macOS or Linux. Or run it without installing: npx @vincemakes/kiso-code. The first run needs no key: kiso plays a scripted demo turn, so you see the shape before anything is spent, then asks you to connect a model.

kiso login deepseek      # or anthropic / openai / zai
kiso login chatgpt       # a ChatGPT subscription: a browser sign-in, no key
kiso login --endpoint https://gateway.example/v1   # a gateway: its key, sent to it alone

Keys never go in the config file. Profiles, effort levels, context windows and every other option: docs/configuration.md.

kiso web

The same agent in the browser, on this machine: a local web app with a stream of each run, its changes and files beside it, and the history of every folder's work. It is its own package, beside the terminal's:

npm install -g @vincemakes/kiso-web
kiso web

kiso web starts the host and opens the page at http://127.0.0.1:4317 (--port <n> for another, --no-open to print the address instead). The host must be running for the page to work: it runs while the command runs, and with the command stopped the page cannot load. The model, the effort and the sign-in are the terminal's own (~/.kiso/config.json, kiso login). Without the package installed, kiso web prints the install command.

To keep it on the desktop, open the page once and add it as an app: Safari (macOS Sonoma or later), File > Add to Dock; Chrome or Edge (macOS or Linux), Install page as app. The port is fixed, so the app keeps its address; start kiso web before opening it. kiso web runs on macOS and Linux; Windows is not supported yet.

Sign-in is local: the command opens the page on a one-time code, which the page trades for a session cookie. A signed-in session is a key to this machine's shell: whoever holds it can run commands as you. The host listens on 127.0.0.1 only. kiso web --revoke-sessions signs every page out; each signs in again from the command.

Under the hood

  • It picks up where it left off. After a crash, a kill -9 or a closed terminal, kiso resume continues from the durable committed prefix: generation still streaming when it died is regenerated, and a side effect whose outcome is unknown goes to a human rather than being repeated.
  • Long tasks don't overflow. Past half the window, kiso compacts at the end of a phase, and each new summary replaces the last instead of piling up.
  • Any model you have. DeepSeek, Claude, GPT, a ChatGPT subscription, and any OpenAI-compatible endpoint or gateway.
  • You can see where it goes. Each turn ends with its fresh input, output and cache hits; /context shows what fills the context.
  • Small and inspectable. The kernel is capped at 2,200 lines (2,194 of 2,200 today); a session is a JSONL log you can read; every design decision is one of 46 ADRs, with why, and when to overturn it.

Keys, commands and the status row: docs/cli.md. ? shows the keys in a session and /help lists the commands. ctrl+v attaches the clipboard image on macOS; elsewhere, put the image's path in your message.

Approval modes

/mode or shift+tab switches; the status row always names the mode.

mode does
default reads and read-only shell run; writes, edits and other shell ask
accept-edits default, and edits run too (except into .git/ or .kiso/)
plan reads only; everything else is refused
full-access everything runs without asking — a user deny and the floor still hold

A mode is one voice in a deny > allow > ask chain, so a saved "don't ask again" rule still allows under any mode: switching modes is not a revocation. The rules live in ~/.kiso/extensions/dont-ask-again.mjs; delete one to be asked again. In every mode, full access included, a destructive command aimed at what cannot be recovered — /, your home directory, the workspace root, its .git, ~/.ssh and the like — is refused. The full rules: docs/cli.md.

Extensions

An extension is a plain .mjs file — no build step. Five ship built in: MCP, skills, subagents, ask and task. Writing your own: docs/extensions.md.

Which children are stripped. The two a model can cause to run — the shell tool and an MCP server started over stdio — lose provider credentials: the known key variables, anything ending _API_KEY or _AUTH_TOKEN, and every variable a profile names in apiKeyEnv. NOT stripped: a subagent's child (it is kiso itself and must reach the model) and the programs you start yourself ($EDITOR, the sign-in browser, kiso update), which inherit your environment.

Using it

The agent is built on @vincemakes/kiso-runtime: a durable, append-only session store, an agent factory and a typed event stream.

import { defineTool } from "@vincemakes/kiso-core";
import { createAgent, SessionStore } from "@vincemakes/kiso-runtime";
import { createAnthropicAdapter } from "@vincemakes/kiso-provider-anthropic";
import Anthropic from "@anthropic-ai/sdk";

const agent = createAgent({
  model: "claude-sonnet-5",
  tools: [
    defineTool({
      name: "add",
      description: "Add two numbers",
      parameters: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"], additionalProperties: false },
      execute: async ({ a, b }) => ({ content: String(a + b), isError: false }),
    }),
  ],
  store: new SessionStore("./sessions"),          // append-only JSONL
  adapter: createAnthropicAdapter(new Anthropic()),
});

const session = await agent.session({ id: "demo" });
for await (const ev of session.run("What is 2+3?")) {
  switch (ev.type) {
    case "text_delta": process.stdout.write(ev.text); break;
    case "terminal": console.log("\n", ev.outcome.kind); break;
  }
}

Getting started with the SDK: docs/getting-started.md.

Documentation

Start cli-quickstart.md · getting-started.md
Reference cli.md · configuration.md · extensions.md · sdk.md
Design durability.md · context.md · architecture.md · kernel-rule.md · ADRs
Status status.md · bench/README.md

License

MIT