thClaws

Positioning#

thClaws targets developers and knowledge workers who need highly controllable, local-first AI assistance. It addresses pain points in multi-model access, agent orchestration, and toolchain integration. Its capabilities are explicitly scoped to local-first execution, with KMS using grep + read instead of vector embeddings, and sub-agent recursion capped at 3 levels.

Core Capabilities#

Model & Interaction Modes#

• Multi-model provider support: Anthropic, OpenAI, Gemini, Alibaba DashScope, OpenRouter, Ollama (local), and generic OpenAI-compatible endpoints (LiteLLM / Portkey / Helicone / vLLM). Auto-detection by model name prefix with in-session switching.
• Three interaction modes: ① Desktop GUI (thclaws) with Terminal/Chat/Files/Team tabs; ② CLI REPL (thclaws --cli); ③ Non-interactive single execution (thclaws -p "prompt") for scripts and CI.

Orchestration & Memory#

• Agent orchestration: Task tool delegates subtasks to isolated child agents (max 3-level recursion); Agent Teams enable multi-process coordination via shared mailbox and task queue, each with independent tmux panes and optional git worktrees.
• Memory system: Persistent storage categorized as user/feedback/project/reference, stored as editable Markdown files.
• Knowledge Bases (KMS): Project-level and user-level Wikis searchable by agents on demand. Uses grep + read (no vector embeddings), following Karpathy's LLM-wiki pattern.

Extensions & Tool Integration#

• MCP server integration: Supports stdio and HTTP Streamable transports with OAuth 2.1 + PKCE authentication. Connects to GitHub, filesystem, databases, browsers, Slack, etc.
• Skills system: Reusable expert workflows (SKILL.md + optional scripts) with whenToUse trigger auto-matching or manual /skill-name invocation. Installable from git URLs or .zip archives.
• Plugin system: Packages Skills + Commands + Agent Definitions + MCP Servers into a single manifest for one-click install/uninstall.

Security & Privacy#

• Security sandbox: Filesystem sandbox restricts file tools to working directory; destructive shell commands require confirmation; all changes need user approval (unless auto-approve is enabled).
• Offline execution: Fully local operation via Ollama without cloud APIs.
• Shell Escape: ! prefix in REPL executes shell commands directly with zero token consumption.
• Open standards: Adopts MCP (tool protocol), AGENTS.md (project instructions), SKILL.md (YAML frontmatter).

Architecture#

• Monorepo structure: Core logic in crates/core/ (Rust 89.6%), frontend in frontend/ (TypeScript 10.0% + React + Vite).
• GUI rendering: CodeMirror (file editing) + Tiptap (rich text), built as a single HTML file embedded in the Rust binary. Rust + webview architecture (webkit2gtk dependency, likely Tauri), with light/dark/system themes.
• Agent multi-process coordination: Isolated processes with independent tmux panes, communicating via shared mailbox and task queue.
• Tool communication: Strict MCP compliance with stdio and HTTP Streamable transports.
• Knowledge retrieval: KMS stored in .thclaws/kms/<name>/pages/, using grep + read for file-level search.

Typical Use Cases#

• AI-assisted coding: Read, edit, browse project files, run commands, auto-test, refactor code.
• Multi-agent parallel development: Backend/frontend built in parallel by separate agents in isolated git worktrees, merged by a lead agent.
• Knowledge worker assistance: Natural language interaction, file access, and knowledge base queries for researchers, PMs, ops, legal, marketing, and finance roles.
• CI/CD integration: Non-interactive mode for pipeline automation tasks.
• Local private deployment: All data stays on-device, cloud calls optional, suitable for security-sensitive environments.

Installation#

Pre-built Binaries#

Supports macOS (Apple Silicon & Intel), Windows (x86_64 & ARM64), Linux (x86_64 & ARM64).

curl -L https://github.com/thClaws/thClaws/releases/latest/download/thclaws-v0.7.4-aarch64-apple-darwin.tar.gz \
  | tar -xz && sudo mv thclaws /usr/local/bin/

Build from Source#

Prerequisites: Rust 1.85+, Node.js 20+, pnpm 9+

git clone https://github.com/thClaws/thClaws.git
cd ThClaws
cd frontend && pnpm install && pnpm build && cd ..
cargo build --release --features gui --bin thclaws
./target/release/thclaws          # GUI
./target/release/thclaws --cli    # CLI

Configuration#

• Priority: CLI flags > .thclaws/settings.json (project) > ~/.config/thclaws/settings.json (user) > ~/.claude/settings.json (compat fallback) > built-in defaults
• API keys stored in OS keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service), falls back to .env in CI
• Key files: CLAUDE.md/AGENTS.md (system prompts), .thclaws/skills/ (skills), .thclaws/agents/ (sub-agents), .mcp.json (MCP config), .thclaws-plugin/plugin.json (plugin manifest)

Organization & Version#

• Developer: ThaiGPT Co., Ltd. (Thailand)
• Dual licensed: MIT License / Apache License 2.0
• Current version: v0.7.6 (28 releases, 162 commits as of survey)

Unconfirmed Items#

• GUI framework inferred as Tauri (based on webkit2gtk + Rust + webview) but not explicitly stated in docs
• User manual online availability pending confirmation (24 chapters + 7 case studies exist in repo)
• Enterprise Edition feature differences not publicly disclosed
• No performance benchmarks published
• Agent Teams maximum agent count limit not specified