diff --git a/README.md b/README.md index 847b0e7..47ef353 100644 --- a/README.md +++ b/README.md @@ -1,275 +1,123 @@ # OWLEN -A terminal user interface (TUI) for interacting with Ollama models, similar to `claude code` or `gemini-cli` but using Ollama as the backend. +> Terminal-native assistant for running local language models with a comfortable TUI. -## Features +## Pre-Alpha Status +- This project is currently **pre-alpha** and under active development. +- Expect breaking changes, missing features, and occasional rough edges. +- Feedback, bug reports, and ideas are very welcome while we shape the roadmap. -🤖 **AI Chat Interface**: Interactive conversations with Ollama models -🔄 **Real-time Streaming**: See responses as they're generated -📝 **Multi-model Support**: Switch between different Ollama models -⌨️ **Vim-inspired Keys**: Intuitive keyboard navigation -🎨 **Rich UI**: Clean, modern terminal interface with syntax highlighting -📜 **Conversation History**: Keep track of your chat history -🚀 **Fast & Lightweight**: Built in Rust for performance +## 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. -## Prerequisites +### Current Highlights +- Chat-first terminal UI built with `ratatui` and `crossterm`. +- Out-of-the-box Ollama integration with streaming responses. +- Persistent configuration, model caching, and session statistics. +- Project-aware context loading (reads `OWLEN.md` when present). +- Experimental coding assistant mode (opt-in build feature). -- [Ollama](https://ollama.ai/) installed and running -- Rust 1.70+ (for building from source) +## Getting Started -## Development Setup and Usage +### 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 colours. -To set up the project for development, follow these steps: +### Clone and Build +```bash +git clone https://github.com/Owlibou/owlen.git +cd owlen +cargo build -p owlen-cli +``` -1. **Clone the repository:** - ```bash - git clone https://somegit.dev/Owlibou/owlen.git - cd owlen - ``` - -2. **Build the project:** - ```bash - cargo build - ``` - This will compile all crates in the workspace. - -3. **Run tests:** - ```bash - cargo test - ``` - -4. **Run the `owlen` (chat) application in development mode:** - ```bash - cargo run --bin owlen - ``` - -5. **Run the `owlen-code` (code) application in development mode:** - ```bash - cargo run --bin owlen-code - ``` - -## Installation - -### Build from Source +### Run the Chat Client +Make sure Ollama is running, then launch: ```bash -git clone https://github.com/yourusername/owlen -cd owlen -cargo build --release +cargo run -p owlen-cli --bin owlen ``` -This will build two executables: `owlen` (for general chat) and `owlen-code` (for code-focused interactions). +### (Optional) Try the Coding Client +The coding-focused TUI is experimental and ships behind a feature flag: -## Quick Start - -1. **Start Ollama**: Make sure Ollama is running on your system: - ```bash - ollama serve - ``` - -2. **Pull a Model**: Download a model to chat with: - ```bash - ollama pull llama3.2 - ``` - -3. **Run OWLEN (General Chat)**: - ```bash - ./target/release/owlen - # Or using cargo: - cargo run - ``` - -4. **Run OWLEN (Code Mode)**: - ```bash - ./target/release/owlen-code - # Or using cargo: - cargo run --bin owlen-code - ``` - -## Usage (General Chat Mode) - -### Key Bindings - -#### Normal Mode (Default) -- `i` - Enter input mode to type a message -- `m` - Open model selection menu -- `c` - Clear current conversation -- `r` - Refresh available models list -- `j`/`k` - Scroll up/down in chat history -- `↑`/`↓` - Scroll up/down in chat history -- `q` - Quit application - -#### Input Mode -- `Enter` - Send message -- `Esc` - Cancel input and return to normal mode -- `←`/`→` - Move cursor left/right -- `Backspace` - Delete character - -#### Model Selection Mode -- `↑`/`↓` - Navigate model list -- `Enter` - Select model -- `Esc` - Cancel selection - -### Interface Layout - -``` -┌─ OWLEN ──────────────────────────────┐ -│ 🦉 OWLEN - AI Assistant │ -│ Model: llama3.2:latest │ -├──────────────────────────────────────┤ -│ │ -│ 👤 You: │ -│ Hello! Can you help me with Rust? │ -│ │ -│ 🤖 Assistant: │ -│ Of course! I'd be happy to help │ -│ you with Rust programming... │ -│ │ -├──────────────────────────────────────┤ -│ Input (Press 'i' to start typing) │ -│ │ -├──────────────────────────────────────┤ -│ NORMAL | Ready │ -│ Help: i:Input m:Model c:Clear q:Quit │ -└──────────────────────────────────────┘ +```bash +cargo run -p owlen-cli --features code-client --bin owlen-code ``` -## Code Mode (`owlen-code`) +## 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 `owlen-code` binary provides a specialized interface for interacting with LLMs for code-related tasks. It is designed to be used in conjunction with a code editor or IDE, allowing you to quickly get assistance with debugging, code generation, refactoring, and more. - -### Key Bindings - -(Assuming similar key bindings to general chat mode for now. Further details can be added if `owlen-code` has distinct keybindings or features.) - -- `i` - Enter input mode to type a message -- `m` - Open model selection menu -- `c` - Clear current conversation -- `r` - Refresh available models list -- `j`/`k` - Scroll up/down in chat history -- `↑`/`↓` - Scroll up/down in chat history -- `q` - Quit application - -#### Input Mode -- `Enter` - Send message -- `Esc` - Cancel input and return to normal mode -- `←`/`→` - Move cursor left/right -- `Backspace` - Delete character - -#### Model Selection Mode -- `↑`/`↓` - Navigate model list -- `Enter` - Select model -- `Esc` - Cancel selection +The status line surfaces hints, error messages, and streaming progress. ## Configuration +OWLEN stores configuration in `~/.config/owlen/config.toml`. The file is created +on first run and can be edited to customise behaviour: -The application connects to Ollama on `localhost:11434` by default. You can modify this in the source code if needed. +```toml +[general] +default_model = "llama3.2:latest" +enable_streaming = true +project_context_file = "OWLEN.md" -## Use Cases - -### Code Assistant -Perfect for getting help with programming tasks: - -- Debugging code issues -- Learning new programming concepts -- Code reviews and suggestions -- Architecture discussions - -### General AI Chat -Use it as a general-purpose AI assistant: - -- Writing assistance -- Research questions -- Creative projects -- Learning new topics - -## Architecture - -The application is built with a modular architecture, composed of several crates: - -- **owlen-core**: Provides core traits and types for the LLM client, acting as the foundation. -- **owlen-ollama**: Implements the Ollama API client with streaming support, handling communication with Ollama models. -- **owlen-tui**: Manages the Terminal User Interface rendering and interactions using `ratatui`. -- **owlen-cli**: The command-line interface, which orchestrates the `owlen-tui` and `owlen-ollama` crates to provide the main `owlen` and `owlen-code` binaries. - -- **main.rs** - Application entry point and terminal setup -- **app.rs** - Core application state and event handling -- **ollama.rs** - Ollama API client with streaming support -- **ui.rs** - Terminal UI rendering with ratatui -- **events.rs** - Terminal event handling and processing - -## Contributing - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Add tests if applicable -5. Submit a pull request - -## License - -This project is licensed under the MIT License - see the LICENSE file for details. - -## Acknowledgments - -- [Ollama](https://ollama.ai/) - Local LLM inference -- [Ratatui](https://github.com/ratatui/ratatui) - Rust TUI library -- [Claude Code](https://claude.ai/code) - Inspiration for the interface -- [Gemini CLI](https://github.com/google-gemini/gemini-cli) - CLI patterns - -## Troubleshooting - -### Ollama Not Found -``` -Error: Failed to connect to Ollama +[providers.ollama] +provider_type = "ollama" +base_url = "http://localhost:11434" ``` -**Solution**: Make sure Ollama is installed and running: -```bash -# Install Ollama -curl -fsSL https://ollama.ai/install.sh | sh +Additional sections cover UI preferences, file limits, and storage paths. Each +client persists its latest selections back to this file on exit. -# Start Ollama -ollama serve +## 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. -# Pull a model -ollama pull llama3.2 -``` - -### No Models Available -``` -No models available -``` - -**Solution**: Pull at least one model: -```bash -ollama pull llama3.2 -# or -ollama pull codellama -# or -ollama pull mistral -``` - -### Connection Refused -``` -Connection refused (os error 61) -``` - -**Solution**: Check if Ollama is running on the correct port: -```bash -# Default port is 11434 -curl http://localhost:11434/api/tags -``` +## Development Notes +- Standard Rust workflows apply (`cargo fmt`, `cargo clippy`, `cargo test`). +- The codebase uses async Rust (`tokio`) for event handling and streaming. +- Configuration and chat history are cached locally; wipe `~/.config/owlen` to reset. ## Roadmap +- [ ] Add autoscroll. +- [ ] Push user message before loading the LLM response. +- [ ] Add support for "thinking" models. +- [ ] Add theming options. +- [ ] Provide proper configuration UX. +- [ ] Add chat-management tooling. +- [ ] Reactivate and polish the coding client. +- [ ] Add support for streaming responses. +- [ ] Add support for streaming chat history. +- [ ] Add support for streaming model statistics. +- [ ] Add coding client + - [ ] Add support for in project code navigation. + - [ ] Add support for code completion. + - [ ] Add support for code formatting. + - [ ] Add support for code linting. + - [ ] Add support for code refactoring. + - [ ] Add support for code navigation. + - [ ] Add support for code snippets. + - [ ] Add support for in project config folder. +- [ ] Add support for more local LLM providers. +- [ ] Add support for cloud LLM providers. -- [ ] Chat interface (`owlen`) (in progress) -- [ ] Code interface (`owlen-code`) -- [ ] Configuration file support -- [ ] Custom Ollama host configuration -- [ ] Session persistence -- [ ] Export conversations -- [ ] Syntax highlighting for code blocks -- [ ] Plugin system for custom commands -- [ ] Multiple conversation tabs -- [ ] Search within conversations +## 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 +roadmap. + +## License +License terms are still being finalised for the pre-alpha release.