loki-ai

Crates.ioloki-ai
lib.rsloki-ai
version0.1.3
created_at2025-11-08 00:10:34.797266+00
updated_at2025-12-13 21:21:44.442321+00
descriptionAn all-in-one, batteries included LLM CLI Tool
homepagehttps://github.com/Dark-Alex-17/loki
repositoryhttps://github.com/Dark-Alex-17/loki
max_upload_size
id1922365
size8,476,127
Alex Clarke (Dark-Alex-17)

documentation

README

Loki: All-in-one, batteries-included LLM CLI Tool

Test LOC crates.io link Release Crate.io downloads GitHub Downloads

Loki is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistant, CLI & REPL Mode, RAG, AI Tools & Agents, and More.

It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Loki in as little time as possible.

Agent example

Coming from AIChat? Follow the migration guide to get started.

Quick Links

  • AIChat Migration Guide: Coming from AIChat? Follow the migration guide to get started.
  • Installation: Install Loki
  • Getting Started: Get started with Loki by doing first-run setup steps.
  • REPL: Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
  • Vault: Securely store and manage sensitive information such as API keys and credentials.
  • Shell Integrations: Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
  • Function Calling: Leverage function calling capabilities to extend Loki's functionality with custom tools
  • First-Class MCP Server Support: Easily connect and interact with MCP servers for advanced functionality.
  • Macros: Automate repetitive tasks and workflows with Loki "scripts" (macros).
  • RAG: Retrieval-Augmented Generation for enhanced information retrieval and generation.
  • Sessions: Manage and persist conversational contexts and settings across multiple interactions.
  • Roles: Customize model behavior for specific tasks or domains.
  • Agents: Leverage AI agents to perform complex tasks and workflows.
  • Environment Variables: Override and customize your Loki configuration at runtime with environment variables.
  • Client Configurations: Configuration instructions for various LLM providers.
  • Custom Themes: Change the look and feel of Loki to your preferences with custom themes.
  • History: A history of how Loki came to be.

Prerequisites

Loki requires the following tools to be installed on your system:

  • jq
    • brew install jq
  • jira (optional) (For the jira-helper agent)
    • brew tap ankitpokhrel/jira-cli && brew install jira-cli
    • You'll need to create a JIRA API token for authentication
    • Then, save it as an environment variable to your shell profile: 
      # ~/.bashrc or ~/.zshrc
export JIRA_API_TOKEN="your_jira_api_token_here"
    • Then run jira init, select installation type as cloud, and provide the required details to generate a config file for the Jira CLI.
  • usql (For the sql agent)
    • brew install xo/xo/usql
  • docker
  • uv
    • curl -LsSf https://astral.sh/uv/install.sh | sh

These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation, interaction with Jira, and they are used within agents and tools.

Install

Cargo

If you have Cargo installed, then you can install loki from Crates.io:

cargo install loki-ai # Binary name is `loki`

# If you encounter issues installing, try installing with '--locked'
cargo install --locked loki-ai

Homebrew (Mac/Linux)

To install Loki from Homebrew, install the loki tap. Then you'll be able to install loki:

brew tap Dark-Alex-17/loki
brew install loki

# If you need to be more specific, use:
brew install Dark-Alex-17/loki/loki

To upgrade loki using Homebrew:

brew upgrade loki

Scripts

Linux/MacOS (bash)

You can use the following command to run a bash script that downloads and installs the latest version of loki for your OS (Linux/MacOS) and architecture (x86_64/arm64):

curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/loki/main/install_loki.sh | bash

Windows/Linux/MacOS (PowerShell)

You can use the following command to run a PowerShell script that downloads and installs the latest version of loki for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64):

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/loki/main/scripts/install_loki.ps1 | iex"

Manual

Binaries are available on the releases page for the following platforms:

Platform Architecture(s)
macOS x86_64, arm64
Linux GNU/MUSL x86_64, aarch64
Windows x86_64, aarch64

Windows Instructions

To use a binary from the releases page on Windows, do the following:

  1. Download the latest binary for your OS.
  2. Use 7-Zip or TarTool to unpack the Tar file.
  3. Run the executable loki.exe!

Linux/MacOS Instructions

