al3x4kov/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 • Tour • 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.
• A task survives a usage limit. When a subscription runs out mid-task, hand the chat over to another engine or model: same folder, one feed, and the new engine receives the turns it missed.
• 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/

A quick tour

All screenshots are taken from npm run demo — what you see is what you get.

Chats Every chat is bound to an engine, a model and an agent. Claude Code chats are marked.	Subagents When an agent delegates, each run is a card: who, what for, how long, how many steps and tokens.	Inside a run Open a card to see the subagent's steps and its answer, or jump to its own chat.	Relay Hit a usage limit? The same chat continues on another engine — one feed, with a handoff mark.
Pick where to continue From the chat menu at any time, or straight from the limit notice. The folder stays the same.	Subscriptions Usage and remaining quota per connected provider, where it reports them through an official API.	Steps and files Reasoning, tool calls with output, and result files as cards with preview and download.	Light and dark Follows the system theme or your choice; built for one-handed use on a phone.

_{The same UI on a desktop: Claude Opus did the first half, GLM-5.3 picked the task up after the handoff.}

_{A Claude Code chat in the dark theme.}

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, the handoff between engines. One adapter per engine: a client for opencode serve (1.x and 2.x) and a runner that starts claude per turn.
• Harness — everything around the CLI: agents and orchestration (oh-my-opencode-slim), the knowledge-base and sandbox plugin for opencode (ops/opencode/plugin-v2 for 2.x, vault-cache.ts for 1.x), 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; also holds the per-chat journal an engine reads after a handoff.
• 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.