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

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. The README provides two primary paths:

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

# 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, Quick-Start section

Build System: tsup

tsup is the designated bundler for holaOS components. Multiple 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 — main process bootstrap
• 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:

# 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 module implements the client-side protocol handling:

// 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, 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 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 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 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, and apply Tailwind CSS utility classes for styling. Use clsx for conditional class merging if needed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}