thClaws: a native-Rust agent harness with four surfaces and one binary

What thClaws solves, and who it is actually for

Most agent tooling forces a choice early. A terminal tool is convenient over SSH but useless for reviewing a diff visually. A desktop app is pleasant locally but cannot run in CI. A hosted service works everywhere and sends your code everywhere with it. thClaws is an attempt to collapse that choice: the README states that the same `Agent` loop, `Session` and `ToolRegistry` back every surface, and that everything ships in one binary. The four surfaces are the desktop GUI (`thclaws`), the CLI REPL (`thclaws --cli`), a non-interactive single-turn mode (`thclaws -p "prompt"`) that the README describes as pipe-friendly for scripts and CI, and a webapp started with `thclaws --serve --port 7878`.

The intended user is a developer who already runs agents against a real codebase and wants the harness on their own machine. The README frames this as "sovereign by design". That is marketing language, but the underlying claim is checkable: provider keys live in your environment, session state is written under `.thclaws/`, and the webapp is something you host yourself. The project is developed by a small team at ThaiGPT Co., Ltd., with the README noting that a meaningful chunk of the codebase comes from outside contributors. It started in April 2026 and the last push to `main` was on 2026-08-29, with v0.117.0 tagged the same day. That is a fast-moving project, not a settled one.

One engine, four front ends: how the pieces fit

The architecture claim is that surfaces are thin and the engine is shared. Practically, that means a skill you write for the GUI also loads in the REPL and in `--serve`, because tool registration happens in the same `ToolRegistry` regardless of which front end started the process. The README's four-surface list is the clearest statement of this, and the Dockerfile corroborates the shape of the build: a Vite and React frontend stage produces `dist/`, a Rust stage runs `cargo build --release --features gui --bin thclaws`, and a Debian slim runtime carries the binary.

Extension happens through files rather than Rust code. `AGENTS.md` carries project instructions, `SKILL.md` with YAML frontmatter defines packaged workflows, and plugins bundle skills, commands, agent definitions and MCP servers under one manifest. MCP servers arrive over stdio or HTTP-Streamable with OAuth 2.1 and PKCE. Hooks fire shell scripts on lifecycle events the README names as `pre_tool_use`, `permission_denied` and `session_start`.

Orchestration is where the design gets interesting and harder to reason about. There are three tiers: the model-driven `Task` tool for subagents, blocking and up to three levels deep; user-driven side channels via `/agent <name> <prompt>` that run in parallel to the main loop with their own cancel token; and multi-process Agent Teams with a shared mailbox, task queue, tmux panes and optional git worktrees. Three mechanisms for concurrency in one binary is a lot of surface area, and the README does not describe how they interact when you use two at once.

Installing thClaws and running a first non-interactive prompt

The README points to https://thclaws.ai/downloads.html for downloads and to the manual at https://thclaws.ai/manual. The repository also ships a Dockerfile and a docker-compose.yml, and the compose file is the most concrete install path available because it documents its own assumptions inline.

