Turbinado

Turbinado brings an autonomous coding agent into a native, modern webview: it edits code, runs commands, searches the web, drives a headless browser, accepts images, and manages its own tiered memory so it keeps working across long tasks and many sessions.

It is provider-agnostic (Anthropic, OpenAI, and any OpenAI/Anthropic-compatible endpoint including local servers such as vLLM, Ollama, LM Studio and llama.cpp), cache-optimized, and designed to keep small local models on the rails.

Features

• Native VS Code UI — activity-bar view with a Codex-style chat, streaming responses, collapsible tool cards, image attachments, and a live cache/context meter. No terminal required.
• Tiered memory — a small always-resident core memory, an append-only recall log of every message and tool call, a searchable archival store, and a session evidence store for exact snippets that must survive compaction.
• Self-directed memory — the agent saves and searches its own memory: memory_save stores a durable fact and memory_search retrieves it, while supersession means a corrected fact saved under the same subject automatically shadows the older one at retrieval, and memory_forget retires a fact without losing its history. Core memory is loaded for the agent, but the harness owns it.
• Recency-aware retrieval — recent facts outrank old ones, so a memory from months ago cannot masquerade as current truth.
• Context management — warning/flush thresholds, recursive summarization, evidence-aware compaction, and a compaction loop guard.
• Tools — read, write, edit (batched edits array), list, glob, grep, bash, webfetch, web_search, todowrite, memory tools (memory_search, memory_save, memory_forget), and optional browser_* tools (Playwright).
• Quality guards — read-before-edit, write guard, token-aware read guard, malformed tool-call recovery, empty/repeat/error-loop corrections with a consecutive cap that re-arms on any clean step, per-tool recovery guidance injected into the volatile tail, a bash permission gate, a configurable turn cap with a finalize warning, a thinking-budget guard, and a "never end a turn silently" guarantee that also holds once the correction budget is spent.
• Multi-provider — browse providers and models from a built-in model registry, or point at any custom endpoint and auto-detect protocol, models and settings from the URL. API keys are optional for local servers.
• Reasoning levels — per-model reasoning controls, discovered from model metadata or probed from the endpoint, with a dropdown in the chat.
• Per-model profiles — power-user overrides (temperature, optional output cap, turn cap, thinking budget, reasoning levels, request options) stored globally. With no output cap the inference engine's own limit applies.
• Cache optimization — a stable prefix layout with explicit cache breakpoints targets very high prompt-cache reuse; a live meter shows the hit rate.
• Skills — reusable instruction bundles (SKILL.md) with progressive disclosure: only each skill's name + description sit in context, and the full body loads on demand via a skill tool.
• MCP servers — connect stdio/HTTP Model Context Protocol servers and expose their tools to the agent, scoped per-agent with approval gating.

Requirements

• VS Code 1.94.0 or newer.
• A model: a cloud API key, or a local OpenAI/Anthropic-compatible server.
• For development: Node.js 18+ and npm.
• Browser tools are optional and require Playwright + Chromium (see below).

Install

From source (recommended for now)

git clone <this-repo> Turbinado
cd Turbinado
npm install
npm run build

Then press F5 in VS Code (Run → Start Debugging) to launch an Extension Development Host with the harness loaded, or open the repo and use the Run Turbinado Extension launch configuration.

To produce an installable package:

npx @vscode/vsce package
code --install-extension turbinado-0.0.1.vsix

Configure a provider

Open the Turbinado view, click the model button, then Add provider (the ＋ in the picker):

• Browse models.dev — pick from a large registry of providers, enter an API key (optional), and choose a default model. All of the provider's models then become available in the picker.
• Local / Custom — paste an endpoint URL; Turbinado detects the protocol and fetches models and settings. Presets exist for Ollama, vLLM, LM Studio and llama.cpp. The API key is optional for local servers.

The model picker groups models by provider, is searchable, and shows details on hover (context, output, reasoning, modalities, cost). Use the ⚙ on a model to open its profile (temperature, output cap, turn cap, thinking budget, reasoning levels, request options). Profiles are stored globally.

Browser tools (optional)

Run Turbinado: Install Browser Support, or manually:

npm install playwright
npx playwright install chromium

Then enable the Browser toggle in the chat (and "Show the browser window" in Settings if you want it headful). Without Playwright installed the tools return a clear setup message instead of failing.