To use a binary from the releases page on Linux/MacOS, do the following:

  1. Download the latest binary for your OS.
  2. cd to the directory where you downloaded the binary.
  3. Extract the binary with tar -C /usr/local/bin -xzf loki-<arch>.tar.gz (Note: This may require sudo)
  4. Now you can run loki!

Getting Started

After installation, you can generate the configuration files and directories by simply running:

loki --info

Then, you need to set up the Loki vault by creating a vault password file. Loki will do this for you automatically and guide you through the process when you first attempt to access the vault. So, to get started, you can run:

loki --list-secrets

Tab-Completions

You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:

# Bash
# (add to: `~/.bashrc`)
source <(COMPLETE=bash loki) 

# Zsh
# (add to: `~/.zshrc`)
source <(COMPLETE=zsh loki)

# Fish
# (add to: `~/.config/fish/config.fish`)
source <(COMPLETE=fish loki | psub)

# Elvish
# (add to: `~/.elvish/rc.elv`)
eval (E:COMPLETE=elvish loki | slurp)

# PowerShell
# (add to: `$PROFILE`)
$env:COMPLETE = "powershell"
loki | Out-String | Invoke-Expression

Shell Integration

You can integrate Loki's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the corresponding shell integration script to your shell. Then, you can invoke Loki to convert natural language to shell commands by pressing Alt-e. For example:

$ find all markdown files<Alt-e>
# Will be converted to:
find . -name "*.md"

Configuration

The location of the global Loki configuration varies between systems, so you can use the following command to find your config.yaml file:

loki --info | grep 'config_file' | awk '{print $2}'

The configuration file consists of a number of settings. To see a full example configuration file with every setting defined, refer to the example configuration file.

Default LLM

The following settings are available to configure the default LLM that is used when you start Loki, and its hyperparameters:

Setting Description
model The default LLM to use when no model is provided
temperature The default temperature parameter for all models (0,1); Used unless explicitly overridden
top_p The default top_p hyperparameter value to use for all models, with a range of (0,1) (or (0,2) for some models);
Used unless explicitly overridden

CLI Behavior

You can use the following settings to modify the behavior of Loki:

Setting Default Value Description
stream true Controls whether to use stream-style APIs when querying for completions from LLM providers
save true Controls whether to save each query/response to every model to messages.md for posterity; Useful for debugging
keybindings emacs Specifies which keybinding schema to use; can either be emacs or vi
editor null What text editor Loki should use to edit the input buffer or session (e.g. vim, emacs, nano, hx);
Defaults to $EDITOR
wrap no Controls whether text is wrapped (can be no, auto, or some <max_width>
wrap_code false Enables or disables the wrapping of code blocks

Preludes

Preludes let you define the default behavior for the different operating modes of Loki. The available settings are shown below:

Setting Description
repl_prelude This setting lets you specify a default session or role to use when starting Loki in REPL mode.
Values can be
  • role:<name> to define a role
  • session:<name> to define a session
  • <session>:<role> to define both a session and a role to use
cmd_prelude This setting lets you specify a default session or role to use when running one-off queries in Loki via the CLI.
Values can be
  • role:<name> to define a role
  • session:<name> to define a session
  • <session>:<role> to define both a session and a role to use
agent_session This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. temp, default)

Appearance

The appearance of Loki can be modified using the following settings:

Setting Default Value Description
highlight true This setting enables or disables syntax highlighting
light_theme false This setting toggles light mode in Loki

Miscellaneous Settings

Setting Default Value Description
user_agent null The name of the User-Agent that should be passed in the User-Agent header on all requests to model providers
save_shell_history true Enables or disables REPL command history

History

Loki originally started as a fork of the fantastic AIChat CLI. The purpose was to simply fix a bug in how MCP servers worked with AIChat so that I could specify different ones for agents. However, it has since evolved far beyond that and become a passion project with a life of its own!

Loki now has first class MCP server support (with support for local and remote servers alike), a built-in vault for interpolating secrets in configuration files, built-in agents, built-in macros, dynamic tab completions, integrated custom functions (no argc dependency), improved documentation, and much more with many more plans for the future!

The original kudos goes out to all the developers of the wonderful AIChat project!

Creator

Commit count: 0

cargo fmt