Skip to content

ha-china/blueprint-studio

Repository files navigation

Blueprint Studio for Home Assistant 🚀

HACS Default GitHub Release GitHub License GitHub Issues GitHub Stars Home Assistant Maintenance Downloads Support Development Support via PayPal

Hero Banner

Logo

Blueprint Studio for Home Assistant

A modern, feature-rich file editor with AI-powered assistance and full Git integration.

Open in HACS Add Integration

📖 Table of Contents


Why Blueprint Studio? 🌟

Tired of juggling external editors, SSH, or add-ons just to tweak your Home Assistant configs? Blueprint Studio brings the power of a full-fledged IDE right into your HA dashboard. Here's why it's a game-changer:

  • No External Tools Required - Edit local Home Assistant config files directly in Home Assistant without SSH or file shares 🚫
  • Professional Editor - Full-featured code editor with syntax highlighting and linting 💻
  • Safe & Secure - Built-in protection against path traversal and unauthorized access 🛡️
  • Multi-File Editing - Work with multiple files simultaneously using tabs 📁
  • File Management - Create, delete, rename, copy, upload, and download files and folders 📂

Screenshots 📸

Main Editor Interface

Edit your Home Assistant configuration files with syntax highlighting and professional tools

Blueprint Studio Main Interface


File Tree & Multi-Tab Support

Navigate your config directory and work with multiple files simultaneously

File Tree Explorer


Real-Time YAML Validation

Catch errors before saving with built-in YAML linting

YAML Validation


Multi-Tab Editing in Action

Work efficiently with multiple files open at once

Multi-Tab Editing


GitHub Integration 🔗 NEW!

Complete Git workflow - stage, commit, and push directly from Blueprint Studio

Git Changes Panel


Git Settings & Authentication

One-click OAuth login or Personal Access Token authentication

Git Settings Modal


Create GitHub Repositories

Create new repositories without leaving Home Assistant

Create GitHub Repository


Complete Git Workflow

Edit, stage, commit, and push - all in one place

Complete Git Workflow

Editor Preview

✨ Features

Editor Features 🎨

  • AI Studio Copilot (v2.0) - Senior Home Assistant Configuration Expert with Real Entity Awareness, 7 Intelligent Scene Presets (morning, evening, movie, reading, romantic, party, relax), Advanced Script Generation with multi-step sequences, delays & notifications, Jinja Template Validation, and 30+ Device Domains with 100+ synonyms. Supports Gemini 3 & GPT-5 or runs entirely local by default 🧠
  • Syntax Highlighting - Support for YAML, JSON, Python, JavaScript, HTML, CSS, Markdown, and Shell scripts 🌈
  • Code Folding - Collapse and expand code sections for better focus 📜
  • Line Numbers - Easy navigation with line numbers 🔢
  • Active Line Highlighting - See your cursor position clearly 🎯
  • Bracket Matching - Automatic bracket highlighting 🧩
  • Auto-close Brackets - Automatic bracket completion ⌨️
  • Smart Autocomplete - Intelligent suggestions for Home Assistant entities (type light. to see lights), keys, and values 🧠
  • YAML Snippets - Templates for common HA patterns like Automations and Sensors (type snip:) 🧩
  • YAML Linting - Real-time YAML syntax validation with error highlighting ❌
  • Jinja Template Support - Full syntax highlighting for Jinja2 templates with distinct coloring for brackets, keywords, and variables 📝
  • Command Palette - Instant access to all features with Ctrl+K ⌨️
  • UUID Generator - Instantly insert a random UUID v4 with Ctrl+Shift+U 🆔
  • Split View - Edit two files side-by-side with pane-aware tabs and split controls 🪟
  • Minimap - Optional VS Code-style minimap for fast navigation in long files 🗺️
  • Professional Search - Floating Find/Replace widget with navigation controls (Ctrl+F, Ctrl+H) 🔎
  • Global Search - Search across all files with Regex and Case Sensitivity support (Ctrl+Shift+F). Now optimized to skip binary files and hidden folders for lightning-fast results 🌐
  • Entity Explorer Mode - New mode in Global Search to browse the entity registry, view states, and copy IDs directly into your code 🔍
  • Filter by Content - Sidebar toggle to filter the file tree by text content (e.g., find all files containing input_boolean.test) 📂

