thClaws
← back to manual

Chapter 1 — What is thClaws?

Chapter 1 · ภาษาไทย

logo

thClaws is a native-Rust AI Agent Platform that runs locally on your machine — for building AI Agents that help with a wide range of work: writing code, automating workflows, reviewing and organizing documents, managing knowledge bases, or assembling teams of agents that work together. All in one binary. You tell it what you want in natural language; it reads your files, runs commands, uses tools, and talks back to you while it works.

Six surfaces ship as one binary, sharing a single Agent loop, Session, and tool registry — the first five are for a single person (including chatting through LINE on your phone), the sixth lets other software hire thClaws to do work:

  • Desktop GUI (thclaws with no flags) — a native window with a Terminal tab running the same interactive REPL as --cli mode, a streaming Chat tab, a Files browser, and an optional Team tab.
  • CLI REPL (thclaws --cli) — an interactive terminal prompt for SSH sessions, headless servers, or when you want zero GUI overhead.
  • Non-interactive mode (thclaws -p "prompt", long form --print) — runs a single turn and exits. Handy for scripts, CI pipelines, and shell one-liners. Add -v / --verbose to see per-turn token usage on stderr without polluting stdout.
  • Webapp (thclaws --serve --port 7878 + open a browser) — same engine over WebSocket/HTTP, served from your laptop. Reach it remotely via SSH tunnel for “thClaws anywhere” without opening a port.
  • LINE Chat (thclaws --line or GUI Line Connect modal) — chat with your agent through your own LINE Official Account. Goes through a relay tunnel at line.thclaws.ai that bridges the LINE platform and the thClaws running on your machine — the agent stays local but you can reach it from anywhere via your phone (see Chapter 21).
  • AI Agent (API server) (thclaws --serve + HTTP API) — lets other software (orchestrators, external clients, schedulers) call thClaws as an agent over the same HTTP API — details in later chapters.

What makes it different

  • Self-improving AI Agent (auto-learn). Turn on autoLearn: true in settings and thClaws automatically files every substantive session as a new page in a dedicated self_learn KMS (separate from your hand-curated active vaults), then runs throttled /kms reconcile to dedupe and resolve contradictions across pages. Built from existing primitives — /kms ingest, kms-reconcile, the session_end hook — no new agent prompts; just wiring. One flag to enable, rm -rf .thclaws/kms/self_learn/ to reset. See Chapter 9 §Self-improving AI Agent.
  • Three tiers of agent orchestration.
  • Task tool — model-driven subagents that block the parent’s turn. Each gets its own tool registry, recurses up to 3 levels deep. Right when the parent’s reasoning should decide whether and when to delegate.
  • /agent <name> <prompt> — user-driven concurrent side-channels. Spawned on a fresh tokio task, runs in parallel with main, never enters main’s history, has its own cancel token. Right when you know exactly what you want a specialist to do (/agent translator แปลไฟล์ x while you keep coding).
  • Agent Teams — multiple thClaws processes coordinating through a shared mailbox and task queue, each teammate in its own tmux pane and optional git worktree. One agent writes your backend while a teammate builds the frontend in parallel; lead calls TeamMerge when both are done.
  • Hire-able as a working agent — your self-hosted sandbox. The inverse direction of orchestration: thClaws itself runs as a worker for another orchestrator (e.g. Paperclip / thcompany / Anthropic Managed Agents), in either the Employee shape (thclaws_local — a process on the same machine — equivalent to an in-process sandbox) or the Freelancer shape (thclaws_pod — a standalone pod that can run on a VPS, cloud, or your own k3s — equivalent to a self-hosted sandbox where the agent loop is upstream and tool execution stays inside your perimeter). The orchestrator drives it through the same HTTP API users and IDEs use. See Chapter 22.
  • Three tiers of long-term memory.
  • AGENTS.md / CLAUDE.md — drop one in your repo; thClaws walks up from cwd and injects every match into the system prompt, the same way git resolves .gitignore (Chapter 8).
  • Memory store at ~/.config/thclaws/memory/ — longer-lived facts the agent has learned about you, your preferences, and each project, classified as user / feedback / project / reference and indexed as markdown files.
  • KMS (knowledge bases) — per-project and per-user wikis the agent searches and reads on demand. Drop markdown pages under .thclaws/kms/<name>/pages/, tick the box in the sidebar, and the agent gets a table of contents every turn plus a full mutation surface (KmsRead / KmsSearch / KmsWrite / KmsAppend / KmsDelete). No embeddings — grep + read, following Andrej Karpathy’s LLM-wiki pattern. Run /dream and a built-in side-channel agent mines the 10 most recent sessions, dedupes pages, surfaces insights, and writes a dated audit-trail page — review with git diff (Chapter 9).

