🌟 Overview

HalkaX-Mini is a production-grade, state-of-the-art Voice AI Assistant. Harnessing the power of the Google Gemini Live API, HalkaX provides real-time, conversational interactions combined with powerful system integrations.

Whether you prefer a beautiful graphical interface or a blazing-fast command-line experience, HalkaX-Mini adapts to your workflow seamlessly.

📸 Showcase

| Premium Web Interface | Hacker-Style CLI | | :---: | :---: | | | | | Beautiful Three.js Visualizer & React UI | Clean, Silent & Branded Terminal Experience |

✨ Features

• 🎙️ Advanced Voice AI: Powered by Google Gemini Live API for real-time, low-latency, and highly intelligent conversational experiences.
• 💻 Deep OS Integration: Seamlessly open, close, and manage applications on your local Windows machine.
• 🌍 Web Search & Knowledge: Instantly search Google and fetch accurate, up-to-date information.
• 🚀 CLI Powerhouse: Exposes an easy-to-use Command Line Interface (CLI) for power users to manage the assistant entirely from the terminal.

🛠️ Tech Stack

Built with modern, robust technologies ensuring high performance and a premium feel:

• Frontend: React, Tailwind CSS, Framer Motion, Three.js
• Backend: Node.js, Express, Socket.io
• AI Core: Google Gemini Live API, Glowe Agent
• System: Windows API, Decibri (Microphone integration)

🔑 Prerequisites

Before you begin, ensure you have obtained the necessary API Keys:

• Google Gemini API Key

🚀 Quick Start & Installation

You can use HalkaX-Mini as a globally installed CLI (Recommended) or run it locally from the source code for development.

Option A: Global CLI Installation (The Primary Path)

The most robust way to experience HalkaX is directly through your terminal.

⚠️ Important Requirement: HalkaX-Mini strictly requires Node.js v24+. Please ensure your environment is updated before proceeding.

Step 1: Install Globally

Install the package globally via npm to make the halkax command available everywhere on your system:

npm install -g halkax-mini

Step 2: First Run Experience

Launch the assistant for the first time:

halkax

On this initial run, an interactive Setup Wizard will launch. It will guide you to:

1. Input your Gemini API Key.
2. Select your preferred Voice Personality (Choose between the crisp tones of Lyra or Puck).

Note: Subsequent runs will completely bypass this setup, instantly booting the Neural Core and dropping you straight into the Voice AI experience.

Option B: Local Development & Hacker Setup

If you want to poke around the codebase, tweak the UI, or contribute to the project, follow this path.

1. Clone the Repository

git clone https://github.com/201HalkaHack/HalkaX-Mini.git
cd HalkaX-Mini

2. Install Dependencies

Ensure you are on Node.js v24+, then run:

npm install

3. Configure Environment Variables

Create a .env file in the root directory based on the following template. Replace the placeholders with your actual API keys:

# Google Gemini API Key for Voice AI
GEMINI_API_KEY=your_gemini_api_key_here

4. Ignite the Core

Start both the backend server and the React frontend concurrently in development mode:

npm run dev

Option C: Docker Deployment

For headless environments, homelab servers, or cloud deployments, HalkaX-Mini comes fully containerized out-of-the-box.

Note: Running via Docker disables local Windows integrations and native microphone access due to container isolation. It is best suited for network-level access or backend services.

Launch the full stack in detached mode:

docker-compose up -d --build

🚑 Troubleshooting & Common Issues

Encountering issues? Here are the most common hurdles and how to bypass them:

• "Unsupported Engine" Error during npm install: You are running an older version of Node.js. HalkaX-Mini enforces strict environment rules via .npmrc. You must update to Node.js v24+.

• Voice AI / Microphone Not Working (Windows): Windows may block terminal apps from accessing your microphone by default. Go to Windows Settings > Privacy & security > Microphone and ensure that "Let desktop apps access your microphone" is turned ON.

📂 Project Structure

├── bin/                 # CLI Executable
│   └── halkax-mini.ts
├── data/                # Local data storage
│   └── memory.json
├── public/              # Static Assets
├── src/
│   ├── client/          # Premium React Frontend
│   │   ├── assets/
│   │   ├── utils/
│   │   │   └── AICore.tsx
│   │   ├── views/
│   │   │   └── HalkaXMini.tsx
│   │   ├── App.tsx
│   │   ├── index.css
│   │   └── main.tsx
│   ├── config/          # Configuration handling
│   │   └── dot-env.ts
│   └── server/          # Powerful Node.js Backend
│       ├── agent/       # Core Voice Agent
│       │   └── halkax-voice.ts # Gemini Live API
│       ├── constants/
│       │   └── StreamConfig.ts
│       ├── lib/
│       │   └── port-picker.ts
│       ├── tools/       # Specialized Agents
│       │   ├── app-agent.ts
│       │   ├── browser-agent.ts
│       │   └── nexus-agent.ts
│       ├── utils/       # Utility Functions
│       │   └── memory.ts
│       └── main.ts      # Server entrypoint
├── Dockerfile           # Docker Containerization
├── docker-compose.yml   # Multi-container setup
├── .nvmrc               # Node Version Control
├── .npmrc               # NPM Configuration
└── .env                 # Environment Configuration

🛠️ Developer Experience (DX)

HalkaX-Mini is built with a production-ready developer experience in mind. It includes:

• Node Version Management: .nvmrc and .npmrc to strictly control and match Node/NPM environments.
• Containerization: Native Dockerfile and docker-compose.yml support for easy isolated deployments.
• Code Quality: Enforced linting and formatting rules via Prettier and Commitlint.
• Changelog Automation: Configurations for automated, standardized changelog generation.

🤝 Contributing

We welcome contributions from the community! Whether you want to fix bugs, improve documentation, or add new features, please check our Contributing Guidelines to get started.

Please ensure you also review our Code of Conduct to keep our community approachable and respectable.

🛡️ Security

Security is a priority. For instructions on how to report vulnerabilities and our security practices, please refer to our Security Policy.

📄 License

This project is licensed under the terms of the included LICENSE file.