# OWLEN

> Terminal-native assistant for running local language models with a comfortable TUI.

![Status](https://img.shields.io/badge/status-pre--alpha-orange)
![Rust](https://img.shields.io/badge/made_with-Rust-ffc832?logo=rust&logoColor=white)
![License](https://img.shields.io/badge/license-TBD-lightgrey)

## 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.

## 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
- 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).

## 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 colours.

### Clone and Build
```bash
git clone https://github.com/Owlibou/owlen.git
cd owlen
cargo build -p owlen-cli
```

### Run the Chat Client
Make sure Ollama is running, then launch:

```bash
cargo run -p owlen-cli --bin owlen
```

### (Optional) Try the Coding Client
The coding-focused TUI is experimental and ships behind a feature flag:

```bash
cargo run -p owlen-cli --features code-client --bin 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 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:

```toml
[general]
default_model = "llama3.2:latest"
enable_streaming = true
project_context_file = "OWLEN.md"

[providers.ollama]
provider_type = "ollama"
base_url = "http://localhost:11434"
```

Additional sections cover UI preferences, file limits, and storage paths. Each
client persists its latest selections back to this file on exit.

## 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`).
- The codebase uses async Rust (`tokio`) for event handling and streaming.
- Configuration and chat history are cached locally; wipe `~/.config/owlen` to reset.

## Roadmap
- [x] Add autoscroll.
- [x] 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.

## 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.