thClaws

https://thclaws.ai/manual
Admin
thClaws is an open-source native-Rust AI agent workspace that runs locally to provide coding,...
Tokens:181,855
Snippets:1,260
Trust Score:6.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Start a goal with /goal start

Source: https://thclaws.ai/manual/ch31-loops-and-goals.html

Begins a new goal with an objective and an optional token budget. The objective should be quoted to include words starting with '--'.

```shell
❯ /goal start "migrate every test file to the new fixture" --budget-tokens 400000
```

--------------------------------

### Install plugin with /plugin install productivity

Source: https://thclaws.ai/manual/ch16-plugins.html

Installs the named plugin into the project scope. Output confirms the installation path and that skills are callable without restart.

```text
❯ /plugin install productivity
plugin 'productivity' installed (project, 1 skill dir(s)) → .thclaws/plugins/productivity
skills callable in this session — no restart needed
```

--------------------------------

### List skills and invoke pdf skill

Source: https://thclaws.ai/manual/ch10-slash-commands.html

Shows the output of `/skills` listing installed skills and an example invocation of the pdf skill. The output includes the skill resolution and a message indicating the skill is being used.

```text
❯ /skills
  docx — Create, read, edit Word documents
  pdf  — Read, split, merge, OCR PDFs
  …

❯ /pdf extract text from report.pdf
(/pdf → Skill(name: "pdf"))
Using the pdf skill to extract text from report.pdf…
```

--------------------------------

### Install MCP server with /mcp install --user

Source: https://thclaws.ai/manual/ch14-mcp.html

Installs an MCP server in user scope, writing an entry to ~/.config/thclaws/mcp.json. Requires uv for auto-installation; first invocation downloads the package into an isolated environment. Restart thClaws to spawn the MCP.

```text
❯ /mcp install --user weather-mcp
  registered 'weather-mcp' in ~/.config/thclaws/mcp.json (user scope, stdio transport)
  command: uvx --from git+https://github.com/thClaws/marketplace.git#subdirectory=mcp/weather-mcp thclaws-weather
  note: Requires `uv` (one-time: `pip install uv` or `brew install uv`). First invocation downloads the package and dependencies into an isolated env automatically — no separate pip install needed.
  restart thClaws to spawn the MCP and load its tools
```

--------------------------------

### Headless Telegram bot setup with environment variables

Source: https://thclaws.ai/manual/ch23-telegram.html

Sets the bot token and optional owner ID in the environment, then starts the bot loop with `thclaws --telegram`. The owner ID adds you to the allowlist at startup.

```bash
export TELEGRAM_BOT_TOKEN="123456789:AA…"
export TELEGRAM_OWNER_ID="<your numeric Telegram user id>"   # optional but recommended
thclaws --telegram
```

--------------------------------

### Install plugin from Git URL

Source: https://thclaws.ai/manual/ch16-plugins.html

Installs a plugin from a Git repository URL. The output confirms installation to the project plugins directory and notes that skills are refreshed immediately, while MCP servers may need a restart or /mcp add.

```bash
❯ /plugin install https://github.com/agentic-press/deploy-plugin.git
plugin 'agentic-press-deploy' installed (project) → .thclaws/plugins/agentic-press-deploy
Skills refreshed and callable this session.
1 plugin-contributed MCP server(s) still need a restart to spawn — or use /mcp add to register them now.
```

--------------------------------

### Install skill with --user scope

Source: https://thclaws.ai/manual/ch12-skills.html

Installs the skill into ~/.config/thclaws/skills/ instead of the project's .thclaws/skills/. Default is project. The marketplace respects this flag too.

```shell
❯ /skill install --user skill-creator
```

--------------------------------

### Create folder and start thClaws session

Source: https://thclaws.ai/manual/ch27-thclaws-cloud.html

Commands to create an empty folder, navigate into it, and start a thClaws session. Use --cli for the REPL instead of the GUI default.

```bash
# 1. From a shell — make an empty folder for the agent and cd into it.
mkdir my-hello && cd my-hello

# 2. Start a thClaws session there.
thclaws            # GUI default; --cli for the REPL
```

--------------------------------

### Install daemon and check status

Source: https://thclaws.ai/manual/ch19-scheduling.html

Run `thclaws schedule install` to install the daemon, then `thclaws schedule status` to verify. On macOS it writes a LaunchAgent plist and bootstraps it; on Linux it writes a systemd user service and prints next-step commands.

