> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Connector

> Durable, evidence-grade telemetry for Claude Code, built for EU AI Act Article 12

# meshai-claude-code

EU AI Act Article 12 requires durable records of AI system activity, not
best-effort logs. Best-effort telemetry loses events exactly when it
matters most: process crashes, OOM kills, network outages. The
`meshai-claude-code` connector fsyncs every hook event to a local
write-ahead log before anything else happens, so a crash cannot lose an
acknowledged event. Only disk failure can.

## Install

```bash theme={null}
pipx install meshai-claude-code
```

<Note>
  Plain `pip install` inside a virtual environment also works. On a system
  Python, bare `pip install` fails with `error: externally-managed-environment`
  (PEP 668) on modern Debian, Ubuntu, and Homebrew. Use pipx, a venv, or
  `pip install --break-system-packages` if you understand the tradeoff.
</Note>

## Setup

<Steps>
  <Step title="Log in">
    ```bash theme={null}
    meshai-claude-code login --api-key msh_...
    ```
  </Step>

  <Step title="Install hooks">
    ```bash theme={null}
    meshai-claude-code install
    ```

    Registers the connector's hooks in `~/.claude/settings.json`, with a
    backup of your existing settings and a clean uninstall path.
  </Step>

  <Step title="Check status">
    The daemon starts automatically on your next Claude Code session
    (`auto_start_daemon: true` by default), or you can run it directly with
    `meshai-cc-daemon`.

    ```bash theme={null}
    meshai-claude-code status
    ```
  </Step>
</Steps>

## Architecture

```
                fsync                    tail              OTLP POST
  ┌──────┐  event ┌──────┐    nudge   ┌────────┐         ┌────────────┐
  │ hook │───────▶│ WAL  │◀───────────│ daemon │────────▶│ MeshAI API │
  └──────┘        └──────┘            └────┬───┘         └────────────┘
                                      1s poll backstop
```

* **Hooks** run on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
  PreCompact, and Stop. Each hook appends a CRC-framed record to the WAL
  with a real fsync and exits.
* **The WAL** (write-ahead log) is local, durable state. Hooks own writes;
  the daemon only reads.
* **The daemon** converts WAL events to OpenTelemetry spans and exports them
  to MeshAI over OTLP. Delivery is at-least-once; span IDs are minted once
  at hook time, so MeshAI's ingest dedup makes accounting exactly-once.

## Content filtering

Tool content (`tool_input` / `tool_output`) is dropped by default. Structural
metadata (event type, tool name, timing, token counts) always flows. Opt in
per tool in `~/.config/meshai/filters.yaml`:

```yaml theme={null}
tools:
  Bash:
    allow: [tool_input]
```

Allowlisted content passes through the MeshAI SDK's secret-redaction
pipeline before it leaves your machine, and fails closed on any doubt.

## Compliance mode

```yaml theme={null}
# ~/.config/meshai/policy.yaml
fail_closed: true    # WAL append failure blocks Claude Code
agent_name: my-cc     # registry identity; default claude-code-<hostname>
base_url: https://api.meshai.dev
```

With `fail_closed: true`, a tool call that cannot be durably recorded does
not run: no evidence means no action.

## Platforms

macOS, Linux, and WSL (v1). On WSL, state must live on the Linux
filesystem, not `/mnt/c`; this is the default
(`~/.local/state/meshai-cc`). Native Windows support is planned for v2.

## Source

Apache-2.0. Source at
[github.com/meshailabs-org/meshai-claude-code](https://github.com/meshailabs-org/meshai-claude-code).