Electra AI Center

The AI Layer Your Linux Desktop Has Been Waiting For

Electra AI Center is a fully-integrated, OS-level artificial intelligence suite that ships as a single compiled binary. It runs in your terminal, launches a full VSCode-style GUI, integrates with your file manager, connects to Telegram, manages your finances, and autonomously executes tasks while you work on something else.

Think of it as your personal Jarvis — not a chat window bolted onto your desktop, but a deep integration layer that can read your screen, manage your windows, write and run code, browse the web, control smart home devices, generate income, and talk back through Telegram when jobs are done.

Architecture Overview

Electra is a single compiled Nuitka binary (ai_terminal.bin) that bundles the terminal app, GUI, all agents, LSP integration, and finance bot. It connects to the Electra backend API at makululinux.us:2007 for AI inference — the server handles conversation history, model routing, and Patreon tier validation.

Installation

MakuluLinux (Official)

Electra ships pre-installed on MakuluLinux. Launch from your application menu or terminal.

Other Linux Distributions

Electra is compiled against Ubuntu 22.04 for maximum compatibility and runs on most major distributions including Ubuntu, Fedora, Arch, Mint, Pop!_OS, Debian, openSUSE, Manjaro, and others.

# Run the installer (headless distros use install-headless.sh)
bash install.sh

# Or headless (server / no display)
bash install-headless.sh

First Launch

# Terminal mode
ai_terminal.bin

# GUI mode (VSCode-style interface)
ai_terminal.bin --gui

# Or type /gui from inside the terminal app

Login

/login           # Log in with your Electra / Patreon account
/account         # View current account + tier info
/refresh         # Re-sync after changing your Patreon plan
/unlock          # Unlock Pro features with a licence key

Patreon Tiers

Electra uses Patreon for subscription management. Your tier determines daily request limits and which AI providers you can access.

Paid Provider Models (Major / Commander only)

These providers cost real money per token and are gated to Major ($40) and Commander ($100) tiers. They appear in the model picker for all tiers with a 🔒 lock icon, and auto-routing prioritises them for Major/Commander users.

• DeepSeek Direct (ds-) — ds-deepseek-v4-flash ($0.14/$0.28 per 1M), ds-deepseek-v4-pro ($1.74/$3.48 per 1M). Automatic prefix caching at 98% discount.
• ByteDance Ark (bt-) — bt-ark-code-latest, bt-dola-seed-2.0-pro/lite/code, bt-bytedance-seed-code, bt-glm-5.1, bt-glm-4.7, bt-kimi-k2.5, bt-gpt-oss-120b.
• Ollama Cloud (ol-) — 30+ hosted models including ol-qwen3-coder-480b, ol-devstral-2-123b, ol-nemotron-3-ultra, ol-deepseek-v4-pro, ol-kimi-k2.6, and more.

Operating Modes

Electra has six primary operating modes, each with its own AI personality, tool set, and capabilities. Switch modes with a slash command from anywhere.

Chat Mode

The default conversational mode. Backed by server-side memory (conversation_id), so context persists across sessions when you keep the same conversation.

Chat-Mode Commands

Coder Mode

The full autonomous software engineer. Coder mode runs an agentic loop of up to 80 turns (100 in extended mode), calling tools to write files, run code, check errors, and iterate — just like a human developer. All changes are backed up before modification and can be rolled back.

What the AI Can Do in Coder Mode

• Read the full project file tree and symbol index
• Write, edit, create, move, copy, and delete files (GUI tree auto-updates)
• Run shell commands, capture output, auto-fix errors
• Call LSP tools: go-to-definition, find-all-references, rename-symbol, hover
• Run the project (/run) and auto-fix crashes
• Lint files (/lint) and apply fixes
• Read AT-SPI screen context (live text from any focused window)
• Send desktop notifications when long tasks complete
• Tile / arrange windows (Hyprland / wmctrl)
• Generate and run tests (pytest, Jest, go test, RSpec, cargo test)

Coder-Mode Commands

Live Code Map

Coder mode maintains a real-time map of all project files and when they were last modified. The AI uses this to know the exact current state of the workspace at every turn. The code map badge in the GUI activity log shows the tracked file count. Error messages include structured extraction of FILE:LINE:TYPE from tracebacks, and intent-aware routing uses the narrowest tool subset for DEBUG vs REFACTOR vs QUESTION tasks.

Per-Project Stable Memory

Each workspace gets a stable conversation_id derived from its path. This means the server-side MemPalace remembers your project across sessions — the AI knows what you worked on last time, what decisions were made, and what the current architecture looks like, without you having to re-explain.

Writer Mode

Autonomous content creation. Writer mode understands four operations: CREATE (new content), EDIT (modify existing), ADVISE (review without changes), and REMOVE (delete sections). It maintains a live document and exports to multiple formats.

Novel Mode

A complete AI-powered book authoring pipeline. Enter your story idea and Novel Mode guides you through the full process from high-level overview to chapter-by-chapter writing to final EPUB/PDF export.

Command Mode

The autonomous PC manager. Command mode can install packages, manage services, control Docker, open SSH sessions, monitor system health, and perform any task you'd normally do in a terminal — driven entirely by natural language.

System Management

GUI Mode — VSCode-Style IDE

Launch with /gui from the terminal or ai_terminal.bin --gui. The GUI provides a full desktop IDE experience — no terminal required.

Layout Overview

Command Mode 3-Pane Layout

In Command mode, the GUI switches to a dynamic 3-pane layout. An execution log pane auto-shows during tasks, and a file preview pane appears when files are being edited. Both collapse automatically when tasks complete — full command-mode parity without ever opening a terminal.

GUI Feature Highlights

Command Palette (Ctrl+Shift+P)