Using Turbinado

• Chat — type and press Enter. The agent reads/searches files, runs commands, edits code, and replies. It never ends a turn without a reply.
• Images — paste, drag-and-drop, or attach images; multiple at once.
• Model / reasoning — switch model and reasoning level from the controls below the input.
• Web search / Browser — quick toggles below the model; hidden until you hover to keep the UI compact.
• Approvals — mutating tools (write, edit, bash) prompt unless auto-approved. Read-only shell commands run directly; shell redirection and rm/sudo are refused by the permission gate.

Permissions

A mode selector next to the model controls how the agent behaves:

• Chat — read-only. write/edit/bash (and memory writes) are hidden and blocked; the agent only replies.
• Agent (default) — the agent works freely inside the workspace; commands that reach outside the workspace ask for approval.
• Autopilot — no prompts; the agent works freely inside and outside the workspace, except for the hard guards below.

Shell permissions are a blacklist, not an allowlist

• Inside the workspace the agent runs commands as it likes — rm -rf node_modules, npm run build, git rebase, … — with no allowlist.
• Outside the workspace Autopilot is allowed by default; Agent mode asks. An explicit outsideWorkspace policy of allow/deny overrides this.

Independent of mode, hard guards always apply and cannot be relaxed:

• Dangerous commands are refused everywhere — the OS/disk/boot/account destroyers: rm -rf /, rm -rf ~, mkfs, dd of=/dev/sd*, format C:, diskpart, shutdown/reboot, reg delete, sudo, chmod 777, killall, curl … | sh, fork bombs, git reset --hard, git push --force, DROP DATABASE, … A recursive delete aimed at a root, home, .., or an absolute path is blocked; deleting a relative path inside the workspace is fine.
• Secrets — secret files (.env, *.pem, .ssh, .aws, .npmrc, …) are blocked and env-dumping shell commands are refused; the shell environment is scrubbed of secrets, and known key values are redacted from tool output. Dev env templates (.env.example, .env.sample, .env.test, .env.development) stay readable.

In Settings you can extend the blacklist:

• Blocked shell commands — denied in every mode (a single word matches a whole token, a phrase matches as a substring). Use it for things like npm publish, docker push, or kubectl.
• Blocked tools — tools denied outright.

Autopilot shell tier (optional, off by default): all is the blacklist model above; safe/read-only re-enable the old allowlist for commands outside the workspace.

Sub-agents

Sub-agents run on Autopilot by default (free inside, allowed outside except dangerous/blocked commands). Set an agent's Shell permission to Agent in the agent editor to make it ask you before running commands outside the workspace.

Memory model

Turbinado layers memory so it stays useful over long horizons:

Old memories are never lost, but they do not silently become "current": search is recency-weighted and a newer fact with the same subject shadows the older one, while include_superseded reveals history. A background extraction service also records durable facts from a finished session and marks facts stale when the files they concern change.

Memory lives under VS Code's per-workspace storage so projects don't cross-contaminate. "Clear Memory" wipes recall, archival and core. The memory system is on by default; it can be switched off per-workspace in Settings, in which case the agent runs with a lean prompt and no memory tools.

Settings

Management lives in a dedicated Turbinado Settings tab (opened from the gear icon or any header button / command) rather than modals inside the chat, so the chat stays uncluttered. The tab has sections: General, Agents, Skills, MCP servers, Sessions, and Timeline.

Two levels of configuration:

• Global harness settings (gear icon → General): memory thresholds, core-memory limit, heartbeat and catalog refresh intervals, cache TTL/toggle, embeddings, allowed tools, web search/browser toggles, and the shell block-lists (blocked commands / tools).
• Per-model profiles (⚙ on a model): temperature, output cap, turn cap, thinking budget, reasoning levels, request options. The harness imposes no output cap by default — the inference engine decides. A profile's output cap is sent only when set (clamped to the model's real limit); Anthropic always receives that real limit as its required max_tokens, while OpenAI-compatible and Responses models simply omit the field. A set thinking budget is a loop-level nudge, not an abort: reasoning is never cut mid-generation. After a step that reasons past the budget and produces no content, the model is asked once to act. 0 disables the guard (off / infinite).

There are no separate project settings for the harness.

