---
title: "What Katman can read, write and send: permissions"
description: "What Katman reads in your project, what it writes, which network calls it makes and when, what goes to katman.pro with your key, and how it handles your keys."
url: https://katman.pro/docs/permissions
lang: en
updated: 2026-09-30
---

Docs Updated 30 Sep 2026

# Permissions: what Katman can do

> Katman reads the files in your project but never your secrets, writes only to the .katman folder unless you explicitly ask for a generated file, and makes network calls only when a tool needs them. It contacts katman.pro for two things only: a plan check, at most once a day, that sends your KATMAN_KEY and the MCP version, and katman_sync, which sends a project summary only when you call it. Code, file contents, AI answers and your OpenRouter key are never sent to katman.pro.

## In short

|  | What Katman does |
| --- | --- |
| Reads | Files under your project root, except dependencies, build output and secrets |
| Writes | Only the `.katman/` folder, plus two opt-in files you ask for, and a licence cache in `~/.katman/license.json` |
| Network | Only when a tool needs it: your site, OpenRouter, IndexNow, Google autocomplete, and katman.pro for the plan check and `katman_sync` |
| katman.pro | Your key and the MCP version, at most once a day, for the plan check; `katman_sync` summaries only when you call it |
| Secrets | `KATMAN_KEY` and your OpenRouter key are read from the environment, never saved or printed |
| Telemetry | None |
| Consumer chat apps | Never automated |

## What Katman reads

Katman reads files under your project root so it can understand your framework, routes, head tags and content. It skips:

-   `node_modules`, `.git` and build output folders;
-   `.env*` and `.dev.vars*` files;
-   `*.pem`, `*.key` and `*.p12` files;
-   any file with `secret` or `credential` in its name.

The project root is the folder you pass as `project_root`, or `KATMAN_PROJECT_ROOT`, or the root your MCP client reports, or the current folder, in that order.

## What Katman writes

