ASHIGARU

A modular Terminal User Interface (TUI) framework built with React and Ink. ASHIGARU provides a comprehensive desktop-like environment within the terminal, featuring a window manager, extensible program system, AI integration, state persistence, and automatic updates.

Table of Contents

• Overview
• Key Features
• Prerequisites
• Installation
• Usage
• Built-in Programs
  • System Programs
  • ASHIGARU Suite
  • Utility Programs
• Keyboard Controls
• API & IPC System
• Development
  • Project Structure
  • Creating Custom Programs
  • State Persistence
• Themes
• Architecture
• Updating
• Contributing
• License

---

Overview

ASHIGARU is a terminal-based operating system interface that combines the power of modern web technologies with the efficiency of command-line interfaces. It features a complete window management system, multiple concurrent programs, customizable themes, and a modular architecture that allows for easy extension and customization.

---

Key Features

Core Functionality

• Window Management System - Run multiple programs simultaneously with focus management, minimize/maximize capabilities, and keyboard-driven navigation
• State Persistence - Automatic saving and restoration of program states across sessions
• Modular Program Architecture - Extensible plugin system allowing custom programs to integrate seamlessly
• Self-Updating System - Built-in updater that checks GitHub releases and safely installs updates with automatic backup and rollback
• Theme System - Four built-in themes (Cyberpunk, Mono, Matrix, Amber) with customizable color schemes
• Package Manager - Download and install programs from GitHub releases or direct URLs
• AI Integration - Native support for Google Gemini AI with extensible provider architecture

Technical Features

• Built with React 19 and TypeScript for type-safe, component-based development
• Ink-based rendering for efficient terminal UI updates
• Hot-reload development mode for rapid iteration
• Comprehensive error handling and state management
• Session persistence and program state recovery
• Input locking system for text field protection

---

Prerequisites

System Requirements

• Node.js version 16.0.0 or higher
• npm version 7.0.0 or higher
• Terminal with Unicode support
• Minimum terminal size: 80x24 recommended

Optional Requirements

• Google Gemini API key for AI features
• Git for development and contributions
• Audio player for sound effects (one of: mpg123, ffplay, mpv, vlc)

---

---

Installation

Standard Installation

Clone the repository and install dependencies:

git clone https://github.com/savannah-i-g/ASHIGARU.git
cd ASHIGARU
npm install --legacy-peer-deps

Configuration

Copy the environment template and configure your API keys:

cp .env.example .env

Edit the .env file and add your API credentials. The Google Generative AI API key can be obtained from the Google AI Studio.

Required environment variables:

• GOOGLE_GENERATIVE_AI_API_KEY - API key for Google Gemini integration

Building

Compile TypeScript source to JavaScript:

npm run build

This generates the compiled application in the dist/ directory.

---

Usage

Development Mode

Launch the application with hot-reload enabled for development:

npm run dev

Changes to source files will automatically reload the application.

Production Mode

Run the compiled production build:

npm start

---

Built-in Programs

ASHIGARU includes a comprehensive suite of built-in programs organized into system, suite, and utility categories.

System Programs

Core

Control Panel - Comprehensive system configuration center with categorized settings:

• Display: Theme selection, wallpaper, and wallpaper color customization
• Audio: Enable/disable sound effects for UI feedback
• System: Animations, performance mode, and refresh rate settings
• Date & Time: Clock format preferences and timezone display
• Shortcuts: Reference guide for all keyboard shortcuts
• About: System information, version, and credits

System Updater - Check for and install ASHIGARU updates from GitHub releases. Features automatic backup creation, safe installation with rollback capability, and progress tracking.

Package Manager - Download and install programs from GitHub releases or direct URLs. Features automatic manifest validation, folder structure preservation, conflict detection, and update checking.

Environment Manager - View, edit, add, and delete environment variables. Export to .env format. Navigate with arrow keys and search/filter capabilities.

Monitoring

System Info - Display comprehensive system information including hostname, operating system, architecture, CPU details, memory usage, and uptime statistics.

Processes - View and manage running system processes with real-time updates. Displays process ID, CPU usage, memory consumption, and command information. Sort and terminate processes.

Network - Monitor network interfaces and active connections. Shows interface status, IP addresses, MAC addresses, and network statistics.

System Health - Aggregate health monitoring dashboard with health score (0-100), critical issue alerts, system metrics visualization, and quick-fix suggestions.

---

ASHIGARU Suite

Office productivity applications with full state persistence support.

Suite Docs - Document editor with Markdown support. Features line-by-line editing, save to .txt or .md formats, word/character count, and automatic state persistence.

Suite Sheets - CSV spreadsheet viewer and editor. Navigate cells with arrow keys, edit values, add rows/columns dynamically, and save to CSV format.

Suite Slides - JSON-based presentation viewer. Display text slides with formatting control, navigate forward/backward, and support for speaker notes.

---

Utility Programs

Tools

Clock - Digital clock and timer utility with three modes: Clock, Timer (custom minutes), and Stopwatch. Large block-digit display with theme support.

File Browser - Navigate the filesystem with keyboard-driven interface. View directory contents, create/rename/delete files and folders, and file size information.

Data Formatter - Format, validate, and convert between JSON/YAML/XML. Features syntax highlighting, file comparison/diff viewer, and export capabilities.

Productivity

Terminal - Interactive shell terminal with full command execution capabilities. Supports standard shell commands and process management.

Editor - Vim-like code editor with syntax highlighting support. Features multiple editing modes (normal/insert/command), file operations, and scrollable view.

Notes - Quick note-taking application with persistent storage. Create, edit, delete, and list notes with simple interface.

Internet

NeoRin AI - AI-powered assistant using Google Gemini. Provides conversational AI capabilities with session management, context retention, and specialized system prompt for technical analysis. Multiple model selection (Gemini 3 Pro/Flash, 2.5, 2.0, 1.5).

Browser - Text-based web browser for viewing web content in the terminal. Supports basic HTML rendering and navigation.

---

Keyboard Controls

Global Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+L | Open program launcher menu | | ` (backtick) | Toggle window list | | Ctrl+D | Minimize focused window | | Ctrl+X or Ctrl+W | Close focused window | | Ctrl+Q | Quit ASHIGARU | | Tab | Cycle focus between windows | | Esc | Cancel/close current dialog or menu |

Window Management

• Arrow keys to navigate menus and selections
• Click or use arrow keys to select windows
• Multiple windows can run simultaneously in tiled layout
• Minimized windows accessible via window list (backtick)

Text Input Protection

When using text input fields (file paths, editing, search):

• Global shortcuts are automatically disabled to prevent accidental actions
• Esc always available to exit text input mode
• Input automatically unlocked when exiting text mode

---

API & IPC System

ASHIGARU v1.2.5 introduces a unified API layer and Inter-Process Communication (IPC) system for programs.

Unified API

Programs receive an api prop with access to system features:

| Module | Description | |--------|-------------| | api.system | System info, events, and lifecycle | | api.storage | Persistent key-value storage per program | | api.notifications | Toast notifications via IPC | | api.windows | Window management operations | | api.sound | Audio feedback (system + custom sounds) | | api.ai | AI/LLM capabilities |

Example:

const MyProgram = ({ api }) => {
    const stats = api.system.getStats();
    await api.storage.set('key', value);
    api.notifications.success('Saved!');
    api.sound.playCustom('alert.mp3');
};

IPC System

Programs can communicate via the ipc prop:

• Pub/Sub - Broadcast messages to channels (ipc.publish, ipc.subscribe)
• Direct - Send to specific windows (`ipc.sendTo