# TerminalOS
## 🖥️ Overview
TerminalOS is a full desktop-like experience within your terminal. Built using Python and the Textual framework, it offers a responsive and visually appealing TUI (Text User Interface) with multiple applications, window management, theme support, and keyboard navigation—all running inside a terminal window.
## ✨ Features
### 🖥️ Desktop Environment
* Beautiful ASCII desktop with real-time clock and system info
* Window management with modals and multiple screen support
* Theme support: Dark, Light, Matrix, Cyberpunk
* Keyboard shortcuts for quick navigation
### 📱 Built-in Applications
| App | Description | Status | Shortcut |
| ----------------- | ---------------------------------- | -------------- | --------------- |
| 📁 File Manager | Browse directories and file info | ✅ Ready | `1` in launcher |
| 📝 Text Editor | Syntax-highlighted file editing | ✅ Ready | `2` in launcher |
| 🔢 Calculator | Scientific calculator with history | ✅ Ready | `3` in launcher |
| 📊 System Monitor | CPU, memory, and disk usage | ✅ Ready | `4` in launcher |
| 💻 Terminal | Built-in CLI emulator | 🚧 Coming Soon | `5` in launcher |
| 🎵 Music Player | Playlist and audio playback | 🚧 Coming Soon | `6` in launcher |
### 🎨 Themes & Customization
* Dark, Light, Matrix, and Cyberpunk themes
* Persistent configuration settings
* Responsive layout for different terminal sizes
* ASCII art and Unicode icons
### ⌨️ Keyboard Shortcuts
* `F1`: Help
* `F12`: App Launcher
* `Ctrl+Q`: Quit
* `ESC`: Close current dialog/app
* `Tab`: Move between UI elements
## 🚀 Quick Start
### Installation
```bash
git clone https://github.com/000xs/terminalos.git
cd terminalos
pip install -r requirements.txt
pip install -e .
terminalos
```
## 📋 Requirements
* Python 3.8+
* Unicode-supported terminal
* Minimum 80x24 (120x40 recommended)
* Cross-platform (Windows, Linux, macOS)
### Dependencies
* `textual>=0.41.0`
* `rich>=13.0.0`
* `click>=8.1.0`
* `psutil>=5.9.0`
* `pyfiglet>=0.8.0`
* `pygments>=2.14.0`
## 🛠️ Installation Methods
### Method 1: Direct Launcher
```bash
git clone https://github.com/000xs/terminalos.git
cd terminalos
python start_terminalos.py
```
### Method 2: Package Install
```bash
git clone https://github.com/000xs/terminalos.git
cd terminalos
pip install -e .
terminalos
```
## 📖 Usage Guide
### Start TerminalOS
```bash
terminalos
# Optional flags:
--debug
--no-boot
--version
```
### Navigation
* Boot screen: `Enter`
* App launcher: `F12`
* Return to desktop: `ESC`
* Help: `F1`
## 📚 Application Guide
### 📁 File Manager
* Browse using arrow keys
* View metadata in sidebar
### 📝 Text Editor
* Syntax highlighting
* Real-time line/word/char count
* Tabs and file operations
### 🔢 Calculator
* Arithmetic + scientific functions
* Keyboard/mouse input
### 📊 System Monitor
* Live CPU, memory, and disk usage
## 🎨 Theme System
### Available Themes
* Dark (Default)
* Light
* Matrix
* Cyberpunk
### Change Theme
```bash
terminalos --theme matrix
```
## ⚙️ Configuration File
Located at:
* Windows: `%USERPROFILE%\.config\terminalos\`
* Linux/macOS: `~/.config/terminalos/`
Example `config.json`:
```json
{
"theme": "dark",
"debug": false,
"auto_save": true,
"appearance": {
"show_boot": true,
"animations": true,
"font_size": 12
},
"file_manager": {
"show_hidden": false,
"default_path": "~",
"sort_by": "name"
},
"text_editor": {
"syntax_highlighting": true,
"line_numbers": true,
"tab_size": 4
}
}
```
## 🧩 Architecture
```
terminalos/
├── core/ # App framework
├── desktop/ # Desktop and taskbar
├── apps/ # Built-in apps
├── config/ # Settings and themes
└── utils/ # Helpers and logging
```
## 🔧 Development Guide
### Setup
```bash
git clone https://github.com/000xs/terminalos.git
cd terminalos
pip install -e .
```
### Create Custom App
```python
from textual.screen import Screen
from textual.widgets import Header, Footer, Static
class MyCustomApp(Screen):
def compose(self):
yield Header()
yield Static("Hello from my custom app!")
yield Footer()
def on_key(self, event):
if event.key == "escape":
self.dismiss()
```
Add to launcher in `desktop/desktop.py`:
```python
from ..apps.my_app import MyCustomApp
self.dismiss()
self.app.push_screen(MyCustomApp())
```
## 🤝 Contributing
* Bug reports: Include Python version, OS, steps
* Features: Describe use case + mockup if possible
* Pull requests: Follow PEP8, type hints, test coverage
## 📝 Changelog
### v1.0.0
* Initial release
* Desktop, file manager, editor, calculator, system monitor
* 4 themes
### v1.1.0 (Planned)
* Terminal emulator
* Music player
* Plugin system
* More themes
## 🐛 Troubleshooting
* `ModuleNotFoundError`: Use direct launcher
* Python conflict: Use correct Python version
* Missing deps: `pip install textual rich click psutil pyfiglet pygments`
* Terminal display issues: `echo $TERM`
## 🏆 Credits
* Textual, Rich
* Terminalcraft slack channel, josia idea
## 📄 License
[MIT License ](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/000xs/terminalos",
"name": "terminalos",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "terminal, os, tui, cli, desktop",
"author": "000x",
"author_email": "000x <SITHUMSS9122@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/38/b1f32030e1d477ee4b26e50b95e17a70cfb4402ef26c2f409fe03d9d90ce/terminalos-1.0.2.tar.gz",
"platform": null,
"description": "# TerminalOS \n\n\n## \ud83d\udda5\ufe0f Overview\n\nTerminalOS is a full desktop-like experience within your terminal. Built using Python and the Textual framework, it offers a responsive and visually appealing TUI (Text User Interface) with multiple applications, window management, theme support, and keyboard navigation\u2014all running inside a terminal window.\n\n\n\n\n## \u2728 Features\n\n### \ud83d\udda5\ufe0f Desktop Environment\n\n* Beautiful ASCII desktop with real-time clock and system info\n* Window management with modals and multiple screen support\n* Theme support: Dark, Light, Matrix, Cyberpunk\n* Keyboard shortcuts for quick navigation\n\n### \ud83d\udcf1 Built-in Applications\n\n| App | Description | Status | Shortcut |\n| ----------------- | ---------------------------------- | -------------- | --------------- |\n| \ud83d\udcc1 File Manager | Browse directories and file info | \u2705 Ready | `1` in launcher |\n| \ud83d\udcdd Text Editor | Syntax-highlighted file editing | \u2705 Ready | `2` in launcher |\n| \ud83d\udd22 Calculator | Scientific calculator with history | \u2705 Ready | `3` in launcher |\n| \ud83d\udcca System Monitor | CPU, memory, and disk usage | \u2705 Ready | `4` in launcher |\n| \ud83d\udcbb Terminal | Built-in CLI emulator | \ud83d\udea7 Coming Soon | `5` in launcher |\n| \ud83c\udfb5 Music Player | Playlist and audio playback | \ud83d\udea7 Coming Soon | `6` in launcher |\n\n### \ud83c\udfa8 Themes & Customization\n\n* Dark, Light, Matrix, and Cyberpunk themes\n* Persistent configuration settings\n* Responsive layout for different terminal sizes\n* ASCII art and Unicode icons\n\n### \u2328\ufe0f Keyboard Shortcuts\n\n* `F1`: Help\n* `F12`: App Launcher\n* `Ctrl+Q`: Quit\n* `ESC`: Close current dialog/app\n* `Tab`: Move between UI elements\n\n## \ud83d\ude80 Quick Start\n\n \n### Installation\n\n```bash\ngit clone https://github.com/000xs/terminalos.git\ncd terminalos\npip install -r requirements.txt\npip install -e .\nterminalos\n```\n\n## \ud83d\udccb Requirements\n\n* Python 3.8+\n* Unicode-supported terminal\n* Minimum 80x24 (120x40 recommended)\n* Cross-platform (Windows, Linux, macOS)\n\n### Dependencies\n\n* `textual>=0.41.0`\n* `rich>=13.0.0`\n* `click>=8.1.0`\n* `psutil>=5.9.0`\n* `pyfiglet>=0.8.0`\n* `pygments>=2.14.0`\n\n## \ud83d\udee0\ufe0f Installation Methods\n\n### Method 1: Direct Launcher\n\n```bash\ngit clone https://github.com/000xs/terminalos.git\ncd terminalos\npython start_terminalos.py\n```\n\n### Method 2: Package Install\n\n```bash\ngit clone https://github.com/000xs/terminalos.git\ncd terminalos\npip install -e .\nterminalos\n```\n\n \n\n## \ud83d\udcd6 Usage Guide\n\n### Start TerminalOS\n\n```bash\nterminalos\n# Optional flags:\n--debug\n--no-boot\n--version\n```\n\n### Navigation\n\n* Boot screen: `Enter`\n* App launcher: `F12`\n* Return to desktop: `ESC`\n* Help: `F1`\n\n## \ud83d\udcda Application Guide\n\n### \ud83d\udcc1 File Manager\n\n* Browse using arrow keys\n* View metadata in sidebar\n\n### \ud83d\udcdd Text Editor\n\n* Syntax highlighting\n* Real-time line/word/char count\n* Tabs and file operations\n\n### \ud83d\udd22 Calculator\n\n* Arithmetic + scientific functions\n* Keyboard/mouse input\n\n### \ud83d\udcca System Monitor\n\n* Live CPU, memory, and disk usage\n\n## \ud83c\udfa8 Theme System\n\n### Available Themes\n\n* Dark (Default)\n* Light\n* Matrix\n* Cyberpunk\n\n### Change Theme\n\n```bash\nterminalos --theme matrix\n```\n\n## \u2699\ufe0f Configuration File\n\nLocated at:\n\n* Windows: `%USERPROFILE%\\.config\\terminalos\\`\n* Linux/macOS: `~/.config/terminalos/`\n\nExample `config.json`:\n\n```json\n{\n \"theme\": \"dark\",\n \"debug\": false,\n \"auto_save\": true,\n \"appearance\": {\n \"show_boot\": true,\n \"animations\": true,\n \"font_size\": 12\n },\n \"file_manager\": {\n \"show_hidden\": false,\n \"default_path\": \"~\",\n \"sort_by\": \"name\"\n },\n \"text_editor\": {\n \"syntax_highlighting\": true,\n \"line_numbers\": true,\n \"tab_size\": 4\n }\n}\n```\n\n## \ud83e\udde9 Architecture\n\n```\nterminalos/\n\u251c\u2500\u2500 core/ # App framework\n\u251c\u2500\u2500 desktop/ # Desktop and taskbar\n\u251c\u2500\u2500 apps/ # Built-in apps\n\u251c\u2500\u2500 config/ # Settings and themes\n\u2514\u2500\u2500 utils/ # Helpers and logging\n```\n\n## \ud83d\udd27 Development Guide\n\n### Setup\n\n```bash\ngit clone https://github.com/000xs/terminalos.git\ncd terminalos\n \npip install -e .\n```\n\n \n### Create Custom App\n\n```python\nfrom textual.screen import Screen\nfrom textual.widgets import Header, Footer, Static\n\nclass MyCustomApp(Screen):\n def compose(self):\n yield Header()\n yield Static(\"Hello from my custom app!\")\n yield Footer()\n \n def on_key(self, event):\n if event.key == \"escape\":\n self.dismiss()\n```\n\nAdd to launcher in `desktop/desktop.py`:\n\n```python\nfrom ..apps.my_app import MyCustomApp\nself.dismiss()\nself.app.push_screen(MyCustomApp())\n```\n\n## \ud83e\udd1d Contributing\n\n* Bug reports: Include Python version, OS, steps\n* Features: Describe use case + mockup if possible\n* Pull requests: Follow PEP8, type hints, test coverage\n\n## \ud83d\udcdd Changelog\n\n### v1.0.0\n\n* Initial release\n* Desktop, file manager, editor, calculator, system monitor\n* 4 themes\n\n### v1.1.0 (Planned)\n\n* Terminal emulator\n* Music player\n* Plugin system\n* More themes\n\n## \ud83d\udc1b Troubleshooting\n\n* `ModuleNotFoundError`: Use direct launcher\n* Python conflict: Use correct Python version\n* Missing deps: `pip install textual rich click psutil pyfiglet pygments`\n* Terminal display issues: `echo $TERM`\n\n## \ud83c\udfc6 Credits\n\n* Textual, Rich\n* Terminalcraft slack channel, josia idea\n\n## \ud83d\udcc4 License\n\n[MIT License ](LICENSE)\n\n \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A complete operating system experience in your terminal",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/000xs/terminalos/issues",
"Documentation": "https://terminalos.readthedocs.io/",
"Homepage": "https://github.com/000xs/terminalos",
"Repository": "https://github.com/000xs/terminalos"
},
"split_keywords": [
"terminal",
" os",
" tui",
" cli",
" desktop"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d1c24e34995120e4d1aabf177e74582f9999e0c16e6e1f1b0659fa1f20784f9a",
"md5": "baa94a17074e00aaea2ed67924a2c307",
"sha256": "20248b6aade27aa39f455899c0d90ab2db4a771f47e812ec9ba2eb646a894234"
},
"downloads": -1,
"filename": "terminalos-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "baa94a17074e00aaea2ed67924a2c307",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18239,
"upload_time": "2025-07-24T06:19:35",
"upload_time_iso_8601": "2025-07-24T06:19:35.760841Z",
"url": "https://files.pythonhosted.org/packages/d1/c2/4e34995120e4d1aabf177e74582f9999e0c16e6e1f1b0659fa1f20784f9a/terminalos-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a38b1f32030e1d477ee4b26e50b95e17a70cfb4402ef26c2f409fe03d9d90ce",
"md5": "08f9a2ea5d0b3ad349361fa24b8ebdc3",
"sha256": "db9b41d4526f04d56dc6c4a49d0c10c9415b178f528ce09f70b03ec67821c207"
},
"downloads": -1,
"filename": "terminalos-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "08f9a2ea5d0b3ad349361fa24b8ebdc3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17934,
"upload_time": "2025-07-24T06:19:36",
"upload_time_iso_8601": "2025-07-24T06:19:36.994512Z",
"url": "https://files.pythonhosted.org/packages/4a/38/b1f32030e1d477ee4b26e50b95e17a70cfb4402ef26c2f409fe03d9d90ce/terminalos-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 06:19:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "000xs",
"github_project": "terminalos",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "textual",
"specs": [
[
">=",
"0.41.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.9.0"
]
]
},
{
"name": "pyfiglet",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "pygments",
"specs": [
[
">=",
"2.14.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "terminalos"
}
JSON