Katman writes only to `.katman/` inside your project: research, scans, audits, visibility runs, the plan, a report and a dated log. The folder never contains secrets, so it’s safe to commit. The full file list is in [Getting started](https://katman.pro/docs/getting-started).

Two tools can write elsewhere, and only when you pass `write: true`:

-   `katman_generate` writes the file you asked for, such as `robots.txt` or `llms.txt`;
-   `katman_setup_monitoring` writes `.github/workflows/katman.yml`.

Neither replaces an existing file unless you also pass `overwrite: true`. Everything else in your code is changed by your AI coding tool, under that tool’s own approval settings, not by Katman.

Katman also keeps one file outside your project: `~/.katman/license.json`, the answer of the last plan check, stored under the SHA-256 hash of your key (never the key itself).

## What Katman sends over the network

Each call happens only when you, or your agent, call the tool that needs it.

| Destination | Tool | When |
| --- | --- | --- |
| Your own site’s URLs | `katman_audit_site`, `katman_lint_content` with a URL, `katman_indexnow` (to check your key file) | Each time you audit or verify |
| `openrouter.ai` | `katman_visibility_run`; one small judge call in `katman_manual_check` if an OpenRouter key is set | Only with your key, and paid runs only after a dry-run estimate |
| `api.indexnow.org` | `katman_indexnow` | Only with `dry_run: false` |
| `suggestqueries.google.com` | `katman_keywords` | Throttled, at most 40 requests per call |
| `katman.pro` (plan check) | Every tool (`katman_account` only when a key is set) | At most once a day |
| `katman.pro` (sync) | `katman_sync` | Only with `dry_run: false` |

Installing or starting Katman with `npx` also downloads the package from the npm registry. That’s npm, not Katman.

## What goes to katman.pro

Every tool except `katman_account` needs `KATMAN_KEY`. With the key, Katman contacts katman.pro for two things, and nothing else:

1.  **The plan check.** Before a tool runs, Katman needs to know your plan, so it sends your key and the MCP version to katman.pro, at most once a day. No tool names, no project data. The answer (your plan, when Audit Week ends if you’re on it, and the features the key unlocks) is cached on your machine. If katman.pro can’t be reached, the tools keep working for 7 days after the last successful check; Audit Week never runs past its end date.
2.  **`katman_sync`** (Pro), only when you call it with `dry_run: false`. The dry run, which is the default, shows the exact JSON first. The summary contains gate pass counts, visibility rates by assistant and language, plan progress, the top 10 issue titles, dates and the Katman version, and nothing else.

Code, file contents, AI answers, your questions, your prompts and your OpenRouter key never leave your machine for katman.pro. The key is sent only in the body of an HTTPS request to katman.pro, redirects aren’t followed, and a value that doesn’t look like a Katman key is never sent. What katman.pro stores about your account is in the [privacy policy](https://katman.pro/privacy).

## Your keys

-   **`KATMAN_KEY`** (`km_live_…`) is needed for every tool except `katman_account`. After you buy Audit Week or Pro, create it in your account at katman.pro/app → **MCP**, and revoke it there if it leaks.
-   **`OPENROUTER_API_KEY`** (or `KATMAN_OPENROUTER_API_KEY`) is only for visibility runs and goes only to OpenRouter, as the authorisation for your own calls.

Katman reads both from the environment your client starts it with. It never writes them to disk, never prints them, and removes them from error messages. How to set them up per client is in [Getting started](https://katman.pro/docs/getting-started).

## No telemetry

Katman doesn’t send usage data. We don’t know which sites you audit, what the audits find or which tools you call, and the plan check carries no project data. If a future version changes anything that talks to katman.pro, it will be listed here first.

## Why Katman doesn’t automate the chat apps

Katman doesn’t drive ChatGPT, Claude or Perplexity’s web apps with a headless browser, for three reasons:

1.  **Their terms forbid it.** OpenAI’s terms of use prohibit automatically or programmatically extracting data or output, and Anthropic’s, Perplexity’s and Google’s consumer terms have similar rules ([OpenAI](https://openai.com/policies/row-terms-of-use/), [Anthropic](https://www.anthropic.com/legal/consumer-terms), [Perplexity](https://www.perplexity.ai/hub/legal/terms-of-service), [Google](https://policies.google.com/terms); checked 30 September 2026).
2.  **Accounts get banned.**
3.  **It breaks every week,** because the apps’ pages change.

Instead, visibility runs ask the providers’ own models through OpenRouter, with live web search. That is a proxy for what the apps show, and we say so in every report. For the answers people actually see in the apps, you ask the questions yourself, logged out, and paste the answers into `katman_manual_check`. Both methods are explained in [Visibility runs](https://katman.pro/docs/visibility-runs).

## Tool hints for your client

Read-only tools set `readOnlyHint: true`, tools that use the network set `openWorldHint: true`, and no tool is marked destructive. These are hints: your client may still ask you to approve each call, and you can keep that setting on.

## Your AI coding tool is separate

Katman runs inside your coding tool, but what that tool sends to its own model provider, such as your code and your prompts, is governed by the tool’s own settings and terms, not by Katman. What katman.pro itself collects is in the [privacy policy](https://katman.pro/privacy).

## Frequently asked questions

### Can Katman read my .env file?

No. Katman never opens .env or .dev.vars files, .pem, .key or .p12 files, or any file with “secret” or “credential” in its name.

### Does Katman send my code anywhere?

No. Katman reads your code locally and sends none of it over the network; audits fetch your public site, visibility runs send only your questions to OpenRouter, and katman\_sync sends aggregate numbers, never code or file contents.

### What does Katman send to katman.pro?

Two things, and nothing else: your key and the MCP version, at most once a day, to check your plan; and, only when you call katman\_sync with dry\_run: false, a project summary of gate counts, visibility rates, plan progress, issue titles and dates.

### Does Katman collect usage data?

No. There is no telemetry: no tool names, no project data and no usage counts are sent with the plan check.

### Can Katman change my code?

Only by writing a generated file when you call katman\_generate or katman\_setup\_monitoring with write: true. Everything else in your code is changed by your AI coding tool, under its own approval settings.

### Why can’t Katman check the ChatGPT app automatically?

Because the consumer apps’ terms forbid automated extraction, accounts get banned, and the pages change often. Katman uses the providers’ models through OpenRouter and records app answers that you paste in with katman\_manual\_check.

## Related pages

-   [**Tools reference** Reference for all 17 Katman MCP tools: what each one does, whether it needs Audit Week or Pro, its key inputs, what it writes, and an example call to copy.](https://katman.pro/docs/tools)
-   [**Getting started with Katman** Install Katman MCP in Cursor, Claude Code, VS Code, Windsurf, Codex or Gemini CLI, add your Katman key and optional OpenRouter key, and run your first session.](https://katman.pro/docs/getting-started)
-   [**Visibility runs** How Katman measures AI visibility: 12+2 question set, five assistants via OpenRouter, cost caps, manual checks in the apps, and why one run is a small sample.](https://katman.pro/docs/visibility-runs)
-   [**Privacy policy** What katman.pro, Katman accounts and the Katman MCP collect, why, how long we keep it, who processes it for us, and your rights under UK data protection law.](https://katman.pro/privacy)

Updated 30 September 2026 · Katman