ðŸĶ€ Rust MIT Licensed ⭐ 19 stars

TinyHarness

Lightweight AI assistant framework in Rust. Pluggable LLM providers, built-in tool calling, web search, agent skills — and a reusable library crate. Runs on under 20 MB of RAM with zero idle CPU.

View on GitHub Get Started →
TinyHarness terminal screenshot

Features

🔌

Pluggable Providers

Ollama, llama.cpp, vLLM, and any OpenAI-compatible API. Swap backends without changing application code.

🛠ïļ

Tool System

Modular tools — ls, read, write, edit, grep, glob, run, web_search — that let the AI interact with your filesystem and the web.

🎭

Agent Modes

Four modes — casual, planning, agent, and research — to control what the AI can do at any given moment.

ðŸ§Đ

Skills

Pluggable skill modules that inject specialized instructions for specific tasks like PDF processing or image analysis.

ðŸ’ū

Session Persistence

JSONL-based sessions with UUIDs, saved locally. Pick up conversations right where you left off.

🌐

Web Search

Built-in web_search and web_fetch tools powered by the Ollama web search API. The AI can look up documentation, fetch web pages, and stay current without leaving the terminal.

ðŸŠķ

Low Memory Footprint

Minimal resource usage — typically under 20 MB of RAM. Zero CPU utilization when idle. Writes directly to STDOUT instead of a full TUI framework, keeping memory and dependencies to a minimum. Check it yourself:

smem -t -k | grep tinyharness | awk '{ total = total + $NF } END { print total }'

Installation

Prerequisites

Cargo Install Recommended

cargo install tinyharness

Available on crates.io. Installs the binary to ~/.cargo/bin.

Build from Source

git clone https://github.com/PTFOPlayer/TinyHarness.git
cd TinyHarness
make install

Builds in release mode and copies the binary to ~/.local/bin.

Usage

Ollama Default

tinyharness

Connects to http://127.0.0.1:11434

llama.cpp

tinyharness --llama-cpp

Connects to http://127.0.0.1:8080

vLLM

tinyharness --vllm

Connects to http://127.0.0.1:8000

Custom URLs

tinyharness --llama-cpp --url http://localhost:2832
tinyharness --ollama --url http://192.168.1.50:11434
tinyharness --vllm --url http://gpu-server:8000

Use as a Library

The core of TinyHarness is exposed as tinyharness-lib — a crate you can pull into any Rust project to get AI tooling without the terminal frontend.

Add the dependency

[dependencies]
tinyharness-lib = "0.1"

Or run cargo add tinyharness-lib.

What you get

  • Provider trait — Ollama, llama.cpp, vLLM, and OpenAI-compatible backends, ready to swap
  • Tool system — ls, read, write, edit, grep, glob, run, web_search with confirmation hooks
  • Session management — JSONL-based conversations with UUIDs, token estimation, and compaction
  • Agent modes — casual, planning, agent, research — control which tools are available
  • Skills registry — pluggable instruction injectors for specialized tasks
  • Project context — TINYHARNESS.md parsing and file pinning

Agent Modes

Mode Tools Available Purpose
casual None Pure chat, no filesystem access
planning ls, read, grep, glob, web_search, switch_mode, question Analyze & plan, then escalate to agent
agent All tools Full development access — code, commands, web
research web_search, web_fetch, ls, read, grep, glob, switch_mode, question Web research, then escalate for execution

Slash Commands

/help Show available commands
/mode Switch agent mode
/compact Summarize older messages
/session Manage conversation sessions
/settings Show configuration
/command Manage auto-accepted commands
/model List or switch models
/apikey Set/show/clear API key
/add  /drop Pin/unpin files into context
/context Show project context
/init Generate TINYHARNESS.md
/clear  /exit Clear screen / quit

Project Structure

Cargo workspace with two crates — a frontend-agnostic library and a terminal-UI binary.

Library tinyharness-lib/

  • provider/ Provider trait + implementations
  • config/ Settings persistence
  • mode.rs Agent modes + system prompts
  • context.rs Project metadata + TINYHARNESS.md
  • session.rs JSONL session persistence
  • token.rs Token estimation
  • skill.rs Skill discovery & registry
  • tools/ Tool implementations

Binary src/

  • main.rs Entry point, CLI parsing
  • agent.rs Main interaction loop
  • style.rs ANSI color constants
  • commands/ Slash command handlers
  • ui/ Terminal UI helpers

Security

⚠ïļ

TinyHarness grants LLMs the ability to interact with your filesystem through tool calling. Run within a sandboxed environment (Docker container, VM) to prevent unintended modifications.

The run tool can never be auto-accepted — unlike write and edit. Always review proposed actions. You assume full responsibility for all operations performed by the AI.