teleharness

Run Claude Code and opencode on your own machine and drive them from any browser.
You don't chat with a bare model: every message goes through a real agent CLI, with its agents,
skills, MCP servers, hooks and an Obsidian vault as long-term memory.

Try the demo •
Features •
Quick start •
Architecture •
Configuration •
Contributing •
Русский

Why Teleharness

Chat apps give you a model. Agent CLIs give you much more — tools, file access, subagents, skills,
MCP servers, hooks, project memory — but they live in a terminal on your desk.

Teleharness puts a mobile-first web UI in front of those CLIs, so the full harness is one tap away:

• CLIs, not models. Each chat runs through opencode serve or the claude CLI. Whatever you have
  configured there — agents, skills, plugins, MCP — works from your phone.
• Many providers through one portal. opencode talks to Z.ai GLM, OpenAI, Google Gemini, Anthropic,
  OpenRouter, local models and more; Claude Code brings your Claude subscription. Pick the engine and
  model per chat.
• Memory that outlives a chat. An Obsidian vault works as an active cache: agents get a snapshot
  of your notes at the start of a chat and leave a digest after each turn.
• Your machine, your data. Files, tools and history stay on your server. Providers only see the
  prompts and tool results needed for inference.
• Share it safely. Multiple users with their own folders, quotas and system prompts; on Windows
  their commands run in an AppContainer sandbox.

Try it in 30 seconds

No engines, no API keys — the UI on synthetic chats:

git clone https://github.com/al3x4kov/teleharness.git
cd teleharness
npm ci
npm run demo     # → http://127.0.0.1:4171/zai/

Features

Quick start

Requirements

You need at least one of the two engines.

Install and run

git clone --branch v1.19.2 https://github.com/al3x4kov/teleharness.git
cd teleharness
npm ci && npm run build

cp .env.example .env               # every value is optional

# engines (you need at least one)
opencode auth login                # add the providers you want
claude setup-token                 # Claude engine: put the token into .env as CLAUDE_CODE_OAUTH_TOKEN

./ops/opencode/serve-v2.sh &       # opencode 2.x on 127.0.0.1:4196, password in ~/.zai/oc2-password
./ops/web-v2.sh                    # → http://127.0.0.1:4170/zai/

git clone --branch v1.19.2 https://github.com/al3x4kov/teleharness.git
cd teleharness
npm ci; npm run build

Copy-Item .env.example .env        # every value is optional

opencode auth login
claude setup-token

# opencode 2.x with HTTP Basic auth; the portal gets the same password
$env:OPENCODE_SERVER_PASSWORD = [guid]::NewGuid().ToString('N')
Start-Process opencode -ArgumentList 'serve','--hostname','127.0.0.1','--port','4196'

$env:ZAI_OC_API = 'v2'; $env:ZAI_UPSTREAM = 'http://127.0.0.1:4196'; $env:ZAI_OC_PASSWORD = $env:OPENCODE_SERVER_PASSWORD
node server.js                     # → http://127.0.0.1:4170/zai/

Step-by-step for a Mac, including launchd services and phone access: docs/macos.md.

On first start the portal creates an admin and writes the login token to data/admin-token.txt
(or uses ZAI_ADMIN_TOKEN). To reach it from your phone, put it behind TLS — the bundled edge server
(ops/portal-server.js) or any reverse proxy (Caddy, nginx, Tailscale Serve).

[!NOTE]
zai is the project's original codename. It stays in the URL path (/zai/), environment variables
(ZAI_*) and storage keys so existing installs keep working.

Platform support

On macOS and Linux shell access for regular users is refused (fail-closed); admins are not affected.
User isolation is moving to one container per user with the full agent runtime — the same on every host OS —
so the Windows sandbox is intentionally not ported to other systems.

Architecture

• Portal (server.js) — API, auth and users, the event hub, chat-to-engine binding. One adapter per
  engine: a proxy to opencode serve and a runner that starts claude per turn.
• Harness — everything around the CLI: agents and orchestration (oh-my-opencode-slim), the
  vault-cache.ts plugin, Claude Code hooks, skills, MCP servers. This decides what an agent can do and
  what it knows.
• Obsidian — long-term memory for agents, one zone per user.
• Voice — a separate local Python process (Piper TTS, GigaAM STT).
• Sandbox — Windows AppContainer for other users' commands.

More: docs/architecture.md (in Russian), requirements in openspec/specs/.

Configuration

Everything is configured with environment variables; the schema with types, defaults and validation is
lib/config.js, the template is .env.example.

Agent configs

config/ holds the author's Claude Code and opencode setup as a working example —
agents, prompts, the vault-cache plugin, document skills. Install with ./config/install.sh
(macOS/Linux) or ./config/install.ps1 (Windows); secrets are taken from the environment.
The configs contain absolute paths — review them before use.

Third-party skills are not bundled; install them from their sources:
agent-skills (/plugin marketplace add addyosmani/agent-skills),
OpenSpec (npm i -g @fission-ai/openspec).

Development

npm test                 # unit, UI components (happy-dom), server and edge tests
npm run build            # esbuild → public/app.js, public/app.css
npm run demo             # mock mode on fixtures-demo/

See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

Built with

opencode · Claude Code ·
oh-my-opencode-slim · Preact ·
esbuild · marked · DOMPurify ·
highlight.js · Piper · sherpa-onnx

License

MIT. Bundled third-party files keep their licenses: openspec-* / opsx-* skills and
commands — MIT (OpenSpec), the dogfood skill — Apache-2.0.