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

Add comprehensive documentation and examples for Owlen architecture and usage

Browse Source 
- Include detailed architecture overview in `docs/architecture.md`.
- Add `docs/configuration.md`, detailing configuration file structure and settings.
- Provide a step-by-step provider implementation guide in `docs/provider-implementation.md`.
- Add frequently asked questions (FAQ) document in `docs/faq.md`.
- Create `docs/migration-guide.md` for future breaking changes and version upgrades.
- Introduce new examples in `examples/` showcasing basic chat, custom providers, and theming.
- Add a changelog (`CHANGELOG.md`) for tracking significant changes.
- Provide contribution guidelines (`CONTRIBUTING.md`) and a Code of Conduct (`CODE_OF_CONDUCT.md`).
This commit is contained in:
vikingowl
2025-10-05 02:23:32 +02:00
parent 979347bf53
commit 5b202fed4f
26 changed files with 1108 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
README.md
View File

@@ -7,13 +7,6 @@
![Rust](https://img.shields.io/badge/made_with-Rust-ffc832?logo=rust&logoColor=white)
![License](https://img.shields.io/badge/license-AGPL--3.0-blue)
## 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
@@ -21,366 +14,90 @@ 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.
## Alpha Status
This project is currently in **alpha** and under active development. Core features are functional, but expect occasional bugs and breaking changes. Feedback, bug reports, and contributions are very welcome!
## 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`)
The OWLEN interface features a clean, multi-panel layout with vim-inspired navigation. See more screenshots in the [`images/`](images/) directory.
## 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
- **Vim-style Navigation**: Normal, editing, visual, and command modes.
- **Streaming Responses**: Real-time token streaming from Ollama.
- **Advanced Text Editing**: Multi-line input, history, and clipboard support.
- **Session Management**: Save, load, and manage conversations.
- **Theming System**: 10 built-in themes and support for custom themes.
- **Modular Architecture**: Extensible provider system (currently Ollama).
## 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
- Rust 1.75+ and Cargo.
- A running Ollama instance.
- A terminal that supports 256 colors.
### Installation from Source on Linux and macOS
### Installation
#### Linux & macOS
The recommended way to install on Linux and macOS is to clone the repository and install using `cargo`.
```bash
git clone https://somegit.dev/Owlibou/owlen.git
git clone https://github.com/Owlibou/owlen.git
cd owlen
cargo install --path crates/owlen-cli
```
**Note for macOS**: While this method works, official binary releases for macOS are planned for the future.
**Note**: Make sure `~/.cargo/bin` is in your PATH to run the installed binary:
#### Windows
The Windows build has not been thoroughly tested yet. Installation is possible via the same `cargo install` method, but it is considered experimental at this time.
### Running OWLEN
Make sure Ollama is running, then launch the application:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
owlen
```
### 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:
If you built from source without installing, you can run it with:
```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)
OWLEN uses a modal, vim-inspired interface. Press `?` in Normal mode to view the help screen with all keybindings.
**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
- **Normal Mode**: Navigate with `h/j/k/l`, `w/b`, `gg/G`.
- **Editing Mode**: Enter with `i` or `a`. Send messages with `Enter`.
- **Command Mode**: Enter with `:`. Access commands like `:quit`, `:save`, `:theme`.
**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
## Documentation
**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
For more detailed information, please refer to the following documents:
**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
- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Guidelines for contributing to the project.
- **[CHANGELOG.md](CHANGELOG.md)**: A log of changes for each version.
- **[docs/architecture.md](docs/architecture.md)**: An overview of the project's architecture.
- **[docs/troubleshooting.md](docs/troubleshooting.md)**: Help with common issues.
- **[docs/provider-implementation.md](docs/provider-implementation.md)**: A guide for adding new providers.
## Configuration
OWLEN stores configuration in `~/.config/owlen/config.toml`. The file is created
on first run and can be edited to customize behavior:
OWLEN stores its configuration in `~/.config/owlen/config.toml`. This file is created on the first run and can be customized. You can also add custom themes in `~/.config/owlen/themes/`.
```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`
See the [themes/README.md](themes/README.md) for more details on theming.
## 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
We are actively working on enhancing the code client, adding more providers (OpenAI, Anthropic), and improving the overall user experience. See the [Roadmap section in the old README](https://github.com/Owlibou/owlen/blob/main/README.md?plain=1#L295) for more details.
## 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.
Contributions are highly welcome! Please see our **[Contributing Guide](CONTRIBUTING.md)** for details on how to get started, including our code style, commit conventions, and pull request process.
## 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** 🦀
This project is licensed under the GNU Affero General Public License v3.0. See the [LICENSE](LICENSE) file for details.