VS Code-style command palette with fuzzy search across all commands, file operations, mode switches, and custom actions. Press Ctrl+Shift+P from anywhere in the GUI.

Quick File Open (Ctrl+P)

Fuzzy file picker — type part of any filename to jump to it instantly. Same muscle memory as VS Code.

Inline AI Edit (Ctrl+K)

Select text in the editor and press Ctrl+K to open a popup that lets you describe a change. The AI surgically rewrites just the selected region with surrounding file context (±30 lines) injected for accuracy. Preserves indentation automatically.

Git Panel

Full Git integration in the sidebar: unstaged/staged changes, diff viewer, commit message, push/pull. Visual indicators on file tree for modified/added/deleted files.

Diagnostics Tab

Live LSP diagnostics from pyright, tsserver, rust-analyzer, clangd, or gopls displayed in a sortable list. Click any error to jump to it in the editor. AI can auto-fix all issues in the list.

Minimap

Code minimap on the right edge of the editor. Toggle with Ctrl+Shift+\ or the button in the status bar.

Split Editor

Split the editor vertically with Ctrl+\. Each pane has its own tab bar and independently tracks the active file.

Theme System

Electra is fully isolated from the system GTK theme — no matter what theme the user has installed (Breeze, Mint-Y, Arc, Yaru, etc.), Electra renders identically. Built-in themes: Light Ink, Dark Terminal, Solarized, Monokai, Nord, and any themes installed via Open VSX extensions.

Voice Input

Click the 🎤 button or press Ctrl+M to dictate a message. Uses local speech recognition. The transcript appears in the chat input automatically.

Image Attachment

Click the attachment button or press Ctrl+I to attach an image for AI vision analysis. Compatible with vision-capable models from NVIDIA NIM, MiniMax, and others.

@-Mention File Context

Type @filename in the chat to inject that file's content directly into the AI context. The AI can then discuss, edit, or refactor the file without you having to copy-paste.

Next-Step Suggestions

After a Coder task completes, the GUI offers 3 clickable suggested next actions based on what was just done — e.g. "Run tests", "Commit changes", "Review diff".

Session Restore

The workspace, open tabs, and scroll positions are restored between sessions automatically.

VS Code Extensions (Open VSX Registry)

Click the 🧩 Extensions icon in the activity bar to open the extension browser. Search or browse the Open VSX Registry (open-vsx.org) and install .vsix extensions with one click.

What Gets Activated on Install

LSP Integration & Ghost-Text

Language Server Protocol (LSP)

Electra integrates with language servers for real-time code intelligence. Use /lsp to check status.

The AI coder agent has four LSP tools it can call: lsp_goto_definition, lsp_find_references, lsp_rename_symbol, and lsp_hover. LSP diagnostics appear in the Diagnostics tab in real-time.

Ghost-Text Inline Completions

As you type, Electra shows a grayed-out AI completion suggestion. Press Tab to accept it, or keep typing to dismiss it. Ghost-text uses a dedicated fast-model chain completely separate from the main coder agent:

nemotron-nano-4b → mis-mistral-small-2603 → qc-qwen-coder-flash
  → ms-qwen2.5-coder-7b → llm7-deepseek-coder-v2-lite

The ghost model auto-advances on timeout or empty response and resets to the fastest model after a successful completion. Select the primary ghost model from the 👻 picker in the status bar (visible in Coder mode).

Keyboard Shortcuts

Model Providers & Prefixes

Electra connects to 11 provider networks with 150+ models. Each provider has a prefix used in the model picker and command line. Use /model to switch models interactively.

Notable Models by Category

Auto-Routing System

When you send a message, Electra's routing system selects the best available model automatically — no manual switching required. The system uses a composite 60% capability / 40% speed score to rank candidates.

How Routing Works

• Capability caps check: Each mode has required capability flags (e.g., Coder requires Co+Re or T+Ag). Models that don't meet the caps are excluded.
• Paid pre-pass (Major/Commander): If you're on Major or Commander tier, the router first tries PAID_PROVIDER_MODELS (ds-/bt-/ol-) before falling back to free models.
• Large context detection: If your prompt + context exceeds 60K characters, only models in _LARGE_CTX_MODELS are eligible.
• Ban list: sf- models and ms- models are never auto-routed. Models that fail repeatedly are temporarily banned and retried on the next request.
• Fallback chain: If the primary model fails mid-stream, Electra silently switches to the next model in the chain and continues — you rarely see an error.

🐝 Agent Swarm

Agent Swarm parallelizes large multi-file coding tasks across multiple AI workers simultaneously. An orchestrator analyzes your request, splits it into sub-tasks, runs worker agents in parallel, then passes all results to a reviewer for final integration. Requires Major ($40) or Commander ($100) tier.

/swarm          # Toggle swarm mode on/off
/swarm on       # Enable swarm for next task
/swarm off      # Disable swarm, return to normal coder

Plugin Engine

Electra has a full plugin system. Plugins are Python files that extend the routing system with custom commands, hooks, and agents. The AI can write plugins for you on demand, and a community GitHub marketplace lets you share and discover plugins.

Plugin Commands

Plugin API

A plugin is a Python file placed in ~/.config/ai_plugins/. It exports a ROUTE_TOKEN, run(prompt, context) function, and optional lifecycle hooks. Plugins can add slash commands, register as routing agents, and notify the GUI panel.

Self-Repair / Auto-Forge

When Electra encounters a repeated error it can't handle, it automatically forges a repair plugin using the Plugin Forge AI agent. These plugins are installed silently and auto-synced to GitHub for the community. The repair ledger (/repair) shows all forged plugins and error history.

Delegate & Parallel Agents

Send tasks to background agents while you continue working. Results are posted to your memory and session when complete.

# Run a single background task
/delegate write unit tests for utils.py

