ollie-kde/README.md

ollie-kde

KDE-native integration for ollie — thin KDE clients (GUI application, KRunner plugin, Kate plugin, Dolphin menus, Plasmoid) that connect directly to the Ollie 9P filesystem.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     Plasma Desktop                            │
│  GUI App │ KRunner │ Kate Plugin │ Dolphin │ Plasmoid        │
└──────────────────────────┬───────────────────────────────────┘
                           │ 9P filesystem (ollie-9p transport)
                           │
          ┌────────────────┴────────────────┐
          │                                 │
┌─────────┴──────────┐          ┌───────────┴──────────────────┐
│   olliesrv (../9p) │          │  ollie-9p (../cmd/ollie-9p)   │
│   9P server        │          │  9P client + transport        │
│   Go │ lib9p       │          │  Go │ lib9p                   │
└────────────────────┘          └──────────────────────────────┘

All KDE components use the 9P filesystem directly via ollie-9p subprocess calls. No D-Bus dependency — the architecture is fully 9P-based.

Components

• ollie-gui — Main Qt/QML GUI application with session management and chat interface
• krunner_ollie.so — KRunner plugin for quick prompts and session management
• ollie_kate.so — Kate plugin with integrated chat panel and editor integration
• Plasmoid — Desktop widget for session monitoring and quick access
• Dolphin service menus — Right-click actions for files and directories

Note: No system tray component exists (old documentation was incorrect).

Dependencies

• Qt 6 (Core, Widgets, Quick, QuickControls2) or Qt 5 (Core, Widgets, Quick, Qml, QuickControls2)
• KDE Frameworks 6 (Runner, CoreAddons, Config, TextEditor, SyntaxHighlighting) or KF5 equivalents
• Plasma 6 or Plasma 5 (for Plasmoid)
• ECM (Extra CMake Modules)
• libollie9p.so (from ../lib9p/)

KF6/Qt6 is the default. To build against KF5/Qt5:

just kde-kf5

Build

just kde          # builds all components (KF6)
just kde-kf5      # builds all components (KF5)

Outputs:

• build-cmake/ollie-gui — main GUI application
• build-cmake/lib/kf6/krunner/krunner_ollie.so — KRunner plugin
• build-cmake/lib/kf6/ktexteditor/ollie_kate.so — Kate plugin
• build-cmake/lib/libollie-plasmoid-plugin.so — Plasmoid QML plugin
• build-cmake/org/ollie/private/ollie-plasmoid-pluginplugin.so — Plasmoid plugin loader

Install

just install-kde      # installs all KDE components (KF6)
just install-kde-kf5  # installs all KDE components (KF5)

The installation:

• Installs binaries to ~/.local/bin/
• Installs plugins to ~/.local/lib64/qt6/plugins/ (KF6) or ~/.local/lib/qt5/plugins/ (KF5)
• Installs Dolphin service menus to ~/.local/share/kio/servicemenus/
• Installs desktop entry to ~/.local/share/applications/
• Installs icon to ~/.local/share/icons/hicolor/scalable/apps/
• Sets up environment script in ~/.config/plasma-workspace/env/

Note: Restart Plasma (plasmashell --replace or log out/in) to pick up new plugins.

Usage

GUI Application (ollie-gui)

Launch from application menu or terminal:

ollie-gui

Features:

• Session list with state indicators (idle, thinking, tool call)
• Live chat view with auto-scroll
• Inline prompt input
• Real-time updates via 9P polling
• Theme support (light/dark/system)

KRunner

• ollie <prompt> — one-shot generation via Generate (no session created); shows result in a popup
• ollie list — show active sessions
• ollie kill <id> — terminate a session

Dolphin

Right-click any file or directory:

• Ask Ollie about this — one-shot prompt with file context, shows result in kdialog
• Start Ollie session here — creates a persistent session in that directory

Kate

Enable the "Ollie" plugin in Settings → Configure Kate → Plugins. Panel appears on the right with:

• Session indicator + CWD label
• New — create session in project/file directory
• Ask File — send current file path for description
• Explain — send selected text for explanation
• Prompt input for free-form messages
• Live-streaming chat view
• Editor integration (inline annotations, code block application, ghost text completion)

Plasmoid

Add the "Ollie" widget to your panel or desktop:

• Session list with state indicators
• Live chat view with auto-scroll
• Inline prompt input
• Real-time updates via 9P polling

File Layout

ollie-kde/
├── justfile                        # Build orchestration
├── CMakeLists.txt                  # Main CMake configuration
├── CMakeLists-kf5.txt              # KF5-specific overrides
├── gui/
│   ├── main.cpp                    # GUI application entry
│   ├── main.qml                    # QML interface
│   ├── ollie9pclient.h/cpp         # 9P client for GUI
│   ├── lib9pclient.h/cpp           # Shared 9P client library
│   ├── chatblockmodel.h/cpp        # Chat data model
│   ├── thememanager.h/cpp          # Theme management
│   ├── streamfsm.h/cpp             # Streaming state machine
│   ├── ninepconnection.h/cpp       # 9P connection management
│   └── org.ollie.gui.desktop       # Desktop entry
├── krunner/
│   ├── metadata.json               # Plugin metadata
│   └── ollie_runner.h/cpp          # KRunner plugin (9P-based)
├── kate/
│   ├── metadata.json               # Plugin metadata
│   ├── ollie_kate.h/cpp            # Kate plugin (9P-based)
│   ├── ollie_ghost.h/cpp           # Ghost text provider (9P-based)
│   ├── chat_renderer.h/cpp         # Chat rendering engine
│   ├── ktexteditor_utils.h         # Editor utilities
│   └── diffparams.h                # Diff viewer parameters
├── plasmoid/
│   ├── plugin/
│   │   └── olliedbusclient.h/cpp   # QML singleton (9P client - misnamed)
│   └── contents/ui/main.qml        # Plasmoid QML interface
├── dolphin/
│   ├── ollie-actions.desktop       # Service menu entries (KF6)
│   ├── ollie-actions-kf5.desktop   # Service menu entries (KF5)
│   ├── ollie-ask                   # One-shot helper script (9P-based)
│   └── ollie-session-here          # Session creation helper (9P-based)
├── 99-ollie.sh                     # Environment script (KF6)
├── 99-ollie-kf5.sh                 # Environment script (KF5)
└── test-peers.sh                   # Peer connection tests

Development Notes

• All components use ollie-9p for 9P transport — no D-Bus dependencies
• The Kate plugin includes sophisticated editor integration with ghost text, inline annotations, and diff viewing
• The GUI application uses Qt Quick for a modern, responsive interface
• Build system supports both KF6/Qt6 and KF5/Qt5 via CMake option OLLIE_KF5
• Installation is user-local (~/.local/) by default, no system-wide installation needed

Troubleshooting

Plugins not appearing after installation:

• Run kbuildsycoca6 (KF6) or kbuildsycoca5 (KF5) to rebuild system cache
• Restart Plasma: plasmashell --replace or log out/in

"ollie-9p not found" errors:

• Ensure ollie-9p is in your PATH or build/install the main Ollie project first

Kate plugin crashes:

• Check that libollie9p.so is installed in ~/.local/lib/
• Verify Kate is using the same Qt version as the plugin (Qt5 vs Qt6)

Dolphin actions not working:

• Ensure ollie-ask and ollie-session-here are installed in ~/.local/bin/
• Check that the service menu desktop files are in ~/.local/share/kio/servicemenus/