Metadata-Version: 2.4
Name: aicheat
Version: 0.7.0
Summary: A command line AI coding assistant
Author-email: brethil <bretello@distruzione.org>
License: GPLv3
Keywords: ai,cli,coding-assistant,llm,developer-tools,openai
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pygments>=2.16.0
Requires-Dist: tomlkit>=0.14.0
Requires-Dist: pygit2>=1.19.1
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: ruff>=0.15.4; extra == "dev"
Requires-Dist: typing-extensions>=4.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"

# aicheat

A command-line based AI coding assistant

[![demo](https://git.decapod.one/brethil/aicheat/raw/tag/v0.4.0.post2/aicheat-demo.mp4)](https://asciinema.org/a/1vcAJJKvLWtSu6Ni)

## Features

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

## Requirements

- Python 3.8+
- An OpenAI-compatible API server (like vLLM or llama.cpp)
- [`ripgrep`](https://github.com/BurntSushi/ripgrep) (optional, for improved search functionality)
- `cht.sh` CLI tool (optional, for [cheat.sh](https://cheat.sh) functionality)

## Quick Start

### Installation

```bash
# Install a stable version
uv pip install aicheat

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

# Install the latest dev (unstable)
uv pip 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](https://github.com/vllm-project/vllm), or [llama.cpp](https://github.com/ggerganov/llama.cpp), see instructions in [docs](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

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

#### Provider Documentation

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

- [OpenAI API](docs/providers/openai.md)
- [vLLM](docs/providers/vllm.md)
- [llama.cpp](docs/providers/llamacpp.md)

### Usage

```bash
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

```bash
# 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:

```bash
aicheat --help
```

#### In-Chat Commands

Once in the chat, you can use these commands:

- `/help` - List available commands
- `/tools` - List available tools
- `/clear` - Clear the conversation history (or hit ctrl-c twice)
- `/multiline` - Toggle multiline input mode, also see Editor/Multiline section below
- `/model` - Show/set the active model
- `/fragment <file> [prompt]` - Include a file in the session with optional instructions
- `/config` - Show/save configuration, including token usage display settings

#### Tools

aicheat comes with several built-in tools

##### File Operations

- `read_file(filename)` - Read the content of a file
- `write_file(filename, content)` - Write content to a file
- `apply_patch(filename, content)` - Patch a file
- `search(pattern, path)` - Search for patterns in files using ripgrep

##### System & Shell

- `execute_shell_command(cmd)` - Execute shell commands (with confirmation)
- `man(program_name)` - Retrieve man pages for programs
- `pwd()` - Get current working directory
- `cd(path)` - Change directory

##### Git Integration

- `git_status()` - Show git status as a diff
- `git_updates(from_refish)` - Show commits since last tag/release
- `git_show_patch(commit_id)` - Show patch for a specific commit
- `git_list_files()` - List all git-tracked files

##### Code Execution

- `execute_python_code(code)` - Execute Python code snippets (with confirmation)

##### Web & Documentation

- `cheat_sh_search(program_name)` - Search cheat.sh for program documentation

##### Other tools

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:

```console
$ 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:

```console
$ 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/`](./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](./AGENTS.md)

### Adding custom tools

You can extend aicheat with custom tools by creating new modules in `src/aicheat/tools/`.

Here's an example for a `ping` tool to check network status:

```python
from aicheat.tools.core import tool
from subprocess import check_output, CalledProcessError, STDOUT
import re


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

    try:
        result = check_output(
            ["ping", "-c", str(count), host],
            text=True,
            stderr=STDOUT,  # redirect stderr to stdout
        )
    except CalledProcessError as exc:
        result = f"ping failed with returncode={exc.returncode}\noutput:\n{exc.stdout}"

    return result
```

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

### Token Usage Display

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

```
ctx: 50/1664/262144 (0.63%) ❯
```

Where:

- `50` = completion tokens (last response)
- `1664` = total tokens (cumulative)
- `262144` = max model context length
- `0.63%` = percentage of context used

Toggle token usage display with `ctrl-T or use `/config`:

```bash
/config show_tokens no          # Disable (default)
/config show_tokens percentage  # Show: "968 (0.36%) ❯"
/config show_tokens verbose     # Show: "ctx: 50/1664/262144 (0.63%) ❯"
/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:

```bash
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.