# Run 3 tasks IN PARALLEL (pipe-separated)
/delegate refactor auth.py | update README.md | add type hints to models.py

# Check task status
/tasks
/tasks cancel <id>
/tasks clear

Headless Browser Agent

Electra embeds a headless Chromium browser that the AI can control. Navigate pages, click elements, fill forms, take screenshots, and extract content — all from natural language commands.

/browser install   # Install Playwright + Chromium (~170 MB, one-time)
/browser status    # Check browser availability

# Then just ask naturally:
"Go to github.com and find open issues tagged 'bug'"
"Fill out the contact form at example.com"
"Take a screenshot of the dashboard"
"Extract all product prices from this page"

AT-SPI Screen Context & D-Bus

AT-SPI Daemon (Screen Reader)

On first launch, Electra auto-installs electra_atspi_daemon.py as a systemd user service. It polls the AT-SPI accessibility tree every 2.5 seconds and writes the focused window's text to /tmp/electra_atspi_context.json.

The AI automatically reads this context in Chat, Command, and Coder modes — so it can see your browser tab, terminal output, or PDF document without you having to copy-paste anything. Context is only injected when actually available, to avoid wasting tokens.

D-Bus Daemon (Two-Way Communication)

The D-Bus daemon (electra_dbus.py) exposes Electra on the session bus at org.makululinux.Electra. Any desktop application, script, or keyboard shortcut can send queries to Electra and receive responses.

dbus-send --session --print-reply \
  --dest=org.makululinux.Electra \
  /org/makululinux/Electra \
  org.makululinux.Electra.Query string:"explain this error"

Integrations Overview

Electra integrates with a wide range of external services. All integrations are compiled into the single binary — no separate installs required.

Telegram Bridge

The Telegram bridge lets you control Electra from your phone or any Telegram client. Configure your bot token and chat ID, then start the bridge with /telegram.

# First-time setup — enter your bot token and chat ID
/telegram

# Check status
/telegram status

# Manage as a systemd service (survives reboots)
/telegram service start
/telegram service install    # Registers as user service
/telegram service enable

Home Assistant

Connect Electra to your Home Assistant instance to control smart home devices with natural language via the AI.

/ha                    # Home Assistant overview
/ha status             # Connection status
/ha lights on|off      # Control lights
/ha <natural language> # "turn off all lights in bedroom"
                       # "set living room temperature to 22"

GitHub Integration

Connect with a Personal Access Token to enable full GitHub management from inside Electra.

Auto-Bug-Reporting

When Electra encounters an unhandled error in an agent, it automatically files a GitHub issue on the Electra repository with full context (error type, traceback, system info, model, prompt). A fingerprint prevents duplicate reports. You can view the auto-report ledger at any time.

Finance Bot

The Finance Bot is an autonomous income generation system integrated into Electra. It manages 33 income stream modules — scanning for opportunities, creating content and products, drafting proposals, and queuing actions for your approval. It never moves money without your explicit /hustle approve <id> command.

Finance Center GUI

Type /finance to open the full Finance Center — a dashboard with income streams, wallet balances, earnings history, opportunity scanner, approval queue, and an AI chat assistant trained on your income data.

Terminal Commands

Data Storage

• Config: ~/.config/ai_terminal/finance.conf
• Database: ~/.electra/finance.db (SQLite — earnings, products, pending actions, opportunities, activity log)
• Content: ~/ElectraFinance/

33 Income Streams

Each stream is an autonomous module that creates content, products, or opportunities in its niche. Streams marked ✅ have full API integration and can publish/list without browser automation.

Heartbeat Agent

The Heartbeat Agent runs as a background service, executing persistent tasks on a schedule. Configure tasks via Electra and it runs autonomously — perfect for daily Finance Bot runs, system health checks, content publishing, and anything else that should happen on autopilot.

ISO Agent

The ISO Agent provides tools for working with Linux ISO images — mounting, extracting, analyzing, and creating bootable images. Primarily used for MakuluLinux ISO development and testing.

Full Command Reference

Type /? or /help in the terminal to see the full command list. Commands are grouped by category below.

Session & History

Model & Config

Notifications & Scheduling

Third-Party API Keys

Utility Commands

Changelog — Recent Releases

v2026.06.21-r5 — Coder Elite

• Live Code Map: AI knows exactly which files exist + when last touched
• Structured Error Parsing: FILE:LINE:TYPE extracted from tracebacks
• Intent-aware tool routing: DEBUG/REFACTOR/QUESTION use narrowest subset
• Next-Step Suggestions: 3 clickable actions after task complete (GUI)
• Code map badge in activity log shows tracked file count
• Workspace map reset on workspace change

v2026.06.21-r4 — Extension Quick Wins

• Tabstop navigation: Tab jumps $1→$2→$3, Esc exits
• TM_ variables: ${TM_FILENAME}, ${TM_FILENAME_BASE}, ${TM_DIRECTORY}, ${TM_SELECTED_TEXT}
• ✂ Snippets button in editor status bar (Coder mode)
• Ctrl+Shift+S opens snippet palette from editor
• Theme picker shows EXT THEMES section after extension install

v2026.06.21-r3 — Extension Activation (All 4 Layers)

• Layer 1 - Snippets: installed extension snippets load at startup; Tab expands triggers
• Layer 2 - AI awareness: installed extensions injected into every coder system prompt
• Layer 3 - Theme import: VS Code JSON themes parsed and added to Electra theme picker
• Layer 4 - LSP auto-reg: bundled LSP servers detected and registered with electra_lsp

v2026.06.21-r2 — Open VSX Extension Browser

• New 🧩 Extensions icon in sidebar activity bar
• Browse / search Open VSX Registry (open-vsx.org) in the GUI sidebar
• Install .vsix extensions — themes, grammars, snippets auto-applied
• TextMate grammars registered with GtkSourceView language-specs

v2026.06.21-r1 — Command Mode GUI

• Dynamic 3-pane layout for command mode: execution log pane auto-shows during tasks
• File preview pane shows when files are being edited
• Both collapse when tasks complete — full command-mode parity without the terminal

v2026.06.20 — GUI Theme Isolation & Tier Enforcement

• GUI fully isolated from system GTK theme (Breeze, Mint-Y, Arc, Yaru have zero influence)
• Three-layer isolation: forced Adwaita base + P800 reset provider + CSS_TEMPLATE universal reset
• Model picker tier enforcement in both GUI and terminal
• 🔒 [Major+] shown on ds-/bt-/ol- models for non-Major users; clicking shows upgrade toast
• Major/Commander users see paid providers sorted to the TOP of the picker
• AT-SPI screen context injected into Coder mode (was previously command + chat only)
• New tool notify_user and tile_windows added to Coder mode

v2026.06.19 — Major/Commander Paid-Tier Priority

• Paid-provider pre-pass in auto-routing: ds-/bt-/ol- models tried first for Major/Commander
• Same pre-pass in context-aware coder model selection
• Cap safety: paid pre-pass requires full caps; relaxed to Co/T in pass 2
• 5 coder/command stability bugs fixed (kill path depth leak, checkpoint chunk injection, ban list in fallback queue)

v2026.06.18 — Ghost Text & Inline Edit Polish

• Ghost-text stale suggestion prevention via monotonic sequence counter
• Inline Edit (Ctrl+K) complete rewrite: modal popup, Apply/Cancel buttons, loading state, indent preservation
• File system tools (delete_file, move_file, create_directory, copy_file) all GUI-integrated: tree refresh, tab tracking, activity logging
• Agent Swarm: Orchestrator/Workers/Reviewer API URL fixes, worker upgraded to 8-round agentic loop

Earlier Highlights (June 2026)

• Agent Swarm (Major/Commander) — parallel multi-file editing with orchestrator + reviewer pipeline
• Open VSX extension browser with 4-layer activation system
• LSP integration: pyright, tsserver, rust-analyzer, clangd, gopls with 4 AI tools
• Ghost-text inline completions with dedicated fast-model chain and auto-fallback
• Command Palette (Ctrl+Shift+P), Quick File Open (Ctrl+P)
• @-mention file context in chat, Apply to File on every AI code block
• Git panel, Diagnostics tab, Minimap, image preview tabs, voice input, split editor
• Symbol breadcrumb, workspace session restore, collapsible thinking blocks
• Per-project stable conversation_id (server MemPalace memory across sessions)
• Project knowledge base (.electra_project.md / /pk commands)
• D-Bus daemon: two-way desktop ↔ Electra communication
• AT-SPI daemon: live screen text context for all modes
• Finance Center GUI (/finance), 33 income streams total
• Model routing rebuilt: step-3.5/3.7-flash as primary; Ollama Cloud (ol- prefix) added; SiliconFlow permanently removed from auto-routing
• Daily limits updated: Free 50 / Private 500 / Corporal 1500 / Sergeant 4000 / Major 10000 / Commander ∞
• Auto-report GitHub issue filing on unhandled errors
• SSL/TLS cert repair for Nuitka onefile binaries (auto-finds newest cacert.pem in /tmp/electra)
• Right-click context actions auto-installed on first launch in Nemo/Dolphin/Nautilus/Thunar/Caja/PCManFM

Launching Electra 🚀

Electra is pre-installed on MakuluLinux. You can launch it several ways:

# Standard terminal launch
ai_terminal.bin

# Launch directly into GUI mode
ai_terminal.bin --gui

# Launch and immediately chat
ai_terminal.bin --chat "explain how SSH keys work"

# Launch and immediately enter Coder mode with a task
ai_terminal.bin --coder "add user authentication to my Flask app"

# Launch and immediately write something
ai_terminal.bin --writer "write a blog post about Linux gaming"

# Launch and run a command via natural language
ai_terminal.bin --command "show my disk usage"

# Open a file for analysis (from Nemo right-click action)
ai_terminal.bin /path/to/file.py

# Show help
ai_terminal.bin --help

On first launch, Electra creates its configuration directory at ~/.electra/ and populates it with default configuration files. All data is stored in your home directory — no system-wide writes.

Key Directories

First-Time Setup

When you first open Electra, it is ready to use in Chat mode immediately. To unlock the full power of integrations, set up each service you want to use:

• Google Workspace: /google login
• Home Assistant: /ha setup
• Spotify: /spotify setup
• Discord: /discord setup
• GitHub (personal): /github connect
• Telegram Bot: /telegram setup (in terminal, then start the bridge)
• Finance Bot: /hustle setup — configure income streams, API keys, and payment accounts

Additional Directories

💻 IDE Mode — Terminator Terminal IDE

IDE mode launches Electra inside a custom Terminator layout — a true terminal IDE for users who prefer the keyboard over a GUI. It provides a multi-pane workspace with a file tree, file preview, output log, and AI chat pane, all in one window.

/ide                              # Enter IDE from terminal session
ai_terminal.bin --ide             # Launch directly in IDE mode
ai_terminal.bin --ide --cwd "%P" # Nemo action — opens IDE in selected folder
sudo apt install terminator       # Required dependency

IDE Layout

IDE Features

• Auto font detection — picks the best available monospace font: JetBrains Mono → Fira Code → Hack → Ubuntu Mono → Monospace
• Three Terminator profiles — default (tree/preview/chat), shell (teal cursor), info (dark status bar)
• Only right pane is interactive — tree, preview, and log panes have stty -echo -icanon applied
• Session summary auto-display — when AI finishes a task, the preview pane automatically switches to show .electra_session.md
• Git branch in status bar — read directly from .git/HEAD, no subprocess overhead
• Keybindings — Ctrl+=/-, Tab, Ctrl+W, Ctrl+Z, F11, Ctrl+Shift+C/V