All three are plain markdown you read, edit, and commit. All three survive restart. - Skills. Reusable expert workflows packaged as a directory with SKILL.md (YAML frontmatter + Markdown instructions the model follows) and optional scripts. The agent picks the right skill automatically when a user request matches the whenToUse trigger, or you can invoke one explicitly as /<skill-name>. Install with /skill install from a git URL or .zip archive. Discovery looks in .thclaws/skills/, ~/.config/thclaws/skills/, plus .claude/skills/ as a fallback location. - MCP servers. The Model Context Protocol lets you plug in tools built by third parties — GitHub, filesystems, databases, browsers, Slack, and more. Both stdio (spawned subprocess) and HTTP Streamable transports are supported, with OAuth 2.1 + PKCE for protected servers. Add one with /mcp add or ship a .mcp.json in your project; discovered tools are namespaced by server name and the agent can call them like any built-in. - Plugin system. Skills + commands + agent definitions + MCP servers bundled under a single manifest (.thclaws-plugin/plugin.json or .claude-plugin/plugin.json), installable from a git URL or a .zip archive. One install, one uninstall, one version to pin — ideal for sharing a team’s extensions. - Multi-provider. Anthropic (native + Claude Agent SDK via Claude Code auth), OpenAI (Chat Completions + Responses/Codex), Google Gemini & Gemma, Alibaba DashScope (Qwen), DeepSeek, Z.ai (GLM Coding Plan), NVIDIA NIM, NSTDA Thai LLM (OpenThaiGPT, Typhoon, Pathumma, THaLLE), OpenRouter, Agentic Press, Azure AI Foundry, Ollama (local, local Anthropic-compatible, and Ollama Cloud), LMStudio, plus a generic OpenAI-compatible slot (oai/*) for LiteLLM / Portkey / Helicone / vLLM / internal proxies — auto-detected by model name prefix. Switch models mid-session with /model (validated against the provider’s catalogue) or swap the whole provider with /provider. - API-ready for standard tooling. --serve exposes /v1/chat/completions (OpenAI-compatible for Cursor, Aider, n8n, openai-python) and /agent/run + /v1/agent/info (thClaws-native for orchestrators like thcompany). One agent instance can serve humans and other software at the same time. - Async webhook delivery. Long-running runs (deploys, builds, multi-step research) send the prompt + x_callback and close the connection; thClaws POSTs the terminal result back when done. Survives network blips and orchestrator pod restarts mid-flight. - Plan mode. For multi-step work, the agent can EnterPlanMode, propose an ordered list of steps, and let you review and approve before execution. Each step runs sequentially with its own retry budget; failures stop the chain so you can decide. Same UX in GUI (sidebar with Approve / Cancel / Skip / Retry per step) and REPL (/plan slash command). - Schedule recurring jobs. /schedule add runs an agent on cron (0 9 * * MON-FRI), at fixed intervals, or whenever a watched directory changes (watchWorkspace). Three composable layers: manual /schedule run, in-process scheduler (lives as long as your REPL), and a native daemon (launchd on macOS / systemd-user on Linux) that survives reboots. Per-job working directory, optional model override, full output capture. - Long-running loops & overnight builds. /loop for fixed-interval iteration. /goal for audit-driven completion (the agent works toward a goal until an audit prompt confirms “done” or hits the budget). Compose them: /goal --auto is a Ralph-style overnight builder that keeps going until the goal is satisfied or you wake up. - Document workflow. Native PDF, DOCX, PPTX, XLSX read + edit + create tools, plus image rendering. The agent can ingest a 50-page PDF, summarize it into KMS, and produce a follow-up PowerPoint deck — all in one conversation, no separate file-conversion step. - Hooks. Run shell scripts on agent lifecycle events: pre_tool_use, post_tool_use, permission_denied, session_start, pre_compact, etc. Audit every Bash invocation, gate Edit/Write through your linter, fire a Slack notification when long sessions end. Eight events × per-event environment variables × timeout-with- SIGKILL guarantees. - Any knowledge worker, not just engineers. The Chat tab is a streaming conversation panel anyone can drive — researchers, analysts, PMs, ops, legal, marketing, finance. Ask in natural language; the agent reads your files, edits documents, searches your knowledge base, drafts outputs. Engineers prefer the Terminal tab’s REPL. Both share the same sessions and config, so a mixed team can switch between interfaces freely without losing context. - File viewer & editor in the Files tab. A working-directory file tree with a syntax-highlighted preview pane (CodeMirror 6, ~40 languages) and server-rendered GFM markdown in a sandboxed iframe. Click the pencil icon to edit .md in a WYSIWYG editor (TipTap) or code in a highlighted editor (CodeMirror) — Cmd/Ctrl+S to save, native OS confirm dialog before discarding edits. Auto-refresh polling pauses while you’re editing so concurrent Write/Edit tool calls from the agent can’t clobber your in-progress buffer. - Runs on every major platform. A single native Rust binary runs on macOS (Apple Silicon + Intel), Windows, and Linux. Drop the same binary into a Docker container to deploy on a VPS, cloud, or Kubernetes — one codebase covers everything from a personal laptop to a pod on a cluster. - Offline-capable. Ollama (native and Anthropic-compat) lets you run entirely against a local model. - Open standards, not a walled garden. thClaws is built on the conventions the agent-tooling industry is converging on, not on bespoke formats you have to learn only for us. The Model Context Protocol for tool servers. AGENTS.md for project instructions — the vendor-neutral standard stewarded by the Agentic AI Foundation and adopted by Google, OpenAI, Factory, Sourcegraph, and Cursor. SKILL.md with YAML frontmatter for packaged workflows. .mcp.json for MCP server configuration. Your configuration is portable — between thClaws, other agents that speak the same standards, and whatever comes next. - Safety first. A filesystem sandbox scopes file tools to the working directory. Destructive shell commands are flagged before execution. You approve every mutating tool call unless you’ve opted into auto-approve. Permission requests label which agent is asking when multiple are running concurrently (main vs. side-channel vs. subagent), so you don’t approve a translator’s Bash thinking it’s main’s. - Transparent cost tracking. Built-in model catalogue carries per-token-type pricing (input / output / cached read / cache write / reasoning) sourced from LiteLLM. Every turn’s usage block reports all five fields so orchestrators / UIs can compute cost locally without asking the provider. - Host thClaws anywhere. Run it locally on your own machine, or deploy it to thCompany.ai so a cloud-hosted thClaws runs under your account — either hired by a Company (as employee or freelancer via Chapter 22) or standing alone to take work directly. The deploy flow ships as a plugin (/plugin install …-deploy) so hosts are swappable — the client never locks you in. - Session resume. thclaws --resume last picks up where you left off; thclaws --resume <id> jumps to a specific session. Sessions live as JSONL under .thclaws/sessions/ — git-friendly, grep-friendly, never opaque. - Settings. Every runtime knob — permission mode, thinking budget, allowed/disallowed tools, provider endpoints, KMS attachments, max output tokens — is one JSON file: .thclaws/settings.json (project, commit it with the repo) or ~/.config/thclaws/settings.json (user-global). ~/.claude/settings.json is read as a fallback location. API keys go in the OS keychain by default (Windows Credential Manager / macOS Keychain / Linux Secret Service) with .env fallback for CI and headless servers. The gear icon in the desktop GUI is a visual editor for keys, global/folder AGENTS.md, and the secrets backend choice. - Shell escape. Prefix any REPL line with ! to run the rest as a shell command directly in your terminal — no tokens, no approval prompt, no agent round-trip (e.g. ! git status).

What you need

  • A supported OS: macOS (arm64 or x86_64), Linux (arm64 or x86_64), or Windows (arm64 or x86_64).
  • At least one LLM API key — Anthropic, OpenAI, Gemini, OpenRouter, Agentic Press, DashScope, DeepSeek, Z.ai, NVIDIA NIM, NSTDA Thai LLM, or Azure AI Foundry. (Or a local Ollama / LMStudio install if you’d rather stay offline.)

Chapter 2 walks through installation and first launch. Chapter 6 covers where and how to paste keys.

How this manual is organised

22 chapters of reference material — how to install thClaws and then every user-facing feature explained once with the commands and configuration you need:

Setup - Chapter 2 — Installation - Chapter 3 — Working directory + run modes - Chapter 4 — Desktop GUI tour - Chapter 5 — Permissions - Chapter 6 — Providers, models, API keys

Core features - Chapter 7 — Sessions and resume - Chapter 8 — Memory and AGENTS.md - Chapter 9 — Knowledge bases (KMS), including self-improving auto-learn - Chapter 10 — Slash commands - Chapter 11 — Built-in tools - Chapter 12 — Skills - Chapter 13 — Hooks - Chapter 14 — MCP

Composing agents - Chapter 15 — Subagents - Chapter 16 — Plugins - Chapter 17 — Agent teams - Chapter 18 — Plan mode - Chapter 19 — Scheduling - Chapter 20 — /research (background research)

Reaching thClaws from elsewhere - Chapter 21 — LINE chat + browser bridge - Chapter 22 — Paperclip adapter (let an orchestrator hire thClaws)

If you’re new, read Chapter 2 next. If you’re migrating from Claude Code, skip to Chapters 6, 7, 11, and 13. If you already know the basics and want what’s new, the recent additions live in Chapter 9 (auto-learn, /dream), Chapter 15 (/agent side-channels), Chapter 21 (LINE), and Chapter 22 (Paperclip adapter).