```sh
$ thclaws schedule install
wrote /Users/jimmy/Library/LaunchAgents/sh.thclaws.scheduler.plist
daemon bootstrapped — `thclaws schedule status` to verify

$ thclaws schedule status
daemon: running (pid 88294)

recent fires:
  ok   morning-brief             2026-05-06T08:30:04Z
  —    deps-audit                never
```

--------------------------------

### Install Linux GUI runtime dependencies on Debian/Ubuntu and Fedora/RHEL

Source: https://thclaws.ai/manual/ch02-installation.html

Installs the Wayland, WebKit2GTK, and libsoup packages required by the Linux GUI binary. Use the appropriate command for your distribution.

```bash
# Debian / Ubuntu
$ sudo apt install libwayland-client0 libwebkit2gtk-4.1-0 libsoup-3.0-0

# Fedora / RHEL
$ sudo dnf install wayland libsoup3 webkit2gtk4.1
```

--------------------------------

### Memory file YAML frontmatter example

Source: https://thclaws.ai/manual/ch08-memory-and-agents-md.html

Example of a memory file with YAML frontmatter containing name, description, and type fields, followed by the body content.

```markdown
---
name: project_context
description: Ongoing context about the Q2 refactor
type: project
---

The billing module rewrite is blocked on legal review of the new
pricing tiers. Target unblock date: 2026-09-15. Contact: Priya.
```

--------------------------------

### SKILL.md anatomy example

Source: https://thclaws.ai/manual/ch12-skills.html

Example SKILL.md file with frontmatter (`name`, `description`, `whenToUse`) and a numbered body. `{skill_dir}` is substituted with the absolute path to the skill directory at load time.

```markdown
---
name: deploy-to-staging
description: Deploy the current branch to staging and run smoke tests
whenToUse: When the user asks to deploy or ship to staging
---

1. Ensure the working tree is clean (`git status`). Abort if dirty.
2. Run `{skill_dir}/scripts/build.sh` to build the production bundle.
3. Upload `dist/` via `{skill_dir}/scripts/push-to-staging.sh`.
4. Run `{skill_dir}/scripts/smoke-test.sh` — it should exit 0.
5. Report the staging URL to the user.

If any step fails, abort and report the failing step.
```

--------------------------------

### Example settings.json with all documented keys

Source: https://thclaws.ai/manual/ch03-working-directory-and-modes.html

A complete example of a settings.json file showing the default and configured values for the keys described in the tables above. Use this as a template for your own configuration. Note that sibling files like .thclaws/mcp.json and .env are not included here.

```json
{
  "model": "claude-sonnet-4-6",
  "permissions": "auto",
  "maxTokens": 32000,
  "maxIterations": 50,
  "thinkingBudget": 10000,
  "searchEngine": "auto",
  "planContextStrategy": "compact",
  "skillsListingStrategy": "full",
  "kms": { "active": ["project-notes"] },
  "autoLearn": true,
  "openrouterFreeOnly": false,
  "gatewayUseFor": [],
  "teamEnabled": false,
  "windowWidth": null,
  "windowHeight": null,
  "guiScale": null
}
```

--------------------------------

### Install Ollama on macOS, Linux, and Windows

Source: https://thclaws.ai/manual/ch02-installation.html

Commands to install Ollama on macOS via Homebrew, on Linux via the script installer, and a note to download the installer for Windows. After installation, start the Ollama daemon with 'ollama serve' or the desktop app.

```bash
# macOS
brew install ollama

# Linux (script installer)
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download the installer from ollama.com/download
```

--------------------------------

### Run daemon in foreground for testing

Source: https://thclaws.ai/manual/ch19-scheduling.html

Run `thclaws daemon` to start the scheduler in the foreground without installing the launchd/systemd entry. Useful to verify a schedule actually fires before installing.

```sh
$ thclaws daemon
[daemon] thclaws scheduler started (pid 12345, pid file ~/.local/state/thclaws/scheduler.pid)
[schedule] in-process scheduler running (tick 30s)
[schedule] 'morning-brief' fired — exit=0 duration=38.412s log=...
^C
[daemon] SIGINT received — shutting down
[daemon] stopped cleanly
```

--------------------------------

### .env file example for provider API keys

Source: https://thclaws.ai/manual/ch06-providers-models-api-keys.html

Example .env file content for configuring API keys and base URLs for various providers. Place this file at ~/.config/thclaws/.env or in the project root. The OLLAMA_BASE_URL defaults to http://localhost:11434. The OPENAI_COMPAT_BASE_URL points to any OpenAI-compatible gateway. Add .env to .gitignore immediately to prevent key leaks.