The compose file expects a `.env` alongside it holding whichever provider keys you want available inside the agent, naming `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and `GEMINI_API_KEY` as examples. Its header comments describe the sequence: drop the `.env`, change into your project directory, then run `docker compose up` or `docker compose up -d` to detach, and open http://localhost:8443 in your browser. After startup the current directory is mounted at `/workspace` and the agent treats that as its project folder, writing session, plan and team state to `./.thclaws/` on the host. The default bind is `127.0.0.1:8443`, so the port is reachable only from the host machine. The compose comments also note that if you pin a Compose version older than 2.24, the workaround for the optional `env_file` is to `touch .env` before `up`.

For a local binary rather than a container, the single-turn mode is the quickest way to confirm the engine works before you commit to a GUI session:

thclaws -p "prompt"

The README states that `-p` runs a single turn and exits, and that adding `-v` prints token usage on stderr. That makes the pair usable in a pipeline where you want the answer on stdout and the cost on stderr. The README does not document an install command for the binary itself beyond the downloads page, so treat the download page as the source of truth for platform packages.

The container image is heavier than a headless server needs

The Dockerfile is unusually candid about a real cost. It notes that the `gui` feature pulls in tao, wry, comrak, rfd and native-dialog, and that although `--serve` never opens a window, the binary is dynamically linked to those libraries, so GTK and WebKit2GTK must be present in the runtime image. The comment states plainly that a future refactor gating `--serve` independently of `gui` would let the project drop those and shrink the image significantly.

For anyone deploying the webapp to a small VM or a CI runner, that is the whole trade-off in one paragraph. You are shipping a desktop toolkit's shared libraries to serve HTTP and WebSocket traffic. It works, and the compose file sets the bind address safely by default, but the image size and the attack surface are larger than the feature set requires. The Dockerfile also warns that the container has no application-level auth, so the README's advice to SSH-tunnel rather than open a port is not optional caution. It is the only access control the image ships with.

Where thClaws is the wrong tool

The version number tells you a lot. This is v0.117.0. The README itself sets v1.0 as a future milestone, describing the target as "the multi-platform agent" with bridges into Telegram, Discord, Slack, WhatsApp, Facebook Messenger and LINE, of which Telegram, LINE and Messenger are said to be shipping while Discord, Slack and WhatsApp are next. A project that ships roughly a release a week and has not reached 1.0 is not a stable platform to build an internal toolchain on top of, and the README does not promise configuration or plugin API stability across releases.

The knowledge base design is another deliberate constraint. The README describes KMS wikis stored under `.thclaws/kms/<name>/pages/`, indexed by a one-line `index.md`, and states that retrieval is grep plus read with no embeddings, following what it calls Andrej Karpathy's LLM-wiki pattern. That is a defensible choice for small, curated wikis where exact string matching is enough. It is the wrong tool for a large corpus where you need semantic recall, and no configuration flag turns embeddings on.

Finally, the README does not document rollback, downgrade or migration between releases. If you pin v0.117.0 and later need to move, there is no procedure. That absence is worth weighing against the weekly release cadence.

How thClaws differs from Claude Code

The comparison the README invites is with Claude Code, and the difference is not the agent loop so much as the deployment shape. The README lists Anthropic as a provider in two forms, native and via the Claude Agent SDK using Claude Code auth, which means thClaws can consume the same credentials. What differs is what wraps the loop. Claude Code is a terminal tool tied to one vendor's models. thClaws is a Rust binary with a desktop window, a webapp, an OpenAI-compatible slot listed as `oai/*` for LiteLLM, Portkey, Helicone, vLLM or internal proxies, and a provider list that runs from Anthropic and OpenAI through Gemini, DashScope, DeepSeek, Z.ai, NVIDIA NIM, NSTDA Thai LLM, OpenRouter, Azure AI Foundry, Ollama and LMStudio. Switching happens mid-session with `/model` or `/provider`.

The interesting contrast is where the extension points live. Claude Code users extend through configuration and MCP. thClaws adds `SKILL.md` folders, plugin manifests bundling skills with commands and agent definitions, and lifecycle hooks firing on `pre_tool_use` and `permission_denied`. If your work is already standardised on `AGENTS.md` and MCP, the portable parts move with you. If you depend on a vendor-specific feature, the portability argument cuts the other way, because a generic harness exposes the intersection of what its providers support, not the union.

Licence and the cost of keeping up

The repository root holds both LICENSE-APACHE and LICENSE-MIT, and the project is described as Apache-2.0. The presence of two licence files suggests a dual-licensed arrangement rather than a single Apache-2.0 grant, and the repository does not spell out which terms apply to which parts of the tree. That is a question for whoever reviews licences in your organisation, not something to infer from a README line. Apache-2.0 carries an explicit patent grant and notice requirements, which matters if you redistribute a modified binary.

Upgrade cost is the practical concern. The release list shows v0.115.0 on 2026-08-19, v0.116.0 on 2026-08-25 and v0.117.0 on 2026-08-29, roughly a release every six days across that window. A project moving at that rate will keep adding providers, tools and surfaces, and the README's own v1.0 roadmap names three messaging bridges still to come. Budget for reading the CHANGELOG.md at each bump rather than assuming compatibility, and pin a version if you are wiring thClaws into anything automated. The repository does not describe a long-term support branch or a deprecation policy.

Editorial conclusion

Adopt thClaws if you want one Rust binary that covers GUI, CLI, headless and a browser surface, and you are comfortable reading a manual that is still filling in. Skip it if you need a stable v1.0 API, a managed cloud, or a container image that is not carrying GTK and WebKit2GTK for a headless process. Before committing, verify three things on your own machine: that your provider key works under the surface you actually intend to use, that the Docker image pulls and starts on port 8443, and that your organisation is satisfied with the Apache-2.0 and MIT split recorded in LICENSE-APACHE and LICENSE-MIT.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes