# Recommended Tools and Frameworks for holaOS Development: A Complete Step-by-Step Guide

> Explore essential tools and frameworks for holaOS development including TypeScript, npm, Electron with React, and Tailwind CSS. Master your holaOS projects with this comprehensive guide.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: getting-started
- Published: 2026-08-15

---

**Developers building on holaOS should use TypeScript, npm, tsup, Electron with React, Tailwind CSS, and dotenv for environment configuration; the platform also integrates Context7 MCP for agent communication and Superpowers for skill orchestration.**

holaOS is a **local-first, TypeScript-based monorepo** that powers a desktop AI operating system built by `holaboss-ai`. Whether you're contributing to the core runtime, building new skills, or customizing the desktop interface, understanding the officially supported tools and frameworks is essential for productive development. This walkthrough references actual source files and commands from the `holaboss-ai/holaOS` repository to ensure accuracy.

---

## Core Development Stack

The holaOS project standardizes on a modern TypeScript toolchain with clear conventions for each layer of the stack.

### Programming Language: TypeScript

The entire codebase—from the runtime API server to the desktop UI—is written in **TypeScript 4.x or higher**. This is explicitly highlighted in the repository's badge list and used consistently across all packages.

You can verify this by examining any source file in the runtime or desktop directories. Type checking is enforced as part of the standard development workflow.

### Package Manager: npm

All installation and build commands rely on **npm scripts** defined in the root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json). The README provides two primary paths:

- **Quick install**: A one-line bootstrap script
- **Manual install**: Step-by-step `npm run` commands

```bash

# Quick start (downloads, builds, and launches)

curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/refs/heads/main/scripts/install.sh \
  | bash -s -- --launch

```

*Source: [`README.md`](https://github.com/holaboss-ai/holaOS/blob/main/README.md), Quick-Start section*

### Build System: tsup

**tsup** is the designated bundler for holaOS components. Multiple [`tsup.config.ts`](https://github.com/holaboss-ai/holaOS/blob/main/tsup.config.ts) files exist across the repository, including in `runtime/api-server/`, indicating consistent use for building the channel gateway, API server, and other runtime modules.

This choice emphasizes fast, esbuild-powered compilation with native TypeScript support—ideal for a monorepo with interdependent packages.

---

## Desktop Application Framework

### Electron + React

The holaOS desktop shell is built on **Electron** with a **React** frontend. The `apps/desktop/` directory contains the Electron entry point and React component hierarchy.

Key files include:
- [`apps/desktop/electron/main.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/electron/main.ts) — main process bootstrap
- [`apps/desktop/README.md`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/README.md) — desktop-specific architecture notes

### Styling: Tailwind CSS

UI components use **Tailwind CSS** utility classes. The configuration is defined in `apps/desktop/tailwind.config.cjs`, which extends the standard Tailwind preset with project-specific design tokens.

When building new components, Tailwind classes should follow the conventions established in `packages/ui/`.

---

## Environment and Configuration

### dotenv for Local Settings

Development requires environment-specific configuration. The repository provides `apps/desktop/.env.example` as a template:

```bash

# Copy template to active environment file

cp apps/desktop/.env.example apps/desktop/.env

```

Edit this file to set values like MCP endpoint URLs and API keys before running the application.

---

## Agent and Model Integration

### Context7 MCP (Model Context Protocol)

holaOS uses **MCP** to abstract communication with any model server. The [`runtime-tools-mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime-tools-mcp.ts) module implements the client-side protocol handling:

```ts
// runtime/api-server/src/runtime-tools-mcp.ts
import { MCPClient } from '@holaos/mcp-client';

const client = new MCPClient({
  endpoint: process.env.MCP_ENDPOINT!,
  apiKey: process.env.MCP_API_KEY,
});

// Generate completions through any MCP-compatible model
const response = await client.complete({
  model: 'gpt-5.6',
  prompt: 'Summarize the latest project updates.',
});

```

This abstraction allows holaOS to switch between different LLM providers without changing application code.

### Superpowers for Skill Development

The documentation refers to **Superpowers** as the recommended pattern for adding capabilities. Specifically, "superpowers:subagent-driven-development" is highlighted as the architectural approach for extending holaOS functionality.

Skills are organized as reusable modules that agents can invoke, with clear separation between the skill implementation and the agent orchestration layer.

---

## Development Workflow Commands

After initial setup, these npm scripts drive daily development:

| Command | Purpose |
|---------|---------|
| `npm run desktop:install` | Install all desktop dependencies |
| `npm run desktop:prepare-runtime:local` | Build the local runtime bundle |
| `npm run desktop:typecheck` | Validate TypeScript types |
| `npm run desktop:dev` | Launch Electron in development mode |

*Source: [`README.md`](https://github.com/holaboss-ai/holaOS/blob/main/README.md), Manual Install section*

---

## Testing and Quality Assurance

### Vitest for Unit Testing

The repository includes `*.test.ts` files throughout and uses **Vitest** as the test runner. A [`scripts/test.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/test.sh) wrapper provides convenient execution.

### ESLint and Type Checking

Code quality is enforced through:
- **ESLint** for linting rules
- **TypeScript type-check** via `npm run desktop:typecheck`

Run type checking before committing to catch errors early in the development cycle.

---

## CI/CD and Version Control

### Git and GitHub Actions

Standard **Git** workflows are assumed, with **GitHub Actions** handling continuous integration. The README displays a CI status badge indicating automated testing on every push.

---

## Summary

- **TypeScript** is the sole language for all holaOS development
- **npm** manages dependencies and orchestrates builds through standardized scripts
- **tsup** bundles TypeScript modules across the monorepo
- **Electron + React** powers the desktop application with **Tailwind CSS** for styling
- **dotenv** handles environment configuration via `.env` files
- **Context7 MCP** provides model-agnostic LLM integration
- **Superpowers** offers the recommended pattern for skill and agent development
- **Vitest**, **ESLint**, and **GitHub Actions** maintain code quality and CI/CD

---

## Frequently Asked Questions

### What Node.js version does holaOS require?

holaOS development requires **Node.js ≥ 24** as specified in the installation bootstrap script and README prerequisites. The one-line installer will check for this version and prompt for upgrade if needed.

### Can I use yarn or pnpm instead of npm?

The official documentation and all [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) scripts are written for **npm**. While the monorepo structure might work with other package managers, only npm is tested and supported; using alternatives may break script assumptions.

### How do I add a custom MCP server to holaOS?

Edit your `apps/desktop/.env` file to include `MCP_ENDPOINT` and `MCP_API_KEY` variables pointing to your server. The [`runtime-tools-mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime-tools-mcp.ts) module will automatically use these values when initializing the `MCPClient`. No code changes are required if your server follows the MCP specification.

### Where should I place new UI components?

Create React components in `apps/desktop/src/components/` following the existing directory structure. Import icons from `@/components/ui/icons` as documented in [`AGENTS.md`](https://github.com/holaboss-ai/holaOS/blob/main/AGENTS.md), and apply **Tailwind CSS** utility classes for styling. Use `clsx` for conditional class merging if needed.