thclaws-agent-harness

What this skill does

```markdown
---
name: thclaws-agent-harness
description: Expert skill for using thClaws, the native Rust AI agent workspace platform with multi-provider support, skills, MCP servers, and agent orchestration.
triggers:
  - "set up thClaws agent harness"
  - "configure thClaws with a provider"
  - "install a skill in thClaws"
  - "add an MCP server to thClaws"
  - "create an AGENTS.md for thClaws"
  - "run thClaws in CLI mode"
  - "orchestrate agents with thClaws"
  - "build a thClaws plugin"
---

# thClaws Agent Harness Platform

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

thClaws is a native-Rust AI agent workspace that runs entirely on your local machine. It edits code, automates workflows, searches knowledge bases, and coordinates teams of agents through a single binary. Three interfaces — Desktop GUI, interactive CLI REPL, and non-interactive one-shot mode — share one config, one session store, and one provider layer.

---

## Installation

### Pre-built binary (fastest)

Download from [thclaws.ai/downloads](https://thclaws.ai/downloads) or the GitHub Releases page for macOS (Apple Silicon / Intel), Windows (x86_64 / ARM64), or Linux (x86_64 / ARM64).

### Build from source

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

```sh
git clone https://github.com/thClaws/thClaws.git
cd thClaws

# 1. Build the React frontend (bundled as a single HTML file)
cd frontend && pnpm install && pnpm build && cd ..

# 2. Build the Rust binary with GUI support
cargo build --release --features gui --bin thclaws

# 3. Verify
./target/release/thclaws --version
```

---

## Running thClaws

```sh
# Desktop GUI (default)
thclaws

# Interactive CLI REPL — no window, ideal for SSH / headless
thclaws --cli

# Non-interactive one-shot — runs one turn and exits
thclaws -p "summarise src/main.rs in three bullet points"

# One-shot with a specific working directory
thclaws -p "list all TODO comments" --cwd /path/to/project

# Shell escape inside the REPL — prefix with !
❯ ! git status
❯ ! ls -la
```

---

## First-Run Setup

On first launch, thClaws prompts you to choose a secrets backend:

- **OS Keychain** (recommended) — macOS Keychain, Windows Credential Manager, Linux Secret Service
- **`.env` file** — for CI or environments without a keychain

API keys are **never written to config JSON files**.

### Configure a provider inside the REPL

```
❯ /provider anthropic
❯ /model claude-sonnet-4-6

# Switch to OpenRouter (300+ models, one API key)
❯ /provider openrouter
❯ /model openrouter/anthropic/claude-sonnet-4-6

# Use a local Ollama model — no cloud, no API key
❯ /provider ollama
❯ /model llama3

