tether-agent-core

Agent runtime behind the Tether desktop workbench.

Use it when you want the same local loop as Tether—model calls, workspace tools, OS sandbox, permissions, checkpoints, MCP, and session history—without shipping the Electron UI. Typical hosts are desktop shells, IDE plugins, and automation scripts.

Defaults to DeepSeek. OpenAI-compatible gateways, Ollama/vLLM-style local endpoints, and other configured providers plug in through the same client.

Requires Node.js 22.19+.

Built on Pi

This package is not a from-scratch agent. It builds on the open-source Pi ecosystem:

| Pi package | What it provides here | | --- | --- | | @earendil-works/pi-agent-core | Agent state, message streams, tool calls, thinking levels | | @earendil-works/pi-ai | Model/provider contracts, message & usage types, OpenAI API foundations | | @earendil-works/pi-coding-agent | Extension system, sessions & settings, project trust, RPC client/worker | | @earendil-works/pi-tui | Text components, themes, and terminal interaction for the CLI surface |

On top of that, tether-agent-core adds the DeepSeek-first defaults, permission modes, OS sandboxing, workspace-scoped tools, durable patch checkpoints, MCP/Hooks/Skills wiring, and the ~/.tether local data layout.

Install

npm install tether-agent-core

Auth is one of:

export DEEPSEEK_API_KEY=sk-...
# optional — OpenAI-compatible gateways, Ollama, vLLM
# export DEEPSEEK_BASE_URL=https://api.deepseek.com

import { saveDeepSeekKey } from "tether-agent-core";
await saveDeepSeekKey("sk-...");

Quick start

import { createTetherRpcClient } from "tether-agent-core/rpc";

const agent = createTetherRpcClient({ cwd: process.cwd() });

await agent.start();
agent.onEvent((event) => {
  if (event.type === "message_update") process.stdout.write(".");
});

await agent.prompt("Summarize the architecture of this repo in three bullets.");
await agent.stop();

By default the worker runs permission auto and sandbox workspace-write: it can edit files in cwd without prompting. Sessions and stored keys live under ~/.tether.

tether-agent-core exports auth/settings helpers for a GUI login flow; tether-agent-core/rpc is the bundled worker client.

What you get

• Bundled RPC worker — no separate CLI install for the host process
• Workspace tools with macOS Seatbelt; Windows sandbox helpers where available and enabled
• Permission modes, patch checkpoints (/undo-style restore with conflict checks), Skills, MCP, hooks
• Credential helpers and settings APIs for building a GUI login flow
• Durable sessions under ~/.tether by default

License

MIT. See LICENSE. Pi ecosystem dependencies keep their own licenses and copyright.