# Ollama setup for Uncommit the Dead

Ollama runs downloaded AI models on your computer. Uncommit the Dead sends repository evidence to Ollama at `http://127.0.0.1:11434`, then turns the response into a resurrection plan, salvage plan, or farewell document.

Use a downloaded, local open-weight model. You do not need an API key or cloud account for local inference. Model weights have their own licences; review the model's terms. Avoid cloud model tags (such as `:cloud`) if you want repository evidence to stay on your machine.

## 1. Install and start Ollama

Download the installer for **macOS, Windows, or Linux** from [ollama.com/download](https://ollama.com/download) and follow the platform instructions.

- **macOS / Windows:** open the Ollama application after installation.
- **Linux / terminal setup:** start the server if it is not already running with `ollama serve`. Keep that terminal open while using the app.

Open Terminal (macOS/Linux) or PowerShell (Windows) and verify the CLI:

```sh
ollama --version
```

If the command cannot be found, reopen your terminal after installing. If `ollama serve` says the address is already in use, Ollama may already be running; check the connection before starting another instance.

## 2. Download a model

Start with Gemma 3 4B for this app:

```sh
ollama pull gemma3:4b
```

Wait for the download to finish. It needs internet and free disk space. You can run these commands from any folder, not just the project folder.

| Model | Approximate download | Use here |
| --- | --- | --- |
| `gemma3:1b` | 806 MB | A small setup check; responses can be generic or incomplete. |
| `gemma3:4b` | 3.4 GB | Suggested starting point for repository plans. |
| `gemma3:12b` | 8.2 GB | Optional larger model if your hardware can run it comfortably. |

These are listed download sizes, not RAM requirements. Runtime memory also includes context and overhead; speed depends on your CPU/GPU, available memory, and model settings. Larger is not automatically better for every repository. Model tags and sizes can change; check the [official Gemma library](https://ollama.com/library/gemma3).

To download the smaller option instead:

```sh
ollama pull gemma3:1b
```

Confirm the exact installed name:

```sh
ollama ls
```

Other local instruction/chat models that support structured JSON output can be selected too. Embedding-only models cannot generate a plan.

## 3. Try the model in your terminal

```sh
ollama run gemma3:4b "Suggest one tiny feature for an unfinished todo app."
```

You should see a text response. The first request may take longer while weights load. For an interactive chat, use `ollama run gemma3:4b` without a prompt; enter `/bye` to leave the chat.

Test the local API in a browser by opening:

http://127.0.0.1:11434/api/tags

A working server returns JSON with a `models` array. An empty array means no models are installed in that Ollama instance.

## 4. Use the model in Uncommit the Dead

1. Start this project with `npm install` followed by `npm run dev`.
2. Open the local URL printed in your terminal (usually `http://127.0.0.1:3000`; the current development preview uses port `3007`).
3. Go to **Graveyard → Connect local AI** (or **Local AI connected**).
4. Click **Check connection** after each new model download.
5. Choose the exact installed model, such as `gemma3:4b`, from the dropdown.
6. Use **Add a repository** and choose a Git repository containing at least one commit, or select a labelled sample.
7. Choose **One last commit**, **Donate its organs**, or **Rest in peace**, then click **Summon its last wish**.
8. Review the plan and its evidence. Download the Markdown if useful.

Generated plans are suggestions. The app does not edit files, execute commands, or verify completion. Inference is local when you select a local model. Once the app dependencies and model weights are installed, no cloud inference is needed.

## 5. Manage models

```sh
# See downloaded models
ollama ls

# See models currently loaded
ollama ps

# Unload a model from memory, keeping its download
ollama stop gemma3:4b

# Delete this model's local installation; pull it again to reinstall
ollama rm gemma3:4b
```

## Troubleshooting

### Ollama is offline / connection refused
Open the Ollama application or run `ollama serve`, then choose **Check connection**. This app expects Ollama on the same computer at port `11434`; remote endpoints are not configurable in this version.

### Connected, but the model list is empty
Run `ollama pull gemma3:4b`, wait for completion, confirm it with `ollama ls`, then refresh the connection. Make sure your terminal and app are using the same local Ollama instance.

### Model unavailable / model not found
Use the exact name shown by `ollama ls`, including its size tag. Refresh the connection after downloading or removing models.

### The response is slow or the app times out
The app allows up to two minutes for a generation request. Try a smaller model, close memory-heavy applications, or unload an unused model with `ollama stop MODEL_NAME`. A small model may be faster but less useful. A timeout does not prove that the repository is invalid.

### The model missed part of the plan / could not cite evidence
Try once more, or choose a more capable local instruction model. The app requires structured fields and evidence references matching the repository; not every model produces them reliably. More informative README and TODO notes can help. Do not enter secrets to improve context.

### The chosen folder will not import
Choose a Git repository with at least one commit. Plain source folders are not Git repositories. The picker can resolve a subfolder to its repository root. Check that your account has permission to read the folder.

## Official references

- [Ollama quickstart](https://docs.ollama.com/quickstart)
- [Ollama CLI reference](https://docs.ollama.com/cli)
- [Local model-list API](https://docs.ollama.com/api/tags)
- [Gemma 3 model library](https://ollama.com/library/gemma3)

Commands and model listings checked on October 28, 2026.