# List models available for the active provider
❯ /models
```

### Supported providers (auto-detected by model name prefix)

| Provider | Model prefix example |
|---|---|
| Anthropic | `claude-*` |
| OpenAI | `gpt-*`, `o1-*`, `o3-*` |
| Google Gemini | `gemini-*` |
| Alibaba DashScope | `qwen-*` |
| OpenRouter | `openrouter/*` |
| Ollama (local) | `ollama/*` or bare model name |
| Agentic Press | configured via `/provider agenticpress` |

---

## Configuration Files

Settings are merged in this precedence order (higher index wins):

```
compiled defaults
~/.config/thclaws/settings.json   (user-global)
~/.claude/settings.json           (fallback location)
.thclaws/settings.json            (project-level)
CLI flags
```

### Minimal project settings — `.thclaws/settings.json`

```json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "permissionMode": "default",
  "thinkingBudget": 8000,
  "allowedTools": ["Read", "Write", "Bash", "Task"],
  "disallowedTools": [],
  "autoApprove": false
}
```

### Permission modes

| Value | Behaviour |
|---|---|
| `"default"` | Approve every mutating tool call interactively |
| `"auto"` | Auto-approve all tool calls (use in CI / trusted scripts) |
| `"restricted"` | Read-only — no writes, no shell |

---

## AGENTS.md — Project Instructions

Drop an `AGENTS.md` (or `CLAUDE.md`) at any directory level. thClaws walks up from `cwd` and injects every match it finds into the system prompt automatically.

```markdown
# AGENTS.md

## Project: Payment Service

### Stack
- Rust 1.85, Axum 0.7, SQLx 0.7, PostgreSQL 15
- Tests: `cargo nextest run`
- Linting: `cargo clippy -- -D warnings`

### Conventions
- All DB queries must use prepared statements via SQLx macros.
- Never commit secrets; use `.env` and the `dotenvy` crate.
- PR titles follow Conventional Commits: `feat:`, `fix:`, `chore:`.

### Commands the agent may run without asking
- `cargo build`, `cargo test`, `cargo clippy`, `cargo fmt`
- `psql $DATABASE_URL -c "..."` for schema inspection

### Off-limits
- Do not modify `migrations/` directly; create new migration files.
- Do not alter `.github/workflows/` without human review.
```

---

## Skills

Skills are reusable expert workflows. The agent picks the right skill automatically when a request matches `whenToUse`, or you invoke one explicitly as `/<skill-name>`.

### Install a skill

```sh
# From a git URL
❯ /skill install https://github.com/anthropics/skills.git

# From a zip archive
❯ /skill install ./my-skill.zip

# List installed skills
❯ /skills
```

### Write a custom skill — `.thclaws/skills/code-review/SKILL.md`

```markdown
---
name: code-review
description: Performs a structured Rust code review checking safety, performance, and idiomatic style.
whenToUse: "review my code, check this PR, audit this file for Rust idioms"
---

# Code Review Skill

## Steps

1. Read every changed file with `Read`.
2. Run `cargo clippy -- -D warnings` and capture output.
3. Run `cargo test` and note failures.
4. Produce a structured report:
   - **Safety** — any `unsafe` blocks, unwrap calls, or panic paths
   - **Performance** — unnecessary allocations, cloning, or blocking calls in async contexts
   - **Idioms** — suggest `?` over `unwrap`, iterators over manual loops, etc.
5. Offer to apply suggested fixes with `Write`.
```

---

## MCP Servers (Tool Plugins)

MCP servers extend the agent's tool set with third-party integrations.

### Add a server inside the REPL

```sh
# stdio transport
❯ /mcp add github https://mcp.github.com

# HTTP Streamable transport
❯ /mcp add mydb http://localhost:3100/mcp

# List active servers
❯ /mcp list
```

### Declare servers in `.mcp.json` (committed to the repo)

```json
{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "postgres": {
      "transport": "http",
      "url": "http://localhost:3200/mcp",
      "oauth": true
    }
  }
}
```

---

## Knowledge Bases (KMS)

Per-project wikis the agent can search and read on demand. No embeddings — plain grep + read.

### Structure

```
.thclaws/kms/
└── architecture/
    ├── index.md          ← one-line entry per page (table of contents)
    └── pages/
        ├── overview.md
        ├── database-schema.md
        └── api-contracts.md
```

### `index.md` format

```markdown
# Architecture Knowledge Base

- overview.md — High-level system diagram and service boundaries
- database-schema.md — PostgreSQL table definitions and relationships
- api-contracts.md — REST and WebSocket API contracts with examples
```

The agent receives this index every turn and uses `KmsRead` / `KmsSearch` tools to pull specific pages on demand.

### Attach a KMS in settings

```json
{
  "kms": [
    { "name": "architecture", "path": ".thclaws/kms/architecture" },
    { "name": "runbooks", "path": "/shared/runbooks" }
  ]
}
```

```sh
# List attached knowledge bases
❯ /kms
```

---

## Agent Orchestration

### Sub-agents via the `Task` tool

The agent can delegate subtasks to isolated child agents (up to 3 levels deep), each with its own