Editor Customization ⚙️ NEW in v2.0.0!

  • Font Size - Adjustable from 10px to 24px to suit your preference 🔤
  • Font Family - Choose from 7 popular programming fonts (SF Mono, Fira Code, JetBrains Mono, Cascadia Code, Source Code Pro, Ubuntu Mono) 🔡
  • Word Wrap - Toggle line wrapping for long lines ↩️
  • Line Numbers - Show or hide line numbers #️⃣
  • Show Whitespace - Display spaces and tabs visually ␣
  • Auto-Save - Automatically save files after a configurable delay (500ms - 5000ms) 💾
  • Tabbed Settings - New organized settings interface with General, Appearance, Editor, and Features tabs 🗂️

UI Features 🎨

  • 6 Theme Presets - Choose from Dark, Light, High Contrast, Solarized Dark, Solarized Light, Ocean, and Dracula themes 🎨
  • Custom Accent Colors - Personalize the accent color with 8 vibrant options 🔵🟣🔴🟢
  • Onboarding Wizard - Step-by-step tour for new users to initialize and connect 🎓
  • File Tree Explorer - Navigate your config directory with an expandable folder tree 🌳
  • File Type Icons - Different colored icons for various file types (toggle on/off) 🎨
  • Compact File Tree Mode - Dense layout option for smaller screens 📱
  • Multiple Tabs - Open and edit multiple files simultaneously 🗂️
  • Recent Files - Quickly reopen recently edited files from the sidebar 🕘
  • Resizable Sidebar - Drag to resize the file explorer 📏
  • Breadcrumb Navigation - Move through folders without losing context 🧭
  • File Search - Filter files in the explorer 🔍
  • Status Bar - Shows cursor position, file type, and connection status 📊
  • Toast Notifications - Elegant success/error messages with persistent error display 🔔
  • Custom Editor Colors - Customize font colors for syntax highlighting (Comments, Keywords, Strings, etc.) in Settings 🎨

File Management 📁

  • Create Files & Folders - Right-click context menu for creating new items ➕
  • Bulk Operations - New selection mode to pick multiple files and folders for batch actions 📦
  • Drag & Drop Reorganization - Move files and folders by dragging them 📦
  • Upload Files - Drag & drop files directly into the file tree or use the upload button ⬆️
  • Download Files - Download individual files, multiple selected items, or entire folders as ZIP ⬇️
  • Copy & Paste - Duplicate files and folders 📋
  • Rename & Move - Rename files or move them to different locations 🔄
  • Delete - Remove files and folders (with protection for critical files) 🗑️
  • Folder Operations - Upload/download entire folder structures as ZIP files 📦
  • Folder Sizes - View directory sizes directly in the file explorer 📊
  • Asset Preview - View images, PDFs, videos, and audio files directly in the editor 🖼️
  • Pin Favorites - Pin frequently used files for quick access at the top of the sidebar 📌

Remote Access & Terminal 🖥️ NEW!

  • SFTP Browser - Connect to remote servers, browse folders, and edit files through the same editor 🔐
  • Shared SSH Hosts - Reuse saved hosts between SFTP and the embedded terminal 🔁
  • Password or SSH Key Auth - Store password-based or PEM key-based connection profiles 🔑
  • Remote File Operations - Create, rename, copy, move, delete, upload, download, and ZIP remote folders 📦
  • Streaming Media Preview - Preview remote images, PDFs, audio, and video through tokenized streams 🎬
  • Embedded Terminal - Run commands in an xterm.js terminal panel or move it into an editor tab ⌨️
  • ZIP Progress UI - Track large local and SFTP folder downloads without blocking the interface 📊

