haforge

A small CLI that pulls data from your Home Assistant instance(s) and dumps it into files that you can feed to an LLM — so you can ask it to build Lovelace dashboards, write automations, or whatever else you need, with full knowledge of your actual entities.

How it works

haforge sync ha.example.com

That's mostly it. It fetches entity states, system config, and anything else you add, and writes them as JSON files next to your dashboards. Then you hand those files to an LLM and say "here's my setup, help me build a dashboard".

Setup

1. Install

# From source (uv)
uv tool install .

# Or with pip
pip install .

2. Add an instance

haforge init ha.example.com
cp ha.example.com/.env.example ha.example.com/.env
# edit .env and paste your long-lived access token

Generate a token in Home Assistant under Profile → Long-lived access tokens.

3. Sync

haforge sync ha.example.com          # pulls entities + config
haforge sync ha.example.com entities # just entities

4. Use with an LLM

haforge init generates a PROMPT.md in every instance folder. It explains the files, includes example prompts, and is designed to be pasted or attached at the start of an LLM conversation.

Open your editor, attach ha.example.com/PROMPT.md and ha.example.com/entities.json, and ask away:

"Here are my entities. Build me a Lovelace energy dashboard that shows solar production, battery state, and grid exchange."

Multiple instances

Each instance lives in its own folder. The workspace defaults to your current directory, but you can point it elsewhere:

export HAFORGE_WORKSPACE=~/my-ha-instances
haforge sync ha.home.com
haforge sync ha.cabin.com
haforge list

Project layout

workspace/
├── ha.example.com/
│   ├── config.toml        # URL + which env var holds the token (commit this)
│   ├── .env               # actual token (gitignored)
│   ├── .env.example       # template (commit this)
│   ├── PROMPT.md          # LLM context file generated by init (commit this)
│   ├── entities.json      # synced by haforge (gitignored)
│   ├── ha_config.json     # synced by haforge (gitignored)
│   └── dashboards/
│       └── energy.yaml    # your dashboards (commit these)
└── ha.other.com/
    └── ...

Commands

haforge init <instance>             scaffold a new instance folder
haforge sync <instance> [resource]  pull data from HA (default: all resources)
haforge list                        show all known instances in the workspace

MCP server

haforge also ships as an MCP server, so you can connect it directly to Claude Desktop (or any MCP-capable client) instead of manually attaching JSON files.

haforge-mcp   # starts the stdio server

The server exposes these tools:

Tool	Description
list_instances	List all instances in the workspace
sync	Pull fresh entities / config from HA
get_entities	Read entities, optionally filtered by domain
get_entity	Look up a single entity by ID
list_dashboards	List dashboard YAML files for an instance
read_dashboard	Read a dashboard YAML
write_dashboard	Write or update a dashboard YAML

Connecting to Claude Desktop

Add this to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "haforge": {
      "command": "uv",
      "args": ["--directory", "/path/to/your/workspace", "run", "haforge-mcp"],
      "env": {
        "HAFORGE_WORKSPACE": "/path/to/your/workspace"
      }
    }
  }
}

Replace /path/to/your/workspace with the folder that contains your instance directories. Each instance still needs its own .env file with a valid token — the MCP server reads those the same way the CLI does.