⚡ NeuroOS

AI-Native Operating System Experience

A futuristic, modular AI runtime featuring an intelligent shell, workflow engine, memory system, and desktop environment built on top of Linux.

Created by Tanuj Bairwa

Live Demo • Documentation • Specification • Report Issue

📋 Table of Contents

Vision
Key Features
Tech Stack
Quick Start
Architecture
Usage Guide
Project Structure
Environment Variables
AI Integration
Testing
Roadmap
Contributing
License

🧠 Vision

NeuroOS is an AI-first operating system experience that sits on top of Linux as a hardware compatibility layer. Every interaction—from the command line to the desktop—is designed around AI assistance, context awareness, and autonomous task execution.

Core Principles:

Principle	Description
⚡ Futuristic	Clean, modern, sci-fi inspired aesthetics
🤖 Autonomous	AI proactively assists and anticipates your needs
🧩 Intelligent	Context-aware, learns from your patterns
🚀 Productivity-Focused	Streamlined workflows, minimal friction
🔮 AI-Centric	Every feature designed around AI interaction first

✨ Key Features

🤖 NeuroShell — AI-native command shell with context memory and intelligent command completion
💾 Persistent Memory — SQLite-backed context storage with full-text search and session management
⚙️ Workflow Engine — YAML-based automation with retry logic, timeouts, and 7+ built-in actions
🖥️ Desktop Environment — Next.js + Tauri desktop UI with live AI assistant, file manager, and system monitoring
🔌 Multi-AI Support — OpenAI, Google Gemini, Anthropic, Ollama (local), and more
📦 Clean Architecture — Modular, event-driven design with strong typing (Python, TypeScript, Rust)

🛠️ Tech Stack

Layer	Technologies
Backend	Python 3.10+, Rust 2021
Frontend	TypeScript 5.3, Next.js, React, Tauri
Data & Storage	SQLite (WAL mode), JSON, YAML
AI/ML	OpenAI GPT-4o-mini, Anthropic, Google Gemini
Architecture	Clean Architecture, Event-Driven, Monorepo (pnpm)
Testing	pytest, Coverage Reports

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

Tool	Version	Purpose
Python	3.10+	Shell & Workflow Engine
Node.js	20 LTS	Desktop UI
npm	10+	Package management
Git	Latest	Version control
Rust	Edition 2021	(Optional) Core components

Installation Steps

1. Clone the Repository

git clone https://github.com/TanujBairwa/NeuroOS.git
cd NeuroOS

2. Set Up Python Environment

# Create virtual environment
python -m venv .venv

# Activate (Linux / macOS)
source .venv/bin/activate

# Activate (Windows PowerShell)
.venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

3. Start NeuroShell

python neuroshell.py

Expected Output:

NeuroShell v0.2.0 — AI-Native Shell
Type help for commands · ai <prompt> for AI · exit to quit

neurosh❯ help
neurosh❯ mem set project "NeuroOS"
neurosh❯ mem get project
neurosh❯ status
neurosh❯ exit

4. Run Workflow Engine

python neuroworkflow.py

5. Launch Desktop UI

cd apps/desktop
npm install
npm run dev
# Open http://localhost:3000

The desktop includes:

🤖 Full-featured AI Assistant (GPT-4o-mini)
💻 Interactive NeuroShell terminal
📁 File Manager
⚙️ Settings Panel
📊 System Monitoring

6. Run Tests

python -m pytest tests/ -v

🏗️ Architecture

┌────────────────────────────────────────────────────────────────┐
│                    NeuroOS User Experience                      │
├──────────────┬──────────────────┬──────────────────────────────┤
│  NeuroShell  │  NeuroDesktop    │  NeuroWorkflow               │
│  (AI Shell)  │  (Next.js/Tauri) │  (Task Automation)           │
├──────────────┴──────────────────┴──────────────────────────────┤
│                       Application Layer                         │
│   Command Registry  │  Workflow Engine  │  AI Command Center   │
├────────────────────────────────────────────────────────────────┤
│                        Service Layer                            │
│   ConfigService  │  MemoryRepository  │  EventBus              │
├────────────────────────────────────────────────────────────────┤
│                        Domain Layer                             │
│  Frozen Dataclasses (Python)  │  Branded Primitives (TS)       │
├────────────────────────────────────────────────────────────────┤
│                  Linux Kernel (Hardware Layer)                  │
└────────────────────────────────────────────────────────────────┘

Design Principles: Clean Architecture · Event-Driven · Modular · Strongly Typed · Open/Closed Principle · Full Documentation

For detailed architecture, see ARCHITECTURE.md.

💻 Usage Guide

NeuroShell Commands