Git Integration 🔗 NEW!

  • Easy Authentication - One-click OAuth Device Flow or manual PAT 🔐
  • Create GitHub Repos - One-click repository creation directly from Blueprint Studio 🚀
  • Gitea Support - Connect to self-hosted Gitea servers with repository creation and sync controls 🏠
  • Stay Logged In - Credentials persist across restarts ✨
  • Push & Pull - Sync your configs with GitHub 🔄
  • Commit History - Dedicated panel to browse past commits and view full diffs 📜
  • Stage & Commit - Manage changes with visual Git panel 📝
  • Explorer-Integrated Diff - Click the "Difference" icon in the file tree for instant side-by-side reviews 🔍
  • Visual Diff Viewer - Compare changes side-by-side before committing with color-coded highlighting 🌈
  • Smart Commit Messages - Auto-generates messages based on staged files (e.g., "Update config") 🧠
  • Advanced Sync Recovery - One-click tools to "Abort" stuck syncs or resolve "Diverged" history 🛡️
  • Branch Management - Intelligent tools to repair local master -> main mismatches 🔄
  • Visual Sync Status - Real-time arrows (↑/↓) showing commits ahead/behind remote 🔄
  • Advanced .gitignore - Manage exclusions with a full interactive tree and automated redundancy filtering 🛡️
  • Safety Checks - Proactively prompts to commit unstated changes before pushing 🛡️
  • Auto-Repair - Detects and fixes "index.lock" and corrupt index errors with one click 🔧
  • Manage Remotes - Add or remove remote repositories from Settings 🗑️
  • Automatic Status Updates - Git panel updates automatically after file operations ⚡
  • Periodic Polling - Detects changes made outside Blueprint Studio (every 30s) 🔄
  • Real-time Status - See modified, added, deleted files instantly 👁️
  • GitHub Octicons - Professional Git icons matching GitHub's UI 🎨

Toolbar 🛠️

Restart Home Assistant Button

New Restart Button - Quickly restart HA from the toolbar

  • Save / Save All 💾
  • Undo / Redo ↶↷
  • Cut / Copy / Paste ✂️📋
  • Search / Replace 🔍🔄
  • Bulk Select Mode ☑️
  • YAML Validation ✅
  • Restart Home Assistant 🔄
  • Refresh file list 🔄
  • Collapse/Expand all folders 📂📁
  • Upload/Download files and folders ⬆️⬇️
  • Developer Tools 🧰
  • Terminal ⌨️
  • Git Pull / Push / Status / Settings 🔗

Keyboard Shortcuts ⌨️

