220 lines
9.1 KiB
Markdown
220 lines
9.1 KiB
Markdown
# ollie-kde
|
|
|
|
KDE-native integration for [ollie](../README.md) — thin KDE clients (GUI application, KRunner plugin, Kate plugin, Dolphin menus) that connect to the Ollie 9P filesystem via `olliesrv`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Plasma Desktop │
|
|
│ GUI App │ KRunner │ Kate Plugin │ Dolphin │
|
|
└──────────┬──────────────┬──────────────────┬─────────────┘
|
|
│ │ │
|
|
│ ┌───────────┴──────────────┐ │
|
|
│ │ 9P client tools │ │
|
|
│ │ libollie9p │ ollie-9p │ │
|
|
│ │ plan9port's 9p │ │
|
|
│ └───────────┬──────────────┘ │
|
|
│ │ │
|
|
└──────────────┼──────────────────┘
|
|
│ 9P protocol (Unix socket)
|
|
│
|
|
┌──────────┴──────────┐
|
|
│ olliesrv (../9p) │
|
|
│ 9P server │
|
|
│ Go │ lib9p │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
Every KDE component talks to `olliesrv` via 9P protocol using one of the available 9P clients (`libollie9p.so` directly, `ollie-9p` subprocess, or plan9port's `9p`).
|
|
|
|
## 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 context actions and ghost text completion
|
|
- **Dolphin service menus** — Right-click actions for files and directories
|
|
|
|
**Note**: No system tray component exists.
|
|
|
|
## 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
|
|
- ECM (Extra CMake Modules)
|
|
- libollie9p.so (from `../lib9p/`)
|
|
|
|
KF6/Qt6 is the default. To build against KF5/Qt5:
|
|
```sh
|
|
just kde-kf5
|
|
```
|
|
|
|
## Build
|
|
|
|
```sh
|
|
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
|
|
|
|
## Install
|
|
|
|
```sh
|
|
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:
|
|
```sh
|
|
ollie-gui
|
|
```
|
|
|
|
Features:
|
|
- Session list with state indicators (idle, thinking, tool call)
|
|
- Collapsible sidebar (Ctrl+B to toggle)
|
|
- Live chat view with auto-scroll
|
|
- Inline prompt input
|
|
- Real-time updates via 9P polling
|
|
- Theme support (light/dark/system)
|
|
- Font customization
|
|
|
|
### 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. The plugin provides:
|
|
|
|
**Context menu actions** (right-click in editor):
|
|
- **Ask about file** — describe and explain the current file
|
|
- **Explain this** — explain selected code (or current line)
|
|
- **Fix this** — ask agent to fix selected code
|
|
- **Refactor this** — ask agent to refactor selected code
|
|
- **Add tests for this** — generate unit tests for selection
|
|
- **Document this** — add documentation comments to selection
|
|
- **Send verbatim** — send selected text wrapped in a code fence (language auto-detected)
|
|
- **Review Diff** — review a diff for issues (visible on Diff-highlighted documents)
|
|
|
|
**Ghost text completion:**
|
|
- Inline AI code completions appear as faded text at end-of-line
|
|
- Triggered automatically after 500ms of cursor idle (at end-of-line only)
|
|
- Multi-line continuations shown when near EOF
|
|
|
|
**Keyboard shortcuts:**
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| Tab | Accept ghost suggestion |
|
|
| Meta+O, N | Next suggestion |
|
|
| Meta+O, P | Previous suggestion |
|
|
| Meta+O, C | Toggle completion on/off |
|
|
| Meta+O, D | Dismiss suggestion |
|
|
| Meta+O, Tab | Request completion manually |
|
|
|
|
**Agent management:**
|
|
- Auto-creates a "kate" session with one agent per project directory
|
|
- Auto-selects agent matching the current Kate project
|
|
- Connection health monitoring with auto-reconnect (5s heartbeat)
|
|
- Status bar shows state:
|
|
- Red `✗ disconnected` — server unreachable
|
|
- Gray `○ no agent` — connected, no agent
|
|
- Green `● kate/ID` — connected with active agent
|
|
|
|
**Configuration** (via environment variables):
|
|
- `OLLIE_COMPLETE_BACKEND` — completion backend override
|
|
- `OLLIE_COMPLETE_MODEL` — completion model override
|
|
|
|
**Git++ integration:**
|
|
- "Ollie: Review Diff" action registered in Git++ plugin's diff context menu
|
|
|
|
**Tip:** Tile the `ollie-gui` window alongside Kate to see the full chat stream from context actions.
|
|
|
|
## File Layout
|
|
|
|
```
|
|
ollie-kde/
|
|
├── justfile # Build orchestration
|
|
├── CMakeLists.txt # Main CMake configuration
|
|
├── 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 (context actions, agent mgmt)
|
|
│ └── ollie_ghost.h/cpp # Ghost text completion provider
|
|
├── 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)
|
|
```
|
|
|
|
## Development Notes
|
|
|
|
- **All components use `libollie9p.so` for 9P transport** (direct C library, no subprocess)
|
|
- The Kate plugin is lightweight: context actions + ghost text, no chat panel (use ollie-gui for chat)
|
|
- 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)
|
|
|
|
**Ghost text not appearing:**
|
|
- Ensure `olliesrv` is running and the 9P socket is accessible
|
|
- Ghost text only shows when cursor is at end-of-line
|
|
- Check Meta+O, C hasn't toggled completion off
|
|
|
|
**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/`
|