AI Commands
  ai <prompt>              Send a prompt to the AI assistant
  ai context               Show active AI context

Memory Commands
  mem set <key> <value>    Store a key-value pair persistently
  mem get <key>            Retrieve by key
  mem search <query>       Full-text search across memories
  mem list [type]          List memories (general / workflow / session / preference)
  mem del <key>            Delete entries for a key

System Commands
  status                   Show system status (memory, AI, config)
  version                  Print NeuroShell version
  history [n]              Show last N commands
  config [get <section>]   Show configuration
  ! <command>              Execute shell commands (e.g. !ls, !git status)
  clear                    Clear the terminal screen
  exit / quit              Exit NeuroShell

Workflow Engine

Define automation workflows in YAML or JSON. Place them in ~/.config/neuroos/workflows/.

Example Workflow:

name: daily_check
description: Daily system check and backup
enabled: true
steps:
  - name: log_start
    action: log
    params:
      message: "Daily check starting…"
      level: info

  - name: notify
    action: notify
    params:
      title: NeuroOS
      body: "All systems nominal."
    on_error: continue

  - name: backup
    action: shell
    params:
      command: "tar -czf ~/backup-{date}.tar.gz ~/Documents"
    retry_count: 2
    timeout_ms: 60000

Built-in Actions:

Action	Description
`log`	Log a message (debug / info / warn / error)
`shell`	Run a shell command asynchronously
`notify`	Send a desktop notification
`sleep`	Wait for N seconds
`store`	Write a value to NeuroMemory
`retrieve`	Read from NeuroMemory into context
`if`	Evaluate a condition and branch

Add Custom Actions:

engine.register_action("send_email", my_email_handler)

📦 Project Structure

NeuroOS/
├── neuroshell.py                 ← AI shell entry point
├── neuroworkflow.py              ← Workflow engine demo
├── requirements.txt              ← Python dependencies
├── ARCHITECTURE.md               ← Detailed architecture guide
│
├── src/                          ← Python source packages
│   ├── neurocore/
│   │   ├── domain/types.py       ← Frozen dataclasses, Result monad
│   │   ├── infrastructure/
│   │   │   ├── event_bus.py      ← Thread-safe EventBus
│   │   │   └── memory_repository.py  ← SQLite (WAL mode)
│   │   └── services/
│   │       └── config_service.py ← Validated config
│   ├── neuroshell/
│   │   └── commands.py           ← Command registry
│   └── neuroworkflow/
│       ├── engine.py             ← WorkflowEngine
│       ├── actions.py            ← Action handlers
│       └── loader.py             ← YAML/JSON loader
│
├── packages/                     ← TypeScript monorepo
│   ├── core/src/                 ← Types, events, config
│   ├── ai/src/                   ← AI engine, parser
│   ├── hooks/src/                ← React hooks
│   └── ui/src/                   ← Shared UI components
│
├── apps/
│   └── desktop/src/              ← Next.js + Tauri desktop
│       ├── components/           ← UI components
│       └── services/             ← API layer
│
├── tests/
│   └── test_core.py              ← 12+ unit tests
├── scripts/
│   └── setup.sh                  ← Linux setup script
└── SPEC.md                       ← Product specification

🌍 Environment Variables

Create a .env file in the root directory:

# AI Provider & Model
NEURO_AI_PROVIDER=openai              # openai | anthropic | google | ollama
NEURO_AI_MODEL=gpt-4o-mini            # Model name
NEURO_AI_API_KEY=sk-proj-xxxxx        # API key (if needed)

# Logging
NEURO_LOG_LEVEL=info                  # debug | info | warn | error

# Runtime
NEURO_ENV=development                 # development | production

Minimal Setup (Desktop):

export NEURO_AI_PROVIDER=openai
export NEURO_AI_API_KEY=sk-proj-...
export NEURO_AI_MODEL=gpt-4o-mini
npm run dev

Local AI (No Key Required):

export NEURO_AI_PROVIDER=ollama
export NEURO_AI_MODEL=llama3
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3
python neuroshell.py

🤖 AI Integration

NeuroOS supports multiple AI providers. Seamlessly switch between cloud and local models.

Provider	Model	Status	Config
OpenAI	gpt-4o-mini, gpt-4o	✅ Active	`sk-proj-...` key
Google Gemini	gemini-2.0-flash-lite	⚙️ Supported	Replace base URL + key
Anthropic	claude-3-5-sonnet	⚙️ Supported	Replace base URL + key
Ollama (Local)	llama3, mistral	✅ Free	No key needed

Quick Switch:

# Cloud AI
export NEURO_AI_PROVIDER=openai
export NEURO_AI_API_KEY=sk-proj-...
python neuroshell.py

