clive-llm 0.1.0

A local-first coding-assistant CLI that wraps Ollama, making open-source LLMs easy to chat with, run in sessions, and safely edit code from your terminal.
clive-llm-0.1.0 is not a library.

Clive — a friendly CLI for local LLMs

Clive mascot

CI License: MIT Rust Ollama Contributions Welcome

Clive is a local-first coding-assistant CLI powered by Ollama. It makes open-source LLMs easy to use from the terminal: streaming chat, interactive coding sessions, model management, safe file editing, and autonomous multi-file agent workflows — all running on your own machine, with no data leaving your computer.

New here? Jump to Quick Start to be chatting with a local model in under five minutes.

Table of Contents

Features

  • ASCII art banner at startup
  • Chat with local Ollama models
  • Stream tokens in real time (chat and session)
  • Interactive multi-turn coding sessions
  • Autonomous multi-file agent workflows
  • Manage Ollama from Clive (serve, pull/install, remove)
  • Get curated model recommendations by profile
  • List installed models and verify connectivity
  • Edit source files with preview/apply flow
  • Generate unified patches and optionally apply
  • Optional git safety checks and auto-stage on write
  • Shell completions for bash, zsh, fish, powershell, and elvish
  • Non-interactive JSON reports for automation
  • Persistent configuration (default model, Ollama URL, system prompt)
  • Pipe file contents or command output straight into chat via stdin
  • Save and reload interactive session history
  • Progress spinner while waiting for non-streamed responses

Quick Start

# 1. Install Clive from source (not yet published to crates.io)
cargo install --path .

# 2. Start Ollama in the background
clive ollama serve --detach

# 3. Pull a coding model
clive ollama pull qwen2.5-coder:latest

# 4. Chat!
clive chat "Explain Rust's ownership model in two sentences"

# 5. Or start an interactive session
clive session --model qwen2.5-coder:latest

That's it — everything runs locally against your own Ollama instance.

Prerequisites

  • Rust toolchain (cargo, rustc) — 1.85 or newer
  • Ollama installed on your machine

You do not need a separate terminal for Ollama setup once Clive is installed.

Installation

From source

git clone https://github.com/SedarOlmez94/clive.git
cd clive
cargo install --path .

From crates.io

Not yet available. Once published, install with:

cargo install clive-llm

The clive crate name is already taken by an unrelated project, so Clive will publish under the package name clive-llm instead. The GitHub repo and the installed binary are both still named clive. This README will be updated once the crates.io release exists.

The binary is installed to (usually):

~/.cargo/bin/clive

Make sure ~/.cargo/bin is on your PATH.

Updating

cargo install --path . --force

Reinstall after building from source. The clive on your PATH is a compiled binary — editing the source does not change it until you re-run cargo install --path . --force.

Uninstalling

cargo uninstall clive

One-Terminal Onboarding (Recommended)

  1. Start Ollama from Clive in background:
clive ollama serve --detach
  1. Verify connection:
clive doctor
  1. Install a coding model (example):
clive ollama pull qwen2.5-coder:latest

Clive uses the local Ollama CLI for pulls, so long model downloads stay attached to the terminal and do not time out over HTTP.

  1. Confirm model is available:
clive models
  1. Start using Clive:
clive session --model qwen2.5-coder:latest
  1. Optional: check curated recommendations:
clive ollama recommend --profile rust

Core Commands

Show help:

clive --help

Set a global default model for all commands:

export CLIVE_MODEL=qwen2.5-coder:latest

Or pass it directly:

clive -m qwen2.5-coder:latest session

If no model is provided, Clive auto-selects your first installed local model. If none are installed, it falls back to llama3.1.

Hide startup ASCII art:

clive --no-banner doctor

Persistent Configuration

Clive can remember your defaults so you don't have to pass flags every time. Values are stored as JSON at:

  • Linux/macOS: $XDG_CONFIG_HOME/clive/config.json or ~/.config/clive/config.json
  • Windows: %APPDATA%\clive\config.json
  • Override with the CLIVE_CONFIG environment variable

Precedence for any setting is: CLI flag > environment variable > config file > built-in default.

# Set persistent defaults
clive config set model qwen2.5-coder:latest
clive config set ollama_url http://127.0.0.1:11434
clive config set system "Be concise and production-focused"

# Inspect current configuration and its location
clive config show
clive config path

