Caution
I'm making this for myself. Use it if you want to, but I can't provide support for you.
An LLM terminal agent harness. A lot like pi, but built in Rust.
- Interactive TUI - Full terminal UI with syntax-highlighted markdown, multi-line editor with word-level cursor navigation, undo support, and keyboard-driven session/model pickers
- Print mode - Send a prompt and get the response printed to stdout, then exit
- RPC mode - JSON-RPC over stdin/stdout for programmatic integration
- Provider support - Supports any OpenAI-compatible provider with either Completions or Responses API endpoints
- Tool use - Built-in tools for
bash,grep,find,ls,read,write, andedit - Image support - Attach images to prompts for multimodal models (bmp, gif, jpeg, png, webp)
- Skills & prompt templates - Auto-discovered from user and project directories; manual loading via CLI flags
- Thinking/reasoning visibility - Toggle display of model chain-of-thought
- Context window management - Automatic compaction and truncation
cargo install --locked --index "sparse+https://git.smalls.online/api/packages/smalls/cargo/" hallucinatecargo install --locked --git "https://git.smalls.online/smalls/hallucinate-cli.git" hallucinateOr from the GitHub mirror:
cargo install --locked --git "https://github.com/Smalls1652/hallucinate-cli.git" hallucinatecargo install --locked --path ./crates/hallucinate hallucinatemake build-release-artifacts
# Binary is placed in artifacts/<os>_<arch>/hallucinate- Rust 1.85+ (uses edition 2024)
- A supported LLM provider API and API key
For full documentation on how to use hallucinate, click here.
Models are not included by default. Add at least one provider and model to settings.toml before starting a run mode. For example:
default_model = "local/llama-3"
[providers.local]
base_url = "http://localhost:1234/v1"
[providers.local.models.llama-3]
name = "Llama 3"
# Use `openai-responses` for providers exposing /responses.
# api = "openai-responses"The settings file is stored in the application's configuration directory. Provider model IDs and metadata are user-configurable, so the same structure works for any OpenAI-compatible endpoint.
# Save an API key (prefer passing via environment variable)
hallucinate auth set <provider> --api-key "$HALLUCINATE_API_KEY"
# List saved providers
hallucinate auth list
# Remove a saved key
hallucinate auth remove <provider>hallucinatehallucinate print "Explain why metalcore music is sometimes referred to as unga-bunga music"hallucinate rpchallucinate [OPTIONS] [COMMAND]
Commands:
auth Save, remove, or list provider API keys
print Send a prompt and print the response, then exit
rpc Run in RPC mode (JSON-RPC over stdin/stdout)
Options:
-m, --model <MODEL> Model to use as a configured model ID or "provider/model" pair
--api-key <API_KEY> API key for the provider. Overrides environment variables and stored credentials.
--base-url <BASE_URL> Base URL for the API (for OpenAI-compatible providers)
--shell <SHELL> Shell executable for the bash tool
--session <SESSION> Resume this persisted session in interactive mode
--max-tokens <MAX_TOKENS> Maximum number of tokens in the response
--thinking Show model thinking/reasoning in output
--temperature <TEMPERATURE> Temperature for sampling (0.0 - 2.0)
--system-prompt <SYSTEM_PROMPT> System prompt to use
--image <IMAGES> Attach an image to a print-mode prompt (repeatable)
--skill <SKILLS> Load a skill Markdown file or directory (repeatable)
--no-skills Disable automatic skill discovery
--prompt-template <PROMPT_TEMPLATES> Load a prompt template file or directory (repeatable)
--no-prompt-templates Disable automatic prompt template discovery
--debug Write diagnostic logs to the application cache directory
-h, --help Print help
-V, --version Print version
| Target | Command |
|---|---|
| Debug build | make build |
| Release build | make build-release |
| Release + artifacts | make build-release-artifacts |
| Format code | make format |
| Check for errors | make check |
| Clean | make clean |
The project is a Cargo workspace with four crates:
| Crate | Description |
|---|---|
hallucinate |
CLI binary - argument parsing and run-mode startup policy |
hallucinate-agent |
Agent core - LLM provider abstraction, runtime, tools, config, and skills |
hallucinate-session |
CLI-oriented append-only JSONL session persistence and lifecycle archival |
hallucinate-tui |
Terminal UI and interactive controller - rendering, editor, input, and commands |
MIT License - see LICENSE for details.
Copyright (c) 2026 Smalls.Online (Timothy Small)