# Local AI (Ollama)
export NEURO_AI_PROVIDER=ollama
export NEURO_AI_MODEL=llama3
python neuroshell.py

🧪 Testing

Run Full Test Suite

python -m pytest tests/ -v

Run Specific Test

python -m pytest tests/test_core.py::TestMemoryRepository -v

Generate Coverage Report

python -m pytest tests/ --cov=src --cov-report=term-missing

🖥️ Testing on VirtualBox

NeuroOS runs on top of Linux—it is not a bootable ISO. To test locally:

Download VirtualBox → virtualbox.org
Download Ubuntu 22.04 Server → ubuntu.com
Create VM — 4 GB RAM, 25 GB disk, Ubuntu 64-bit
Install Ubuntu inside the VM
Copy NeuroOS via Shared Folder or scp

Run Setup:

chmod +x scripts/setup.sh && ./scripts/setup.sh

On Windows? Test Python components now—no VM needed:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python neuroshell.py

🗺️ Roadmap

Phase	Status	Description
Phase 1 — Foundation	✅ Complete	Shell, config, runtime, clean architecture
Phase 2 — Memory & Context	✅ Complete	SQLite memory, persistence, search
Phase 3 — Workflow Engine	✅ Complete	Automation, retry, timeout, event-driven
Phase 4 — Desktop Environment	✅ Complete	Next.js desktop, AI sidebar, shell, files, settings
Phase 5 — AI Integration	✅ Complete	OpenAI GPT-4o-mini live chat, conversation history
Phase 6 — Backend Gateway	🔄 In Progress	Python ↔ Next.js IPC, real memory/workflow API
Phase 7 — Autonomous Agents	🔮 Planned	Tool-use, task planning, multi-agent workflows

🎨 Design Patterns

Result Monad Pattern

Never throw across layer boundaries:

result = repo.retrieve("key")
if result.ok:
    print(result.value.value)
else:
    print(result.error.message)  # ErrorCode.MEMORY_NOT_FOUND

Event-Driven Architecture

All components communicate via the EventBus:

event_bus.publish(NeuroEvents.MEMORY_STORED, {"key": "foo", "value": "bar"})
unsub = event_bus.subscribe("memory.stored", lambda e: print(e.payload))
unsub()  # clean up

Open/Closed Principle

Extend without modifying:

# Add a new shell command
@command("weather", "Show current weather")
async def cmd_weather(args, svc):
    return CommandResult(success=True, output="☀️  25°C, Clear")

# Add a new workflow action
engine.register_action("send_slack", slack_handler)

🤝 Contributing

We welcome contributions! Follow these steps:

Fork the repository
Create a feature branch: git checkout -b feat/my-feature
Follow coding rules in ARCHITECTURE.md
Write tests for new modules
Open a Pull Request with a clear description

Before committing:

Run tests: pytest tests/ -v
Check coverage: pytest --cov=src
Follow clean code principles

📄 License

This project is licensed under the MIT License. See LICENSE for details.

📞 Contact & Support

GitHub: @TanujBairwa
Issues: Report a bug
Discussions: Join conversations

🚀 Building the future of computing, one AI at a time.

NeuroOS v0.2.0 — Specification • Architecture • License

Built with ❤️ by Tanuj Bairwa | Powered by OpenAI GPT-4o-mini

⭐ If you find NeuroOS helpful, please consider giving it a star!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
apps/desktop		apps/desktop
config		config
crates		crates
distro		distro
docs		docs
packages		packages
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
ARCHITECTURE.md		ARCHITECTURE.md
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
SPEC.md		SPEC.md
docker-compose.yml		docker-compose.yml
neuroshell.py		neuroshell.py
neuroworkflow.py		neuroworkflow.py
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

⚡ NeuroOS

AI-Native Operating System Experience

📋 Table of Contents

🧠 Vision

✨ Key Features

🛠️ Tech Stack

🚀 Quick Start

Prerequisites

Installation Steps

1. Clone the Repository

2. Set Up Python Environment

3. Start NeuroShell

4. Run Workflow Engine

5. Launch Desktop UI

6. Run Tests

🏗️ Architecture

💻 Usage Guide

NeuroShell Commands

Workflow Engine

📦 Project Structure

🌍 Environment Variables

🤖 AI Integration

🧪 Testing

Run Full Test Suite

Run Specific Test

Generate Coverage Report

🖥️ Testing on VirtualBox

🗺️ Roadmap

🎨 Design Patterns

Result Monad Pattern

Event-Driven Architecture

Open/Closed Principle

🤝 Contributing

📄 License

📞 Contact & Support

🚀 Building the future of computing, one AI at a time.

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages