aicheat

A command-line based AI coding assistant

Features

• Supports OpenAI-compatible inference servers (such as vLLM/llama.cpp/OpenAI, ...)
• Powerful line editing/completion capabilities: powered by prompt-toolkit
• Theming support using pygments
• Extensibility via custom tool definitions
• Skills support

Requirements

• An OpenAI-compatible API server (like vLLM or llama.cpp)
• ripgrep (optional, for improved search functionality)
• cht.sh CLI tool (optional, for cheat.sh functionality)

Quick Start

Installation

# Install a stable version
uv tool install aicheat

# Install the latest main
uv tool install git+https://git.decapod.one/brethil/aicheat@main

# Install the latest dev (unstable)
uv tool install git+https://git.decapod.one/brethil/aicheat@dev

# Clone and install (development)
git clone https://git.decapod.one/brethil/aicheat
uv pip install -e ".[dev]"

Configuration requires an OpenAI API key or an a OpenAI-compatible server. These can be configured via environment variables or command-line arguments.

Environment Variables

• AICHEAT_HOST: path to an OpenAI-compatible server, such as vllm, or llama.cpp, see instructions in docs
• OPENAI_API_KEY: (optional) set if API Key is required to connect to AICHEAT_HOST
• AICHEAT_MODEL: (optional) set default model. If a single model is available on AICHEAT_HOST, it is automatically selected. If multiple models are available, user is prompted to select the model.

Note: this should also work with the official OpenAI API, although this is untested.

Command-Line Flags

aicheat [--host <host or endpoint url>] [--api-key <api key>]

Provider Documentation

See docs/providers/ for detailed instructions on using aicheat with different OpenAI-compatible API providers:

• OpenAI API
• vLLM
• llama.cpp

Usage

aicheat --help
# to start chatting:
aicheat
# optionally, a starting message can be provided:

aicheat "What's the current status of this git repo?"

In the aicheat "REPL":

• Type /help for available commands
• Type /tools to see available tools
• Use /theme list to list/select available themes, using /config save to persist the theme choice.
• Prefix messages with ! to run a shell command, e.g. !uptime calls uptime.
• Type a question to start chatting

Additional command-line flags

# Skip confirmation prompts for tool calls (YOLO mode)
aicheat --no-confirm "Fix this bug"

# Skip loading AGENTS.md and memory.md files
aicheat --no-agent-files --no-memory "Explain this code"
# Always load AGENTS.md and memory.md files
aicheat --agent-files --memory "Explain this code"

# Disable all tools
aicheat --no-tools

# Start a session in incognito mode (no persistence)
aicheat --no-confirm --no-agent-files --no-memory

For a complete list of flags, use:

aicheat --help

In-Chat Commands

Once in the chat, you can use these commands:

• /help - List available commands
• /tools - List available tools
• /session - Manage sessions (list, resume, delete, rename, summarize)
• /skill - Manage skills (list, load, unload, enable, disable)
• /model - Show/set the active model
• /config - Show/save configuration
• /yolo - Toggle YOLO mode (skip tool call confirmations)
• /reasoning - Toggle reasoning display and effort level
• /messages - Show conversation messages
• /fragment <file> [prompt] - Include a file in the session with optional instructions

Use /help for the full list of commands.

Tools

aicheat comes with several built-in tools:

• File operations: read, write, and patch files, search file contents
• Shell: execute shell commands, navigate directories, retrieve man pages
• Git: view status, commits, patches, and tracked files (automatically enabled in git repos)
• Python: execute Python code snippets
• Web: search cheat.sh for command cheat sheets, search Wikipedia (disabled by default)
• Tmux: manage tmux sessions and panes, can be used to orchestrate aicheat agents, see the tmux-aicheat skill

Use the /tools in-chat command to get an up-to-date list of tools with descriptions.

Restoring sessions

Sessions are automatically saved to ~/.local/share/aicheat/sessions.db and can be resumed:

$ aicheat
❯ Hello
➜ Hello! 👋
❯ /session
Session: wonderful-babbage
ID: d82b17fa-7e2b-4fb0-ab5e-553b5e9ae6bc
Messages: 2
Created: 2026-05-26 18:53
Updated: 2026-05-26 18:53

After exiting, the session can be resumed after starting aicheat using /session resume, or from the cli:

$ aicheat --resume wonderful-babbage

/session list can be used to list saved sessions:

❯ /session list
                                                Recent sessions
