TinyHarness

Lightweight AI assistant framework in Rust with pluggable LLM providers (Ollama, llama.cpp, vLLM), built-in tool calling, agent skills, and customizable system prompts.

Features

• Pluggable Providers: Ollama, llama.cpp, vLLM, any OpenAI-compatible API gateway (OpenRouter, Together, etc.) with Bearer auth, and ⚠️ Sockudo AI Transport as a highly experimental backend requiring a running Sockudo server and a worker bridge (see docs/examples/sockudo-worker/). Ollama supports retries with backoff, configurable timeouts, and reasoning/think levels.
• Tool System: 15 modular tools (ls, read, write, edit, grep, glob, run, web_search, web_fetch, auto_compact, invoke_skill, switch_mode, question, screenshot, plus the built-in read image loader for multimodal models).
• Agent Modes: Four modes — casual (web-only), planning (read-only + signals), agent (full access), and research (web-focused) — to control what the AI can do. Modes are backed by customizable .md prompt files.
• Skills: Pluggable SKILL.md modules discovered from ~/.config/tinyharness/skills/ and .tinyharness/skills/. Invokable by the AI via invoke_skill or by the user via /use <name>. Supports YAML frontmatter with name, description, compatibility, licensing, and model-invocation controls.
• Context Management: Token estimation with per-model context window sizes (8K–256K), load warnings at 70%/90% thresholds, and cascading conversation compaction via /compact.
• Session Persistence: JSONL-based sessions with UUIDs, saved in ~/.local/share/tinyharness/sessions/. Supports session listing, switching by prefix, renaming, deletion, and auto-save every 5 messages.
• Async Streaming: Built on tokio for efficient streaming with all providers. Ctrl+C interrupts generation gracefully.
• Experimental TUI: Split-pane terminal UI with conversation view, sidebar, input bar, and tool output panel. Built from scratch with no external TUI framework. Activate with --tui. ⚠️ Experimental — may have rendering issues or incomplete features.
• Interactive CLI: Color-coded terminal interface with 24+ slash commands for session management, configuration, file pinning, image attachment, audit logging, debug diagnostics, and tool control.
• Customizable Prompts: System prompts are seeded from hardcoded defaults on first launch to ~/.config/tinyharness/prompts/ and can be freely edited.
• Command Safety: Smart auto-accept for safe shell commands with prefix matching, deny lists, redirection stripping, and audit logging.
• Thinking Display: Optionally render the model's reasoning chain inline during streaming (toggle via /showthink).
• Image Attachments: Multimodal support — attach images with /image and the read tool automatically loads image files for visual models.
• Project Instructions: Auto-discovers TINYHARNESS.md, .tinyharness.md, AGENTS.md, or CLAUDE.md walking up from the current directory. Configurable via TINYHARNESS_MD_FILES env var or settings. Additional project-specific files (e.g. RULES.md, .cursorrules) can be loaded from .tinyharness/config.json.
• Per-Project Settings: Layer .tinyharness/config.json over global settings. Override safe/denied commands, auto-accept behavior, context limits, preferred mode, and more per project. View merged settings with /project-settings.
• Smart Language Detection: Auto-detects 17+ languages and build tools (Rust, Zig, Deno, Bun, Swift, Ruby, Elixir, Haskell, Kotlin, .NET, Dart/Flutter, Nix, Node.js, Python, Go, Java, C/C++). Detects monorepos (e.g. "Rust + Node.js").

Getting Started

Prerequisites

• Rust (latest stable, edition 2024)
• At least one LLM backend:
• Ollama (default, local)
• llama.cpp server (local, no auth)
• vLLM (local, no auth)
• Any OpenAI-compatible API gateway (OpenRouter, Together, custom proxies, etc.) — requires an API key and explicit URL
• Sockudo (⚠️ highly experimental — requires a worker bridge, see docs/examples/sockudo-worker/)

Installation

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

This builds in release mode and copies the binary to ~/.local/bin. Make sure ~/.local/bin is in your $PATH:

export PATH="$HOME/.local/bin:$PATH"

To uninstall:

make uninstall

Alternatively, install via Cargo:

cargo install --path .

Installation (Nix)

A Nix flake is provided for reproducible builds and dev environments.

Run once without installing:

nix run github:PTFOPlayer/TinyHarness

Build the package:

cd TinyHarness
nix build
./result/bin/tinyharness

Enter a development shell (with Rust toolchain, rustfmt, and clippy pre-configured):

nix develop

Usage

Ollama (default):

tinyharness

Connects to http://127.0.0.1:11434. Supports configurable timeout, retries, and think/reasoning level.

llama.cpp:

tinyharness --llama-cpp

Connects to http://127.0.0.1:8080 by default.

vLLM:

tinyharness --vllm

Connects to http://127.0.0.1:8000 by default.

OpenAI-compatible gateway (OpenRouter, Together, custom proxies, etc.):

tinyharness --openai-compat --url https://openrouter.ai/api/v1 --api-key <YOUR_KEY>

Requires --url (no default URL) and an API key. You can also set the OPENAI_API_KEY environment variable instead of --api-key. Bearer auth is sent on every request. Use --skip-health-check if the gateway doesn't expose a /health endpoint.

Sockudo (⚠️ highly experimental):

tinyharness --sockudo

Connects to http://127.0.0.1:6001 by default. Requires a running Sockudo server with AI Transport enabled and a worker bridge process (see docs/examples/sockudo-worker/). This backend is not recommended for production use.

A health check runs on startup to verify the provider is reachable. If the saved model is unavailable, the first available model is auto-selected with a warning.

Custom URL (works with any provider):

tinyharness --llama-cpp --url http://localhost:2832
tinyharness --ollama --url http://192.168.1.50:11434
tinyharness --vllm --url http://gpu-server:8000
tinyharness --openai-compat --url https://api.example.com/v1 --api-key sk-xxx

Continue last session:

tinyharness --continue

Resumes the most recent session in the current working directory.

Non-interactive prompt:

tinyharness -p "What does this project do?"
tinyharness --prompt "Explain the architecture"

Sends an initial prompt and then drops into the interactive loop for follow-up turns.

Terminal UI (experimental):

tinyharness --tui

Launches a split-pane TUI with conversation view, sidebar, input bar, and tool output panel. Built from scratch using raw ANSI escape sequences — no external TUI framework. This is experimental and may have rendering issues or incomplete features.

Interactive setup:

tinyharness --config

Runs a guided setup: pick a provider, enter a URL, save to settings. Exits when done.

CLI Arguments

Agent Modes

Switch modes with /mode <name>, use shortcut aliases (/plan, /agent, /research, /casual), or let the AI request escalation via switch_mode.

Tools

Slash Commands

Session Management

Mode & Model

Context & Files

Conversation

Skills

Configuration

General

Command Management

The /command system controls which shell commands are auto-accepted:

/command list          # Show safe and denied commands
/command add <cmd>     # Add a command to auto-accept list
/command rm <cmd>      # Remove from auto-accept list
/command deny <cmd>    # Add to deny list (always requires confirmation)
/command undeny <cmd>  # Remove from deny list
/command reset         # Reset safe commands to defaults
/command resetdeny     # Clear the deny list

Safe commands include cd, ls, grep, cat, git status, git diff, git log, cargo tree, and ~40 more. Shell redirections (2>&1, 2>/dev/null) are stripped before matching. The deny list takes priority — if a command matches both lists, it is denied. The run tool can never be auto-accepted even in auto-ac