atoo-studio 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markus Furtlehner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.github.md

@@ -0,0 +1,328 @@
+<p align="center">
+  <img src="https://atoo.ai/img/logo_64x64.png" alt="Atoo Studio" width="64" height="64">
+</p>
+
+<h1 align="center">Atoo Studio</h1>
+
+<p align="center">
+  <strong>Local-first workspace for Claude Code, Codex CLI, and other coding agents.</strong><br>
+  Run multiple agents across projects and worktrees, fork and chain sessions, preview apps with real Chrome + DevTools, and manage Git, GitHub, databases, containers, and hardware from one browser UI.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/status-early%20alpha-orange" alt="Early Alpha">
+</p>
+
+<p align="center">
+  <a href="https://atoo.ai">Website</a> ·
+  <a href="#demo">Demo</a> ·
+  <a href="#getting-started">Getting Started</a> ·
+  <a href="#core-capabilities">Core Capabilities</a> ·
+  <a href="#platform-support">Platform Support</a>
+</p>
+
+<p align="center">
+  Built by <a href="https://github.com/markusfurtlehner">Markus Furtlehner</a> ·
+  <a href="https://www.ittrail.at">IT Trail GmbH</a>
+</p>
+
+---
+
+## Demo
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="demoassets/layout-21-9.png" alt="Atoo Studio on an ultrawide display" width="820"></td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Ultrawide (21:9) — the full workspace with agent sessions, file tree, editor, and live app preview side by side.</sub></td>
+  </tr>
+</table>
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="demoassets/layout-16-9.png" alt="Atoo Studio on a standard display" width="560"></td>
+    <td align="center"><img src="demoassets/mobile-mockup-portrait.jpg" alt="Atoo Studio on mobile" width="225"></td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Standard (16:9) — collapsible sidebars keep the full workspace usable, including the live app preview.</sub></td>
+    <td align="center"><sub>Mobile — a dedicated layout with all features accessible on any phone or tablet.</sub></td>
+  </tr>
+</table>
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="demoassets/atoo-studio-carousel-mode.gif" alt="Atoo Studio carousel mode" width="420"></td>
+  </tr>
+  <tr>
+    <td align="center"><sub>Experimental carousel view — a 2D panel layout where the active view follows mouse movement automatically.</sub></td>
+  </tr>
+</table>
+
+## What is Atoo Studio?
+
+Atoo Studio is a browser-based control room for working with coding agents like **Claude Code** and **Codex CLI**.
+
+It does not replace your editor or your agent. It gives them a shared environment: agent sessions, code, live preview, DevTools, Git, GitHub, databases, containers, and even hardware access in one place.
+
+Run it locally on Linux, macOS, or WSL as a local web server. No cloud dependency. No vendor lock-in.
+
+## Why it exists
+
+Coding agents are great at focused tasks. The chaos starts around them.
+
+Once you work across multiple projects, worktrees, terminals, dev servers, browser tabs, and agent sessions, the workflow breaks down fast. You lose context, you lose overview, and you spend too much time managing the environment instead of shipping.
+
+Atoo Studio was built from that exact pain: creating a workspace that actually matches how agent-driven development works in practice.
+
+## Core capabilities
+
+### Agent workflows
+
+- Run multiple coding agents in parallel across isolated projects and worktrees.
+- Each agent runs in a real PTY session with full terminal capabilities.
+- Fork sessions to explore alternative approaches without losing the original context.
+- Chain sessions across agents, so you can start with Claude Code and continue with Codex using the same conversation history.
+- Search session history via MCP so agents can reuse past decisions, failed attempts, and implementation context.
+- Set session names, descriptions, and tags for better navigation and recall.
+- Track project-level changes so you always know what has been done, by which session, and when.
+
+### Preview and debugging
+
+- Built-in app preview powered by headless Chrome and the Chrome DevTools Protocol.
+- Pixel-streamed preview, not iframes, so there are no cross-origin limitations.
+- Open Chrome DevTools directly inside the workspace.
+- Request trusted HTTPS certificates from the built-in CA for local testing.
+- Test responsive layouts with device presets, custom viewports, zoom, rotation, and touch emulation.
+
+### Git and GitHub workflow
+
+- Browse issues and pull requests, view comments, and open or update PRs from the GitHub panel.
+- Link sessions to issues or pull requests for better task context.
+- Inspect branches, commit history, stashes, and diffs from the Git panel.
+- Work with multiple Git worktrees side by side as separate projects.
+- Use the one-click **Publish** flow to commit, push, and open a PR.
+
+### Data, infrastructure, and devices
+
+- Explore 15 database types including PostgreSQL, MySQL, SQLite, Redis, MongoDB, Elasticsearch, ClickHouse, CockroachDB, Cassandra, Neo4j, and InfluxDB.
+- Auto-discover database connections from `docker-compose` files, environment variables, and port scanning.
+- Manage Docker, Podman, and LXC containers from the workspace.
+- Browse container images, networks, volumes, compose projects, logs, and stats.
+- Connect real hardware like ESP32 boards through Web Serial, bridged to a virtual PTY so agents can flash firmware and monitor output.
+
+### Workspace experience
+
+- File explorer and editor with source, diff, rendered, and hex views.
+- Integrated terminal tabs running directly on the server.
+- Built-in reverse proxy with subdomain and path-based routing.
+- Optional authentication with password, TOTP, and WebAuthn/passkeys.
+- Real-time shared workspace views across multiple browsers.
+- Responsive mobile layout for monitoring and control on the go.
+- Installable as a desktop app via PWA.
+
+## Platform support
+
+| Capability | Linux | macOS | Native Windows |
+|------------|-------|-------|----------------|
+| Core workspace (agents, terminal, git, files) | Yes | Yes | No |
+| Browser preview (CDP streaming) | Yes | Yes | - |
+| Serial devices (PTY bridge) | Yes | Yes | - |
+| Serial control signals (DTR/RTS via CUSE) | Yes | No | - |
+
+**Native Windows is not supported. Use WSL instead.**
+
+**macOS support is completely untested at this time.** It should work in principle, but expect rough edges.
+
+## Getting started
+
+### Requirements
+
+**Required**
+- Node.js 18+
+- Git
+- Linux, macOS, or WSL
+
+**Optional dependencies**
+
+| Dependency | Enables |
+|------------|---------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) | Claude Code agent support |
+| [Codex CLI](https://github.com/openai/codex) (`codex`) | Codex agent support |
+| [GitHub CLI](https://cli.github.com/) (`gh`) | GitHub issues and PR integration |
+| `docker`, `podman`, or `lxc` | Container management |
+| `ffmpeg` | Screen recording |
+| Chrome libraries on Linux | Browser preview |
+| CUSE on Linux | Serial control signals (DTR/RTS) |
+
+Missing optional dependencies are reported as warnings on startup.
+
+### Quick start
+
+```bash
+npx atoo-studio
+```
+
+Then open `https://localhost:3010` in your browser.
+
+To use a different port, set the `ATOO_PORT` environment variable:
+
+```bash
+ATOO_PORT=4000 npx atoo-studio
+```
+
+### Docker
+
+```bash
+docker run -p 3010:3010 ghcr.io/atooai/atoo-studio
+```
+
+To persist data across container restarts:
+
+```bash
+docker run -p 3010:3010 -v atoo-data:/home/atoo/.atoo-studio ghcr.io/atooai/atoo-studio
+```
+
+### LXC / LXD
+
+Download the LXC image from the [latest release](https://github.com/atooai/atoo-studio/releases) and import it:
+
+```bash
+lxc image import atoo-studio-lxc-amd64.tar.gz --alias atoo-studio
+lxc launch atoo-studio my-atoo-studio
+```
+
+### Proxmox (experimental)
+
+Run one of the setup scripts on your Proxmox host:
+
+**LXC container** — lightweight, 2 CPU / 2 GB RAM / 20 GB disk
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/atooai/atoo-studio/main/proxmox/lxc.sh)"
+```
+
+**VM** — stronger isolation, CUSE/serial support, 4 CPU / 4 GB RAM / 50 GB disk
+
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/atooai/atoo-studio/main/proxmox/vm.sh)"
+```
+
+Both scripts prompt for container or VM ID, hostname, storage, and resources with sensible defaults.
+
+### Linux setup
+
+To enable browser preview and screen recording support:
+
+```bash
+sudo ./setup.sh
+```
+
+To enable CUSE for serial control signals like DTR/RTS:
+
+```bash
+sudo ./setup-cuse.sh
+```
+
+`setup.sh` supports `apt-get` (Debian/Ubuntu), `dnf` (Fedora/RHEL), and `pacman` (Arch).
+
+`setup-cuse.sh` builds the native CUSE helper, loads the kernel module, and configures permissions. Check the script header for container-specific notes for Docker or LXC.
+
+### macOS setup
+
+No additional setup is required for core functionality.
+
+For screen recording support, install `ffmpeg` via the setup script:
+
+```bash
+./setup.sh
+```
+
+CUSE is not available on macOS, so serial control signals like DTR/RTS are not supported. When flashing boards such as ESP32, use the **BOOT** button manually.
+
+## Architecture
+
+Atoo Studio runs as a single local backend process on the same machine or server as your coding agents.
+
+```text
+Browser (any device)
+    │
+    │ WebSocket + HTTP
+    ▼
+Atoo Studio Backend
+    │
+    ├── Agent adapters (Claude Code, Codex)
+    ├── PTY session manager
+    ├── Session chain & fork system
+    ├── Project & worktree manager
+    ├── Git & GitHub integration
+    ├── Database explorer
+    ├── Container manager (Docker, Podman, LXC)
+    ├── Reverse proxy with service registry
+    ├── CDP preview (headless Chrome)
+    ├── Certificate authority
+    ├── Serial device bridge
+    ├── Authentication system
+    └── MCP server
+```
+
+Agents run inside real terminal sessions. Atoo Studio does not replace the agent — it provides the environment where agents operate.
+
+## MCP integration
+
+Atoo Studio exposes MCP tools that let agents talk back to the workspace UI.
+
+| Tool | Description |
+|------|-------------|
+| `generate_certificate` | Request a trusted HTTPS certificate for any hostname |
+| `report_tcp_services` | Report started services so they appear in the preview panel |
+| `request_serial_device` | Request USB serial device access via the Web Serial bridge |
+| `search_session_history` | Search across all session history or within the current session chain |
+| `suggest_continue_in_other_session` | Suggest switching to an existing session with relevant context |
+| `open_file` | Open a file in the browser editor with user approval |
+| `get_session_metadata` | Read session name, description, and tags |
+| `set_session_metadata` | Set session name, description, and tags |
+| `github_issue_pr_changed` | Notify the UI when a GitHub issue or PR changes |
+| `connect_database` | Open the database explorer with a specific connection |
+| `track_project_changes` | Track what has been done in a project (get/set/delete) |
+
+## Commercial support
+
+Need help building agent tooling, multi-agent workflows, local-first developer environments, or custom integrations around Claude Code and Codex?
+
+Commercial support and consulting are available via [IT Trail GmbH](https://www.ittrail.at).
+
+## Status
+
+Atoo Studio is in **early alpha**. It is used for real day-to-day development across multiple projects and worktrees, but APIs, configuration, and UI may change without notice.
+
+Bug reports and feedback are welcome.
+
+## Roadmap
+
+- [ ] Add Gemini CLI as a third supported agent
+- [ ] Standalone Electron app with real browser sessions for preview (in addition to headless CDP streaming)
+- [ ] Refine mobile layout and bring all recently added features to the mobile view
+- [ ] Self-hosted Git platform support: Gitea, GitLab, and Azure DevOps Server
+- [ ] Evaluate cloud platforms for native management (containers, databases, infrastructure)
+- [ ] Experiment with alternative workspace layouts
+- [ ] Optional per-project development containers
+- [ ] Replace xterm.js with atoo-term (currently in development)
+
+## Feedback
+
+Atoo Studio is not accepting code contributions at this stage. The architecture is evolving quickly and external PRs would likely conflict with ongoing changes.
+
+Bug reports, feature ideas, and workflow pain points are very welcome — please open an issue.
+
+## License
+
+[MIT](LICENSE)
+
+## Author
+
+Built by [Markus Furtlehner](https://github.com/markusfurtlehner) — founder of [IT Trail GmbH](https://www.ittrail.at).
+
+Built from real pain, not a pitch deck.
+
+> [atoo.ai](https://atoo.ai)

package/README.md

@@ -0,0 +1,118 @@
+# Atoo Studio
+
+**Agentic Development Environment** — A workspace where coding agents build, run and debug real systems.
+
+Atoo Studio is a browser-based development environment for working with coding agents like Claude Code and Codex CLI. It brings agents, code, preview, DevTools, Git, GitHub, databases and hardware devices into one workspace.
+
+Runs on Linux, macOS or WSL as a local web server. No cloud dependency, no vendor lock-in.
+
+## Quick Start
+
+```bash
+npx atoo-studio
+```
+
+Then open `https://localhost:3010` in your browser.
+
+To use a different port:
+
+```bash
+ATOO_PORT=4000 npx atoo-studio
+```
+
+## Install Globally
+
+```bash
+npm install -g atoo-studio
+atoo-studio
+```
+
+## Docker
+
+```bash
+docker run -p 3010:3010 ghcr.io/atooai/atoo-studio
+```
+
+## Features
+
+- **Multi-agent workflows** — Run Claude Code, Codex CLI and more in parallel across projects and worktrees
+- **Session forking & chaining** — Chain sessions across agents, search history via MCP
+- **Project changes tracking** — Know what was done, by which session, and when
+- **App preview** — Live preview via headless Chrome (CDP pixel streaming), with DevTools and responsive testing
+- **GitHub integration** — Issues, PRs, comments, labels — all from the workspace
+- **Git integration** — Branches, commits, worktrees, stash, diff views, one-click publish
+- **Database explorer** — 15+ database types with specialized views (PostgreSQL, MySQL, SQLite, Redis, MongoDB, Neo4j, InfluxDB, and more)
+- **Container management** — Docker, Podman, and LXC containers
+- **File editor** — Source, diff, rendered, and hex views with drag-and-drop
+- **Serial devices** — Flash ESP32 and Arduino boards through the browser via Web Serial
+- **Terminal** — Multiple PTY sessions with full terminal capabilities
+- **Reverse proxy** — Subdomain and path-based routing with automatic service detection
+- **Authentication** — Password, TOTP, and WebAuthn/passkey support
+- **HTTPS** — Built-in certificate authority trusted by the preview browser
+- **Mobile layout** — Responsive UI with swipe gestures
+- **PWA** — Installable as a desktop app
+
+## Requirements
+
+- Node.js 18+
+- Linux, macOS or WSL
+- git
+
+### Optional dependencies
+
+| Dependency | Feature |
+|------------|---------|
+| `claude` (Claude Code) | Claude Code agent |
+| `codex` (Codex CLI) | Codex agent |
+| `gh` (GitHub CLI) | GitHub integration |
+| docker / podman / lxc | Container management |
+| ffmpeg | Screen recording |
+
+Missing dependencies are reported as warnings on startup.
+
+### Linux setup
+
+```bash
+# Install Chrome/Puppeteer dependencies and ffmpeg
+sudo ./setup.sh
+
+# Optional: Serial control signals (DTR/RTS) for device flashing
+sudo ./setup-cuse.sh
+```
+
+### macOS setup
+
+```bash
+# Install ffmpeg for screen recording (optional)
+./setup.sh
+```
+
+## Platform Support
+
+| Feature | Linux | macOS | Windows |
+|---------|-------|-------|---------|
+| Core (agents, terminal, git, files) | Yes | Yes | No (use WSL) |
+| Browser preview | Yes | Yes | — |
+| Serial devices (CUSE) | Yes | No | — |
+| Serial devices (PTY fallback) | Yes | Yes | — |
+
+## MCP Tools
+
+Atoo Studio exposes MCP tools for agent integration:
+
+`generate_certificate` · `report_tcp_services` · `request_serial_device` · `search_session_history` · `suggest_continue_in_other_session` · `open_file` · `get_session_metadata` · `set_session_metadata` · `github_issue_pr_changed` · `connect_database` · `track_project_changes`
+
+## Other Installation Methods
+
+- **Docker**: `ghcr.io/atooai/atoo-studio`
+- **LXC/LXD**: Download from [GitHub Releases](https://github.com/atooai/atoo-studio/releases)
+- **Proxmox**: One-command [LXC](https://github.com/atooai/atoo-studio/tree/main/proxmox) and [VM](https://github.com/atooai/atoo-studio/tree/main/proxmox) scripts
+
+## Links
+
+- [GitHub](https://github.com/atooai/atoo-studio)
+- [Website](https://atoo.ai)
+
+## License
+
+MIT — Built by [Markus Furtlehner](https://github.com/markusfurtlehner)

package/README.npm.md

@@ -0,0 +1,118 @@
+# Atoo Studio
+
+**Agentic Development Environment** — A workspace where coding agents build, run and debug real systems.
+
+Atoo Studio is a browser-based development environment for working with coding agents like Claude Code and Codex CLI. It brings agents, code, preview, DevTools, Git, GitHub, databases and hardware devices into one workspace.
+
+Runs on Linux, macOS or WSL as a local web server. No cloud dependency, no vendor lock-in.
+
+## Quick Start
+
+```bash
+npx atoo-studio
+```
+
+Then open `https://localhost:3010` in your browser.
+
+To use a different port:
+
+```bash
+ATOO_PORT=4000 npx atoo-studio
+```
+
+## Install Globally
+
+```bash
+npm install -g atoo-studio
+atoo-studio
+```
+
+## Docker
+
+```bash
+docker run -p 3010:3010 ghcr.io/atooai/atoo-studio
+```
+
+## Features
+
+- **Multi-agent workflows** — Run Claude Code, Codex CLI and more in parallel across projects and worktrees
+- **Session forking & chaining** — Chain sessions across agents, search history via MCP
+- **Project changes tracking** — Know what was done, by which session, and when
+- **App preview** — Live preview via headless Chrome (CDP pixel streaming), with DevTools and responsive testing
+- **GitHub integration** — Issues, PRs, comments, labels — all from the workspace
+- **Git integration** — Branches, commits, worktrees, stash, diff views, one-click publish
+- **Database explorer** — 15+ database types with specialized views (PostgreSQL, MySQL, SQLite, Redis, MongoDB, Neo4j, InfluxDB, and more)
+- **Container management** — Docker, Podman, and LXC containers
+- **File editor** — Source, diff, rendered, and hex views with drag-and-drop
+- **Serial devices** — Flash ESP32 and Arduino boards through the browser via Web Serial
+- **Terminal** — Multiple PTY sessions with full terminal capabilities
+- **Reverse proxy** — Subdomain and path-based routing with automatic service detection
+- **Authentication** — Password, TOTP, and WebAuthn/passkey support
+- **HTTPS** — Built-in certificate authority trusted by the preview browser
+- **Mobile layout** — Responsive UI with swipe gestures
+- **PWA** — Installable as a desktop app
+
+## Requirements
+
+- Node.js 18+
+- Linux, macOS or WSL
+- git
+
+### Optional dependencies
+
+| Dependency | Feature |
+|------------|---------|
+| `claude` (Claude Code) | Claude Code agent |
+| `codex` (Codex CLI) | Codex agent |
+| `gh` (GitHub CLI) | GitHub integration |
+| docker / podman / lxc | Container management |
+| ffmpeg | Screen recording |
+
+Missing dependencies are reported as warnings on startup.
+
+### Linux setup
+
+```bash
+# Install Chrome/Puppeteer dependencies and ffmpeg
+sudo ./setup.sh
+
+# Optional: Serial control signals (DTR/RTS) for device flashing
+sudo ./setup-cuse.sh
+```
+
+### macOS setup
+
+```bash
+# Install ffmpeg for screen recording (optional)
+./setup.sh
+```
+
+## Platform Support
+
+| Feature | Linux | macOS | Windows |
+|---------|-------|-------|---------|
+| Core (agents, terminal, git, files) | Yes | Yes | No (use WSL) |
+| Browser preview | Yes | Yes | — |
+| Serial devices (CUSE) | Yes | No | — |
+| Serial devices (PTY fallback) | Yes | Yes | — |
+
+## MCP Tools
+
+Atoo Studio exposes MCP tools for agent integration:
+
+`generate_certificate` · `report_tcp_services` · `request_serial_device` · `search_session_history` · `suggest_continue_in_other_session` · `open_file` · `get_session_metadata` · `set_session_metadata` · `github_issue_pr_changed` · `connect_database` · `track_project_changes`
+
+## Other Installation Methods
+
+- **Docker**: `ghcr.io/atooai/atoo-studio`
+- **LXC/LXD**: Download from [GitHub Releases](https://github.com/atooai/atoo-studio/releases)
+- **Proxmox**: One-command [LXC](https://github.com/atooai/atoo-studio/tree/main/proxmox) and [VM](https://github.com/atooai/atoo-studio/tree/main/proxmox) scripts
+
+## Links
+
+- [GitHub](https://github.com/atooai/atoo-studio)
+- [Website](https://atoo.ai)
+
+## License
+
+MIT — Built by [Markus Furtlehner](https://github.com/markusfurtlehner)

package/bin/atoo-studio.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import fs from 'fs';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '..');
+
+/** Check if a command exists on PATH */
+function hasCommand(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- Windows: not supported ---
+if (process.platform === 'win32') {
+  console.error('[atoo-studio] Windows is not supported. Use WSL instead.');
+  process.exit(1);
+}
+
+// --- Check dependencies ---
+const warnings = [];
+const setupHints = new Set();
+
+// Required: git — core feature (version control, worktrees, file tracking)
+if (!hasCommand('git')) {
+  warnings.push('git not found — version control, worktrees, and file tracking will not work.');
+}
+
+// Optional: gh — GitHub integration (issues, PRs, authentication)
+if (!hasCommand('gh')) {
+  warnings.push('gh (GitHub CLI) not found — GitHub integration will not be available.');
+}
+
+// Optional: agent CLIs
+if (!hasCommand('claude')) {
+  warnings.push('claude (Claude Code) not found — Claude Code agent will not be available.');
+}
+if (!hasCommand('codex')) {
+  warnings.push('codex (Codex CLI) not found — Codex agent will not be available.');
+}
+
+// Optional: container runtimes
+if (!hasCommand('docker') && !hasCommand('podman') && !hasCommand('lxc')) {
+  warnings.push('No container runtime found (docker, podman, or lxc) — container management will not be available.');
+}
+
+// Optional: ffmpeg — screen recording
+if (!hasCommand('ffmpeg')) {
+  warnings.push('ffmpeg not found — screen recording will not work.');
+  setupHints.add('setup.sh');
+}
+
+// Platform-specific checks
+if (process.platform === 'linux') {
+  // Chrome / Puppeteer libs (only needed on Linux — macOS ships its own)
+  try {
+    execSync('ldconfig -p | grep -q libatk-1.0', { stdio: 'ignore' });
+  } catch {
+    warnings.push('Missing Chrome dependencies — browser preview/streaming will not work.');
+    setupHints.add('setup.sh');
+  }
+
+  // CUSE for serial control signals (DTR/RTS)
+  const cusebin = path.join(process.env.HOME || '', '.atoo-studio', 'bin', 'cuse_serial');
+  if (!fs.existsSync('/dev/cuse') || !fs.existsSync(cusebin)) {
+    warnings.push('CUSE not set up — serial control signals (DTR/RTS) will not work (e.g. auto-reset for ESP32).');
+    setupHints.add('setup-cuse.sh');
+  }
+}
+
+// Print warnings
+if (warnings.length > 0) {
+  for (const w of warnings) console.warn(`[atoo-studio] ${w}`);
+  if (setupHints.size > 0) {
+    const prefix = process.platform === 'linux' ? 'sudo ' : '';
+    const scripts = [...setupHints].map(s => `${prefix}./${s}`).join('  and  ');
+    console.warn(`[atoo-studio] Run:  ${scripts}`);
+  }
+  console.warn('');
+}
+
+// Start the server
+await import('../dist/src/index.js');