# bim-cli Claude Code Plugin

Claude Code plugin for [bim-cli](https://bimcli.com). Lets AI agents drive Revit 2024-2027,
check drawing-set PDFs, and pull US site and flood data -- local, free, no account.
Revit jobs need Revit installed on the machine: bim starts or attaches to it and drives it,
so no one has to click through Revit. PDF, site and IFC jobs need no desktop app.

**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:

- `pdf_set.check` -- find missing sheets, unresolved callouts and titleblock mismatches in a drawing set
- `pdf_text` -- extract text from a PDF without opening it
- `pdf_stamp.add` -- apply a Bates stamp or watermark to PDF pages
- `pdf_page.split`, `pdf_page.merge` -- split or combine PDF files
- `site_flood.lookup`, `site_assess` -- flood zone and site data for a US address
- `blender_convert` -- convert IFC/FBX/glTF in the background

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 -OutFile $env:TEMP\bim-install.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\bim-install.ps1
   ```

   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)