Skills

Skills are reusable instruction bundles: a directory containing a SKILL.md file (YAML frontmatter with name + description, then a markdown body). The harness keeps context lean by loading a skill's full instructions only when a task matches its description:

• Discover — Turbinado scans its managed skills folder plus ~/.agents/skills, ~/.claude/skills, and <workspace>/.turbinado/skills, so Claude-Code / OpenCode-style skills work out of the box.
• Manage — create, install (from a git URL or a local folder), or delete skills from the Skills panel (command Turbinado: Manage Skills).
• Enable per agent — pick which skills each agent sees in the agent editor, and which apply in single-model mode (the Single model section in the Agents panel).
• Loaded on demand — only each enabled skill's name + description enter the system prompt; the body is loaded via the skill tool when the agent decides to use it.
• Session-scoped — skill changes are applied when you start a new session.

MCP servers

Connect to Model Context Protocol servers and expose their tools to the agent:

• Add & test — add a stdio server (command / args / env) or an HTTP server (URL / headers), then test the connection, from the MCP panel (command Turbinado: Manage MCP Servers).
• Tools — each server's tools become agent tools named mcp__<server>__<tool>.
• Enable per agent — pick which servers each agent (and single-model mode) can use, via the agent editor / Single model section.
• Permissions — MCP tools ask for approval in Agent mode and are disabled in Chat and Autopilot; a server is arbitrary local/remote code, and its results are treated as untrusted data.
• Session-scoped — MCP server changes are applied when you start a new session.

Development

npm run build        # bundle extension (esbuild) + webview (vite)
npm run watch:ext    # rebuild extension on change
npm run watch:webview
npm run typecheck    # tsc for extension + webview + tests
npm test             # unit + behavior tests
npm run test:live    # end-to-end tests against a live model

npm run typecheck covers three projects: tsconfig.json (extension host), tsconfig.webview.json (React UI) and tsconfig.test.json (the test suite, with vscode aliased to test/vscode-stub.ts). The test project matters — without it the fixtures drift away from the real RuntimeConfig / ToolContext shapes while still bundling and "passing".