# Remove a stored value
clive config unset system

Ollama Management from Clive

Start Ollama in foreground:

clive ollama serve

Start Ollama in background:

clive ollama serve --detach

Install a model:

clive ollama pull llama3.1
clive ollama pull qwen2.5-coder:latest

Recommended models by use-case profile:

clive ollama recommend --profile coding
clive ollama recommend --profile rust
clive ollama recommend --profile fast
clive ollama recommend --profile reasoning

Only show recommendations that are already installed:

clive ollama recommend --profile coding --installed-only

Remove an installed model:

clive ollama rm qwen2.5-coder:latest

List installed models:

clive models

Health check:

clive doctor

Chat (Single Prompt)

clive chat "Explain Rust ownership in simple terms"
clive chat "Refactor this function" --model qwen2.5-coder:latest

By default, chat streams tokens as they are generated. Disable streaming:

clive chat "Summarize this module" --no-stream

Thinking models (e.g. qwen3, deepseek-r1) emit their reasoning in a separate stream before the final answer. Clive shows this live on stderr as a dimmed [thinking] ... block so long reasoning phases don't look like a hang, then prints the answer on stdout. Redirect stderr (2>/dev/null) if you only want the final answer.

Optional system prompt:

clive chat "Create tests for this module" --system "Be concise and production-focused"

Pipe file contents or command output directly into the model via stdin.

When you pipe input without a prompt, the piped text becomes the prompt:

git diff | clive chat "" # or simply: clive chat < notes.txt
clive chat < notes.txt

To combine your own prompt with piped input, add the --stdin flag (this keeps the normal clive chat "message" case from ever waiting on stdin):

cat src/main.rs | clive chat "Review this file and suggest improvements" --stdin
git diff | clive chat "Write a concise commit message for this diff" --stdin

Interactive Session (Multi-Turn)

clive session --model qwen2.5-coder:latest

Disable streaming in session mode:

clive session --model qwen2.5-coder:latest --no-stream

Session commands:

  • /help shows available commands
  • /clear resets conversation context (keeps system instruction)
  • /save <file> writes the conversation history to a JSON file
  • /load <file> restores a previously saved conversation
  • /exit exits the session

Agent Workflow (Phase 1, 2, 3)

Run an autonomous workflow over specific files:

clive agent "Refactor error handling and add tests" \
	--files src/main.rs \
	--verify "cargo check -q" \
	--apply

Key options:

  • --files required allow-list of files Clive may edit
  • --verify repeatable verification commands after apply
  • --apply writes edits to disk (otherwise preview only)
  • --rollback-on-fail restores originals if verification never passes
  • --require-clean-git refuses writes when target files are dirty
  • --profile quick|balanced|strict adjusts default iteration and verification behavior
  • --max-iterations overrides profile default loop depth
  • --json prints machine-readable run report for CI/automation
  • --allow-agent-commands allows run_command actions from the model (disabled by default for safety)

Strict profile example:

clive agent "Harden CLI argument validation" \
	--files src/main.rs \
	--apply \
	--rollback-on-fail \
	--profile strict

Automation-friendly JSON mode:

clive --no-banner agent "Improve docs" \
	--files README.md \
	--json

Enable command actions when you explicitly trust the run context:

clive agent "Run formatter and fix lint issues" \
        --files src/main.rs \
        --apply \
        --allow-agent-commands \
        --verify "cargo check -q"

Apply changes:

clive edit src/main.rs "Add structured logging and stronger error handling" --write

Create backup before write:

clive edit src/main.rs "Add structured logging" --write --backup

Git-aware write protection:

clive edit src/main.rs "Refactor parsing logic" --write --require-clean-git

Auto-stage after write:

clive edit src/main.rs "Refactor parsing logic" --write --stage

Patch Mode (Unified Diff)

Show unified patch instead of line-marked diff:

clive patch src/main.rs "Extract helper functions"

Apply patch result to file:

clive patch src/main.rs "Extract helper functions" --write

Professional CLI Features (Clap)

Clive uses a polished Clap configuration with:

  • command aliases (for example: ask, ls, health, repl)
  • inferred subcommands
  • strict help behavior when commands are missing
  • global model selection via -m and CLIVE_MODEL
  • typed shell completion generation

Generate shell completions:

clive completions bash > ~/.clive-complete.bash
clive completions zsh > ~/.clive-complete.zsh
clive completions fish > ~/.config/fish/completions/clive.fish

