Owlibou/owlen
2
0
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects Releases 5 Activity

Update README: refine content, add screenshots, improve structure, and document new features and usage details.

Browse Source
This commit is contained in:
vikingowl
2025-09-30 03:07:13 +02:00
parent 053f389b1e
commit 4ca71a7c6b
6 changed files with 223 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
README.md
View File

@@ -2,126 +2,278 @@
> Terminal-native assistant for running local language models with a comfortable TUI. > Terminal-native assistant for running local language models with a comfortable TUI.
![Status](https://img.shields.io/badge/status-pre--alpha-orange) ![Status](https://img.shields.io/badge/status-alpha-yellow)
![Version](https://img.shields.io/badge/version-0.1.0-blue)
![Rust](https://img.shields.io/badge/made_with-Rust-ffc832?logo=rust&logoColor=white) ![Rust](https://img.shields.io/badge/made_with-Rust-ffc832?logo=rust&logoColor=white)
![License](https://img.shields.io/badge/license-TBD-lightgrey) ![License](https://img.shields.io/badge/license-MIT-green)
## Pre-Alpha Status ## Alpha Status
- This project is currently **pre-alpha** and under active development.
- Expect breaking changes, missing features, and occasional rough edges. - This project is currently in **alpha** (v0.1.0) and under active development.
- Feedback, bug reports, and ideas are very welcome while we shape the roadmap. - 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? ## What Is OWLEN?
OWLEN is a Rust-powered, terminal-first interface for interacting with local large
language models. It focuses on a responsive chat workflow that runs against
[Ollama](https://ollama.com/) and surfaces the tools needed to manage sessions,
inspect project context, and iterate quickly without leaving your shell.
### Current Highlights OWLEN is a Rust-powered, terminal-first interface for interacting with local large
- Chat-first terminal UI built with `ratatui` and `crossterm`. language models. It provides a responsive chat workflow that runs against
- Out-of-the-box Ollama integration with streaming responses. [Ollama](https://ollama.com/) with a focus on developer productivity, vim-style navigation,
- Persistent configuration, model caching, and session statistics. and seamless session management—all without leaving your terminal.
- Project-aware context loading (reads `OWLEN.md` when present).
- Experimental coding assistant mode (opt-in build feature). ## Screenshots
### Initial Layout
![OWLEN TUI Layout](images/layout.png)
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`)
- **Session Management** - Start new conversations, clear history
- **Thinking Mode Support** - Dedicated panel for extended reasoning content
- **Bracketed Paste** - Safe paste handling for multi-line content
### 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 ## Getting Started
### Prerequisites ### Prerequisites
- Rust 1.75+ and Cargo (`rustup` recommended). - Rust 1.75+ and Cargo (`rustup` recommended)
- A running Ollama instance with at least one model pulled - A running Ollama instance with at least one model pulled
(defaults to `http://localhost:11434`). (defaults to `http://localhost:11434`)
- A terminal that supports 256 colours. - A terminal that supports 256 colors
### Clone and Build ### Clone and Build
```bash ```bash
git clone https://github.com/Owlibou/owlen.git git clone https://somegit.dev/Owlibou/owlen.git
cd owlen cd owlen
cargo build -p owlen-cli cargo build --release
``` ```
### Run the Chat Client ### Run the Chat Client
Make sure Ollama is running, then launch: Make sure Ollama is running, then launch:
```bash ```bash
cargo run -p owlen-cli --bin owlen ./target/release/owlen
# or during development:
cargo run --bin owlen
``` ```
### (Optional) Try the Coding Client ### (Optional) Try the Code Client
The coding-focused TUI is experimental and ships behind a feature flag:
The coding-focused TUI is experimental:
```bash ```bash
cargo run -p owlen-cli --features code-client --bin owlen-code cargo build --release --bin owlen-code --features code-client
./target/release/owlen-code
``` ```
## Using the TUI ## Using the TUI
- `i` / `Enter` – focus the input box.
- `Enter` – send the current message.
- `Shift+Enter` / `Ctrl+J` – insert a newline while editing.
- `m` – open the model selector.
- `n` – start a fresh conversation.
- `c` – clear the current chat history.
- `h` – open inline help.
- `q` – quit.
The status line surfaces hints, error messages, and streaming progress. ### 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
- Paste events handled automatically
**Visual Mode**:
- `j/k/h/l` - Extend selection
- `w/b/e` - Word-based selection
- `y` - Yank (copy) selection
- `d` - Cut selection (Input panel only)
- `Esc` - Cancel selection
**Command Mode**:
- `:q` / `:quit` - Quit application
- `:c` / `:clear` - Clear conversation
- `:m` / `:model` - Open model selector
- `:n` / `:new` - Start new conversation
- `:h` / `:help` - Show help
### 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 ## Configuration
OWLEN stores configuration in `~/.config/owlen/config.toml`. The file is created OWLEN stores configuration in `~/.config/owlen/config.toml`. The file is created
on first run and can be edited to customise behaviour: on first run and can be edited to customize behavior:
```toml ```toml
[general] [general]
default_model = "llama3.2:latest" default_model = "llama3.2:latest"
default_provider = "ollama"
enable_streaming = true enable_streaming = true
project_context_file = "OWLEN.md" project_context_file = "OWLEN.md"
[providers.ollama] [providers.ollama]
provider_type = "ollama" provider_type = "ollama"
base_url = "http://localhost:11434" base_url = "http://localhost:11434"
timeout = 300
``` ```
Additional sections cover UI preferences, file limits, and storage paths. Each Configuration is automatically saved when you change models or providers.
client persists its latest selections back to this file on exit.
## Repository Layout ## Repository Layout
- `crates/owlen-core` – shared types, configuration, and session orchestration.
- `crates/owlen-ollama` – provider implementation that speaks to the Ollama API.
- `crates/owlen-tui` – `ratatui`-based UI, helpers, and event handling.
- `crates/owlen-cli` – binaries (`owlen`, `owlen-code`) wiring everything together.
- `tests` – integration-style smoke tests.
## Development Notes ```
- Standard Rust workflows apply (`cargo fmt`, `cargo clippy`, `cargo test`). owlen/
- The codebase uses async Rust (`tokio`) for event handling and streaming. ├── crates/
- Configuration and chat history are cached locally; wipe `~/.config/owlen` to reset. │ ├── owlen-core/ # Core types, session management, 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)
├── LICENSE # MIT 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 ## Roadmap
- [x] Add autoscroll.
- [x] Push user message before loading the LLM response. ### Completed ✓
- [ ] Add support for "thinking" models. - [x] Streaming responses with real-time display
- [ ] Add theming options. - [x] Autoscroll and viewport management
- [ ] Provide proper configuration UX. - [x] Push user message before loading LLM response
- [ ] Add chat-management tooling. - [x] Thinking mode support with dedicated panel
- [ ] Reactivate and polish the coding client. - [x] Vim-style modal editing (Normal, Visual, Command modes)
- [ ] Add support for streaming responses. - [x] Multi-panel focus management
- [ ] Add support for streaming chat history. - [x] Text selection and clipboard functionality
- [ ] Add support for streaming model statistics. - [x] Comprehensive keyboard navigation
- [ ] Add coding client - [x] Bracketed paste support
- [ ] Add support for in project code navigation.
- [ ] Add support for code completion. ### In Progress
- [ ] Add support for code formatting. - [ ] Theming options and color customization
- [ ] Add support for code linting. - [ ] Enhanced configuration UX (in-app settings)
- [ ] Add support for code refactoring. - [ ] Chat history management (save/load/export)
- [ ] Add support for code navigation.
- [ ] Add support for code snippets. ### Planned
- [ ] Add support for in project config folder. - [ ] Code Client Enhancement
- [ ] Add support for more local LLM providers. - [ ] In-project code navigation
- [ ] Add support for cloud LLM providers. - [ ] 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 ## Contributing
Contributions are encouraged, but expect a moving target while we stabilise the
core experience. Opening an issue before a sizeable change helps coordinate the Contributions are welcome! Here's how to get started:
roadmap.
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 ## License
License terms are still being finalised for the pre-alpha release.
This project is licensed under the MIT License - 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.0 | **License**: MIT | **Made with Rust** 🦀

BIN
images/chat_view.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
images/help.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB

BIN
images/layout.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
images/model_select.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

BIN
images/select_mode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB