# Concepts (/docs/concepts)



Knowledge [#knowledge]

A knowledge entry is the atomic unit in workthin. Each entry contains:

| Field               | Type      | Description                                                             |
| ------------------- | --------- | ----------------------------------------------------------------------- |
| `id`                | UUID      | Unique identifier (e.g. `550e8400-e29b-41d4-a716-446655440000`)         |
| `title`             | string    | Short, searchable title                                                 |
| `body`              | string    | Free-form content — AI structures this into problem/solution/root cause |
| `scope`             | enum      | Visibility: `personal`, `project`, `global`                             |
| `tags`              | string\[] | Categorization labels (auto-generated and manual)                       |
| `prev_knowledge_id` | UUID?     | Links to a previous version (thought chaining)                          |
| `branch_from_id`    | UUID?     | Links to the parent entry this was forked from                          |
| `url`               | string?   | Reference URL (e.g. incident link, PR, docs)                            |
| `etag`              | string    | Optimistic concurrency control token                                    |
| `created_at`        | timestamp | Creation time                                                           |
| `updated_at`        | timestamp | Last update time                                                        |

Thought Chains [#thought-chains]

When a problem recurs or evolves, link knowledge entries together using `prev_knowledge_id`. This creates a chronological chain:

```
550e8400-... : Redis split-brain (initial)
  └─ 660f9500-... : Redis split-brain (recurrence)
       └─ 770a0600-... : Redis split-brain (final fix)
```

Each entry in the chain preserves its own context while maintaining the full history of how a solution evolved.

Branches [#branches]

Use `branch_from_id` to fork a knowledge entry and explore an alternative solution. Branches are independent — changes to the branch do not affect the original.

```
550e8400-... : OOM fix (set max-old-space-size)
  ├─ branch: 880b1700-... : OOM fix (use cgroups v2 memory limits)
  └─ branch: 990c2800-... : OOM fix (switch to Bun runtime)
```

Scopes [#scopes]

Scopes control who can see and use a knowledge entry.

| Scope      | Visibility   | Use Case                              |
| ---------- | ------------ | ------------------------------------- |
| `personal` | Only you     | Personal notes, draft solutions       |
| `project`  | Your project | Project-specific fixes and procedures |
| `global`   | Everyone     | Company-wide knowledge base           |

Joining a Project [#joining-a-project]

There are two ways to join a project:

* **Via git remote** — Run `wt init` in a repository. workthin detects the git remote and auto-creates or joins the matching project. Everyone who runs `wt init` in the same repository joins the same project automatically. No invitation needed.
* **Via invitation** — A project admin can invite existing workthin users by email from the project settings page. The invited user must already have a workthin account.

The project description is auto-generated from `package.json` when available.

Global Reads & Contributor Rewards [#global-reads--contributor-rewards]

Global knowledge is read-limited on the Free tier (30 reads/month). Pro plan has unlimited reads.

A "global read" is counted each time your AI searches or retrieves a global-scoped knowledge entry. Personal and project-scoped reads are always free and unlimited.

How rewards work [#how-rewards-work]

Contributing to the global library earns additional reads on top of your monthly allowance:

| Action               | Reward            | When counted                                                                         |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------ |
| Publish to global    | +1.0 read         | When you set scope to `global`                                                       |
| Viewed by others     | +0.1 / view       | When another user's AI retrieves your knowledge (5-hour cooldown per user per entry) |
| Referenced in search | +0.3 / reference  | When your knowledge appears in another user's search results                         |
| Resolved a problem   | +1.0 / resolution | When another user marks your knowledge as "this helped"                              |
| Branched by others   | +0.5              | When someone forks your knowledge via `branch_from_id`                               |
| Quality flag (valid) | +0.5              | When a warning or deprecation comment you added is confirmed useful                  |

Rewards are credited instantly and accumulate throughout the month. The counter resets on the 1st of each month. Pro users earn rewards too, but since their reads are already unlimited, the rewards serve as a contribution score.

Example [#example]

You publish 3 knowledge entries to global (+3.0). Over the month, they get viewed 20 times (+2.0) and referenced in 10 searches (+3.0). Your effective monthly allowance becomes 30 + 8.0 = 38 global reads.

The more you contribute, the more you can read.

Detail Levels [#detail-levels]

Control how much information is returned in API responses.

| Level               | Tokens  | Content                                        |
| ------------------- | ------- | ---------------------------------------------- |
| **L1** (`summary`)  | \~100   | `title` and solution summary only              |
| **L2** (`standard`) | \~500   | L1 + full body, tags, metadata                 |
| **L3** (`full`)     | \~2,000 | L2 + comments, thought chain history, branches |

Use the string values (`summary`, `standard`, `full`) in API and CLI calls. Default is `summary`. Use `summary` for chatbot integrations where token cost matters.

Comment Types [#comment-types]

Knowledge entries support four comment types:

| Type          | Purpose                                                       |
| ------------- | ------------------------------------------------------------- |
| `supplement`  | Additional context, tips, or edge cases                       |
| `warning`     | Caveats, known issues, or conditions where the solution fails |
| `deprecation` | Mark the knowledge as outdated or superseded                  |
| `reference`   | Link to related knowledge, external docs, or resources        |

Secret Protection [#secret-protection]

workthin runs a 3-stage secret masking pipeline before storing any knowledge:

1. **Regex stage** — Pattern-based detection of common secret formats (API keys, tokens, connection strings, passwords)
2. **Entropy stage** — High-entropy string detection catches secrets that don't match known patterns
3. **AI stage** — LLM-based analysis identifies contextual secrets (e.g. internal hostnames, private IPs, proprietary identifiers)

All three stages run on every `create` and `update` operation. Detected secrets are masked with `[MASKED:pattern_name]` before storage.


---

# Overview (/docs)



What is workthin? [#what-is-workthin]

workthin is a knowledge vaccination platform. When your project solves a problem — a production outage, a tricky configuration issue, a migration pitfall — workthin captures that solution as **knowledge**. Next time anyone on the project encounters the same class of problem, workthin automatically surfaces the proven fix.

Core Concepts [#core-concepts]

| Concept                     | Description                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| **Knowledge**               | A reusable knowledge unit: title, body, AI-structured fields, and metadata                     |
| **Scope**                   | Visibility boundary — `personal`, `project`, or `global`                                       |
| **Protection Layer**        | 3-stage secret masking pipeline (regex + entropy + AI) that sanitizes knowledge before storage |
| **Detail Level**            | Response verbosity — `summary`, `standard`, `full`                                             |
| **Thought Chain**           | Linked sequence of knowledge entries via `prev_knowledge_id` for tracking evolving solutions   |
| **Branch**                  | Fork a knowledge entry via `branch_from_id` to explore alternative solutions                   |
| **Environment Fingerprint** | Captured runtime context (OS, language versions, etc.) attached to knowledge                   |
| **Contributor Rewards**     | Credit system for knowledge that gets promoted to `global` scope                               |

Architecture [#architecture]

```
Problem → Protection Layer → Match?
                              ├─ Yes → Return knowledge (auto-resolve)
                              └─ No  → Create new knowledge from solution
```

Access Methods [#access-methods]

* **CLI** — `$ wt` commands for terminal workflows
* **MCP Server** — Native integration with Claude Desktop, Claude Code, Cursor, and AI assistants
* **REST API** — Programmatic access for automation and integrations
* **Web UI** — Dashboard for browsing, creating, and managing knowledge

Next Steps [#next-steps]

* [Quick Start](/docs/quick-start) — Get running in 5 minutes
* [Concepts](/docs/concepts) — Deep dive into the data model
* [CLI Installation](/docs/cli/installation) — Install the CLI


---

# Quick Start (/docs/quick-start)



Set Up in One Command [#set-up-in-one-command]

```bash
npx workthin@latest init
```

This single command handles everything: authentication, project detection, AI tool configuration, and optional global CLI install — no pre-installation required.

> Already have `wt` installed? Run `wt init` directly instead.

Create Knowledge [#create-knowledge]

```bash
wt create "Redis connection timeout in staging" \
  --body "Redis connections drop after 30s idle in staging k8s pods. \
    Set tcp-keepalive 60 in redis.conf and \
    add timeout: 0 to prevent idle disconnection." \
  --scope project
```

AI automatically structures the body into problem, root cause, and solution fields. Tags are auto-generated by AI based on the content.

Search for Solutions [#search-for-solutions]

```bash
wt search "redis timeout kubernetes"
```

The Protection Layer returns matching knowledge ranked by relevance.

Resolve a Problem [#resolve-a-problem]

When you encounter a known problem:

```bash
wt resolve 550e8400-e29b-41d4-a716-446655440000 --comment "Confirmed fix works on staging cluster"
```

workthin marks the knowledge as resolved and adds your comment.

Set Up Your AI Workflow [#set-up-your-ai-workflow]

The fastest way to configure workthin for your AI tool:

```bash
# First time (no wt installed yet)
npx workthin@latest init

# Already have wt
wt init
```

This interactive command will:

1. **AGENTS.md** — Add the workthin knowledge loop to your project
2. **MCP config** — Configure the MCP server for your selected AI tool
3. **Tool-specific rules** — Optionally write `.cursorrules`, etc.

Supported Tools [#supported-tools]

Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code / GitHub Copilot, OpenAI Codex CLI, GitHub Copilot CLI, Gemini CLI. Any other MCP-compatible tool can connect manually via the MCP endpoint.

The Knowledge Loop [#the-knowledge-loop]

workthin works best when your AI tools follow the **search → solve → vaccinate** loop:

1. **SEARCH** — Before solving a problem, check if knowledge already exists
2. **SOLVE** — Use existing knowledge if found, or solve independently
3. **VACCINATE** — Capture the solution as new knowledge

```bash
# 1. Search first
wt search "redis timeout kubernetes"

# 2. Solve (you do this part)

# 3. Vaccinate
wt create "Fix redis timeout in k8s" \
  --body "Set tcp-keepalive 60 in redis.conf..." \
  --scope project
```

What **wt init** writes to AGENTS.md [#what-wt-init-writes-to-agentsmd]

`wt init` adds the workthin knowledge protocol to your project's `AGENTS.md`. The canonical content is always available at:

```
https://workthin.app/agents.md
```

For **desktop AI tools** (Claude Desktop, ChatGPT), copy the content from `https://workthin.app/agents.md` and paste it into the tool's Instructions or System Prompt field. See the [Claude Desktop](/docs/mcp/integrations/claude-desktop) or [ChatGPT](/docs/mcp/integrations/chatgpt) integration guide for the full text.

For **CLI tools** (Claude Code, Cursor, etc.), `wt init` fetches the content and writes it to your local `AGENTS.md` automatically.

See [MCP Integrations](/docs/mcp/integrations) for manual configuration of individual tools.

What's Next [#whats-next]

* [Concepts](/docs/concepts) — Understand knowledge, scopes, and detail levels
* [CLI Commands](/docs/cli/commands) — Full command reference
* [MCP Setup](/docs/mcp/setup) — Connect to AI assistants via MCP
* [MCP Integrations](/docs/mcp/integrations) — Claude Desktop, Claude Code, Cursor, and more
* [Skills & Commands](/docs/mcp/skills) — `/workthin` and `/workthin-search` for all AI tools


---

# Authentication (/docs/api/auth)



Base URL [#base-url]

```
https://workthin.app/api/v1
```

API Key Authentication [#api-key-authentication]

For programmatic access, use an API key as a Bearer token.

Generate an API Key [#generate-an-api-key]

1. Open the workthin web UI
2. Navigate to **Settings > API Keys**
3. Click **Create Key**
4. Copy the key (shown only once)

API keys use the `wt_` prefix (e.g. `wt_a1b2c3d4e5f6g7h8i9j0`).

Usage [#usage]

Include the key in the `Authorization` header:

```bash
curl https://workthin.app/api/v1/knowledge \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0"
```

Revoke a Key [#revoke-a-key]

Navigate to **Settings > API Keys** and click **Revoke** next to the key. Revoked keys return `401 Unauthorized` immediately.

Cookie-Based Authentication (Supabase) [#cookie-based-authentication-supabase]

The web UI uses Supabase cookie-based authentication. This is handled automatically by the browser — no manual configuration needed.

Device Code Flow (CLI) [#device-code-flow-cli]

The CLI uses a device code flow for authentication:

1. `wt login` generates a device code
2. User opens the verification URL in a browser
3. User enters the code and signs in
4. CLI receives and stores credentials in `~/.workthin/config.json`

Endpoints [#endpoints]

| Method | Path                 | Description                             |
| ------ | -------------------- | --------------------------------------- |
| `POST` | `/auth/device-code`  | Request a new device code               |
| `POST` | `/auth/device-token` | Poll for token after user authorization |

Key Scopes [#key-scopes]

Keys inherit the permissions of the user who created them. A key created by a project admin can access project-scoped knowledge.


---

# Detail Levels (/docs/api/detail-levels)



Comparison [#comparison]

|                  | `summary` (L1) | `standard` (L2) | `full` (L3) |
| ---------------- | -------------- | --------------- | ----------- |
| **Tokens**       | \~100          | \~500           | \~2,000     |
| `title`          | Yes            | Yes             | Yes         |
| `body` (summary) | Yes            | —               | —           |
| `body` (full)    | —              | Yes             | Yes         |
| `tags`           | No             | Yes             | Yes         |
| `scope`          | No             | Yes             | Yes         |
| `url`            | No             | Yes             | Yes         |
| `comments`       | No             | No              | Yes         |
| `thought_chain`  | No             | No              | Yes         |
| `branches`       | No             | No              | Yes         |

Usage [#usage]

Pass `detail` as a query parameter:

```bash
# Get by ID
curl "https://workthin.app/api/v1/knowledge/550e8400-e29b-41d4-a716-446655440000?detail=summary" \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0"

# Search
curl "https://workthin.app/api/v1/search?q=redis+timeout&detail=summary" \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0"
```

When to Use Each Level [#when-to-use-each-level]

| Level          | Best For                                                      |
| -------------- | ------------------------------------------------------------- |
| **`summary`**  | Chatbot integrations, quick lookups, token-sensitive contexts |
| **`standard`** | Interactive CLI and dashboard workflows                       |
| **`full`**     | Incident postmortems, deep analysis, audit trails             |


---

# Endpoints (/docs/api/endpoints)



Base URL [#base-url]

```
https://workthin.app/api/v1
```

Endpoints [#endpoints]

| Method   | Path                                           | Description                              |
| -------- | ---------------------------------------------- | ---------------------------------------- |
| `POST`   | `/knowledge`                                   | Create a knowledge entry                 |
| `GET`    | `/knowledge`                                   | List knowledge entries                   |
| `GET`    | `/knowledge/:id`                               | Get a knowledge entry                    |
| `PATCH`  | `/knowledge/:id`                               | Update a knowledge entry                 |
| `DELETE` | `/knowledge/:id`                               | Delete a knowledge entry                 |
| `GET`    | `/search?q=...&scope=...&limit=...&detail=...` | Search knowledge                         |
| `POST`   | `/knowledge/:id/resolve`                       | Resolve a knowledge entry                |
| `POST`   | `/knowledge/:id/comments`                      | Add a comment                            |
| `POST`   | `/knowledge/:id/publish`                       | Publish knowledge to a wider scope       |
| `POST`   | `/knowledge/:id/fork`                          | Fork a knowledge entry (create a branch) |
| `POST`   | `/projects/join`                               | Join or create a project by git remote   |
| `POST`   | `/api-keys`                                    | Generate a new API key                   |
| `DELETE` | `/api-keys`                                    | Revoke API key                           |
| `POST`   | `/oauth/register`                              | OAuth 2.1 dynamic client registration    |
| `GET`    | `/oauth/authorize`                             | OAuth 2.1 authorization endpoint         |
| `POST`   | `/oauth/token`                                 | OAuth 2.1 token endpoint                 |
| `GET`    | `/.well-known/oauth-protected-resource`        | OAuth protected resource metadata        |
| `GET`    | `/.well-known/oauth-authorization-server`      | OAuth authorization server metadata      |

Example: Create Knowledge [#example-create-knowledge]

```bash
curl -X POST https://workthin.app/api/v1/knowledge \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix CORS errors in API Gateway",
    "body": "Browser requests blocked by CORS policy. Add Access-Control-Allow-Origin header in API Gateway response.",
    "scope": "project"
  }'
```

Example: Search [#example-search]

```bash
curl "https://workthin.app/api/v1/search?q=CORS+api+gateway&limit=5&detail=standard" \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0"
```

Example: Get by ID [#example-get-by-id]

```bash
curl https://workthin.app/api/v1/knowledge/550e8400-e29b-41d4-a716-446655440000?detail=standard \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0"
```

Example: Add Comment [#example-add-comment]

```bash
curl -X POST https://workthin.app/api/v1/knowledge/550e8400-e29b-41d4-a716-446655440000/comments \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Also applies to CloudFront distributions",
    "type": "supplement"
  }'
```

Example: Fork Knowledge [#example-fork-knowledge]

```bash
curl -X POST https://workthin.app/api/v1/knowledge/550e8400-e29b-41d4-a716-446655440000/fork \
  -H "Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix CORS errors in API Gateway (alternative approach)"
  }'
```


---

# Error Codes (/docs/api/errors)



Error Format [#error-format]

All errors return a consistent JSON structure:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Knowledge 550e8400-e29b-41d4-a716-446655440000 not found",
    "status": 404
  }
}
```

Status Codes [#status-codes]

| Status | Code               | Description                                               |
| ------ | ------------------ | --------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR` | Invalid request body (missing fields, bad format)         |
| `401`  | `UNAUTHORIZED`     | Missing or invalid API key                                |
| `403`  | `FORBIDDEN`        | Key lacks permission for this scope                       |
| `404`  | `NOT_FOUND`        | Knowledge or resource not found                           |
| `409`  | `CONFLICT`         | Concurrent update conflict (etag mismatch)                |
| `429`  | `RATE_LIMITED`     | Too many requests. Retry after `Retry-After` header value |

Rate Limits [#rate-limits]

| Plan       | Requests/min |
| ---------- | ------------ |
| Free       | 60           |
| Pro        | 600          |
| Enterprise | Custom       |

The `429` response includes a `Retry-After` header with seconds to wait.


---

# Authentication (/docs/cli/auth)



Login [#login]

The default authentication method uses device code flow:

```bash
wt login
```

A URL and code are displayed in the terminal. Open the URL in your browser, enter the code, and sign in. Credentials are stored in `~/.workthin/config.json`.

Device Code Flow Details [#device-code-flow-details]

1. `wt login` initiates the device code flow and displays a URL with a one-time code
2. Open the URL in your browser and approve the request
3. An API key is generated and stored in `~/.workthin/config.json`
4. `wt init` validates saved credentials before using them — if expired, it re-initiates the login flow

API Key [#api-key]

For CI/CD and automation, set an API key via environment variable:

```bash
export WORKTHIN_API_KEY=wt_a1b2c3d4e5f6g7h8i9j0
```

Generate API keys in the web UI under **Settings > API Keys**.

Auth Status [#auth-status]

Check your current authentication state:

```bash
wt auth-status
```

Logout [#logout]

```bash
wt logout
```

Config [#config]

View or update CLI configuration:

```bash
wt config
```

Priority Order [#priority-order]

The CLI resolves credentials in this order:

1. `WORKTHIN_API_KEY` environment variable (highest priority)
2. Stored credentials from `wt login` (`~/.workthin/config.json`)


---

# Commands Reference (/docs/cli/commands)



All commands support `--json` for machine-readable output.

init [#init]

Set up workthin in the current project. Detects git remote, auto-creates/joins a project, configures MCP for your AI tool, and generates AGENTS.md.

```bash
wt init
```

The interactive setup will:

1. Authenticate (or validate existing credentials)
2. Detect git remote and auto-create/join a project
3. Ask which AI tool you use (Claude Code, Cursor, VS Code, etc.)
4. Write AGENTS.md with workthin configuration
5. Configure MCP for the selected tool
6. (Claude Code) Generate /workthin and /workthin-search skills

add [#add]

Add MCP configuration for an AI tool without running the full `wt init` flow. Useful for adding a new tool to an already-initialized project.

```bash
wt add [tool]
```

With a tool name, it configures that tool immediately:

```bash
wt add cursor
wt add vscode
wt add claude-code
```

Without a tool name, it shows an interactive selection:

```bash
wt add
```

Available tools: `claude-code`, `claude-desktop`, `cursor`, `vscode`, `codex-cli`, `copilot-cli`, `gemini-cli`

hooks [#hooks]

Set up automatic knowledge search/capture hooks for AI tools. Hooks trigger `wt search` before each prompt and remind your AI to call `create-knowledge` after each session.

```bash
wt hooks [tool]
```

With a tool name, configures hooks for that tool immediately:

```bash
wt hooks claude-code
wt hooks cursor
wt hooks gemini-cli
```

Without a tool name, shows an interactive multiselect:

```bash
wt hooks
```

Hooks can also be enabled during `wt init` when prompted.

See [Hooks](/docs/mcp/hooks) for the full list of supported events per tool.

create [#create]

Create a new knowledge entry. AI automatically structures the body content. Tags are auto-generated by AI based on the content.

```bash
wt create "Redis connection timeout in staging" \
  --body "Redis connections drop after 30s idle in staging k8s pods. Set tcp-keepalive 60 in redis.conf." \
  --scope project \
  --url "https://github.com/org/repo/issues/42"
```

| Flag            | Required | Default    | Description                               |
| --------------- | -------- | ---------- | ----------------------------------------- |
| `<title>`       | Yes      | —          | Knowledge title (positional argument)     |
| `--body`        | No       | —          | Free-form body content (AI structures it) |
| `--scope`       | No       | `personal` | `personal`, `project`, `global`           |
| `--url`         | No       | —          | Reference URL                             |
| `--branch-from` | No       | —          | UUID of knowledge to branch from          |
| `--json`        | No       | —          | Output as JSON                            |

get [#get]

Retrieve a specific knowledge entry by ID.

```bash
wt get 550e8400-e29b-41d4-a716-446655440000 --detail full
```

| Flag       | Default   | Description                                    |
| ---------- | --------- | ---------------------------------------------- |
| `--detail` | `summary` | Detail level (`summary` / `standard` / `full`) |
| `--json`   | —         | Output as JSON                                 |

update [#update]

Update an existing knowledge entry.

```bash
wt update 550e8400-e29b-41d4-a716-446655440000 \
  --title "Updated title" \
  --body "Updated body content" \
  --scope project \
  --add-tags redis,kubernetes \
  --remove-tags staging \
  --etag "abc123"
```

| Flag            | Required | Default | Description                                    |
| --------------- | -------- | ------- | ---------------------------------------------- |
| `<id>`          | Yes      | —       | Knowledge UUID (positional argument)           |
| `--title`       | No       | —       | Updated title                                  |
| `--body`        | No       | —       | Updated body                                   |
| `--scope`       | No       | —       | Updated scope: `personal`, `project`, `global` |
| `--add-tags`    | No       | —       | Comma-separated tags to add                    |
| `--remove-tags` | No       | —       | Comma-separated tags to remove                 |
| `--etag`        | No       | —       | Optimistic concurrency token                   |
| `--json`        | No       | —       | Output as JSON                                 |

list [#list]

List knowledge entries.

```bash
wt list --scope project --sort created --limit 20 --offset 0 --detail summary
```

| Flag       | Default   | Description                                             |
| ---------- | --------- | ------------------------------------------------------- |
| `--scope`  | —         | Filter by scope: `personal`, `project`, `global`, `all` |
| `--sort`   | `created` | Sort by: `created`, `resolved`, `accessed`              |
| `--limit`  | 20        | Max results                                             |
| `--offset` | 0         | Pagination offset                                       |
| `--detail` | `summary` | Detail level (`summary` / `standard` / `full`)          |
| `--json`   | —         | Output as JSON                                          |

search [#search]

Search knowledge via the Protection Layer.

```bash
wt search "kubernetes pod crashloop" --scope global --limit 5
```

| Flag      | Default        | Description                                      |
| --------- | -------------- | ------------------------------------------------ |
| `<query>` | —              | Search query (positional argument)               |
| `--scope` | all accessible | Filter by scope: `personal`, `project`, `global` |
| `--limit` | 10             | Max results                                      |
| `--json`  | —              | Output as JSON                                   |

check [#check]

Check if knowledge exists for a given query without creating anything.

```bash
wt check "redis timeout kubernetes"
```

| Flag      | Default | Description                          |
| --------- | ------- | ------------------------------------ |
| `<query>` | —       | Query to check (positional argument) |
| `--json`  | —       | Output as JSON                       |

resolve [#resolve]

Mark a knowledge entry as resolved, optionally with a comment.

```bash
wt resolve 550e8400-e29b-41d4-a716-446655440000 --comment "Confirmed fix on production"
```

| Flag        | Required | Default | Description                          |
| ----------- | -------- | ------- | ------------------------------------ |
| `<id>`      | Yes      | —       | Knowledge UUID (positional argument) |
| `--comment` | No       | —       | Resolution comment                   |
| `--json`    | No       | —       | Output as JSON                       |

comment [#comment]

Add a comment to a knowledge entry.

```bash
wt comment 550e8400-e29b-41d4-a716-446655440000 \
  --body "Also applies to ElastiCache clusters" \
  --type supplement
```

| Flag     | Required | Description                                         |
| -------- | -------- | --------------------------------------------------- |
| `<id>`   | Yes      | Knowledge UUID (positional argument)                |
| `--body` | Yes      | Comment text                                        |
| `--type` | Yes      | `supplement`, `warning`, `deprecation`, `reference` |
| `--json` | No       | Output as JSON                                      |

login [#login]

Authenticate via device code flow.

```bash
wt login
```

logout [#logout]

Clear stored credentials.

```bash
wt logout
```

auth-status [#auth-status]

Check current authentication state.

```bash
wt auth-status
```

config [#config]

View or update CLI configuration.

```bash
wt config
```


---

# Installation (/docs/cli/installation)



One command (recommended) [#one-command-recommended]

```bash
npx workthin@latest init
```

Runs setup end-to-end — authentication, project detection, MCP configuration, and optional global install. No pre-installation required.

Global install [#global-install]

```bash
npm install -g workthin
```

Install the `wt` CLI globally, then run `wt init` to configure your project.

Verify [#verify]

```bash
wt --version
```

Requirements [#requirements]

* Node.js 18+
* npm, yarn, pnpm, or bun

Update [#update]

```bash
npm install -g workthin@latest
```

Uninstall [#uninstall]

```bash
npm uninstall -g workthin
```


---

# Chatbot Integration (/docs/guides/chatbot)



Overview [#overview]

Connect workthin to your support chatbot. When a customer reports an issue, the chatbot checks workthin first. If matching knowledge exists, it resolves automatically — no human needed.

REST API Usage [#rest-api-usage]

```typescript
async function handleCustomerMessage(message: string) {
  // Search workthin for matching knowledge
  const params = new URLSearchParams({
    q: message,
    scope: 'global',
    detail: 'summary',
  })

  const res = await fetch(
    `https://workthin.app/api/v1/search?${params}`,
    {
      headers: {
        'Authorization': 'Bearer ' + process.env.WORKTHIN_API_KEY,
      },
    }
  )

  const data = await res.json()

  if (data.data && data.data.length > 0) {
    return {
      resolved: true,
      response: data.data[0].title + ': ' + data.data[0].body,
    }
  }

  // No match — escalate to human agent
  return {
    resolved: false,
    response: 'Connecting you with a support agent...',
  }
}
```

Escalation Flow [#escalation-flow]

```
Customer message
  → workthin search (summary)
    → Match found → Return solution (auto-resolve)
    → No match   → Escalate to human
                    → Human solves
                    → Create knowledge (vaccinate)
```

Projected Results [#projected-results]

Projects using this pattern report (projected):

| Metric                      | Before  | After                         |
| --------------------------- | ------- | ----------------------------- |
| Tickets escalated to humans | 100%    | \~40% (projected)             |
| Average resolution time     | 4 hours | 12 seconds auto (projected)   |
| Repeat issue rate           | High    | Decreasing weekly (projected) |

The more knowledge you create, the fewer tickets reach human agents.


---

# Incident Response (/docs/guides/incident)



Postmortem Workflow [#postmortem-workflow]

After resolving an incident, create knowledge to prevent recurrence:

```bash
wt create "Database failover caused 5min outage" \
  --body "Primary database failed, replica promotion took 5 minutes. Configure automatic failover with 30s timeout, add health check endpoint, and set up PgBouncer connection pooling. Root cause: manual failover process, no health checks on replica." \
  --scope global
```

Thought Chaining [#thought-chaining]

When an incident is related to a previous one, link them with `--branch-from` or `prev_knowledge_id`:

```bash
# First incident
wt create "Redis cluster split-brain" \
  --body "Split-brain detected in Redis cluster..." \
  --scope global --json
# Returns: { "id": "550e8400-e29b-41d4-a716-446655440000" }

# Follow-up incident (3 months later)
wt create "Redis cluster split-brain (recurrence)" \
  --body "Same split-brain issue, different trigger. Added Sentinel quorum validation." \
  --scope global
```

Chaining creates a timeline:

```
550e8400-... : Redis split-brain (initial)
  └─ 660f9500-... : Redis split-brain (recurrence)
       └─ 770a0600-... : Redis split-brain (final fix)
```

Automated Postmortem Template [#automated-postmortem-template]

Integrate with your incident management tool via the REST API:

```typescript
async function createPostmortem(incident: Incident) {
  const res = await fetch('https://workthin.app/api/v1/knowledge', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.WORKTHIN_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: `[${incident.severity}] ${incident.title}`,
      body: `${incident.description}\n\nResolution: ${incident.resolution}\n\nRoot cause: ${incident.rootCause}`,
      tags: ['incident', incident.severity, ...incident.services],
      scope: 'global',
    }),
  })

  const data = await res.json()
  return data.id
}
```


---

# Token Optimization (/docs/guides/tokens)



The Problem [#the-problem]

Without workthin, every AI-assisted resolution requires full context:

| Approach                   | Tokens per query | Monthly cost (10K queries) |
| -------------------------- | ---------------- | -------------------------- |
| Full context (no workthin) | 3,000-10,000     | $150-$500                  |
| workthin `summary`         | \~100            | $5                         |
| workthin `standard`        | \~500            | $25                        |

Summary Strategy for Chatbots [#summary-strategy-for-chatbots]

For customer-facing chatbots, use `summary` by default:

```typescript
const params = new URLSearchParams({
  q: customerMessage,
  detail: 'summary', // ~100 tokens
})

const res = await fetch(
  `https://workthin.app/api/v1/search?${params}`,
  {
    headers: {
      'Authorization': 'Bearer ' + process.env.WORKTHIN_API_KEY,
    },
  }
)
```

`summary` returns only `title` and a body summary — enough for most auto-resolutions.

If the customer needs more detail, escalate to `standard`:

```typescript
const detailed = await fetch(
  `https://workthin.app/api/v1/knowledge/${knowledgeId}?detail=standard`,
  {
    headers: {
      'Authorization': 'Bearer ' + process.env.WORKTHIN_API_KEY,
    },
  }
)
```

Cost Calculation [#cost-calculation]

|                      | Without workthin | With workthin (`summary`) |
| -------------------- | ---------------- | ------------------------- |
| Queries/month        | 10,000           | 10,000                    |
| Tokens/query         | \~5,000          | \~100                     |
| Total tokens         | 50M              | 1M                        |
| Cost (GPT-4 pricing) | \~$500/mo        | \~$10/mo                  |
| **Annual savings**   | —                | **$5,880**                |

For organizations with 100K+ queries/month, annual savings exceed **$48,000**.

Best Practices [#best-practices]

1. **Default to `summary`** for automated integrations
2. **Use `standard`** for interactive CLI and dashboard workflows
3. **Reserve `full`** for incident postmortems and deep analysis
4. **Cache `summary` responses** — they rarely change and are small enough to store


---

# Integrations (/docs/mcp/integrations)



Select your AI tool to get started:

* [Claude Desktop](/docs/mcp/integrations/claude-desktop) — OAuth Connectors (no API key required)
* [Claude Code](/docs/mcp/integrations/claude-code) — CLI one-liner setup
* [VS Code / GitHub Copilot](/docs/mcp/integrations/vscode) — Built-in MCP support (v1.99+)
* [Cursor](/docs/mcp/integrations/cursor) — Global MCP config
* [OpenAI Codex CLI](/docs/mcp/integrations/codex-cli) — TOML config
* [GitHub Copilot CLI](/docs/mcp/integrations/github-copilot) — `mcp.json` config
* [Gemini CLI](/docs/mcp/integrations/gemini-cli) — `settings.json` config

Not using any of the above? Any MCP-compatible tool can connect to:

* **URL**: `https://workthin.app/api/mcp`
* **Transport**: Streamable HTTP
* **Auth**: `Authorization: Bearer <your-api-key>`

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.


---

# Setup (/docs/mcp/setup)



Overview [#overview]

The workthin MCP server is an HTTP endpoint that exposes knowledge tools for AI assistants. Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) can search, create, and resolve knowledge directly.

Endpoint [#endpoint]

```
https://workthin.app/api/mcp
```

Transport: HTTP (Streamable HTTP / SSE)

Authentication [#authentication]

Use an API key as a Bearer token:

```
Authorization: Bearer wt_a1b2c3d4e5f6g7h8i9j0
```

Generate API keys in the web UI under **Settings > API Keys**.

:::note
workthin uses OAuth 2.1 for MCP HTTP transport authentication. Claude Code handles the OAuth flow automatically. Existing API key auth (`wt_` prefix) is also supported for CLI and other clients.
:::

Available Tools [#available-tools]

| Tool                | Description                                                                    |
| ------------------- | ------------------------------------------------------------------------------ |
| `search-knowledge`  | Search knowledge by natural language query                                     |
| `create-knowledge`  | Create a new knowledge entry from a solved problem                             |
| `resolve-knowledge` | Mark a knowledge entry as resolved                                             |
| `get-knowledge`     | Retrieve a specific knowledge entry by ID                                      |
| `update-knowledge`  | Update an existing knowledge entry                                             |
| `list-knowledge`    | List knowledge entries with filters                                            |
| `delete-knowledge`  | Delete a knowledge entry                                                       |
| `comment-knowledge` | Add a comment to a knowledge entry                                             |
| `check-knowledge`   | Check if knowledge exists for a query                                          |
| `get-chain`         | Get the thought chain (ancestors, descendants, branches) for a knowledge entry |

Verify [#verify]

After configuration, your AI assistant should list workthin tools. Test with:

> "Search workthin for redis timeout solutions"

See [Integrations](/docs/mcp/integrations) for setup instructions for specific clients.


---

# Skills & Commands (/docs/mcp/skills)



Overview [#overview]

When you run `wt init` or `wt add`, workthin automatically generates slash commands for your selected AI tool:

* **`/workthin`** — Capture the current session's solution as knowledge
* **`/workthin-search`** — Search for existing knowledge before solving a problem

These files are committed to git, so all team members get them automatically.

Supported Tools [#supported-tools]

| Tool               | Format       | Location                             |
| ------------------ | ------------ | ------------------------------------ |
| Claude Code        | `SKILL.md`   | `.claude/skills/workthin/`           |
| OpenAI Codex CLI   | `SKILL.md`   | `.agents/skills/workthin/`           |
| GitHub Copilot CLI | `.prompt.md` | `.github/prompts/workthin.prompt.md` |
| Cursor             | Markdown     | `.cursor/commands/workthin.md`       |
| Gemini CLI         | TOML         | `.gemini/commands/workthin.toml`     |

/workthin — Capture Knowledge [#workthin--capture-knowledge]

Use after solving a problem to record the solution.

```
/workthin
```

What it does:

1. Reviews the current conversation
2. Identifies the key problem(s) solved
3. Checks for duplicate knowledge (`check-knowledge`)
4. Creates a new knowledge entry with AI-structured problem/solution
5. Returns `suggested_scope` — if it recommends a different scope, asks you to confirm

For multiple problems in one session, it creates separate entries and chains them with `prev_knowledge_id`.

/workthin-search — Find Existing Knowledge [#workthin-search--find-existing-knowledge]

Use when encountering a technical issue to check if a solution already exists.

```
/workthin-search redis connection timeout
```

What it does:

1. Searches workthin with the problem description
2. Shows top matches with titles and solution summaries
3. Retrieves full details if needed
4. If no results found, reminds you to use `/workthin` after solving

Auto-invocation [#auto-invocation]

Both commands can be invoked automatically by your AI tool when it detects a relevant situation:

* **`/workthin`** — triggered when a problem has been solved
* **`/workthin-search`** — triggered when encountering a technical issue

This enables the **search → solve → capture** loop without manual intervention.

Claude Code Extras [#claude-code-extras]

When Claude Code is selected, `wt init` / `wt add` also adds a **SessionStart hook** to `.claude/settings.json`:

> workthin connected. SEARCH before solving, capture after. Use /workthin to save solutions.

This reminder is displayed at the start of every session.

File Locations by Tool [#file-locations-by-tool]

Claude Code [#claude-code]

```
.claude/
├── skills/
│   ├── workthin/
│   │   └── SKILL.md
│   └── workthin-search/
│       └── SKILL.md
└── settings.json          # SessionStart hook
```

Cursor [#cursor]

```
.cursor/
└── commands/
    ├── workthin.md
    └── workthin-search.md
```

GitHub Copilot CLI [#github-copilot-cli]

```
.github/
└── prompts/
    ├── workthin.prompt.md
    └── workthin-search.prompt.md
```

Gemini CLI [#gemini-cli]

```
.gemini/
└── commands/
    ├── workthin.toml
    └── workthin-search.toml
```

OpenAI Codex CLI [#openai-codex-cli]

```
.agents/
└── skills/
    ├── workthin/
    │   └── SKILL.md
    └── workthin-search/
        └── SKILL.md
```


---

# Tools Reference (/docs/mcp/tools)



:::note
All MCP tools require a `user_id` to identify who is creating or modifying knowledge. In practice, the MCP server authenticates via the API key and resolves `user_id` automatically from the key — you do not need to pass it explicitly.
:::

search-knowledge [#search-knowledge]

```json
{
  "name": "search-knowledge",
  "arguments": {
    "query": "kubernetes pod crashloop after deploy",
    "scope": "global",
    "limit": 5,
    "detail": "standard"
  }
}
```

**Response** includes an array of matching knowledge entries with relevance scores.

create-knowledge [#create-knowledge]

```json
{
  "name": "create-knowledge",
  "arguments": {
    "title": "Fix OOM kills in Node.js containers",
    "body": "Node.js containers get OOM killed under load in k8s. Set --max-old-space-size to 75% of container memory limit. Root cause: V8 heap grows beyond container memory limit by default.",
    "scope": "project"
  }
}
```

The response includes a `suggested_scope` field with an AI-recommended scope and reason. If the suggested scope differs from the saved scope, consider updating it via `update-knowledge`.

resolve-knowledge [#resolve-knowledge]

```json
{
  "name": "resolve-knowledge",
  "arguments": {
    "knowledge_id": "550e8400-e29b-41d4-a716-446655440000",
    "comment": "Confirmed fix works on production cluster"
  }
}
```

Marks the knowledge entry as resolved and adds an optional comment.

get-knowledge [#get-knowledge]

```json
{
  "name": "get-knowledge",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "detail": "full"
  }
}
```

update-knowledge [#update-knowledge]

```json
{
  "name": "update-knowledge",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "body": "Updated: set --max-old-space-size AND configure resource limits in deployment.yaml",
    "add_tags": ["production"],
    "remove_tags": ["draft"]
  }
}
```

list-knowledge [#list-knowledge]

```json
{
  "name": "list-knowledge",
  "arguments": {
    "scope": "project",
    "limit": 10
  }
}
```

delete-knowledge [#delete-knowledge]

```json
{
  "name": "delete-knowledge",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

comment-knowledge [#comment-knowledge]

```json
{
  "name": "comment-knowledge",
  "arguments": {
    "knowledge_id": "550e8400-e29b-41d4-a716-446655440000",
    "body": "Also applies to ElastiCache clusters",
    "type": "supplement"
  }
}
```

Comment types: `supplement`, `warning`, `deprecation`, `reference`.

check-knowledge [#check-knowledge]

```json
{
  "name": "check-knowledge",
  "arguments": {
    "query": "redis timeout kubernetes"
  }
}
```

Returns matching knowledge if it exists, without creating anything.


---

# Access Control (/docs/security/access-control)



Scopes [#scopes]

| Scope      | Who Can Read     | Who Can Write    |
| ---------- | ---------------- | ---------------- |
| `personal` | Only the creator | Only the creator |
| `project`  | Project members  | Only the creator |
| `global`   | Everyone         | Only the creator |

Row Level Security (RLS) [#row-level-security-rls]

Every database query is filtered by PostgreSQL RLS policies:

* **Knowledge**: Scope-based visibility enforced at the database level
* **Comments**: Visible if the parent knowledge is visible
* **Resolves**: Visible if the parent knowledge is visible
* **Project members**: Visible to project members only
* **Security rules**: Modifiable by project admins only

API Authentication [#api-authentication]

Two methods:

1. **Bearer Token** — `Authorization: Bearer wt_xxx` (CLI, MCP, API)
2. **Cookie Auth** — Supabase session cookie (Web UI)

API keys are SHA-256 hashed before storage. Original keys are never stored.

Project Roles [#project-roles]

| Role     | Permissions                                                        |
| -------- | ------------------------------------------------------------------ |
| `admin`  | Full access: invite, remove, change roles, manage security rules   |
| `member` | Create, read, update, delete own knowledge. Read project knowledge |
| `viewer` | Read-only access to project knowledge                              |


---

# Security Overview (/docs/security/overview)



Architecture [#architecture]

workthin implements defense-in-depth:

1. **Secret Protection** — 3-stage pipeline masks secrets before storage
2. **Access Control** — Row Level Security (RLS) per user and project
3. **Encryption** — AES-256 at rest, TLS 1.3 in transit
4. **API Authentication** — Bearer token + Supabase cookie auth

Sub-processors [#sub-processors]

| Service  | Purpose                         | Data Location |
| -------- | ------------------------------- | ------------- |
| Supabase | Database, Auth, Storage         | US            |
| Vercel   | Hosting, CDN                    | US            |
| OpenAI   | Structuring, Tagging, Embedding | US            |
| Stripe   | Payments                        | US            |
| PostHog  | Analytics                       | US            |
| Upstash  | Rate Limiting                   | US            |

Data Policy [#data-policy]

* We do **not** use your data to train AI models
* You own your data — export or delete anytime
* GDPR-ready data deletion on request

AI Data Handling [#ai-data-handling]

workthin uses the OpenAI API for structuring, tagging, embedding, and classification. API data is not used for model training:

> **"OpenAI does not train on data sent via the API by default."**
>
> — [Your data | OpenAI Platform](https://developers.openai.com/api/docs/guides/your-data)

See also: [Enterprise privacy at OpenAI](https://openai.com/enterprise-privacy/), [How your data is used](https://openai.com/policies/how-your-data-is-used-to-improve-model-performance/)


---

# Secret Protection (/docs/security/secret-protection)



Pipeline Overview [#pipeline-overview]

Every knowledge entry passes through 3 stages before storage:

Stage 1: Regex Patterns (20+ built-in) [#stage-1-regex-patterns-20-built-in]

| Pattern             | Example Detected                         |
| ------------------- | ---------------------------------------- |
| AWS Access Key      | `AKIAIOSFODNN7EXAMPLE`                   |
| GitHub Token        | `ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgh` |
| OpenAI Key          | `sk-proj-...` (80+ chars)                |
| Stripe Secret       | `sk_live_...`                            |
| Private Key         | `-----BEGIN RSA PRIVATE KEY-----`        |
| JWT                 | `eyJhbGci...` (3-part structure)         |
| DB Connection       | `postgres://user:pass@host/db`           |
| Password Assignment | `password="secret123"`                   |

Stage 2: Entropy Detection [#stage-2-entropy-detection]

Catches secrets that don't match known patterns. Uses Shannon entropy to find high-randomness strings near keywords like `key`, `token`, `secret`, `auth`.

Stage 3: AI Classification [#stage-3-ai-classification]

GPT-5-mini fallback for ambiguous content. Only runs when Stages 1-2 find nothing in text longer than 100 characters.

Detection Examples [#detection-examples]

**Input:**

```
My API key is sk-proj-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
```

**After protection:**

```
My API key is [MASKED:openai_key]
```

***

**Input:**

```
Connect to postgres://admin:s3cret_p4ss@db.prod.example.com:5432/myapp
```

**After protection:**

```
Connect to [MASKED:connection_string]
```

***

**Input:**

```
Set SECRET_TOKEN=aF3kR9mN2xP7qW4sD8jL1bV6yT0uE5hZ
```

**After protection:**

```
Set [MASKED:env_secret_assignment]
```

What Passes Safely [#what-passes-safely]

These are **not** detected as secrets:

* UUIDs: `550e8400-e29b-41d4-a716-446655440000`
* URLs without credentials: `https://docs.example.com/api/v1`
* Short hashes: `abc123def` (under 16 characters)
* Package versions: `next@16.1.6`
* Normal code: function names, variable names, imports

Custom Rules [#custom-rules]

Projects can add custom regex patterns via **Settings > Security Rules**:

1. Add a regex pattern (e.g., `INTERNAL_.*_KEY`)
2. Choose action: **Mask** (replace with placeholder) or **Block** (prevent saving)
3. Test with sample input before saving
4. Enable/disable rules at any time


---

# Claude Code Hooks (/docs/mcp/hooks/claude-code)



Auto [#auto]

```bash
wt hooks claude-code
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` adds the following hooks to `~/.claude/settings.json` (user-level, applies to all projects):

| Event              | Action                                    |
| ------------------ | ----------------------------------------- |
| `SessionStart`     | Pre-loads project knowledge into context  |
| `UserPromptSubmit` | Searches workthin with your prompt        |
| `Stop`             | Reminds Claude to call `create-knowledge` |
| `SessionEnd`       | Same reminder at session end              |

Manual [#manual]

Add to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wt search \"${CLAUDE_USER_PROMPT:0:300}\" --hook 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '{\"systemMessage\": \"Session ending. If you solved a problem, call create-knowledge.\"}'"
          }
        ]
      }
    ]
  }
}
```

Verify [#verify]

Start a new Claude Code session and ask a technical question. If matching knowledge exists in workthin, it will appear as context before Claude responds.


---

# OpenAI Codex CLI Hooks (/docs/mcp/hooks/codex-cli)



Auto [#auto]

```bash
wt hooks codex-cli
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` writes `~/.codex/hooks.json` (user-level, applies to all projects) with the following hooks:

| Event              | Action                                    |
| ------------------ | ----------------------------------------- |
| `SessionStart`     | Pre-loads project knowledge into context  |
| `UserPromptSubmit` | Searches workthin with your prompt        |
| `Stop`             | Reminds the AI to call `create-knowledge` |

> **Note:** Codex CLI does not support a `SessionEnd` event. Use `Stop` to capture knowledge at the end of each agent turn.

Manual [#manual]

Create `~/.codex/hooks.json`:

```json
{
  "hooks": {
    "SessionStart": {
      "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
    },
    "UserPromptSubmit": {
      "command": "wt search \"$CODEX_USER_PROMPT\" --hook 2>/dev/null || true"
    },
    "Stop": {
      "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
    }
  }
}
```

See the [Codex CLI hooks documentation](https://github.com/openai/codex/blob/main/codex-cli/docs/hooks.md) for more details.


---

# Cursor Hooks (/docs/mcp/hooks/cursor)



Auto [#auto]

```bash
wt hooks cursor
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` writes `~/.cursor/hooks.json` (user-level, applies to all projects) with the following hooks:

| Event                | Action                                    |
| -------------------- | ----------------------------------------- |
| `sessionStart`       | Pre-loads project knowledge into context  |
| `beforeSubmitPrompt` | Searches workthin with your prompt        |
| `stop`               | Reminds the AI to call `create-knowledge` |
| `sessionEnd`         | Same reminder at session end              |

Manual [#manual]

Create `~/.cursor/hooks.json`:

```json
{
  "hooks": [
    {
      "event": "sessionStart",
      "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
    },
    {
      "event": "beforeSubmitPrompt",
      "command": "wt search \"$CURSOR_USER_PROMPT\" --hook 2>/dev/null || true"
    },
    {
      "event": "stop",
      "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
    },
    {
      "event": "sessionEnd",
      "command": "printf '{\"systemMessage\": \"Session ending. If you solved a problem, call create-knowledge.\"}'"
    }
  ]
}
```

See the [Cursor hooks documentation](https://docs.cursor.com/agent/hooks) for more details on available events.


---

# Gemini CLI Hooks (/docs/mcp/hooks/gemini-cli)



Auto [#auto]

```bash
wt hooks gemini-cli
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` adds the following hooks to `~/.gemini/settings.json`:

| Event          | Action                                    |
| -------------- | ----------------------------------------- |
| `SessionStart` | Pre-loads project knowledge into context  |
| `BeforeAgent`  | Searches workthin with your prompt        |
| `AfterAgent`   | Reminds the AI to call `create-knowledge` |
| `SessionEnd`   | Same reminder at session end              |

Manual [#manual]

Add to `~/.gemini/settings.json`:

```json
{
  "hooks": {
    "SessionStart": {
      "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
    },
    "BeforeAgent": {
      "command": "wt search \"$GEMINI_USER_PROMPT\" --hook 2>/dev/null || true"
    },
    "AfterAgent": {
      "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
    },
    "SessionEnd": {
      "command": "printf '{\"systemMessage\": \"Session ending. If you solved a problem, call create-knowledge.\"}'"
    }
  }
}
```

See the [Gemini CLI hooks documentation](https://google-gemini.github.io/gemini-cli/docs/hooks) for more details.

:::note
`wt init` also creates `/workthin` and `/workthin-search` skills in `~/.agents/skills/` (shared with Codex CLI). Gemini CLI auto-scans this directory.
:::


---

# GitHub Copilot Hooks (/docs/mcp/hooks/github-copilot)



Auto [#auto]

```bash
wt hooks copilot-cli
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` writes `~/.github/copilot/hooks.json` (user-level, applies to all projects) with the following hooks:

| Event                 | Action                                    |
| --------------------- | ----------------------------------------- |
| `sessionStart`        | Pre-loads project knowledge into context  |
| `userPromptSubmitted` | Searches workthin with your prompt        |
| `mainAgentStop`       | Reminds the AI to call `create-knowledge` |
| `sessionEnd`          | Same reminder at session end              |

Manual [#manual]

Create `~/.github/copilot/hooks.json`:

```json
{
  "hooks": [
    {
      "event": "sessionStart",
      "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
    },
    {
      "event": "userPromptSubmitted",
      "command": "wt search \"$GITHUB_COPILOT_PROMPT\" --hook 2>/dev/null || true"
    },
    {
      "event": "mainAgentStop",
      "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
    },
    {
      "event": "sessionEnd",
      "command": "printf '{\"systemMessage\": \"Session ending. If you solved a problem, call create-knowledge.\"}'"
    }
  ]
}
```

See the [GitHub Copilot hooks documentation](https://docs.github.com/copilot/concepts/agents/coding-agent/about-hooks) for more details.


---

# Hooks (/docs/mcp/hooks)



Hooks let workthin run automatically in the background: searching for relevant knowledge at session start and before each prompt, and reminding you to capture solutions when a session ends.

How it works [#how-it-works]

<Mermaid
  chart="sequenceDiagram
    participant User
    participant AI as AI Tool
    participant Hook
    participant wt as workthin

    User->>AI: Start session
    AI->>Hook: SessionStart
    Hook->>wt: wt search &#x22;recent solutions&#x22;
    wt-->>AI: Inject project knowledge

    User->>AI: Submit prompt
    AI->>Hook: UserPromptSubmit
    Hook->>wt: wt search prompt
    wt-->>AI: Inject relevant knowledge
    AI->>User: Response with context

    User->>AI: Solve problem
    AI->>Hook: Stop / SessionEnd
    Hook-->>AI: Remind to capture
    AI->>wt: create-knowledge"
/>

Setup [#setup]

```bash
wt hooks
```

Or add hooks to a specific tool:

```bash
wt hooks cursor
```

Hooks can also be enabled during `wt init` — you will be prompted automatically.

Supported Tools [#supported-tools]

| Tool                                   | Session start | Search on prompt | Capture | Session end |
| -------------------------------------- | :-----------: | :--------------: | :-----: | :---------: |
| [Claude Code](./claude-code)           |       ✓       |         ✓        |    ✓    |      ✓      |
| [Cursor](./cursor)                     |       ✓       |         ✓        |    ✓    |      ✓      |
| [VS Code](./vscode)                    |       ✓       |         ✓        |    ✓    |      —      |
| [GitHub Copilot CLI](./github-copilot) |       ✓       |         ✓        |    ✓    |      ✓      |
| [OpenAI Codex CLI](./codex-cli)        |       ✓       |         ✓        |    ✓    |      —      |
| [Gemini CLI](./gemini-cli)             |       ✓       |         ✓        |    ✓    |      ✓      |

ChatGPT and Claude Desktop do not support hooks — use [Instructions](/docs/mcp/integrations/claude-desktop#add-workthin-instructions) instead.

Hook behavior [#hook-behavior]

**On session start** — `wt search "project recent solutions" --hook` pre-loads relevant project knowledge into context.

**On prompt submission** — `wt search "<prompt>" --hook` runs in the background. If matching knowledge exists, it is injected as a system message before the AI responds.

**On stop / session end*&#x2A; — A system message reminds the AI: &#x2A;"If you solved a problem, call create-knowledge to capture it."* The AI then calls the `create-knowledge` MCP tool directly.


---

# VS Code Hooks (/docs/mcp/hooks/vscode)



Auto [#auto]

```bash
wt hooks vscode
```

Or enable during `wt init` when prompted.

What gets written [#what-gets-written]

`wt hooks` creates `~/.copilot/hooks/workthin.json` (user-level, applies to all projects) with the following hooks:

| Event              | Action                                    |
| ------------------ | ----------------------------------------- |
| `SessionStart`     | Pre-loads project knowledge into context  |
| `UserPromptSubmit` | Searches workthin with your prompt        |
| `Stop`             | Reminds the AI to call `create-knowledge` |

> **Note:** VS Code does not support a `SessionEnd` event. Use `Stop` to capture knowledge at the end of each agent turn.

Manual [#manual]

Create `~/.copilot/hooks/workthin.json`:

```json
{
  "hooks": [
    {
      "event": "SessionStart",
      "command": "wt search \"project recent solutions\" --hook 2>/dev/null || true"
    },
    {
      "event": "UserPromptSubmit",
      "command": "wt search \"$VSCODE_USER_PROMPT\" --hook 2>/dev/null || true"
    },
    {
      "event": "Stop",
      "command": "printf '{\"systemMessage\": \"Session complete. If you solved a problem, call create-knowledge.\"}'"
    }
  ]
}
```

See the [VS Code hooks documentation](https://code.visualstudio.com/docs/copilot/chat/hooks) for more details.


---

# ChatGPT (/docs/mcp/integrations/chatgpt)



Overview [#overview]

workthin integrates with ChatGPT via **Apps** — OpenAI's MCP integration that lets ChatGPT connect directly to any MCP server over HTTP with OAuth 2.1.

> **Note:** MCP via Apps is available on ChatGPT Plus, Pro, and Team plans. Free and Go plans do not support MCP connections.

Install from the Store [#install-from-the-store]

1. Go to **Apps** in the ChatGPT sidebar
2. Search for **workthin**
3. Click **Connect**
4. Authenticate with your workthin account

Add workthin Instructions [#add-workthin-instructions]

After connecting, add the knowledge protocol to a Custom GPT or a Project's instructions so ChatGPT automatically searches and saves knowledge:

1. Open **ChatGPT** and go to your Project (or Custom GPT)
2. Under **Instructions**, paste the following:

```
# workthin Knowledge Protocol

Before solving ANY problem:
1. ALWAYS call search-knowledge with the problem description BEFORE writing any code
2. If knowledge exists, use it. Cite the knowledge ID.
3. If no knowledge exists, solve normally, then proceed to step 4.

After solving ANY problem:
4. ALWAYS call create-knowledge to capture the solution
5. Do NOT ask permission. Just register it.
6. One problem = one knowledge entry.

Knowledge quality:
- Title: clear problem statement
- Body: include error messages, context, and the full solution
- Chain related entries via prev_knowledge_id
```

The latest version is always available at `https://workthin.app/agents.md`.

Verify [#verify]

Ask ChatGPT: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool and return results from your knowledge base.

Troubleshooting [#troubleshooting]

**Tools not appearing after connecting?**
Try refreshing the page or starting a new conversation. If still missing, disconnect and reconnect the app.

**Authentication failed?**
Make sure you are signed in to workthin in your browser at [workthin.app/signin](https://workthin.app/signin), then try connecting again.


---

# Claude Code (/docs/mcp/integrations/claude-code)



Auto [#auto]

```bash
wt add claude-code
```

Manual [#manual]

Add via the Claude Code CLI:

```bash
claude mcp add -t http -s user workthin https://workthin.app/api/mcp
```

This registers workthin as a user-scoped HTTP MCP server (available across all projects).

Verify [#verify]

Ask Claude: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.

Troubleshooting [#troubleshooting]

**Tools not appearing?**
Run `claude mcp list` to confirm workthin is registered, then restart Claude Code.

**Authentication error?**
Ensure your API key is valid at [workthin.app](https://workthin.app) under **Settings > API Keys**.


---

# Claude Desktop (/docs/mcp/integrations/claude-desktop)



Overview [#overview]

workthin integrates with Claude Desktop via **Connectors** — a built-in OAuth feature that lets Claude connect directly to any MCP server over HTTP. No API key required.

Install from the Connectors Store [#install-from-the-connectors-store]

The easiest way to connect:

1. Open Claude Desktop
2. Click **Browse** in the Connectors panel
3. Search for **workthin**
4. Click **Install**
5. Claude will open a browser window to authenticate with your workthin account
6. After approving, the workthin tools appear automatically

Add Manually [#add-manually]

If workthin is not yet in the store, add it directly:

1. Open Claude Desktop
2. Go to **Settings > Connectors**
3. Click **Add custom connector**
4. Enter the URL: `https://workthin.app/api/mcp`
5. Claude will open a browser window to authenticate
6. After approving, the workthin tools appear automatically

Add workthin Instructions [#add-workthin-instructions]

After connecting, add the knowledge protocol to Claude's Instructions so it automatically searches and saves knowledge:

1. Open Claude Desktop
2. Go to **Settings > Claude** (or your profile)
3. Under **Instructions**, paste the following:

```
# workthin Knowledge Protocol

Before solving ANY problem:
1. ALWAYS call search-knowledge with the problem description BEFORE writing any code
2. If knowledge exists, use it. Cite the knowledge ID.
3. If no knowledge exists, solve normally, then proceed to step 4.

After solving ANY problem:
4. ALWAYS call create-knowledge to capture the solution
5. Do NOT ask permission. Just register it.
6. One problem = one knowledge entry.

Knowledge quality:
- Title: clear problem statement
- Body: include error messages, context, and the full solution
- Chain related entries via prev_knowledge_id
```

The latest version is always available at `https://workthin.app/agents.md`.

Verify [#verify]

Ask Claude: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.

Troubleshooting [#troubleshooting]

**Tools not appearing after connecting?**
Restart Claude Desktop after adding the connector.

**Authentication failed?**
First, make sure you are signed in to workthin in your browser. If not, go to [workthin.app/signin](https://workthin.app/signin) and log in, then try connecting again. If still failing, remove the connector and re-add it.


---

# OpenAI Codex CLI (/docs/mcp/integrations/codex-cli)



Auto [#auto]

```bash
wt add codex-cli
```

Manual [#manual]

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.workthin]
type = "http"
url = "https://workthin.app/api/mcp"

[mcp_servers.workthin.headers]
Authorization = "Bearer wt_your_api_key"
```

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.

Verify [#verify]

Ask Codex: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.


---

# Cursor (/docs/mcp/integrations/cursor)



Auto [#auto]

```bash
wt add cursor
```

Manual [#manual]

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "workthin": {
      "url": "https://workthin.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wt_your_api_key"
      }
    }
  }
}
```

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.

Verify [#verify]

Ask the AI: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.

Troubleshooting [#troubleshooting]

**Tools not appearing?**
Restart Cursor after editing `mcp.json`.


---

# Gemini CLI (/docs/mcp/integrations/gemini-cli)



Auto [#auto]

```bash
wt add gemini-cli
```

Manual [#manual]

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "workthin": {
      "httpUrl": "https://workthin.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wt_your_api_key"
      }
    }
  }
}
```

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.

Verify [#verify]

Ask Gemini: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.


---

# GitHub Copilot CLI (/docs/mcp/integrations/github-copilot)



Auto [#auto]

```bash
wt add copilot-cli
```

Manual [#manual]

Add to `~/.github/copilot/mcp.json`:

```json
{
  "servers": {
    "workthin": {
      "type": "http",
      "url": "https://workthin.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wt_your_api_key"
      }
    }
  }
}
```

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.

Verify [#verify]

Ask Copilot CLI: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.


---

# Integrations (/docs/mcp/integrations/index)



Select your AI tool to get started:

* [Claude Desktop](/docs/mcp/integrations/claude-desktop) — OAuth Connectors (no API key required)
* [Claude Code](/docs/mcp/integrations/claude-code) — CLI one-liner setup
* [ChatGPT](/docs/mcp/integrations/chatgpt) — Apps & Connectors (Plus/Pro/Team)
* [VS Code / GitHub Copilot](/docs/mcp/integrations/vscode) — Built-in MCP support (v1.99+)
* [Cursor](/docs/mcp/integrations/cursor) — Global MCP config
* [OpenAI Codex CLI](/docs/mcp/integrations/codex-cli) — TOML config
* [GitHub Copilot CLI](/docs/mcp/integrations/github-copilot) — `mcp.json` config
* [Gemini CLI](/docs/mcp/integrations/gemini-cli) — `settings.json` config

Not using any of the above? Any MCP-compatible tool can connect to:

* **URL**: `https://workthin.app/api/mcp`
* **Transport**: Streamable HTTP
* **Auth**: `Authorization: Bearer <your-api-key>`

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.


---

# VS Code / GitHub Copilot (/docs/mcp/integrations/vscode)



Auto [#auto]

```bash
wt add vscode
```

Manual [#manual]

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "workthin": {
      "type": "http",
      "url": "https://workthin.app/api/mcp",
      "headers": {
        "Authorization": "Bearer wt_your_api_key"
      }
    }
  }
}
```

Get your API key at [workthin.app](https://workthin.app) under **Settings > API Keys**.

Verify [#verify]

Ask Copilot: "Search workthin for recent knowledge" — it should call the `search-knowledge` tool.

Troubleshooting [#troubleshooting]

**Tools not appearing?**
Ensure you are running VS Code v1.99 or later. Reload the window after saving settings.