Shortcut Action
Ctrl+E / Cmd+E Quick File Switcher 🔍
Ctrl+B / Cmd+B Toggle Sidebar 📂
Ctrl+Shift+] Next Tab ➡️
Ctrl+Shift+[ Previous Tab ⬅️
Ctrl+F / Cmd+F Find in file 🔎
Ctrl+Shift+F / Cmd+Shift+F Global Search 🌐
Ctrl+Shift+U / Cmd+Shift+U Insert UUID 🆔
Ctrl+H / Cmd+H Replace in file 🔄
Ctrl+S / Cmd+S Save file 💾
Ctrl+Shift+S / Cmd+Shift+S Save all files 💾📁
Ctrl+G / Cmd+G Go to line 📍
Ctrl+/ / Cmd+/ Toggle comment 💬
Alt+W Close tab ❌
Ctrl+Z / Cmd+Z Undo ↶
Ctrl+Y / Cmd+Shift+Z Redo ↷
Enter Next Search Match (when search open) ⬇️
Shift+Enter Previous Search Match (when search open) ⬆️
Esc Close Modal / Search / Quick Switcher ✖️

🔧 Installation

This integration is best installed via the Home Assistant Community Store (HACS).

HACS (Recommended) 🛠️

  1. Add the Custom Repository:

    • Ensure HACS is installed.

    • Go to HACS > Integrations > ... (three dots) > Custom repositories.

    • Add this repository's URL: https://github.com/ha-china/blueprint-studio

    • Select the category Integration and click Add.

      Open your Home Assistant instance and open a repository inside the Home Assistant Community Store (HACS).

      Open your Home Assistant instance and start setting up a new integration.

  2. Install the Integration:

    • In HACS, search for "Blueprint Studio" and click Download.
    • Follow the prompts to complete the download.
  3. Restart Home Assistant:

    • Go to Settings > System and click the Restart button.
  4. Add the Integration:

    • Go to Settings > Devices & Services > Add Integration.
    • Search for and select Blueprint Studio.
    • The setup wizard will guide you through the final configuration steps.

Manual Installation 📥

  1. Download the latest release from the releases page 📦
  2. Extract the blueprint_studio folder to your custom_components directory 📂
  3. Restart Home Assistant 🔄
  4. Go to Settings → Devices & Services → Add Integration → Blueprint Studio ⚙️
Installation Preview

⚙️ Configuration

Blueprint Studio requires no configuration! After installation:

  1. The integration will appear in Settings → Devices & Services 📋
  2. A new "Blueprint Studio" menu item will appear in your Home Assistant sidebar 📂
  3. Click it to start editing your files 🚀

Note: Blueprint Studio is admin-only for security reasons. Only users with administrator privileges can access it. 👑


🚀 Usage

Getting Started 🎓

New in v1.3.0! First-time users are greeted with a guided tour to set up the editor. You can choose to enable Git integration for version control or keep it simple with just the file editor.

Onboarding Wizard

Onboarding Wizard - Guided setup with optional Git integration

Opening Files 📂

  • Click on any file in the file tree to open it in the editor 🖱️
  • Files open in new tabs, allowing you to work with multiple files simultaneously 🗂️
  • Use the file search box to quickly find files 🔍

Editing Files ✏️

  • Make your changes in the editor 🎨
  • Press Ctrl+S (or Cmd+S on Mac) to save 💾
  • Use Ctrl+Shift+S to save all open files at once 📁

Creating New Files ➕

  • Right-click in the file tree where you want to create the file 🖱️
  • Select "New File" or "New Folder" 📄
  • Enter the name and the file will be created ✨

Uploading Files ⬆️

  • Use the upload button in the toolbar 📤
  • Drag and drop files directly into the upload dialog 🖱️
  • Choose whether to overwrite existing files ❓

Downloading Files ⬇️

  • Right-click on a file or folder 🖱️
  • Select "Download" 📥
  • Folders are downloaded as ZIP files 📦

YAML Validation ✅

  • Click the YAML validation button in the toolbar 🔍
  • Any syntax errors will be highlighted in red ❌
  • Hover over errors to see the error message 💡

Pinning Favorites 📌

  • Pin files - Click the pin icon next to any file in the tree to add it to favorites
  • Quick access - Pinned files appear at the top of the sidebar for instant access
  • Persistent - Your favorites are saved and persist across restarts
  • Unpin - Click the pin icon again to remove from favorites
  • Visual indicator - Pinned files show an orange pin icon

AI Studio Copilot 🧠

New in v2.5.0! Senior Home Assistant Configuration Expert with advanced intelligence.

  1. Enable in Settings: Go to Settings and toggle "AI Studio Copilot".
  2. Choose Provider: Select between Local (Private), Google Gemini, or OpenAI.
  3. Smart Discovery: The AI knows your real entity IDs! Just ask to "Turn on the living room lights."
  4. Intelligent Scene Generation: Create scenes with natural language - "Create a morning scene for bedroom" generates 100% brightness at 4000K cool white. Supports 7 presets: morning, evening, movie, reading, romantic, party, relax.
  5. Advanced Script Generation: Create multi-step scripts with delays, notifications, and mode detection (single, parallel, restart, queued). Say "Turn on lights, wait 5 minutes, then turn them off."
  6. Jinja Template Support: Edit .jinja, .jinja2, and .j2 files with syntax validation and error detection.
  7. YAML Error Detection: Automatically detects 7+ common YAML errors (legacy syntax, indentation, missing colons) with line-by-line solutions.
  8. Multi-File Support: Generate code specifically for automations.yaml, scripts.yaml, or scenes.yaml.
  9. Context Aware: The Copilot analyzes your open file to provide targeted help and perfectly formatted YAML code blocks.

📖 See Full Guides: AI_CAPABILITIES.mdSCENE_SCRIPT_GUIDE.md

GitHub Integration 🔗

Sync your Home Assistant configuration with GitHub!

Git Settings Modal

Git Settings - One-click OAuth login or Personal Access Token

Quick Setup (30 seconds) ⚡

OAuth is pre-configured - no setup needed!

  1. Click Git Settings button (GitHub icon in toolbar)
  2. Click "Login with GitHub OAuth" (recommended)
  3. Visit the URL shown and enter the code
  4. Authorize Blueprint Studio
  5. Done! You're logged in permanently ✅
GitHub OAuth Login

GitHub OAuth Device Flow - Simple and secure authentication

Or use Personal Access Token (PAT):

  1. Create token at: https://github.com/settings/tokens
  2. Enter username and token in Git Settings
  3. Click "Save Credentials"

Creating a New Repository 🚀

NEW! Create GitHub repositories without leaving Blueprint Studio:

  1. Click Git Settings button
  2. Click "Create New GitHub Repository" button
  3. Enter repository details:
    • Repository name (e.g., "home-assistant-config")
    • Description (optional)
    • Visibility (Private recommended for security)
  4. Click "Create Repository"
  5. Blueprint Studio automatically:
    • Creates the repo on GitHub
    • Initializes local git repository
    • Adds remote origin
    • Ready to push! ✅
Create GitHub Repository

Create GitHub Repository - One-click repo creation

Advanced Management 🛠️

Visual Sync Status & Exclusions

Visual Sync Status

Visual Sync Status - See exactly how many commits to Push (↑) or Pull (↓)

Advanced .gitignore Editor

Advanced .gitignore - Manage exclusions with a full interactive file tree

Using Git Features

Git Changes Panel

Git Changes Panel - Stage, commit, and push your changes

  • Git Status - Automatically updates when you save, create, delete, or modify files
  • Stage Files - Click + icon next to files to stage
  • Commit - Write commit message and commit
  • Push - Upload changes to GitHub
  • Pull - Download changes from GitHub
  • Auto-Refresh - Git panel updates automatically every 30 seconds to catch external changes
Complete Git Workflow

Complete Workflow - Edit, stage, commit, and push in one place

Your credentials persist across restarts! No need to re-login.

Note: The Git Changes panel appears automatically when you have uncommitted changes and disappears when everything is committed. No manual refresh needed!

📖 Full Guide: See GITHUB_AUTH_QUICKSTART.md for complete instructions.

SFTP & Embedded Terminal 🖥️

Blueprint Studio can manage files outside your Home Assistant config directory through saved SSH/SFTP hosts.

  • Enable SFTP Integration and SSH (Terminal) Integration in Settings → Integrations
  • Add a host with password authentication or a private key
  • Browse remote folders from the SFTP sidebar
  • Open remote text files in normal editor tabs and save them back over SFTP
  • Preview remote media files through secure short-lived stream links
  • Use the embedded terminal for local commands or SSH sessions to saved hosts

Gitea Integration 🏠

Use Gitea when you prefer a self-hosted Git server instead of GitHub.

  • Enable Gitea Integration in Settings → Integrations
  • Configure your server URL, username, and token
  • Create repositories, add remotes, stage files, commit, pull, push, and recover stuck syncs from the Gitea panel

Developer Tools 🧰

Blueprint Studio includes Home Assistant-aware tools for quick testing while you edit:

  • Action caller with form and YAML modes
  • Template renderer for Jinja testing
  • Entity/state browser
  • Config check and YAML reload helpers

📄 Supported File Types

Extension Language Icon
.yaml, .yml YAML 🟡
.json JSON 🔵
.py Python 🐍
.js JavaScript
.html HTML 🌐
.css CSS 🎨
.md Markdown 📝
.sh Shell 🐚
.txt, .log Plain Text 📄
.conf, .cfg, .ini Config ⚙️
.jinja, .jinja2, .j2 Jinja2 Template 📄
.pem, .crt, .key Certificate/Key 🔒
.cpp, .h C++ (ESPHome) 🇨
.db, .sqlite Database (Binary) 🗄️
.bin, .ota, .der Binary/Firmware 💾
.tar, .gz, .zip Archive 📦

🔒 Security

Blueprint Studio includes multiple layers of security protection to keep your HA instance safe:

  • Path Traversal Protection - Prevents access to files outside your Home Assistant config directory 🚫
  • Admin Only Access - Only users with administrator privileges can use the editor 👑
  • Allowed File Extensions - Only text-based configuration files can be edited (see Supported File Types) 📄
  • Excluded Directories - Sensitive directories like .storage, deps, and __pycache__ are hidden 🕶️
  • Protected Files - Critical files like configuration.yaml and secrets.yaml cannot be deleted (but can be edited) 🛡️
  • Input Validation - All file operations are validated to prevent malicious input 🔍
  • Authentication Required - All API endpoints require Home Assistant authentication 🔐

Best Practices:

  • Always backup your configuration before making major changes 💾
  • Use YAML validation before saving configuration files ✅
  • Test changes in a development environment when possible 🧪
  • Keep regular backups of your Home Assistant configuration 🔄

🛠️ Troubleshooting

Integration doesn't appear in sidebar ❓

  • Ensure you've restarted Home Assistant after installation 🔄
  • Check that you're logged in as an administrator 👑
  • Clear your browser cache and refresh the page 🧹
  • Check the Home Assistant logs for any errors 📋

Files not showing in the tree 📂

  • Some directories are excluded for security (.storage, deps, .cache, .git, etc.) 🛡️
  • Hidden files (starting with .) are not shown unless "Show Hidden" is enabled 🕶️
  • Only files with supported extensions are displayed 📄
  • Empty folders are now visible (v1.2.0+) 📁
  • Try clicking the refresh button in the toolbar 🔄

Cannot save files 💾

  • Ensure you have write permissions on the config directory 🔑
  • Check that the file extension is in the allowed list 📄
  • Verify there's enough disk space 💾
  • Check the Home Assistant logs for permission errors 📋

YAML validation shows errors ❌

  • Review the error message by hovering over the red highlighted area 💡
  • Common issues: incorrect indentation, missing colons, unquoted special characters 📝
  • Use an online YAML validator for complex debugging 🌐
  • Check the Home Assistant documentation for proper YAML syntax 📚

Upload/Download not working ⬆️⬇️

  • Check browser console for JavaScript errors 🛠️
  • Ensure files are within size limits 📏
  • Verify file extensions are allowed 📄
  • Try a different browser if issues persist 🌐

GitHub Login / Git Issues 🔗

  • Cannot login: Check internet connection to github.com
  • Login expired: Device code expires in 15 minutes, try again
  • Push/Pull fails: Verify credentials are saved in Git Settings
  • Empty Git panel: Click "Git Status" to refresh
  • Permission denied: Check your GitHub PAT has repo scope
  • Credentials lost after restart: This is fixed in v1.2.0+ with persistent storage

📖 See: GITHUB_OAUTH_SETUP.md for detailed troubleshooting.


❓ FAQ

Q: Can I edit files outside the Home Assistant config directory?
A: Local file editing is restricted to your Home Assistant config directory for security reasons. Remote files can be edited through saved SFTP connections. 🛡️

Q: Why can't I see .storage or other hidden directories?
A: These directories are excluded for security. Editing files in .storage can corrupt your Home Assistant installation. ⚠️

Q: Can non-admin users access Blueprint Studio?
A: No. Blueprint Studio requires administrator privileges to ensure only trusted users can edit configuration files. 👑

Q: Does Blueprint Studio backup files automatically?
A: No. You should maintain your own backup strategy using Home Assistant's backup features or external tools. 💾

Q: Can I use Blueprint Studio on mobile devices?
A: Yes, but the experience is optimized for desktop. A larger screen is recommended for editing. 📱

Q: Will my changes take effect immediately?
A: Most configuration changes require reloading the affected integration or restarting Home Assistant. Blueprint Studio only saves files, it doesn't reload configurations. 🔄

Q: Can I install multiple instances?
A: No. Blueprint Studio allows only one instance per Home Assistant installation. 🔒

Q: Is syntax highlighting available for all file types?
A: Yes, for all supported file types listed in the Supported File Types section. 🌈

Q: Can I customize the theme or editor settings? A: Yes! Blueprint Studio v2.2.0+ offers extensive customization:

  • 6 Theme Presets: Dark, Light, High Contrast, Solarized Dark, Solarized Light, Ocean, and Dracula
  • 8 Accent Colors: Choose your preferred highlight color
  • Font Options: Adjust font size (10-24px) and family from 7 popular programming fonts
  • Editor Behavior: Toggle word wrap, line numbers, whitespace visibility, and auto-save
  • File Tree: Compact mode and icon visibility options All settings are available in the Settings modal (gear icon) with a new tabbed interface. 🎨

Q: Is the AI Copilot always on? A: No. For privacy and performance, the AI Copilot is disabled by default. You can enable it in the Settings modal when you need help. 🧠

Q: Does Blueprint Studio support GitHub integration? A: Yes! Blueprint Studio v1.2.0+ includes full GitHub integration with OAuth Device Flow, persistent credentials, and visual Git operations (stage, commit, push, pull). 🔗

Q: Do I need to re-login to GitHub after Home Assistant restart? A: No! Starting with v1.2.0, credentials persist across restarts. You stay logged in permanently. ✨

Q: Can I see empty folders in the file tree? A: Yes! Starting with v1.2.0, empty folders are now visible in the file explorer. 📁

Q: Which is better: OAuth Device Flow or PAT? A: OAuth Device Flow is recommended for easier setup. Both methods work equally well and persist credentials. See GITHUB_AUTH_QUICKSTART.md for comparison. 🔐

🔍 Technical Details

Blueprint Studio is a Home Assistant custom integration with an admin-only panel, a modular JavaScript frontend, and a domain-split Python backend.

Integration Layout

custom_components/blueprint_studio/
├── __init__.py, config_flow.py, const.py, manifest.json
├── backend/
│   ├── api.py              # HTTP API orchestrator and upload/stream views
│   ├── api_files.py        # Local file CRUD, search, streaming, downloads
│   ├── api_git.py          # Git, GitHub, and Gitea actions
│   ├── api_misc.py         # Settings, HA metadata, syntax checks, reloads, AI actions
│   ├── api_sftp.py         # SFTP dispatcher and remote streaming
│   ├── api_terminal.py     # Terminal command API
│   ├── file_manager.py     # Safe local filesystem operations
│   ├── git_manager.py      # Repository, credentials, remotes, branches, conflicts
│   ├── sftp_manager.py     # Paramiko-backed remote filesystem operations
│   ├── terminal_manager.py # Embedded terminal session management
│   ├── ai_*.py             # AI providers, generators, NLP, and validators
│   ├── websocket.py        # Update/settings websocket subscriptions
│   └── zip_utils.py        # Streaming ZIP helpers
└── www/
    ├── modules/            # Frontend ES modules
    ├── styles/modules/     # Split CSS modules
    └── vendor/             # Bundled CodeMirror, xterm.js, PDF.js, Prettier, etc.

Frontend Modules

  • Boot and state - main.js, initialization.js, app.js, state.js, constants.js, event-bus.js, translations.js
  • Editor experience - editor.js, tabs.js, split-view.js, minimap.js, search.js, global-search.js, command-palette.js, ha-autocomplete.js, editorconfig.js, status-bar.js
  • File UI - file-tree.js, file-operations.js, file-operations-ui.js, downloads-uploads.js, zip-progress.js, asset-preview.js, favorites.js, recent-files.js, breadcrumb.js, context-menu.js, selection.js, sidebar.js, toolbar.js
  • Integrations - git.js, git-operations.js, git-ui.js, git-diff.js, github-integration.js, gitea-integration.js, gitea-ui.js, sftp.js, terminal.js, ai.js, ai-ui.js, dev-tools.js
  • Settings and coordination - settings.js, settings-ui.js, settings-sync.js, plus coordinator modules for files, Git, SFTP, terminal, dialogs, settings, and UI

Backend API Surface

  • /api/blueprint_studio handles authenticated JSON actions for files, Git/GitHub/Gitea, SFTP, terminal, AI, settings, Home Assistant metadata, config checks, template rendering, and service calls
  • /api/blueprint_studio/upload streams large multipart uploads to local storage or SFTP without relying on Home Assistant's default request size limit
  • /api/blueprint_studio/stream serves token-protected file, folder ZIP, search, and SFTP media streams for browser downloads/previews
  • WebSocket commands publish file update and settings change events to keep multiple tabs and the PWA in sync

Security Model

  • The panel and backend API require Home Assistant authentication and administrator privileges
  • Local paths are resolved through safe-path helpers to prevent traversal outside the configured root
  • Streaming endpoints use Home Assistant access tokens or short-lived opaque stream IDs so remote credentials are not exposed in URLs
  • Dangerous operations such as hard reset, force push, delete, service calls, template rendering, and Home Assistant restart are explicitly admin-gated

🤝 Contributing

Contributions are welcome! Here's how you can help: 🌍

Reporting Issues 🐛

  • Check existing issues before creating a new one 🔍
  • Include Home Assistant version, browser, and OS information 📋
  • Provide steps to reproduce the problem 📝
  • Include relevant log entries if available 📄

Pull Requests 🔄

  1. Fork the repository 🍴
  2. Create a feature branch (git checkout -b feature/amazing-feature) 🌿
  3. Make your changes ✏️
  4. Test thoroughly with Home Assistant 🧪
  5. Commit your changes (git commit -m 'Add amazing feature') 💾
  6. Push to the branch (git push origin feature/amazing-feature) 🚀
  7. Open a Pull Request 📤

Development Setup 🛠️

  1. Clone the repository into your Home Assistant's custom_components directory 📥
  2. Restart Home Assistant 🔄
  3. Make changes to the code ✏️
  4. Restart Home Assistant to test changes 🔄
  5. Check the Home Assistant logs for any errors 📋

Code Style 📐

  • Follow PEP 8 for Python code 🐍
  • Use type hints where appropriate 💡
  • Add comments for complex logic 📝
  • Test all file operations thoroughly 🧪

📞 Support

If you encounter any issues or have feature requests:

  • Open an issue on GitHub Issues 🐛
  • Provide as much detail as possible 📝
  • Check existing issues first to avoid duplicates 🔍

Join the conversation in the Home Assistant Community Forum or our Discord (coming soon)! 💬


📄 License

This project is licensed under the MIT License - see the LICENSE file for details. 📜


🙌 Acknowledgments

Blueprint Studio is built with and inspired by:

  • CodeMirror - The powerful code editor that powers the editing experience 💻
  • Material Icons - Beautiful icons for file types and UI elements 🎨
  • VS Code - Design inspiration for the interface and user experience 🌟
  • Home Assistant Community - For feedback, testing, and feature suggestions 👏

Special thanks to all contributors and users who help make Blueprint Studio better! 🎉


⚖️ Comparison with Other Solutions

Feature Blueprint Studio File Editor (Official) Studio Code Server SSH/SFTP Configurator
Installation HACS/Custom Component Add-on Add-on External Client Deprecated
Interface VS Code-like, Multi-tab Simple, Single-file Full VS Code Terminal Basic
Resource Usage Lightweight Low High Minimal Low
Security Built-in Restrictions Basic Full Access Full Access None
File Management Full (Upload/Download/ZIP) Basic Full Full Limited
Maintenance Active Official Community N/A Deprecated

Support the Project

This integration is developed and maintained in spare time and is provided free to the Home Assistant community.

If you find it useful and would like to support ongoing development, maintenance, and improvements, any contribution is appreciated — but never required ❤️

Ways to Support

You can also help by:

  • Reporting bugs
  • Submitting pull requests
  • Suggesting features
  • Helping other users
  • Starring the repository ⭐

Thank you for being part of the Home Assistant community.


⭐ Star History

If you find Blueprint Studio useful, please consider giving it a star on GitHub! 🌟

Star History Chart


Made with ❤️ for the Home Assistant Community by soulripper13
Maintained by HA China
MIT LicenseReport BugUpdate Changelog

About

Modern VS Code-like file editor for Home Assistant. Edit YAML configs with syntax highlighting, multi-tab support, and file management

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

117 stars

Watchers

4 watching

Forks

Sponsor this project

Packages

 
 
 

Contributors