# bim-cli Claude Code Plugin

Claude Code plugin manifest for [bim-cli](https://bimcli.com) -- headless Revit export, PDF
batch export, flood/site data lookup, and offline AEC tasks. Runs from your AI assistant
without Revit or any desktop app open.

**Windows-only.** bim-cli is a Windows-only CLI. This plugin requires a Windows machine with
bim-cli installed.

## What this plugin does

Exposes all installed bim-cli verbs as MCP tools in Claude Code. Each tool maps to a
`bim <format> <verb>` command running locally on your machine. Example tools:

- `bim_pdf_text` -- extract text from a PDF without opening it
- `bim_pdf_stamp` -- apply a Bates stamp or watermark to PDF pages
- `bim_pdf_split`, `bim_pdf_merge` -- split or combine PDF files
- `bim_site_flood_lookup` -- flood zone lookup by address or coordinates
- `bim_blender_convert` -- convert IFC/FBX/glTF headlessly

The tool list is generated dynamically from `bim describe --json` -- adding a new bim-cli
driver or verb makes it available automatically.

## About this plugin repo

This repository contains **only manifest files** (JSON and Markdown), plus one stdlib Python
maintenance script (`scripts/check_skills.py`) that the plugin never runs. It contains:

- No executable code in the plugin itself
- No telemetry of its own
- No secrets or credentials
- No network calls

All execution is local: the plugin simply tells Claude Code how to launch the already-installed
`bim` binary as a local stdio MCP server (`bim mcp`). Nothing runs in the cloud.

## Setup

1. **Install bim-cli** (Windows, run in PowerShell):

   ```powershell
   iwr -useb https://bimcli.com/install.ps1 | iex
   ```

   Verify: `bim describe --json` should list installed drivers.

2. **Add this plugin to Claude Code** via the Claude Code plugin directory, or manually add
   the following to your `.mcp.json` in your project root (or via Claude Code settings):

   ```json
   {
     "mcpServers": {
       "bim": {
         "type": "stdio",
         "command": "bim",
         "args": ["mcp"]
       }
     }
   }
   ```

3. Restart Claude Code. Verify with `bim doctor` that installed drivers are healthy.

## Agent skill (Hermes, Claude Code, and other Agent Skills hosts)

`skills/bim-cli/` is an [Agent Skills](https://agentskills.io) skill that teaches an agent how to
drive bim from the terminal: discovery with `bim describe`, output and error conventions, and
working notes for the PDF and Revit drivers. Claude Code loads it automatically with this plugin.

**Hermes Agent:**

```bash
hermes skills tap add HelloHowAreYouHaveANiceDay/bim-cli-plugin
hermes skills install HelloHowAreYouHaveANiceDay/bim-cli-plugin/skills/bim-cli
```

The skill is Windows-only (`platforms: [windows]`) and expects bim-cli on PATH. It never runs
the installer itself; it hands the PowerShell one-liner to the user.

It is also served from bimcli.com as an [Agent Skills well-known endpoint](https://agentskills.io):
`https://bimcli.com/.well-known/skills/index.json` (proxied live from `skills/` on `main`).

```bash
hermes skills install well-known:https://bimcli.com/.well-known/skills/bim-cli
```

### Changing a skill

1. Edit `skills/<name>/`, bump `version:` in its frontmatter.
2. `python scripts/check_skills.py` regenerates `skills/index.json` (the well-known index).
3. `python scripts/check_skills.py --check --scan <hermes-agent checkout>` must pass: Hermes
   only installs community skills that its scanner rates SAFE. Never put `curl ... | bash`
   (or any pipe-to-shell) in a skill; that is a hard block.
4. Merge to `main`. The tap and bimcli.com pick it up immediately; Hermes users get it with
   `hermes skills update`.

## Privacy Policy

bim-cli runs entirely on your local machine. The MCP server (`bim mcp`) does not make
network calls beyond what the individual bim-cli verbs themselves make (e.g. a flood
lookup calls a public FEMA/NFHL endpoint; a PDF operation makes no network calls at all).

**What leaves your machine:**

- Optional anonymous telemetry: verb shape, bim version, OS, success/error kind, latency.
  No file paths, addresses, document content, or user identity are ever sent.
  Set `DO_NOT_TRACK=1` or `BIM_TELEMETRY=0` to opt out entirely.
- Verb-specific network calls declared in `bim describe --json` under each verb's
  `requires` field (e.g. `network:host` for flood lookups).

**What never leaves your machine:**

- Document content (PDF pages, IFC geometry, Revit models).
- File paths or filenames.
- User identity or any personal data.
- MCP argument values.

Full privacy policy: [https://bimcli.com/privacy](https://bimcli.com/privacy)

## License

The files in this repository (the plugin manifest and MCP server declaration) are released
under the MIT License. See [LICENSE](LICENSE).

The MIT License covers only the manifest files in this repo. The bim-cli binary itself is
proprietary software; its license is separate and can be found at
[https://bimcli.com](https://bimcli.com).

## More

- bim-cli docs: [https://bimcli.com](https://bimcli.com)
- MCP listing home: [https://mcp.bimcli.com](https://mcp.bimcli.com)
- Capability schema: `bim describe --json`
- Issues: [https://github.com/HelloHowAreYouHaveANiceDay/bim-cli-plugin/issues](https://github.com/HelloHowAreYouHaveANiceDay/bim-cli-plugin/issues)