RingKo Harness

A provider-neutral Agent Harness for coding agents.

English | 简体中文

RingKo is an Agent Harness. It runs a model against a workspace through a gated
tool registry and an append-only session log. It ships with a terminal UI and a
browser UI; both use the same local server.

Run

Node.js 24+ and Bun 1.2+ must be on PATH. The published executable is a Bun
bundle, so Bun is not optional.

npm install -g @ringko-ai/rkh
ringko          # terminal UI (default)
ringko serve    # browser UI, prints its URL (port 8787)

ringko help lists all commands. npx @ringko-ai/rkh runs the terminal UI
without a global install. Prereleases publish under the next tag:
npm install -g @ringko-ai/rkh@next.

From a checkout:

pnpm install
pnpm dev:tui    # terminal UI
pnpm build      # code, tui and webui

Features

• Tools. read, write, edit, glob, grep, tree, shell,
  webfetch, websearch, ask, plan, update_plan, task and job.
  read handles text, images, PDFs and notebooks.
• Approval. Every tool call is risk-classified, and risky calls wait for the
  host. With no approval handler they are denied. Network and shell tools are
  registered separately from workspace tools.
• Sandbox. read-only, workspace-write or danger-full-access. Linux uses
  bubblewrap, macOS Seatbelt, and Windows a restricted token with a job object.
• Sessions. Append-only JSONL. Resume, fork, or inspect events in the
  trajectory view. Usage statistics are available in the Web UI; see
  Usage statistics for data semantics and limits.
• Delegation. Subagents run in read, write or full mode with separate
  context and an optional model. They can run in the background, be cancelled,
  and report progress in the TUI, Web UI and ringko run.
• Context. Automatic and manual compaction, AGENTS.md instructions
  reloaded before every request, skills, and MCP servers.
• Providers. Any AI SDK model. Thinking levels map to each provider's own
  field, and missing model limits are filled from Models.dev.

Shared sessions

ringko and ringko serve start or reuse one backend per workspace/config pair
and register it under ~/.ringko/backends/. Open the printed URL in a browser,
then select the same session in both clients with ringko -s <id>. Messages,
tool activity, approvals, questions, plans and running state stay in sync. A
second serve for the same pair prints the existing URL; a concurrent submit to
a busy session returns HTTP 409. Disconnecting a client does not cancel a run.

ringko run, ringko loop and embedded REPL hosts still execute locally. Do not
point them at a session another backend is writing.

Sandbox

Execution defaults to workspace-write.

{
  "sandbox": {
    "mode": "workspace-write",
    "additionalWritableRoots": []
  }
}

read-only denies persistent writes. workspace-write allows the workspace and
extra roots. danger-full-access removes those limits. Missing runners fail
closed. Local MCP, explicit REPL commands, file writes and Git review follow the
same policy; remote MCP needs endpoint-bound grants in host settings. See
Sandbox for platform details and remaining limits.

Sessions and tasks

A session is an append-only event log. task runs a subagent with independent
context; write auto-approves workspace edits and full opens every capability
the parent has. ask renders a question in the TUI or Web UI. plan reads the
session plan and update_plan replaces it.

The trajectory view shows user, model, assistant, tool, task, compaction and
session events. Its API returns up to 50 events per page; the browser keeps the
latest 1,000 events and caps an event's detail at 32,768 characters. Full records
stay in the session JSONL.

Configuration

RINGKO_HOME and AGENTS_HOME override the home directories. Inspect them with
ringko config show, ringko skills, ringko mcp and ringko session list.

Providers are selected through configuration. The built-in provider module ships
with the CLI; a custom module is imported at run time. Custom OpenAI-compatible
endpoints use the same file:

{ "provider": { "name": "openai", "model": "gpt-4o-mini" } }

Thinking levels map to Anthropic thinking/effort, Google thinkingConfig,
OpenAI reasoningEffort, and the matching provider-options key for compatible
endpoints. Explicit contextWindow, maxInputTokens and maxOutputTokens
override catalog values; unmatched models use a 128,000-token working window
with a 4,096-token output reserve. Models.dev metadata is cached under
~/.ringko/cache/.

Runtime-managed agents reload global and project AGENTS.md (or project
CLAUDE.md) before each main-model request, including after compaction. Limits
are 256 KiB per file, 1 MiB total, and 64 files. Unreadable or oversized files
fail the request. MCP configuration cannot change while a session is running.

Development

Use the latest Node.js 24 LTS patch, pnpm and Bun. CI resolves the current patch
on every run. A version tag matching packages/tui/package.json publishes
@ringko-ai/rkh after the release checks pass; see the
npm release setup.

pnpm test          # every workspace package
pnpm build         # code + tui + webui

The npm package bundles the CLI, built-in providers and the WebUI. Its browser
terminal uses node-pty. See unreleased changes.

Documentation

• Configuration
• MCP servers
• Providers
• Sandbox
• Usage statistics

Package READMEs document each package's API and behavior. This README and
README.zh-CN.md are the top-level reference; the English
version wins if they disagree.

License

Apache-2.0 - Copyright 2025-2026 KaguyaRing (RingKoAI)

Star History