```bash
# ~/.config/thclaws/.env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-v1-...
GEMINI_API_KEY=AI...
DASHSCOPE_API_KEY=sk-...
OLLAMA_BASE_URL=http://localhost:11434   # defaults to this anyway
OPENAI_COMPAT_BASE_URL=http://localhost:8000/v1   # any OAI-compat gateway
OPENAI_COMPAT_API_KEY=...
```

--------------------------------

### thclaws.skills

Source: https://thclaws.ai/manual/ch26-gui-shells.html

Manage skills: list, get, install, save, and delete. Requires skills.read or skills.write permissions.

```APIDOC
## thclaws.skills

### Description
Manage skills.

### Methods
- `list()` - List skills. Requires `skills.read`.
- `get(name)` - Get a skill by name. Requires `skills.read`.
- `install(url, opts)` - Install a skill from a URL with options. Requires `skills.write`.
- `save(name, body)` - Save a skill with a name and body. Requires `skills.write`.
- `delete(name)` - Delete a skill by name. Requires `skills.write`.

### Permissions
- `skills.read` - for `list()`, `get(name)`
- `skills.write` - for `install(url, opts)`, `save(name, body)`, `delete(name)`
```

--------------------------------

### Start HTTP/WebSocket Server with --serve

Source: https://thclaws.ai/manual/ch03-working-directory-and-modes.html

Start the agent engine over HTTP + WebSocket. Default bind is 127.0.0.1:8443. Use --port for custom port, --bind 0.0.0.0 for all interfaces (auth required), and --gui to also open the desktop window on the same engine.

```bash
thclaws --serve                       # listen on 127.0.0.1:8443
thclaws --serve --port 7878           # custom port
thclaws --serve --bind 0.0.0.0        # bind all interfaces (auth required)
thclaws --serve --gui                 # plus open desktop window on same engine
```

--------------------------------

### Verify thClaws installation

Source: https://thclaws.ai/manual/ch02-installation.html

Commands to verify the thClaws installation: check versions of the GUI and CLI binaries, start the interactive REPL, and run a headless one-shot. All four should print or run without error. If -p/--print asks for a key, no API key is configured.

```bash
$ thclaws --version                   # the GUI binary
$ thclaws-cli --version               # the CLI-only binary
$ thclaws --cli                       # interactive REPL
$ thclaws -p "say hi in one word"     # headless one-shot (--print also works)
```

--------------------------------

### Install skill from marketplace by name

Source: https://thclaws.ai/manual/ch12-skills.html

Installs a skill from the marketplace catalog by name. The command resolves the name to the entry's install_url, clones the subpath from the registry repo, and lands it at .thclaws/skills/<name>/. The skill becomes available in the same session without restart.

```shell
❯ /skill install skill-creator
  cloned https://github.com/thClaws/marketplace.git (subpath: skills/skill-creator) → .thclaws/skills/skill-creator
  installed skill 'skill-creator' (single)
(skill available in this session — no restart needed)
```

--------------------------------

### Example CLAUDE.md project conventions

Source: https://thclaws.ai/manual/ch08-memory-and-agents-md.html

Example content for a CLAUDE.md or AGENTS.md file at the project root, describing conventions the agent should follow. Both filenames are supported; if both exist, both are included with CLAUDE.md first.

```markdown
# Project conventions

- Language: Rust 2021, `cargo fmt` before every commit.
- Tests live alongside code in `#[cfg(test)]` modules.
- Never touch files under `vendor/`.
- Prefer `anyhow::Result` over `Box<dyn Error>` in application code.
- Commit messages: imperative mood, ≤72 chars in the first line.
```

--------------------------------

### Stdio server spawn failure error message

Source: https://thclaws.ai/manual/ch14-mcp.html

Example error message when a stdio server fails to start, typically due to missing npx or Node. thClaws continues running without that server's tools.

```plaintext
[mcp] weather … spawn failed: command not found: npx
```

--------------------------------

### Linux install: extract and install binaries

Source: https://thclaws.ai/manual/ch02-installation.html

Extracts the Linux tarball and installs thclaws and thclaws-cli to ~/.local/bin with install -m 755.

```bash
$ tar -xzf ~/Downloads/thclaws-*-linux-gnu.tar.gz
$ mkdir -p ~/.local/bin
$ install -m 755 thclaws thclaws-cli ~/.local/bin/
```

--------------------------------

### Browse plugin marketplace with /plugin marketplace

Source: https://thclaws.ai/manual/ch16-plugins.html

Displays the curated plugin catalog. Output shows the baseline date, plugin count, and a list of plugins with descriptions and install commands.

```text
❯ /plugin marketplace
plugin marketplace (baseline 2026-04-29, 1 plugin(s))
── workflow ──
  productivity             — Task management, workplace memory, visual dashboard