Install recommendations for best IDE experience

sudo apt install terminator ranger bat inotify-tools fonts-jetbrains-mono
pip3 install pygments    # syntax highlighting fallback

🔌 Offline Mode & Local MemPalace

When internet connectivity is lost or all online models fail, Electra automatically switches to a local Ollama model. This fallback works in all modes — Chat, Coder, Writer, and Command — with full thinking display and a local conversation memory system that mirrors the server-side ChromaDB architecture.

Model Fallback Chain

Online models are tried in priority order before falling back to Ollama:

1. nvidia/nemotron-3-nano-30b-a3b    # primary (fast router + chat)
2. stepfun-ai/step-3.5-flash         # backup 1
3. electra                           # backup 2 (in-house)
4. microsoft/phi-4-multimodal-instruct # backup 3
5. microsoft/phi-4-mini-instruct     # backup 4
6. Local Ollama model                # ultimate offline fallback

Each online model is tried twice. If all fail, Ollama activates automatically — no configuration required.

Offline Setup

/offline                   # guided install from within Electra
# or manually:
curl -fsSL https://ollama.com/install.sh | sh
ollama pull su_robin/gemma-4-E4B-it-Q4_K_M   # 5.3 GB

Offline Mode by Mode

• Chat — full conversation with the local model; thinking displayed in cyan
• Coder / Writer — advisory mode; AI provides code/content you apply manually
• Command — full agentic loop; AI issues bash commands in ```bash blocks, Electra executes them, feeds output back, repeats up to 15 turns

Local MemPalace — Offline Conversation Memory

Electra runs an identical hybrid memory system locally for all Ollama calls, mirroring the server-side ChromaDB architecture:

/offline-memory           # show backend, stored turn count, memory path
/clear-offline-memory     # wipe all local memories (requires YES confirmation)
pip3 install chromadb     # enable full semantic memory (SQLite is fallback)

Memory is stored at ~/.electra/chroma_local_db/ (ChromaDB) or ~/.electra/ollama_memory.db (SQLite). Each user gets a stable conversation ID derived from their home directory.

📟 Electra Bar — Desktop Widget

The Electra Bar (electra_bar.py) is a lightweight GTK3 floating widget that lives directly on your desktop — behind all application windows but always accessible. It provides instant access to Electra's full AI intelligence stack without opening a terminal window. Type a prompt, press Enter, and a terminal opens with the result. Or use the voice button to speak your request.

Since the MakuluLinux 2025 update, the Electra Bar has grown significantly. It now includes a microphone for voice input, a full command history with dropdown preview, drag-to-reposition, customisable appearance, and the new Quick Action Center — a full-screen panel of one-click AI shortcuts organised into six categories.

Bar Layout

┌────────────────────────────────────────────────────────────────────┐
│  ⠿  │   AI : Ask me anything…                  │  ⚡  │  🎤  │
│ drag│          text input area                  │  QA  │ mic  │
└────────────────────────────────────────────────────────────────────┘
  (1)                (2)                            (3)    (4)

(1) Drag handle   — click and drag to reposition the bar on screen
(2) Text input    — type any prompt; Enter to submit; Up/Down for history
(3) ⚡ QA button  — opens the Quick Action Center panel
(4) 🎤 Mic button — voice input via faster-whisper (offline, multilingual)

Features

Text Input & History

• Type any prompt and press Enter — a gnome-terminal opens and Electra processes the request
• The input area auto-expands for multi-line text (up to 400 px)
• Press Up / Down arrows to cycle through the last 7 submitted commands
• A dropdown preview panel appears showing recent history entries
• History is persisted across sessions in ~/.config/electra_bar.json

Voice Input (Mic Button 🎤)

• Click the microphone to start recording — the button turns red (⏹) while active
• Uses faster-whisper for offline, accent-robust, multilingual transcription
• Falls back to Vosk if faster-whisper is not installed
• Live transcription appears in the input field as you speak
• Auto-submits 2.5 seconds after the last detected word (configurable)
• Click the button again to cancel recording before submission
• Whisper model size is configurable: tiny | base | small | medium | large-v3 (set in right-click settings)

Appearance Customisation (Right-Click)

Right-click anywhere on the bar to open the Settings popup:

Positioning

• The bar floats at the top-centre of the primary monitor by default
• Click and drag the drag handle (⠿) on the left to reposition anywhere on-screen
• Position is saved automatically and restored on next launch
• Right-click → Reset Defaults re-centres the bar if it gets lost

Autostart Setup

# Run manually
python3 /usr/share/MakuluSetup/tools/electra_bar.py

# Add to ~/.config/autostart/ (Cinnamon autostart)
# Create: ~/.config/autostart/electra-bar.desktop
[Desktop Entry]
Type=Application
Name=Electra Bar
Exec=python3 /usr/share/MakuluSetup/tools/electra_bar.py
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true

Dependencies

# GTK3 + Cairo (usually pre-installed on MakuluLinux)
sudo apt install python3-gi gir1.2-gtk-3.0 python3-cairo ffmpeg

# Voice recognition (faster-whisper recommended)
pip install faster-whisper pyaudio

# Optional: Vosk fallback STT
pip install vosk

⚡ Quick Action Center

The Quick Action Center is a full-screen GTK3 panel that launches from the ⚡ button on the Electra Bar. It provides a beautifully organised grid of one-click AI action tiles, grouped into six categories. Each tile launches a new terminal with Electra pre-loaded with an optimised prompt for that specific task — no typing required.

Some tiles are simple launchers (click and go), while others are input cards with a text field so you can describe your specific need before launching.

Categories

Action Cards Reference

System Category

Software Category

Development Category

Network Category

AI & Chat Category

Settings Category

📧 Google Services Integration

Electra's Google agent (google_agent.py) provides deep integration with the entire Google Workspace ecosystem via OAuth2. You interact with all Google services using plain English — Electra's AI parsing layer extracts intent, looks up contacts, constructs API calls, shows you a preview, and acts on confirmation.

Setup (One-Time)

Follow these steps carefully — each one is required before Electra can access your Google account. This is a one-time setup; after the token is saved you never need to repeat it.

① Create a Google Cloud Project

1. Open the Google Cloud Console and sign in with your Google account.
2. Click the Project Dropdown at the top of the page (next to the Google Cloud logo).
3. In the dialog that appears, click New Project (top-right corner).
4. Enter a Project Name (e.g. ElectraAI). Google auto-generates a Project ID — you can customise it now but it cannot be changed later.
5. Leave Location as "No organization" unless you're in a Google Workspace org.
6. Click Create and wait a few seconds for the project to be provisioned.

② Create OAuth 2.0 Credentials

1. Go to console.cloud.google.com/apis/credentials.
2. Click Create Credentials → OAuth 2.0 Client ID.
3. If prompted to configure the OAuth consent screen first, fill in the required fields (App name, support email) and save — you can leave everything else as defaults for personal use.
4. For Application Type, choose Desktop app.
5. Click Create. Copy the Client ID and Client Secret shown on screen.
6. Click Download JSON and save the file as:
   ~/.config/ai_terminal/google_oauth.json
   (create the directory if it doesn't exist: mkdir -p ~/.config/ai_terminal)

③ Enable Google APIs

Click each link below and press Enable on that API's page. All services must be enabled before the corresponding Electra commands will work.

④ Authenticate in Electra

1. Open Electra and run: /google login
2. Your browser will open Google's OAuth consent screen — sign in and click Allow.
3. Electra captures the token automatically and saves it to ~/.config/ai_terminal/google_token.json.
4. You're done! All Google commands are now active. The token refreshes automatically — you won't need to log in again.

🎵 Spotify Integration

Full Spotify playback control via the Spotify Web API — play, pause, skip, search, browse playlists, manage liked songs, and control volume — all with natural language or slash commands.

Setup

1. Go to developer.spotify.com/dashboard → Create App
2. Set Redirect URI to http://localhost:8888/callback
3. Copy Client ID and Client Secret
4. Run /spotify setup in Electra
5. Config saved to ~/.config/ai_terminal/spotify_config.json

Spotify Commands

💜 Discord Integration

The Discord agent (discord_agent.py) connects Electra to your Discord servers, allowing you to read channels, send messages, check notifications and DMs, and manage server interactions — all via natural language or slash commands.

Setup

1. Go to discord.com/developers → New Application → Bot tab → Add Bot → Copy Token
2. Enable "Message Content Intent" under Privileged Gateway Intents
3. Invite the bot to your server with read/write permissions
4. Run /discord setup in Electra

Discord Commands

🔺 Reddit Reader

The Reddit agent (reddit_agent.py) provides read access to Reddit using the public JSON API — no API key required. Browse subreddits, search posts, follow trending content, and optionally sign in for personalized features.

Reddit Commands

📰 RSS / News Feed Reader

The RSS agent (rss_agent.py) provides curated news from a hand-picked selection of quality tech, Linux, science, developer, and world news feeds — with no API key required. Add your own custom feeds from any URL.

Built-In Feed Categories

RSS Commands

📋 Clipboard Intelligence Agent

The Clipboard Intelligence Agent runs silently in the background from the moment Electra starts. Every time you copy text — code, a URL, an error message, anything — it is silently stored in a rolling 20-item history. On demand, you can surface, explain, or interrogate any clipboard content without leaving the terminal.

Commands

Example Usage

# Copy an error message from your browser, then:
/clip explain

# Ask a specific question about copied code:
/clip explain what does this function do and are there any bugs?

# View history:
/clip

# Turn off tracking when not needed:
/clip watch off

Requirements

Requires xclip, xsel, or wl-paste (Wayland). Install with: sudo apt install xclip

📸 Screenshot Vision Agent

The Screenshot Vision Agent captures your screen and instantly sends it to a multimodal vision model for analysis. Ask what is on screen, get errors explained, understand unfamiliar UI, or query any visual content — all without leaving the terminal.

Commands

Example Usage

/screenshot explain this error
/screenshot what is this application doing?
/screenshot last what is the stack trace saying?
/screenshot is there any sensitive information visible?

Requirements

Install gnome-screenshot (recommended) or scrot: sudo apt install gnome-screenshot

🔍 OCR Agent — Image Text Extraction

The OCR Agent extracts text from any image file using Tesseract — the gold-standard open-source OCR engine. Photographs of documents, screenshots with text, scanned pages, code photos — all become editable, searchable text. Optionally pipe the result directly to AI for explanation or analysis.

Commands

Requirements

Install Tesseract: sudo apt install tesseract-ocr

For additional language support: sudo apt install tesseract-ocr-fra tesseract-ocr-deu etc.

🐳 Docker Management Agent

The Docker Agent brings full container management into your AI terminal. Fast-path commands handle the most common operations instantly; natural-language requests route through the command agent with a live Docker environment snapshot injected as context, so the AI always knows exactly what containers, images, and resources are present before acting.

Commands

Example Usage

/docker
/docker logs my-api-container
/docker start postgres
/docker what container is using the most memory?
/docker build and run my Dockerfile in this directory
/docker pull nginx and start it on port 8080

⚙️ Systemd Service Manager

The Service Manager puts full systemd control into natural language. Check what is failing, start and stop services, tail journal logs, and let AI write and install entire .service files from a plain-English description — no manual unit file editing required.

Commands

AI Service Creation

# AI writes the .service file, installs it to ~/.config/systemd/user/,
# runs daemon-reload, enables, and starts it — all in one command:

/service create a service that runs my Flask app (~/projects/myapp/app.py) on port 5000
/service create run my Node.js API server from ~/api/ using npm start
/service create keep my Python scraper (~/scripts/scraper.py) running, restart on crash

📦 AI Package Manager Agent

The Package Manager Agent adds intelligent, context-aware package management to Electra. It automatically detects the correct package manager for your project (apt, pip3, npm, cargo, snap) and handles installation, removal, search, and updates — all from natural language.

Commands

Example Usage

# In a Python project directory:
/pkg install the dependencies from requirements.txt
/pkg install flask sqlalchemy python-dotenv

# In a Node.js directory (reads package.json automatically):
/pkg install the missing dependencies for this project

# System tools:
/pkg install ffmpeg tesseract-ocr imagemagick
/pkg search json parser for python
/pkg update

Manager Selection Logic

The agent detects your project context and follows this priority:

1. apt — system tools, C libraries, binary dependencies
2. pip3 --user — Python packages (when requirements.txt or pyproject.toml detected)
3. npm — Node.js packages (when package.json detected)
4. cargo — Rust crates (when Cargo.toml detected)
5. snap — GUI applications as fallback

⏰ Persistent Scheduler

Unlike /remind (which only works while Electra is running), the Persistent Scheduler writes real cron jobs that fire desktop notifications even when Electra is closed — across reboots. All jobs are managed through a simple JSON registry at ~/.electra/schedule.json.

Commands

Time Specification Examples

# Daily reminders
/schedule add every day 9am         Morning standup reminder
/schedule add daily 18:00           End of day — commit your work

# Weekly
/schedule add every monday 8:30am   Weekly planning session
/schedule add every friday 5pm      Weekly review

# Weekdays only
/schedule add every weekday 9am     Daily check-in

# Interval-based
/schedule add every 2h              Stretch break!
/schedule add every 30m             Drink some water

# View and manage
/schedule list
/schedule rm 2

How It Works

Each /schedule add command parses the time specification, converts it to a standard 5-field cron expression, and installs it into your user crontab. The cron job fires a notify-send desktop notification using the system's DBUS session. Jobs survive reboots, app restarts, and Electra upgrades.

📱 QR Code Generator

Generate QR codes for any text, URL, WiFi credentials, contact cards, email addresses, or SMS messages — right from the terminal. The code is saved as a PNG to ~/Pictures/, opened instantly in your image viewer, and also rendered as block characters directly in the terminal so you can scan it immediately without switching windows.

Commands

Example Usage

# Share a URL instantly
/qr https://makululinux.com

# Let guests join your WiFi — scan and connect
/qr wifi HomeNetwork SuperSecret123

# Share contact details
/qr contact Jane Doe +27821234567

# Any text at all
/qr Meet me at the coffee shop at 3pm

Output

Each QR code is saved to ~/Pictures/electra_qr_YYYYMMDD_HHMMSS.png and opened automatically with xdg-open. For codes up to 33×33 modules, a block-character preview is also printed directly in the terminal — no window switch needed to scan it.

Requirements

The qrcode[pil] Python package. Electra installs it automatically on first use: pip3 install qrcode[pil] --user

🎙️ Voice I/O — Offline Speech-to-Text & Text-to-Speech

Electra AI Center ships with a complete, fully offline voice input and output system. You can speak to Electra using a microphone and have it speak back to you using a neural TTS voice — no cloud, no API keys, no privacy concerns.

The system uses faster-whisper (the same Whisper engine used in Electra Bar) for speech recognition, and edge-tts for high-quality Text-to-Speech output — the same voices used by Microsoft Edge's Read Aloud feature.

Voice Commands

/voice          # Speak one message — Electra transcribes it and responds in text
/talk           # Continuous voice dialogue loop — speak > respond > speak again
                # Say "stop" or "exit" to end the conversation
/speak          # Toggle Text-to-Speech on/off. When on, Electra reads every response aloud
/speak en-US-AriaNeural      # Change TTS voice to a specific edge-tts voice
/speak en-GB-SoniaNeural     # British English female voice
/speak en-AU-NatashaNeural   # Australian English female voice

How the Voice Stack Works

Installation

# Install faster-whisper and pyaudio (STT)
pip3 install faster-whisper pyaudio --break-system-packages

# Install edge-tts (TTS)
pip3 install edge-tts --break-system-packages

# Install mpg123 audio player (TTS playback)
sudo apt install mpg123

# Optional: ALSA dev headers if pyaudio fails to compile
sudo apt install portaudio19-dev python3-pyaudio

🎨 Media Retrieval — The Fetch vs. Generate Strategy

Electra AI Center uses a clever and often overlooked philosophy when it comes to media: fetch first, generate only if you must. This strategy drastically reduces latency, computational cost, and produces higher-quality results in most cases.

The reasoning is straightforward: almost every image, video, or piece of music you could ever want has already been created and is sitting on the internet, free to use under appropriate licences. It is often far faster and better to retrieve a high-quality existing asset from a reputable source than to generate a new one from scratch using a generative model — which requires significant compute, introduces quality variance, and takes time.

How It Works

Why This Approach Is Superior

                    FETCH (from web)          GENERATE (AI model)
─────────────────────────────────────────────────────────────────
Speed               <2 seconds                5-30+ seconds
Quality             Professional/consistent   Variable (prompt-dependent)
Cost                Free (API calls)          Compute resources
Licensing           Clear (CC, royalty-free)  Depends on model/output
Availability        Millions of assets        Unlimited but unpredictable
Best for            Real photos, real music,  Unique art, specific prompts
                    professional imagery      that don't exist yet

🐳 Docker Agent — Natural Language Container Management

The Docker Agent gives you a complete natural language interface to Docker. Describe what you want to do with containers, images, volumes, or Docker Compose in plain English — Electra translates it to the correct Docker commands, explains what it's going to do, and executes with your confirmation.

What the Docker Agent Can Do

✈️ Travel Planner — AI-Powered Trip Planning

The Travel Planner activates automatically whenever you mention a trip, destination, flights, hotels, or an itinerary. It uses real-time web search combined with AI to build detailed travel plans with practical recommendations, cost estimates, and day-by-day itineraries.

What It Covers

🔧 Specialist System Agents

Electra includes three dedicated system management agents that handle the most complex and dangerous system operations: software installation, GPU driver management, and hardware fault diagnosis. Each agent operates with extra safety layers and step-by-step explanations.

📦 App Install Agent (APP_AGENT)

The App Install Agent handles all software package management — installation, removal, and repair — across all three major Linux package systems: apt (Debian/Ubuntu), snap, and flatpak. It also handles .deb files and can repair broken package states.

🎮 NVIDIA GPU Agent (NVIDIA_AGENT)

The NVIDIA Agent is a specialist for the notoriously complex task of managing NVIDIA GPU drivers on Linux. It handles driver installation from scratch, updates, CUDA installation, and removal of competing drivers (like nouveau), with full awareness of the Linux GPU ecosystem.

🔍 System Troubleshoot Agent (TROUBLESHOOT)

The Troubleshoot Agent activates when you report something is broken, not working, making noise, running slow, crashing, or behaving unexpectedly — and it's not an app install or NVIDIA driver issue. It follows a systematic diagnosis approach: gather information, identify the cause, propose the fix, and verify resolution.

🔧 Self-Repair System

Electra includes an autonomous self-repair system that detects agent failures, classifies the error type, attempts environment-level fixes (missing packages, permissions), forges a repair plugin that patches the gap, and files a GitHub issue — all silently in the background without interrupting the user.

Error Classification

Error Deduplication

Each error generates a fingerprint (hash of error type + agent name + message). If the same error has already been filed as a GitHub issue, a recurrence comment is added instead of creating a duplicate. A local ledger (~/.electra/repair_ledger.json) tracks all encountered errors and their GitHub issue URLs.

Viewing the Repair Ledger

/repairs       # Show all errors encountered this session with status
/repairs clear # Clear the repair ledger

🌍 Language Settings

Electra supports responding in a wide variety of languages. Once a language is set, all AI prose — explanations, chat replies, writer output, and novel generation — switches to that language. Technical tokens (command names, code, file paths, error labels) always remain in English regardless of the active language, ensuring your tooling stays consistent.

Language preference is saved to ~/.electra/config.json and automatically applied at every startup. On first launch, Electra attempts to detect your country from your IP address and suggests an appropriate language.

Setting Your Language

Supported Languages

The auto-detect map covers the most common world languages. You can also type any language name directly — Electra will set it and instruct the model accordingly. Most frontier models handle the following languages well:

What Stays in English

Even with a non-English language active, the following always remain in English to preserve usability:

• Slash command names and syntax
• Code, scripts, and terminal output
• File paths and directory names
• Error messages and technical labels
• Git commit messages and code comments

Examples

/language French

/language detect

/language Swahili

💡 Tips, Tricks & Best Practices

🚀 Getting the Best Results

/profile language=Python
/profile frameworks=FastAPI, SQLAlchemy, pytest
/profile style=concise, no explanatory comments in code
/profile conventions=always use type hints, snake_case everywhere
/profile paths=~/projects/myapp is my main project

/hotkeys set s=/status
/hotkeys set t=/think
/hotkeys set n=/newchat
/hotkeys set d=/diff all

⚠️ Common Pitfalls

🔧 Personalisation Checklist

• ✅ Set your /profile with language, frameworks, and coding style
• ✅ Configure /hotkeys for your most-used commands
• ✅ Set up Google OAuth for email, calendar, and Drive access
• ✅ Connect Home Assistant if you have smart home devices
• ✅ Set up Spotify for music control from the terminal or Electra Bar
• ✅ Configure the Telegram bridge for remote access from your phone
• ✅ Install the Heartbeat Agent with /agent service install for autonomous background tasks
• ✅ Add your first autonomous task from Telegram: /task add Morning News | Summarise today's headlines | daily 08:00
• ✅ Add your favourite RSS feeds with /rss add <url>
• ✅ Connect your GitHub account with /github connect
• ✅ Browse community plugins with /plugin community
• ✅ Try /guide for the interactive built-in tutorial

🔌 Use Electra AI Anywhere — Public API Access

Your Electra AI account doesn't just power the desktop terminal — it also gives you a personal public API key you can use in any OpenAI-compatible third-party tool or editor. The same daily request limit you have inside Electra is shared across your desktop sessions and your API key usage, so there's no double-counting and no separate subscription needed.

This means you can use your Electra AI access in tools like VS Code, Cursor, Windsurf, Zed, Neovim, Open WebUI, AnythingLLM, or any other application that supports a custom OpenAI-compatible endpoint — all backed by the same pool of 80+ models available in Electra itself.

Endpoint Details

Quick Setup Examples

from openai import OpenAI

client = OpenAI(
    base_url="https://makululinux.us:2006/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="stepfun-ai/step-3.5-flash",
    messages=[{"role": "user", "content": "Hello from VS Code!"}]
)
print(response.choices[0].message.content)

{
  "openai.apiKey": "YOUR_API_KEY",
  "openai.baseURL": "https://makululinux.us:2006/v1"
}