Verification Before Release

Run these checks before cutting a release:

cargo fmt --check
cargo check
cargo test

Ollama Host Configuration

Default:

Override per command:

clive --ollama-url http://127.0.0.1:11434 chat "hello"

Or via environment variable:

export OLLAMA_HOST=http://127.0.0.1:11434

VS Code Workflow Notes

Run Clive from your project root for best relative path behavior.

When you run edit or patch with --write, Clive updates files directly and VS Code reflects changes automatically.

How It Works

Clive is a thin, safety-focused wrapper around a local Ollama server:

┌──────────┐    JSON / streaming     ┌──────────────┐    inference    ┌─────────────┐
│  clive   │ ─────────────────────▶  │ Ollama server │ ───────────────▶│ local model │
│  (CLI)   │ ◀─────────────────────  │ (HTTP :11434) │ ◀───────────────│ e.g. qwen3  │
└──────────┘   tokens / thinking      └──────────────┘                 └─────────────┘
  • Chat & session call Ollama's /api/chat endpoint. Responses stream token by token; reasoning ("thinking") models are surfaced live so long thinking phases never look like a hang.
  • Model management (serve, pull, rm, models) shells out to the local ollama CLI or talks to the HTTP API, whichever is more reliable for the task.
  • Edit / patch / agent load your files, ask the model for a full updated version, show a diff, and only write when you explicitly pass --write / --apply. Optional git checks and rollback keep changes reversible.

Everything runs on your machine. No prompts, code, or files are sent to any third-party service.

Troubleshooting & FAQ

Clive seems to hang with no output when I send a message. You are almost certainly using a thinking model (e.g. qwen3, deepseek-r1). These models stream their reasoning before the final answer. Clive shows this as a dimmed [thinking] … block on stderr. If you want only the answer, redirect stderr: clive chat "…" 2>/dev/null. If you built from source, also make sure you reinstalled: cargo install --path . --force.

clive: command not found. Ensure ~/.cargo/bin is on your PATH. Add this to your shell profile: export PATH="$HOME/.cargo/bin:$PATH".

Ollama not reachable / connection refused. Start the server with clive ollama serve --detach, then verify with clive doctor. If you run Ollama on a non-default host or port, set --ollama-url or the OLLAMA_HOST environment variable.

How do I set a default model so I don't pass --model every time? clive config set model qwen2.5-coder:latest, or export CLIVE_MODEL.

Which models should I use? Run clive ollama recommend --profile coding (or rust, fast, reasoning).

Can I pipe input into Clive? Yes: git diff | clive chat "write a commit message" --stdin, or clive chat < notes.txt.

Does Clive send my data anywhere? No. Clive only talks to your local Ollama server.

Contributing

Contributions are very welcome — bug reports, feature ideas, docs, and code.

  1. Read the Contributing Guide and Code of Conduct.
  2. Fork the repo and create a feature branch.
  3. Make your change with tests where practical.
  4. Run the full check suite before opening a PR:
cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo test
  1. Open a pull request describing the change and its motivation.

Good first issues are labelled good first issue.

Roadmap

Planned and under consideration (feedback welcome via issues):

  • Publish to crates.io as clive-llm (the clive name is taken by an unrelated crate; the clive binary name is unaffected)
  • VS Code Copilot Chat participant (@clive) to run the agent workflow with a chosen local model from inside the editor
  • Configurable model parameters (temperature, context length, num_ctx)
  • Multi-file context in chat/session (attach files as context)
  • Prebuilt release binaries via GitHub Releases (no Rust toolchain needed)
  • Homebrew formula and other package-manager distributions
  • Session transcripts in Markdown, not just JSON
  • Pluggable prompt templates / personas

See the open issues for the current list.

Security

Clive edits files and can run shell commands (only with --apply + --allow-agent-commands). Please review the Security Policy before reporting a vulnerability, and do not open public issues for security problems.

License

Licensed under the MIT License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Clive by you shall be licensed as MIT, without any additional terms or conditions.

Acknowledgements

  • Ollama for making local model hosting effortless.
  • clap for the ergonomic CLI framework.
  • reqwest, serde, anyhow, and similar for doing the heavy lifting.
  • Everyone building and sharing open-source models. ❤️

If Clive is useful to you, please consider giving the repo a ⭐ — it helps others discover the project.