# GGUF Editor

GGUF Editor is a terminal user interface for inspecting and editing the metadata
stored in GGUF model files. It reads the GGUF header, metadata records and tensor
directory, then lets you change scalar metadata values without loading the model
tensors into memory.

The tool is intended for small, deliberate metadata changes on existing GGUF
files. When you save, it writes a new file named `modified_<original-name>` next
to the source file and streams the original tensor data into the output file.

## What it does

- Opens GGUF v2 and v3 files.
- Shows metadata keys, value types and display values in a keyboard-driven table.
- Shows the GGUF version, tensor count and source file size.
- Edits scalar metadata values such as strings, booleans, integers and floats.
- Adds new scalar metadata keys.
- Deletes metadata keys.
- Preserves tensor data by copying it from the original file instead of reading
  it all into memory.

Array metadata values are displayed but cannot currently be edited directly.

## Installation

You need Go installed.

```sh
go install github.com/andydixon/gguf-editor@latest
```

For local development from this repository:

```sh
go build .
```

## Usage

```sh
gguf-editor path/to/model.gguf
```

If you built it locally:

```sh
./gguf-editor path/to/model.gguf
```

Inside the interface:

- `e` or `Enter` edits the selected scalar value.
- `a` adds a new scalar metadata key.
- `d` deletes the selected key.
- `s` saves to `modified_<original-name>`.
- `q` quits.
- `Esc` cancels the current edit, add or confirmation dialogue.

Saving never overwrites the input file. For example, opening `model.gguf` and
pressing `s` writes `modified_model.gguf` in the same directory.

## Implementation notes

The GGUF parser in `gguf.go` reads the magic value, version, tensor count,
metadata count, metadata key-value pairs and tensor descriptors using
little-endian binary reads. Tensor payload data is left on disk until save time.

The terminal interface in `main.go` is built with Charmbracelet Bubble Tea,
Bubbles and Lip Gloss. It keeps a dirty flag for unsaved changes and rebuilds the
metadata table after edits, additions and deletions.

## Licence

This project is licensed under the GNU General Public License version 3. See
`LICENSE` for the full licence text.