vikingowl
5b202fed4f
- 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`).
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# OWLEN
|
|
|
|
> Terminal-native assistant for running local language models with a comfortable TUI.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
## 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
|
|
|
|
|
|
|
|
The OWLEN interface features a clean, multi-panel layout with vim-inspired navigation. See more screenshots in the [`images/`](images/) directory.
|
|
|
|
## Features
|
|
|
|
- **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.
|
|
- A running Ollama instance.
|
|
- A terminal that supports 256 colors.
|
|
|
|
### 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://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.
|
|
|
|
#### 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
|
|
owlen
|
|
```
|
|
If you built from source without installing, you can run it with:
|
|
```bash
|
|
./target/release/owlen
|
|
```
|
|
|
|
## Using the TUI
|
|
|
|
OWLEN uses a modal, vim-inspired interface. Press `?` in Normal mode to view the help screen with all keybindings.
|
|
|
|
- **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`.
|
|
|
|
## Documentation
|
|
|
|
For more detailed information, please refer to the following documents:
|
|
|
|
- **[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 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/`.
|
|
|
|
See the [themes/README.md](themes/README.md) for more details on theming.
|
|
|
|
## Roadmap
|
|
|
|
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 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. See the [LICENSE](LICENSE) file for details.
|