install with: /plugin install <name>   |   detail: /plugin info <name>
```

--------------------------------

### Plan Mode Quick Start Workflow

Source: https://thclaws.ai/manual/ch18-plan-mode.html

Shows the interactive flow of plan mode: starting with /plan, submitting a plan, approving it, and watching step-by-step execution. The output includes the sidebar pill turning cyan and the final 'All 4 steps complete' footer.

```text
You:    /plan
        ↓ (mode flips to PLAN — sidebar pill turns cyan)
You:    submit a plan to add a /healthz endpoint to my web server
Model:  reads existing routes, drafts a 4-step plan
        ↓ sidebar opens with steps + Approve / Cancel
You:    [click Approve]
Model:  step 1 (in_progress) → writes new route handler → step 1 (done)
        step 2 (in_progress) → adds the test → step 2 (done)
        ...
        ↓ all steps ✓ → "All 4 steps complete" footer
```

--------------------------------

### Install plugin from zip file with user scope

Source: https://thclaws.ai/manual/ch16-plugins.html

Installs a plugin from a zip file using the --user flag to install to the user global directory (~/.config/thclaws/plugins/).

```bash
❯ /plugin install --user https://example.com/plugins/deploy-v1.zip
```

--------------------------------

### Switch provider with /providers and /provider

Source: https://thclaws.ai/manual/ch06-providers-models-api-keys.html

Shows the /providers command listing available providers and the /provider command to switch to a specific provider. Switching always forks a fresh session.

```shell
❯ /providers
  * anthropic     → claude-sonnet-4-6
    anthropic-agent → agent/claude-sonnet-4-6
    openrouter    → openrouter/anthropic/claude-sonnet-4-6
    ...

❯ /provider openai
provider → openai (model: gpt-4o, saved to .thclaws/settings.json; new session sess-…)

❯ /provider
current provider: openai (model: gpt-4o)
```

--------------------------------

### Install thClaws on Windows via MSI or ZIP

Source: https://thclaws.ai/

Install thClaws on Windows. The .msi installer is per-user, requires no admin, and sets PATH automatically. ZIP is for portable or policy-blocked-MSI scenarios.

```powershell
# Recommended — .msi installer (per-user, no admin, sets PATH automatically)
# x86_64 (typical Intel/AMD Windows):
iwr -Uri https://github.com/thClaws/thClaws/releases/download/v0.141.0/thclaws-v0.141.0-x86_64-pc-windows-msvc.msi -OutFile thclaws.msi
Start-Process msiexec.exe -ArgumentList '/i', 'thclaws.msi' -Wait

# Windows on ARM (Surface Pro X, Snapdragon X laptops):
iwr -Uri https://github.com/thClaws/thClaws/releases/download/v0.141.0/thclaws-v0.141.0-aarch64-pc-windows-msvc.msi -OutFile thclaws.msi
Start-Process msiexec.exe -ArgumentList '/i', 'thclaws.msi' -Wait

# Or ZIP (portable / policy-blocked-MSI scenarios)
iwr -Uri https://github.com/thClaws/thClaws/releases/download/v0.141.0/thclaws-v0.141.0-x86_64-pc-windows-msvc.zip -OutFile thclaws.zip
Expand-Archive thclaws.zip -DestinationPath $env:LOCALAPPDATA\Programs\thclaws
```

--------------------------------

### Install skill from a .zip URL

Source: https://thclaws.ai/manual/ch12-skills.html

Installs a skill from a zip URL. The zip is downloaded and extracted. There is a 64 MB size cap, zip-slip guarding, Unix exec bits are preserved, and a single top-level wrapper directory is auto-unwrapped.

```shell
❯ /skill install https://example.com/api/skills/deploy-v1.zip
  downloaded https://example.com/...zip (4210 bytes) → extracted
  installed skill 'deploy-v1' (single)
```

--------------------------------

### Install Ollama via Homebrew

Source: https://thclaws.ai/manual/ch06-providers-models-api-keys.html

Install Ollama on macOS using Homebrew. See ollama.com for other platforms.

```bash
brew install ollama
```
Tokens:
Raw