test:live uses TURBINADO_BASE_URL, TURBINADO_MODEL, TURBINADO_API_KEY, and TURBINADO_PROTOCOL (defaults target a local vLLM server at http://localhost:8000/v1). Handy debug helpers live in test/: debug-chat.ts, debug-stream.ts, and measure-context.ts.

Watching a live run (developer trace)

The harness is silent by default — a normal session pays nothing and shows nothing. When you are improving it, set one variable:

TURBINADO_TRACE=1   # analysis
TURBINADO_TRACE=2   # verbose: adds streamed deltas and full prompt dumps

Debug output goes to the VS Code "Turbinado" output channel and to a log file. The path is TURBINADO_LOG_FILE if set, otherwise <os temp>/turbinado-trace.log — outside any workspace, so the agent can never read its own trace. So the whole workflow is:

1. Launch "Run Turbinado Extension (trace)" (F5; it just sets TURBINADO_TRACE=1), or set the variable however you start VS Code.
2. Use the extension normally in whatever workspace you like.
3. Read the log — e.g. Get-Content $env:TEMP\turbinado-trace.log -Tail 50, or hand it to someone else to review.

There is also an optional standalone watcher if you want to drive the agent without VS Code (scripted runs, or a REPL), which additionally streams replies to the console:

npm run trace -- --dir /tmp/myproj                          # interactive REPL
npm run trace -- --dir /tmp/myproj --fresh                  # wipe memory first
npm run trace -- --dir /tmp/myproj --prompt "add a test"    # one-shot
npm run trace -- --dir /tmp/myproj --context 16000          # force compaction
npm run trace -- --dir /tmp/myproj --log /tmp/run.log       # tee the whole run
npm run trace -- --dir /tmp/myproj --prompt-file prompts.txt
#   :stats  :memory  :cancel  :quit

--prompt-file takes one prompt per non-empty line (# comments ignored) and avoids shell quoting; keep --log outside --dir.

Trace lines look like this, and end each turn with the health line:

[trace:request] built messages=6 history=5 tools=20 systemTokens=933 tokens=3753 pressure=normal breakpoints=1,2,4 tail=memory
[trace:gate] allowed tool=bash
[trace:tool] call name=bash input={"command":"node --test"}
[trace:tool] ok name=bash ms=204 outChars=211 out=exit code: 0\n✔ greets a name (0.75ms)\nℹ pass 3
[trace:usage] response in=2865 out=89 cacheRead=1600 cacheWrite=0 hit=0.381
[trace:summary] turn done ms=9108 requests=4 in=10824 out=794 cacheRead=6400 cacheHit=37.2% ctx=4026/32000 (12.6%) pressure=normal corrections=0 toolErrors=0 recall=8 archival=0 pinned=0 core=persona 21/2000, human 23/2000 tokens

What to watch for a healthy run: ctx climbs and drops on a flush, pressure rarely reaches flush, cacheHit is high and stable, requests per turn is single digits, corrections/toolErrors are near zero, and no [trace:compact] PAUSED line.

RuntimeConfig requires only a provider, a model and a workspace; every policy and limit field is optional and resolved from RUNTIME_DEFAULTS in src/agent/runtime.ts. Shared fixtures live in test/harness.ts.

Project layout

src/agent/            agent runtime, providers, cache, quality, memory, tools
src/webview/          VS Code webview host + protocol glue
webview/              React UI
shared/               shared types between host and UI
test/                 unit, behavior, live and debug tests

Releasing

Publishing is automated by GitHub Actions:

• .github/workflows/ci.yml runs on every push to main and every PR: typecheck, the full test suite (including the recorded-session replay), and the duplication gate. A failure here blocks the release.
• .github/workflows/release.yml runs on every push to main. It re-runs the CI gate, bumps the patch version, commits that bump back to main with [skip ci], packages with vsce, publishes to the VS Code Marketplace, attaches the .vsix to a GitHub Release, and (if an OVSX_PAT secret is set) publishes to Open VSX.

The workflow uses the Marketplace’s GitHub OIDC trusted publishing, so no PAT is stored in the repository or in GitHub secrets for the VS Code Marketplace.

One-time setup:

1. Create a publisher at https://marketplace.visualstudio.com/manage whose id matches publisher in package.json (turbinado). Use a Microsoft account.
2. In that publisher, open Trusted Publishing, create a policy for:
   • Repository owner: Napsterae
   • Repository: Turbinado
   • Workflow: release.yml
   • Environment: leave empty
3. In GitHub, allow Actions to write to main: Settings → Actions → General → Workflow permissions → Read and write, and allow the Actions bot to push if main is protected.
4. Optional Open VSX: create a publisher at https://open-vsx.org, add an access token as the repository secret OVSX_PAT (not a variable), and make sure the Open VSX namespace matches publisher.
5. Replace media/icon.png (a 128×128 placeholder) with the real logo.

main is the release branch. The repository currently has an unrelated master history, so make main the source of truth before enabling the workflow.

Package locally without publishing with npm run package.

License

MIT.

Credits

Turbinado is an independent implementation, but its design was inspired by two excellent works:

• MemGPT: Towards LLMs as Operating Systems — the paper that introduced virtual context management, tiered memory and self-directed memory editing for LLMs. https://arxiv.org/abs/2310.08560
• little-coder — a coding agent tuned for small local models, which demonstrated many of the small-model guard and workflow mechanisms used here. https://github.com/itayinbarr/little-coder

Relationship to the paper

The tier names (main context = system instructions + working context + FIFO queue; external context = recall + archival storage), the memory-pressure warning, the flush with a recursive summary, paginated retrieval, and the request_heartbeat chaining flag all come from the paper (§2.1–2.4). The function names (core_memory_append, send_message, pause_heartbeats, …) come from the MemGPT reference implementation, which the paper points to rather than specifies.

Deliberate deviations:

• Flush threshold is 90%, not 100% of the window. A request has to be sent, so compaction must happen before the window is full.
• Eviction is ~50% of the message count, where the paper describes ~50% of the context window. Both are given as examples in the paper ("e.g.").
• Tool calls chain by default; an absent request_heartbeat yields only after send_message. The paper yields on an absent flag. For a coding agent that produced far too many premature stops.
• Supersession (a newer memory_save under a matching subject) and recency-weighted ranking are additions: the paper's archival store is append-only with no notion of a fact going stale.
• conversation_search_date is not implemented.