┏━━━┳━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃   ┃    ┃ session name               ┃ session id ┃ msg count ┃ date             ┃ description                ┃
┡━━━╇━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│   │  1 │ wonderful-babbage          │ d82b17fa   │ 2         │ 2026-05-26 18:53 │                            │
│   │  2 │ secret-session             │ a57c98ec   │ 81        │ 2026-05-26 18:52 │ Implementing a secret      │
│   │    │                            │            │           │                  │ feature for aicheat        │
│   │  3 │ determined-borg            │ 5cbe97c2   │ 48        │ 2026-05-26 15:42 │                            │
└───┴────┴────────────────────────────┴────────────┴───────────┴──────────────────┴────────────────────────────┘

The /session command can be used to set custom names, descriptions, create a descriptions using an LLM summary of the conversation and more.

See /help session for a full list of commands

Skills

Load skills using /skill load path/to/skill to extend aicheat's functionality with custom workflows and interaction patterns.

See ./skills/ for skills examples.

Hacking

An aicheat skill is available in ./skills/aicheat and can be loaded via /skill load ./skills/aicheat. This can help out with development, as well as loading AGENTS.md

Adding custom tools

You can extend aicheat with custom tools by creating new modules in src/aicheat/tools/. For simple function-based tools, use the @tool decorator. For tools requiring lifecycle hooks (on_success, on_error, on_first_output) or access to the Conversation instance, subclass ToolBase.

Simple tool using @tool:

from aicheat.tools.core import tool


@tool(
    message_template="🌐 Pinging {host} {count} times",
    requires_confirmation=False,
)
def ping(host: str, count: int) -> str:
    """Ping a host using the unix `ping` tool"""
    if not host:
        return "No host provided"

    from subprocess import check_output, CalledProcessError, STDOUT
    result = check_output(["ping", "-c", str(count), host], text=True, stderr=STDOUT)
    return result

Advanced tool using ToolBase (for lifecycle hooks, streaming output, etc.):

from aicheat.tools.core import ToolBase

class Ping(ToolBase):
    """Ping a host using the unix `ping` tool"""

    name = "ping"
    requires_confirmation = False
    message_template = "🌐 Pinging {host} {count} times"

    def execute(self, host: str, count: int) -> str:
        from subprocess import check_output, STDOUT
        return check_output(["ping", "-c", str(count), host], text=True, stderr=STDOUT)

Note: @tool() must always be called with parentheses.

For more examples, see:

• aicheat.tools.shell - Shell-related tools
• aicheat.tools.git - Git-related tools
• aicheat.tools.code.python - Python-related code tools

Tips & Tricks

• Hit ctrl-c twice to clear the conversation history. Use ctrl-l to clear the screen without clearing the conversation, then /messages -1 to display the last message again.
• Prefix a message with ! to run a shell command. Anything after # is treated as a shell comment and included in the output, so you can add instructions for the model: ! ls -la # list files and explain what this project does
• Commands like /fragment <file> [prompt], /cd <dir> [prompt], and /cwd [prompt] accept an optional prompt that is sent to the model along with the command output.

Token Usage Display

aicheat can display token usage information in the prompt, showing the current conversation's token consumption:

119.4k (22.77%) ❯

Where:

• 119.4k = total tokens used
• 22.77% = percentage of context used

Cycle token usage display with ctrl-t or use /config:

/config show_tokens no          # Disable (default)
/config show_tokens percentage  # Show: "968 (0.36%) ❯"
/config show_tokens verbose     # Show: "ctx: 301/119.9k/524.3k (22.87%) ❯"
/config save                     # Persist configuration

Token counts are per-conversation and reset when the conversation is cleared.

Shell Integration

Add an alias to aicheat so that it's prefixed by noglob, making it easier to give initial prompts from the shell without expanding globs:

echo "alias aicheat=\"noglob aicheat\"" >> ~/.zshrc

Editor/Multiline

The REPL uses prompt-toolkit to leverage its powerful line-editing capabilities. aicheat, depending on your $EDITOR value supports:

• emacs-style line-editing shortcuts:
  • use ctrl-x ctrl-e to open the current line in your $EDITOR)
  • ctrl-a/ctrl-e to move to beginning/end of the current line and other emacs-style movements
• vi-style line-editing shortcuts:
  • vv to open the current line in your $EDITOR
  • modal editing and other vi-style movement shortcuts

Multiline editing is also supported, either via /multiline or via ctrl-v. This can be useful to paste text/code.