vikingowl
96e2482782
Some checks failed
ci/someci/tag/woodpecker/5 Pipeline is pending
ci/someci/tag/woodpecker/6 Pipeline is pending
ci/someci/tag/woodpecker/7 Pipeline is pending
ci/someci/tag/woodpecker/1 Pipeline failed
ci/someci/tag/woodpecker/2 Pipeline failed
ci/someci/tag/woodpecker/3 Pipeline failed
ci/someci/tag/woodpecker/4 Pipeline failed
- Introduce multiple built-in themes (`default_dark`, `default_light`, `gruvbox`, `dracula`, `solarized`, `midnight-ocean`, `rose-pine`, `monokai`, `material-dark`, `material-light`). - Implement theming system with customizable color schemes for all UI components in the TUI. - Include documentation for themes in `themes/README.md`. - Add fallback mechanisms for default themes in case of parsing errors. - Support custom themes with overrides via configuration.
386 lines
13 KiB
Markdown
386 lines
13 KiB
Markdown
# OWLEN
|
|
|
|
> Terminal-native assistant for running local language models with a comfortable TUI.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Alpha Status
|
|
|
|
- This project is currently in **alpha** (v0.1.9) and under active development.
|
|
- Core features are functional but expect occasional bugs and missing polish.
|
|
- Breaking changes may occur between releases as we refine the API.
|
|
- Feedback, bug reports, and contributions are very welcome!
|
|
|
|
## What Is OWLEN?
|
|
|
|
OWLEN is a Rust-powered, terminal-first interface for interacting with local large
|
|
language models. It provides a responsive chat workflow that runs against
|
|
[Ollama](https://ollama.com/) with a focus on developer productivity, vim-style navigation,
|
|
and seamless session management—all without leaving your terminal.
|
|
|
|
## Screenshots
|
|
|
|
### Initial Layout
|
|
|
|
|
|
The OWLEN interface features a clean, multi-panel layout with vim-inspired navigation. See more screenshots in the [`images/`](images/) directory including:
|
|
- Full chat conversations (`chat_view.png`)
|
|
- Help menu (`help.png`)
|
|
- Model selection (`model_select.png`)
|
|
- Visual selection mode (`select_mode.png`)
|
|
|
|
## Features
|
|
|
|
### Chat Client (`owlen`)
|
|
- **Vim-style Navigation** - Normal, editing, visual, and command modes
|
|
- **Streaming Responses** - Real-time token streaming from Ollama
|
|
- **Multi-Panel Interface** - Separate panels for chat, thinking content, and input
|
|
- **Advanced Text Editing** - Multi-line input with `tui-textarea`, history navigation
|
|
- **Visual Selection & Clipboard** - Yank/paste text across panels
|
|
- **Flexible Scrolling** - Half-page, full-page, and cursor-based navigation
|
|
- **Model Management** - Interactive model and provider selection (press `m`)
|
|
- **Command Autocompletion** - Intelligent Tab completion and suggestions in command mode
|
|
- **Session Persistence** - Save and load conversations to/from disk
|
|
- **AI-Generated Descriptions** - Automatic short summaries for saved sessions
|
|
- **Session Management** - Start new conversations, clear history, browse saved sessions
|
|
- **Thinking Mode Support** - Dedicated panel for extended reasoning content
|
|
- **Bracketed Paste** - Safe paste handling for multi-line content
|
|
- **Theming System** - 10 built-in themes plus custom theme support
|
|
|
|
### Code Client (`owlen-code`) [Experimental]
|
|
- All chat client features
|
|
- Optimized system prompt for programming assistance
|
|
- Foundation for future code-specific features
|
|
|
|
### Core Infrastructure
|
|
- **Modular Architecture** - Separated core logic, TUI components, and providers
|
|
- **Provider System** - Extensible provider trait (currently: Ollama)
|
|
- **Session Controller** - Unified conversation and state management
|
|
- **Configuration Management** - TOML-based config with sensible defaults
|
|
- **Message Formatting** - Markdown rendering, thinking content extraction
|
|
- **Async Runtime** - Built on Tokio for efficient streaming
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Rust 1.75+ and Cargo (`rustup` recommended)
|
|
- A running Ollama instance with at least one model pulled
|
|
(defaults to `http://localhost:11434`)
|
|
- A terminal that supports 256 colors
|
|
|
|
### Installation from Source on Linux and macOS
|
|
|
|
```bash
|
|
git clone https://somegit.dev/Owlibou/owlen.git
|
|
cd owlen
|
|
cargo install --path crates/owlen-cli
|
|
```
|
|
|
|
**Note**: Make sure `~/.cargo/bin` is in your PATH to run the installed binary:
|
|
```bash
|
|
export PATH="$HOME/.cargo/bin:$PATH"
|
|
```
|
|
|
|
### Clone and Build
|
|
|
|
```bash
|
|
git clone https://somegit.dev/Owlibou/owlen.git
|
|
cd owlen
|
|
cargo build --release
|
|
```
|
|
|
|
### Run the Chat Client
|
|
|
|
Make sure Ollama is running, then launch:
|
|
|
|
```bash
|
|
./target/release/owlen
|
|
# or during development:
|
|
cargo run --bin owlen
|
|
```
|
|
|
|
### (Optional) Try the Code Client
|
|
|
|
The coding-focused TUI is experimental:
|
|
|
|
```bash
|
|
cargo build --release --bin owlen-code --features code-client
|
|
./target/release/owlen-code
|
|
```
|
|
|
|
## Using the TUI
|
|
|
|
### Mode System (Vim-inspired)
|
|
|
|
**Normal Mode** (default):
|
|
- `i` / `Enter` - Enter editing mode
|
|
- `a` - Append (move right and enter editing mode)
|
|
- `A` - Append at end of line
|
|
- `I` - Insert at start of line
|
|
- `o` - Insert new line below
|
|
- `O` - Insert new line above
|
|
- `v` - Enter visual mode (text selection)
|
|
- `:` - Enter command mode
|
|
- `h/j/k/l` - Navigate left/down/up/right
|
|
- `w/b/e` - Word navigation
|
|
- `0/$` - Jump to line start/end
|
|
- `gg` - Jump to top
|
|
- `G` - Jump to bottom
|
|
- `Ctrl-d/u` - Half-page scroll
|
|
- `Ctrl-f/b` - Full-page scroll
|
|
- `Tab` - Cycle focus between panels
|
|
- `p` - Paste from clipboard
|
|
- `dd` - Clear input buffer
|
|
- `q` - Quit
|
|
|
|
**Editing Mode**:
|
|
- `Esc` - Return to normal mode
|
|
- `Enter` - Send message and return to normal mode
|
|
- `Ctrl-J` / `Shift-Enter` - Insert newline
|
|
- `Ctrl-↑/↓` - Navigate input history
|
|
- `Ctrl-A` / `Ctrl-E` - Jump to start/end of line
|
|
- `Ctrl-W` / `Ctrl-B` - Word movement
|
|
- `Ctrl-R` - Redo
|
|
- Paste events handled automatically
|
|
|
|
**Visual Mode**:
|
|
- `j/k/h/l` - Extend selection
|
|
- `w/b/e` - Word-based selection
|
|
- `y` - Yank (copy) selection
|
|
- `d` / `Delete` - Cut selection (Input panel only)
|
|
- `Esc` / `v` - Cancel selection
|
|
|
|
**Command Mode**:
|
|
- `Tab` - Autocomplete selected command suggestion
|
|
- `↑` / `↓` or `Ctrl-k` / `Ctrl-j` - Navigate command suggestions
|
|
- `:q` / `:quit` - Quit application
|
|
- `:c` / `:clear` - Clear conversation
|
|
- `:m` / `:model` - Open model selector
|
|
- `:n` / `:new` - Start new conversation
|
|
- `:h` / `:help` - Show help
|
|
- `:save [name]` / `:w [name]` - Save current conversation
|
|
- `:load` / `:open` - Browse and load saved sessions
|
|
- `:sessions` / `:ls` - List saved sessions
|
|
- `:theme <name>` - Switch theme (saved to config)
|
|
- `:themes` - Browse themes in interactive modal
|
|
- `:reload` - Reload configuration and themes
|
|
- *Commands show real-time suggestions as you type*
|
|
|
|
**Theme Browser** (accessed via `:themes`):
|
|
- `j` / `k` / `↑` / `↓` - Navigate themes
|
|
- `Enter` - Apply selected theme
|
|
- `g` / `G` - Jump to top/bottom
|
|
- `Esc` / `q` - Close browser
|
|
|
|
**Session Browser** (accessed via `:load` or `:sessions`):
|
|
- `j` / `k` / `↑` / `↓` - Navigate sessions
|
|
- `Enter` - Load selected session
|
|
- `d` - Delete selected session
|
|
- `Esc` - Close browser
|
|
|
|
### Panel Management
|
|
- Three panels: Chat, Thinking, and Input
|
|
- `Tab` / `Shift-Tab` - Cycle focus forward/backward
|
|
- Focused panel receives scroll and navigation commands
|
|
- Thinking panel appears when extended reasoning is available
|
|
|
|
## Configuration
|
|
|
|
OWLEN stores configuration in `~/.config/owlen/config.toml`. The file is created
|
|
on first run and can be edited to customize behavior:
|
|
|
|
```toml
|
|
[general]
|
|
default_model = "llama3.2:latest"
|
|
default_provider = "ollama"
|
|
enable_streaming = true
|
|
project_context_file = "OWLEN.md"
|
|
|
|
[providers.ollama]
|
|
provider_type = "ollama"
|
|
base_url = "http://localhost:11434"
|
|
timeout = 300
|
|
```
|
|
|
|
### Storage Settings
|
|
|
|
Sessions are saved to platform-specific directories by default:
|
|
- **Linux**: `~/.local/share/owlen/sessions`
|
|
- **Windows**: `%APPDATA%\owlen\sessions`
|
|
- **macOS**: `~/Library/Application Support/owlen/sessions`
|
|
|
|
You can customize this in your config:
|
|
|
|
```toml
|
|
[storage]
|
|
# conversation_dir = "~/custom/path" # Optional: override default location
|
|
max_saved_sessions = 25
|
|
generate_descriptions = true # AI-generated summaries for saved sessions
|
|
```
|
|
|
|
Configuration is automatically saved when you change models or providers.
|
|
|
|
### Theming
|
|
|
|
OWLEN includes 10 built-in themes that are embedded in the binary. You can also create custom themes.
|
|
|
|
**Built-in themes:**
|
|
- `default_dark` (default) - High-contrast dark theme
|
|
- `default_light` - Clean light theme
|
|
- `gruvbox` - Retro warm color scheme
|
|
- `dracula` - Vibrant purple and cyan
|
|
- `solarized` - Precision colors for readability
|
|
- `midnight-ocean` - Deep blue oceanic theme
|
|
- `rose-pine` - Soho vibes with muted pastels
|
|
- `monokai` - Classic code editor theme
|
|
- `material-dark` - Google's Material Design dark variant
|
|
- `material-light` - Google's Material Design light variant
|
|
|
|
**Commands:**
|
|
- `:theme <name>` - Switch theme instantly (automatically saved to config)
|
|
- `:themes` - Browse and select themes in an interactive modal
|
|
- `:reload` - Reload configuration and themes
|
|
|
|
**Setting default theme:**
|
|
```toml
|
|
[ui]
|
|
theme = "gruvbox" # or any built-in/custom theme name
|
|
```
|
|
|
|
**Creating custom themes:**
|
|
|
|
Create a `.toml` file in `~/.config/owlen/themes/`:
|
|
|
|
```toml
|
|
# ~/.config/owlen/themes/my-theme.toml
|
|
name = "my-theme"
|
|
text = "#ffffff"
|
|
background = "#000000"
|
|
focused_panel_border = "#ff00ff"
|
|
unfocused_panel_border = "#800080"
|
|
user_message_role = "#00ffff"
|
|
assistant_message_role = "#ffff00"
|
|
# ... see themes/README.md for full schema
|
|
```
|
|
|
|
**Colors** can be hex RGB (`#rrggbb`) or named colors (`red`, `blue`, `lightgreen`, etc.). See `themes/README.md` for the complete list of supported color names.
|
|
|
|
For reference theme files and detailed documentation, see the `themes/` directory in the repository or `/usr/share/owlen/themes/` after installation.
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
owlen/
|
|
├── crates/
|
|
│ ├── owlen-core/ # Core types, session management, theming, shared UI components
|
|
│ ├── owlen-ollama/ # Ollama provider implementation
|
|
│ ├── owlen-tui/ # TUI components (chat_app, code_app, rendering)
|
|
│ └── owlen-cli/ # Binary entry points (owlen, owlen-code)
|
|
├── themes/ # Built-in theme definitions (embedded in binary)
|
|
├── LICENSE # AGPL-3.0 License
|
|
├── Cargo.toml # Workspace configuration
|
|
└── README.md
|
|
```
|
|
|
|
### Architecture Highlights
|
|
- **owlen-core**: Provider-agnostic core with session controller, UI primitives (AutoScroll, InputMode, FocusedPanel), and shared utilities
|
|
- **owlen-tui**: Ratatui-based UI implementation with vim-style modal editing
|
|
- **Separation of Concerns**: Clean boundaries between business logic, presentation, and provider implementations
|
|
|
|
## Development
|
|
|
|
### Building
|
|
```bash
|
|
# Debug build
|
|
cargo build
|
|
|
|
# Release build
|
|
cargo build --release
|
|
|
|
# Build with all features
|
|
cargo build --all-features
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Check code
|
|
cargo clippy
|
|
cargo fmt
|
|
```
|
|
|
|
### Development Notes
|
|
- Standard Rust workflows apply (`cargo fmt`, `cargo clippy`, `cargo test`)
|
|
- Codebase uses async Rust (`tokio`) for event handling and streaming
|
|
- Configuration is cached in `~/.config/owlen` (wipe to reset)
|
|
- UI components are extensively tested in `owlen-core/src/ui.rs`
|
|
|
|
## Roadmap
|
|
|
|
### Completed ✓
|
|
- [x] Streaming responses with real-time display
|
|
- [x] Autoscroll and viewport management
|
|
- [x] Push user message before loading LLM response
|
|
- [x] Thinking mode support with dedicated panel
|
|
- [x] Vim-style modal editing (Normal, Visual, Command modes)
|
|
- [x] Multi-panel focus management
|
|
- [x] Text selection and clipboard functionality
|
|
- [x] Comprehensive keyboard navigation
|
|
- [x] Bracketed paste support
|
|
- [x] Command autocompletion with Tab completion
|
|
- [x] Session persistence (save/load conversations)
|
|
- [x] Theming system with 9 built-in themes and custom theme support
|
|
|
|
### In Progress
|
|
- [ ] Enhanced configuration UX (in-app settings)
|
|
- [ ] Conversation export (Markdown, JSON, plain text)
|
|
|
|
### Planned
|
|
- [ ] Code Client Enhancement
|
|
- [ ] In-project code navigation
|
|
- [ ] Syntax highlighting for code blocks
|
|
- [ ] File tree browser integration
|
|
- [ ] Project-aware context management
|
|
- [ ] Code snippets and templates
|
|
- [ ] Additional LLM Providers
|
|
- [ ] OpenAI API support
|
|
- [ ] Anthropic Claude support
|
|
- [ ] Local model providers (llama.cpp, etc.)
|
|
- [ ] Advanced Features
|
|
- [ ] Conversation search and filtering
|
|
- [ ] Multi-session management
|
|
- [ ] Export conversations (Markdown, JSON)
|
|
- [ ] Custom keybindings
|
|
- [ ] Plugin system
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Here's how to get started:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Make your changes and add tests
|
|
4. Run `cargo fmt` and `cargo clippy`
|
|
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
6. Push to the branch (`git push origin feature/amazing-feature`)
|
|
7. Open a Pull Request
|
|
|
|
Please open an issue first for significant changes to discuss the approach.
|
|
|
|
## License
|
|
|
|
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
Built with:
|
|
- [ratatui](https://ratatui.rs/) - Terminal UI framework
|
|
- [crossterm](https://github.com/crossterm-rs/crossterm) - Cross-platform terminal manipulation
|
|
- [tokio](https://tokio.rs/) - Async runtime
|
|
- [Ollama](https://ollama.com/) - Local LLM runtime
|
|
|
|
---
|
|
|
|
**Status**: Alpha v0.1.9 | **License**: AGPL-3.0 | **Made with Rust** 🦀 |