docs(prd): add PRD 0049 — named/labelled agents

Draft PRD for prompting operators for a custom label and optional
ANSI color at agent launch time, storing both in metadata.json, and
surfacing the label (in color) in the dashboard's active-agents pane.

Closes #171

docs/prds/0049-named-labelled-agents.md

@@ -0,0 +1,283 @@
+# PRD 0049: Named / Labelled Agents
+
+- **Status:** Draft
+- **Author:** didericis
+- **Created:** 2026-06-03
+- **Issue:** #171
+
+## Summary
+
+At agent launch time, prompt the operator for a short human-readable label
+(defaulting to the manifest agent key) and an optional color from the 16-color
+ANSI palette. Store both in the bottle's `metadata.json`. Display the label —
+rendered in the chosen color — in the dashboard's active-agents pane, replacing
+the bare manifest key. Inject the label and color into the in-container
+`claude.json` as `name` / `color` so Claude Code can surface them in its own
+harness when upstream support lands.
+
+## Problem
+
+The dashboard's agents pane identifies each running instance by its manifest
+agent key (e.g., `implementer`) plus a random slug suffix. When an operator
+runs three `implementer` bottles simultaneously — one each for three different
+repos — the pane shows:
+
+```
+  [docker] a3f9  implementer  started 14:02:11  [egress,pipelock]
+  [docker] b81c  implementer  started 14:03:45  [egress,pipelock]
+  [docker] d220  implementer  started 14:05:01  [egress,pipelock]
+```
+
+There is no way to tell which bottle is working on which task without attaching
+to each one in turn. The slug is opaque; the manifest key is shared. Operators
+working a multi-bottle session resort to keeping a mental map of slug→task,
+which breaks the moment they switch windows.
+
+## Goals / Success Criteria
+
+1. After the operator selects an agent name (dashboard picker or CLI argument),
+   they are prompted for a label. The prompt suggests the manifest key as the
+   default; pressing Enter (or providing no input) accepts it. The label may
+   contain any printable characters up to 64 bytes.
+2. After the label prompt, the operator is optionally prompted for a color from
+   the 16-color ANSI palette (names: `black`, `red`, `green`, `yellow`, `blue`,
+   `magenta`, `cyan`, `white`, `bright-black`, `bright-red`, `bright-green`,
+   `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`,
+   `bright-white`). Pressing Enter without a selection skips color entirely.
+3. `label` and `color` are stored in `BottleMetadata` and written to the
+   bottle's `metadata.json`. Both fields default to `""` (empty / unset).
+4. `ActiveAgent` carries `label` and `color`; `enumerate_active()` reads them
+   from `metadata.json`.
+5. `_format_agent_row` uses the label when non-empty (falling back to
+   `agent_name`). If a non-empty color is set and the terminal supports it, the
+   label substring is rendered in that color.
+6. `BottleSpec` carries `label` and `color`; the docker backend's `prepare`
+   step copies them into `BottleMetadata`.
+7. `agent_provider.py` writes `label` → `"name"` and `color` → `"color"` into
+   the generated `claude.json`, alongside the existing fields. Fields are
+   omitted when empty.
+8. The dashboard's `_new_agent_flow` (PRD 0020) includes the label+color step
+   between agent selection and the backend picker.
+9. `cmd_start` (CLI) includes the label+color step after argument validation
+   and before prepare-with-preflight.
+10. All existing unit tests stay green; no new tests are required for this
+    change (the label/color fields are thin plumbing with no branching logic
+    worth unit-testing beyond the already-tested metadata read/write path).
+
+## Non-goals
+
+- Showing the agent label inside the Claude Code TUI (status line, terminal
+  title, custom header). That requires upstream Claude Code / codex support.
+  Writing to `claude.json` is best-effort scaffolding for when that lands.
+- Per-bottle color affecting anything outside the dashboard agents pane (e.g.,
+  proposal-pane highlights, log prefixes).
+- Validating or constraining label content beyond the 64-byte printable cap.
+- Persisting color-pair state across dashboard restarts (color pairs are
+  initialized fresh each session).
+- Editing the label or color of an already-running bottle.
+- Exposing label/color via `./cli.py list` (out of scope for v1; trivial to
+  add later since the field will be in metadata).
+
+## Design
+
+### Data flow
+
+```
+operator input
+     │
+     ▼
+BottleSpec.label, BottleSpec.color
+     │
+     ├─► docker/prepare.py → BottleMetadata.label / .color → metadata.json
+     │
+     └─► agent_provider.py → claude.json {"name": label, "color": color}
+                                              (omitted when empty)
+
+dashboard refresh
+     │
+     ▼
+enumerate_active() → read_metadata(slug) → ActiveAgent.label / .color
+     │
+     ▼
+_format_agent_row → label (colored) in the row string
+```
+
+### BottleSpec changes
+
+```python
+@dataclass(frozen=True)
+class BottleSpec:
+    manifest: Manifest
+    agent_name: str
+    copy_cwd: bool
+    user_cwd: str
+    identity: str = ""
+    label: str = ""   # operator-chosen display name; defaults to agent_name at render time
+    color: str = ""   # one of the 16 ANSI color names, or "" for terminal default
+```
+
+`label` and `color` default to `""` so all existing callers remain valid with
+no changes.
+
+### BottleMetadata changes
+
+Add two new fields with backward-compatible defaults:
+
+```python
+@dataclass
+class BottleMetadata:
+    identity: str
+    agent_name: str
+    cwd: str
+    copy_cwd: bool
+    started_at: str
+    compose_project: str
+    backend: str
+    label: str = ""
+    color: str = ""
+```
+
+`metadata.json` written by older bot-bottle versions won't have these keys;
+`read_metadata` already uses `dict.get` with defaults, so existing slugs load
+cleanly with `label=""`, `color=""`.
+
+### ActiveAgent changes
+
+```python
+@dataclass(frozen=True)
+class ActiveAgent:
+    backend_name: str
+    slug: str
+    agent_name: str
+    started_at: str
+    services: tuple[str, ...]
+    label: str = ""
+    color: str = ""
+```
+
+`enumerate_active()` copies `label` and `color` out of `BottleMetadata` when
+constructing each `ActiveAgent`. The smolmachines backend gets the same
+additions for symmetry; it reads from its own metadata path.
+
+### Dashboard row rendering
+
+`_format_agent_row` already falls through cleanly on missing fields. The
+change is:
+
+```python
+display_name = a.label if a.label else a.agent_name
+```
+
+Color rendering uses the existing `_try_init_green()` pattern as a model.
+A `_color_pair_for(color_name)` helper initialises a fresh curses color pair
+for the requested named color and returns its attr (or 0 on failure). Each
+unique color in the active agent list gets its own pair index. Color pairs are
+allocated lazily and cached in a `dict[str, int]` that lives for the duration
+of the dashboard session.
+
+The 16 ANSI color name → curses constant mapping:
+
+| Name | curses constant |
+|------|----------------|
+| `black` | `curses.COLOR_BLACK` |
+| `red` | `curses.COLOR_RED` |
+| `green` | `curses.COLOR_GREEN` |
+| `yellow` | `curses.COLOR_YELLOW` |
+| `blue` | `curses.COLOR_BLUE` |
+| `magenta` | `curses.COLOR_MAGENTA` |
+| `cyan` | `curses.COLOR_CYAN` |
+| `white` | `curses.COLOR_WHITE` |
+| `bright-*` | same constant + `curses.A_BOLD` |
+
+Terminals that don't support color fall back to plain text (the helper returns
+0, which ORed in is a no-op — same pattern as `_try_init_green`).
+
+### Label + color prompt — dashboard
+
+In `_new_agent_flow`, after `_picker_modal` returns a non-None name and before
+`_backend_picker_modal`:
+
+```python
+label, color = _label_color_modal(stdscr, default_label=picked)
+```
+
+`_label_color_modal` uses `curses.endwin()` → text-mode prompts → restore
+(the same drop-and-resume pattern as the existing editor flow and preflight
+Y/N). Two sequential prompts:
+
+```
+bot-bottle: agent label [implementer]: <operator types>
+bot-bottle: color (red/green/blue/… or Enter to skip): <operator types>
+```
+
+Invalid color names are silently ignored (treated as empty). The function
+returns `(label, color)` — both strings, both possibly `""`.
+
+### Label + color prompt — CLI
+
+In `cmd_start`, after argument parsing and before `_launch_bottle`:
+
+```python
+label = _text_prompt_label(args.name)
+color = _text_prompt_color()
+```
+
+`_text_prompt_label(default)` writes `"bot-bottle: agent label [{default}]: "`
+to stderr and returns the stripped input (or `default` if blank).
+`_text_prompt_color()` writes the color prompt and returns the stripped input
+(or `""` if blank or invalid).
+
+Both use `read_tty_line()` (already in `start.py`) for the read.
+
+### Claude Code config injection
+
+In `agent_provider.py`, where `claude_config.write_text(...)` is called,
+expand the JSON dict conditionally:
+
+```python
+payload = {
+    "hasCompletedOnboarding": True,
+    "theme": "dark",
+    "bypassPermissionsModeAccepted": True,
+    "projects": claude_projects,
+}
+if spec.label:
+    payload["name"] = spec.label
+if spec.color:
+    payload["color"] = spec.color
+claude_config.write_text(json.dumps(payload, indent=2) + "\n")
+```
+
+`spec` here is the `AgentProvisionSpec` (or equivalent) that `agent_provider`
+already receives; it needs `label` and `color` threaded in from `BottleSpec`
+through whatever plan/provision object the provider operates on.
+
+## Implementation chunks
+
+Two PRs, each independently mergeable.
+
+### Chunk 1 — schema + storage
+
+- Add `label: str = ""` and `color: str = ""` to `BottleSpec`,
+  `BottleMetadata`, and `ActiveAgent`.
+- `docker/prepare.py`: copy `spec.label` / `spec.color` into `BottleMetadata`.
+- `docker/enumerate.py`: copy `metadata.label` / `metadata.color` into
+  `ActiveAgent`.
+- `agent_provider.py` (or the plan object it reads): thread label/color through
+  to `claude.json` write.
+- Smolmachines backend: parallel changes to metadata read/write and
+  `ActiveAgent` construction.
+- No prompt changes; no UI changes. All existing behavior is identical.
+
+### Chunk 2 — prompts + display
+
+- `start.py`: add `_text_prompt_label` and `_text_prompt_color`; call them in
+  `cmd_start` before `_launch_bottle`; pass `label` / `color` into `BottleSpec`.
+- `dashboard.py`: add `_label_color_modal` (drop-and-resume); call it in
+  `_new_agent_flow`; pass label/color into `BottleSpec`; add
+  `_color_pair_for` helper; update `_format_agent_row` to use `a.label` with
+  color rendering.
+
+## Open questions
+
+None.

docs/research/gitea-webhook-agent-dispatch.md

@@ -0,0 +1,151 @@
+# Gitea Webhook Agent Dispatch
+
+## Question
+
+How should bot-bottle spawn and manage agents in response to Gitea PR events — and how do we reuse the same agent (with its full session context) across every event in a PR's lifecycle?
+
+## Summary
+
+A lightweight webhook receiver maps Gitea PR events to `cli.py` invocations. Spawning is straightforward: the existing work on non-interactive run mode (see [host-dispatch-to-container-agents.md](host-dispatch-to-container-agents.md)) is the missing piece. Session continuity is harder: it requires tracking two identifiers per open PR — the **bottle identity** (bot-bottle's slug for the container state dir) and the **Claude session ID** (the UUID Claude writes to its JSONL transcript). The transcript snapshot mechanism already used by capability-block is the right foundation; it just needs a non-interactive path and a PR-keyed store.
+
+## Gitea Webhook Events for PR Lifecycle
+
+Gitea fires `X-Gitea-Event: pull_request` (with an `action` field) for most PR state changes. The payload always includes `pull_request.number`, which is the stable key for correlating events to a running agent.
+
+| `X-Gitea-Event` value | Relevant `action` values | When it fires |
+|---|---|---|
+| `pull_request` | `opened`, `reopened`, `closed`, `synchronized` | PR created, closed, or pushed to |
+| `pull_request_comment` | `created`, `edited` | Timeline comment posted |
+| `pull_request_review_approved` | — | Review submitted with approval |
+| `pull_request_review_rejected` | — | Review submitted requesting changes |
+| `pull_request_review_comment` | — | Inline code review comment |
+| `pull_request_sync` | — | New commits pushed to the PR branch |
+
+`pull_request` with `action: synchronized` and `pull_request_sync` both fire on push; they carry the same information but are separate subscriptions in the webhook config UI. Subscribe to `pull_request` and `pull_request_review` (the umbrella) plus `pull_request_comment` to cover the full lifecycle.
+
+The webhook receiver validates the `X-Gitea-Signature-256` HMAC header (SHA-256 of the raw body, keyed by the configured secret) before dispatching.
+
+## Spawning an Agent From a Webhook
+
+### What we need from bot-bottle
+
+The current `cli.py start` is interactive — it prompts y/N and attaches a tty. A webhook handler needs a non-interactive mode that:
+
+1. Starts the container for a named agent.
+2. Runs `claude -p "<task>" --output-format json --dangerously-skip-permissions` inside it (no tty, no session picker).
+3. Captures stdout as JSON, extracts `session_id`.
+4. Blocks until Claude exits, then tears down.
+
+The [host-dispatch-to-container-agents](host-dispatch-to-container-agents.md) research proposes `cli.py run <agent> <task>` for exactly this. That command is the prerequisite for everything below. It should return the Claude JSON output so callers can extract `session_id`.
+
+### Webhook receiver sketch
+
+The receiver is a small HTTP service (Flask, FastAPI, or a Go net/http handler) running alongside bot-bottle on the host. It:
+
+1. Validates the HMAC signature.
+2. Extracts `pull_request.number` and `X-Gitea-Event` / `action`.
+3. Looks up whether a bottle already exists for this PR number.
+4. Spawns or resumes accordingly (see next section).
+5. Optionally posts a comment back to the PR via Gitea API once Claude finishes.
+
+The receiver does not need to be async or queue-based for a single-repo bot, but should at minimum serialize events for the same PR number (a per-PR lock) to avoid two concurrent sessions clobbering each other's transcript.
+
+## Reusing the Same Agent Across a PR
+
+This is the harder problem. Two separate identities need to be tracked and connected:
+
+### Identity 1: bottle identity (bot-bottle slug)
+
+The slug is the per-bottle state directory name (`~/.bot-bottle/state/<slug>/`). It's what `cli.py resume <slug>` uses to relaunch a container and mount the preserved state — including the transcript snapshot. This already works for the capability-block flow.
+
+### Identity 2: Claude session ID
+
+Claude Code's `--output-format json` response includes a `session_id` UUID. Passing `--resume <session_id>` on a subsequent non-interactive run makes Claude continue from exactly that conversation, with full memory of prior tool calls. `--continue` (which maps to `resume_args` in `agent_provider.py`) only picks up the *most recent* session in the project directory — unsafe when multiple sessions may be running concurrently.
+
+The session JSONL lives at `~/.claude/projects/<encoded-cwd>/<session_id>.jsonl` inside the container guest. The transcript snapshot (`snapshot_transcript(slug)` in `capability_apply.py`) copies all of `~/.claude` out of the container before teardown, so the JSONL is preserved in `~/.bot-bottle/state/<slug>/transcript/.claude/`. When the bottle is relaunched and the transcript remounted, `claude --resume <session_id>` can find the JSONL at the right path.
+
+### Per-PR session registry
+
+The receiver needs a small persistent map:
+
+```
+PR number → { bottle_identity: str, claude_session_id: str, agent_name: str }
+```
+
+The simplest implementation is a JSON file at `~/.bot-bottle/pr-sessions.json`, written after each successful first-run and updated with each resume. A sqlite database is better if concurrent multi-repo support is needed.
+
+### Full lifecycle flow
+
+```
+PR opened
+  → webhook: action=opened
+  → no entry in pr-sessions.json
+  → cli.py run <agent> "Review PR #N: <title>\n<diff URL>"
+      → starts container, runs claude -p ... --output-format json
+      → on success: captures session_id from JSON output
+      → snapshot_transcript(slug)
+      → tears down container
+  → write pr-sessions.json: { pr: N, slug: <slug>, session_id: <uuid> }
+
+PR gets new commit
+  → webhook: action=synchronized OR pull_request_sync
+  → look up pr-sessions.json: found slug + session_id
+  → cli.py run-resume <slug> --claude-session <session_id> "New commits pushed. Review the diff."
+      → relaunches container with transcript snapshot mounted
+      → runs claude -p ... --resume <session_id> --output-format json
+      → captures new session_id (same or rotated)
+      → snapshot_transcript(slug) again
+  → update pr-sessions.json with latest session_id
+
+Comment @-mentions bot
+  → webhook: pull_request_comment, action=created
+  → extract comment body, check for bot mention
+  → same resume flow as above with comment as the prompt
+
+PR closed / merged
+  → webhook: action=closed
+  → cli.py cleanup <slug> (or equivalent)
+  → remove from pr-sessions.json
+```
+
+### What needs to be built
+
+| Piece | Status | Notes |
+|---|---|---|
+| `cli.py run <agent> <task>` | Missing | Non-interactive start; see host-dispatch research |
+| `cli.py run-resume <slug> --claude-session <id> <task>` | Missing | Like `resume` but non-interactive, passes `--resume <id>` to claude |
+| `snapshot_transcript` on clean exit | Exists (PRD 0012) | Already called from `start.py`'s session-end path |
+| Transcript remount on resume | Exists | `bottle_state.py::transcript_snapshot_dir` → docker cp in on launch |
+| PR session registry | Missing | Needs to be designed; `~/.bot-bottle/pr-sessions.json` is the simplest start |
+| Webhook receiver service | Missing | New service; needs to be a declared bottle or run as a host process |
+
+## Known Rough Edges
+
+**Session ID is not available from within the session.** The ID is only in the `--output-format json` result, readable after the process exits. There is no env var or hook that exposes it mid-session ([upstream issue #44607](https://github.com/anthropics/claude-code/issues/44607)). For the webhook bot this is fine — the outer receiver reads it from the subprocess result.
+
+**`--continue` vs `--resume <id>`:** The existing `resume_args = ("--continue",)` in `agent_provider.py` picks up the *most recent* session. For an interactive single-user resume this is fine. For a webhook bot that may have multiple open PRs, it is not safe — two PRs' transcripts would collide if they share a project directory encoding. Use `--resume <session_id>` explicitly.
+
+**Project directory encoding.** Claude stores sessions keyed by the absolute cwd, encoded as a path. Inside the container the cwd is always `/home/node` or a subdir. As long as every run for the same PR uses the same cwd, `--resume <session_id>` will find the right JSONL. The cwd should be pinned per PR entry in the session registry.
+
+**Concurrent events for the same PR.** If two webhooks arrive close together (e.g., push + CI comment), the receiver must serialize them. A per-PR asyncio lock or a simple file lock on the session registry entry is enough.
+
+**Context window growth.** Each resume appends to the same session. A PR with many round trips will eventually hit the context limit. Mitigation options: start a fresh Claude session (new `cli.py run`) periodically and carry forward a summary; or rely on Claude's built-in compaction. The session registry could include a turn count to trigger rotation.
+
+**Webhook delivery ordering.** Gitea does not guarantee ordered delivery or exactly-once delivery. The receiver should be idempotent (same PR event processed twice should not create two bottles) and should ignore events for closed PRs.
+
+## Relationship to Existing Bot-Bottle Infrastructure
+
+The transcript snapshot + bottle identity system (PRD 0012, `capability_apply.py`) was designed for the capability-block flow: an operator-triggered resume after a security event. The webhook flow is the same mechanism on a faster loop driven by Gitea events instead of operator action. The implementation delta is:
+
+1. Non-interactive run mode (the `cli.py run` gap already identified in host-dispatch research).
+2. Passing `--resume <session_id>` explicitly rather than `--continue`.
+3. A PR-keyed registry to connect PR numbers to bottle identities and session IDs.
+4. A webhook receiver to drive the loop.
+
+These are additive changes that sit on top of the existing transcript preservation machinery without altering it.
+
+## Recommendation
+
+Start with the non-interactive run mode (`cli.py run`) since everything else depends on it. Once that exists, the webhook receiver and session registry are straightforward glue. The receiver should run as a host process (not inside a bottle) since it needs to call `cli.py` and manage the session registry file. Serialize per-PR to avoid concurrency bugs. Use `--resume <session_id>` (not `--continue`) for all resume paths.
+
+The PR session registry is deliberately minimal to start — a JSON file is fine. If multi-repo or multi-agent scenarios appear, migrating to sqlite is a one-file change.

docs/research/local-ollama-harness-and-model-selection.md

@@ -0,0 +1,278 @@
+# Local Ollama: Deployment Topology, Harness Selection, and Model Sizing
+
+Research notes on running Ollama locally for a bot-bottle coding agent workflow.
+Covers the native-vs-VM question, which harness integrates best with an agent loop,
+and which models make sense on an RTX 3070 (8 GB VRAM / 30 GB RAM) machine.
+
+---
+
+## 1. Deployment topology: native, container, or VM?
+
+The core question is whether running Ollama in a VM significantly degrades inference
+performance. The short answer: a full KVM/QEMU VM with GPU passthrough adds roughly
+2–5% overhead, Docker on Linux adds roughly 1–2%, and LXC containers add sub-1%. None
+of these are significant for interactive coding use.
+
+### Native (bare metal)
+
+Zero overhead, immediate GPU access, simplest setup. The right default for a solo
+developer doing inference on their own workstation.
+
+### Docker containers on Linux + NVIDIA
+
+With `nvidia-container-toolkit` and `--gpus all`, containerized Ollama runs at
+essentially native speed (~1–2% overhead on Linux). The dramatic exception is macOS,
+where Docker Desktop runs a Linux VM with no access to Apple's Metal/GPU — inference
+is 5–6× slower. On Linux/Windows with NVIDIA hardware, Docker is fine.
+
+Common pitfall: if `docker exec ollama ollama ps` shows 0 GPU layers, the container
+fell back to CPU. Usual causes: stale VRAM allocation, missing `nvidia-container-toolkit`,
+or a host driver too old for the container's CUDA version.
+
+### KVM/QEMU VM with full PCIe passthrough
+
+Full GPU passthrough makes the GPU invisible to the host while the VM owns it. Overhead
+from the IOMMU translation layer and virtualized PCIe bus is ~2–5%. This is viable if
+you need VM-level isolation (snapshotting, migration, separate kernel). Setup complexity
+is non-trivial: BIOS IOMMU, IOMMU group management, VFIO driver binding. Once configured
+it is stable.
+
+**Critical gotcha:** set the VM's CPU type to `host`. If left at the default
+(`x86-64-v2-AES` / "QEMU Virtual CPU version 2.5+"), Ollama may silently disable GPU
+support even when drivers appear correct.
+
+### LXC containers (Proxmox et al.)
+
+The sweet spot for isolation without overhead. Sub-1% performance difference from bare
+metal because LXC shares the host kernel; GPU device files are bind-mounted into the
+container. The tradeoff is weaker isolation (shared kernel) and the requirement that
+host and container driver versions match. Not suitable if you need VM-level snapshots
+or live migration.
+
+### Summary
+
+| Topology | GPU overhead | Isolation | Complexity |
+|---|---|---|---|
+| Native | 0% | None | Low |
+| Docker (Linux) | ~1–2% | Process | Low |
+| LXC | <1% | Namespace | Medium |
+| KVM passthrough | 2–5% | Full VM | High |
+| VM no passthrough | CPU-only | Full VM | Medium |
+
+Running Ollama in a VM will **not** significantly slow inference as long as GPU passthrough
+is configured. Without passthrough (software rendering / CPU fallback) performance
+collapses — that is what the user is rightly worried about.
+
+### Local vs. remote server
+
+| Factor | Local machine | Remote server |
+|---|---|---|
+| Latency | Near-zero | Network round-trip; cumulative in agent loops |
+| Cost | Zero after hardware | Per-token or subscription |
+| Privacy | 100% on-device | Data leaves the machine |
+| Model size ceiling | VRAM-limited | No hard limit (671B+ feasible) |
+| Offline use | Yes | No |
+| Concurrency under load | Sequential by default | Scales horizontally |
+
+For agentic coding workflows making 20–50 tool calls per session, network latency
+accumulates quickly. Local inference eliminates this. A practical hybrid pattern:
+use the local GPU for routine coding loops; route only to a remote API for tasks
+requiring a 70B+ model or very long context (>128K tokens).
+
+---
+
+## 2. Harness selection
+
+The landscape in 2026 has settled into three categories: IDE plugins, terminal agents,
+and chat UIs.
+
+### Continue.dev — recommended IDE plugin
+
+Open-source VS Code / JetBrains / Zed / Vim extension. Routes autocomplete, chat, and
+refactoring commands to any configured LLM backend (Ollama, cloud APIs). The recommended
+setup uses two models: a small FIM-capable model for inline autocomplete (Qwen2.5-Coder 7B)
+and a larger model for chat/edit. Handles inline completions, multi-file edits, and
+codebase-aware chat. No API key, no data leaving the machine.
+
+### Aider — recommended for git-native terminal workflows
+
+Terminal-based coding agent. Builds a codebase map before editing, makes changes
+directly, and auto-commits to git with readable messages. Every change is one
+`git revert` away. Supports 100+ languages; connects to any Ollama-served model
+via the OpenAI-compatible API. Best for terminal-first developers who want
+version-controlled agent interactions. Does not do inline autocomplete.
+
+### OpenCode — recommended for bot-bottle–style agent loops
+
+Terminal-based coding agent with 15 built-in tools (bash execution, file read/write/edit,
+grep, glob, web fetch, MCP support) and connections to 75+ model providers including
+local Ollama models. This is the closest open-source equivalent to a Claude Code–style
+plan → tool-call → execute → observe → loop. Native Ollama integration.
+
+**Critical setup note:** Ollama defaults to a 4096-token context window, which is
+completely insufficient for an agent loop carrying conversation history, tool schemas,
+a system prompt, and code simultaneously. Configure at least 64K tokens explicitly
+in the model's context settings.
+
+### Cline — agentic VS Code assistant
+
+VS Code extension that operates as an autonomous agent: plans, edits files, runs commands
+in a loop, connects to Ollama's local endpoint. Compared to OpenCode it lives inside the
+IDE rather than the terminal; compared to Continue.dev it is a full agent rather than a
+plugin. Its system prompt overhead is higher (~7,000–10,000 tokens) than minimal harnesses.
+
+### Open WebUI / Jan / LM Studio — chat UIs, not coding harnesses
+
+These are browser or desktop chat interfaces useful for ad-hoc conversations (explaining
+APIs, drafting documentation, exploring ideas) but without IDE integration, autocomplete,
+or git integration. LM Studio offers the smoothest onboarding (visual model browser with
+VRAM estimates). Jan is the most privacy-auditable (fully open-source, Apache 2.0, no
+telemetry). Neither is a replacement for a coding harness.
+
+### Harness comparison
+
+| Harness | Type | Autocomplete | Agent loop | Ollama | Git integration |
+|---|---|---|---|---|---|
+| Continue.dev | IDE plugin | Yes (FIM) | Basic | Native | No |
+| Aider | Terminal agent | No | Multi-turn | Via API | Auto-commit |
+| OpenCode | Terminal agent | No | Full tools | Native | Via bash |
+| Cline | IDE agent | No | Full tools | Via API | Via bash |
+| Open WebUI | Chat UI | No | No | Native | No |
+| Jan | Chat UI | No | No | Native | No |
+
+For a bot-bottle workflow (an isolated sandbox running an agentic loop with tool access),
+**OpenCode** is the closest open-source match. For an IDE-first developer who wants
+autocomplete + chat, **Continue.dev + Qwen2.5-Coder 7B** is the recommended pair.
+
+---
+
+## 3. Model selection: RTX 3070 (8 GB VRAM / 30 GB RAM)
+
+### VRAM hard limits at Q4_K_M quantization
+
+| Model size | Approx. VRAM (Q4_K_M) | Fits in 8 GB? | Tokens/sec (RTX 3070) |
+|---|---|---|---|
+| 3–4B | 2.5–3.5 GB | Yes, with headroom | 60–90 |
+| 7–8B | 5–6 GB | Yes | 35–55 |
+| 12–14B | 7.5–9 GB | Edge / RAM offload | 8–18 |
+| 22B+ | 14+ GB | No | — |
+
+The RTX 3070 has high memory bandwidth for its VRAM tier and consistently outperforms
+the newer RTX 4060 Ti on token generation speed. Bandwidth matters more than raw compute
+for inference.
+
+### Does Gemma 4 exist?
+
+Yes. Google released **Gemma 4** on 2 April 2026 (Apache 2.0). The family includes
+E2B (2B), E4B (4B), a 26B MoE, and a 31B Dense. A 12B multimodal variant was announced
+2026-06-04. The 31B scores 80.0% on LiveCodeBench v6 — a major jump from Gemma 3 27B
+at 29.1%. However, only the E4B fits comfortably within 8 GB VRAM:
+
+| Variant | VRAM (approx.) | Fits? |
+|---|---|---|
+| Gemma 4 E2B | ~2 GB | Yes |
+| Gemma 4 E4B | ~5 GB | Yes |
+| Gemma 4 12B | ~8–9 GB (Q4) | Edge |
+| Gemma 4 26B MoE | 14–18 GB | No |
+| Gemma 4 31B Dense | ~20 GB | No |
+
+### Model-by-model evaluation
+
+**Qwen2.5-Coder 7B — primary recommendation**
+
+The strongest purpose-built coding model that fits fully within 8 GB VRAM. Leads
+HumanEval among 7–8B-class models. Strong on Python, JavaScript, TypeScript. Has
+FIM (fill-in-the-middle) support for inline autocomplete. 35–55 tok/sec on RTX 3070.
+
+```
+ollama pull qwen2.5-coder:7b
+```
+
+**Qwen2.5-Coder 14B — secondary, with RAM offloading**
+
+At Q4_K_M this needs ~8.7 GB, just over the 8 GB limit. With 30 GB system RAM, Ollama
+automatically offloads the overflow layers to CPU. Performance drops to ~8–18 tok/sec
+versus 35–55 tok/sec for the 7B fully in VRAM. Quality is noticeably better for complex
+multi-file reasoning. Viable for chat-based coding tasks where quality matters more than
+speed; too slow for live autocomplete. Keep context window at 8K tokens to minimize
+VRAM pressure during offloaded inference.
+
+```
+ollama pull qwen2.5-coder:14b
+```
+
+**Gemma 4 E4B (~5 GB VRAM)**
+
+Fits comfortably with 3 GB to spare. Strong on reasoning, multimodal, and general-purpose
+tasks. Less specialized for coding than Qwen2.5-Coder 7B. Good choice for one model that
+covers coding + general reasoning + image analysis. The E4B outperforms Gemma 3 equivalents
+significantly on coding benchmarks.
+
+```
+ollama pull gemma4:e4b
+```
+
+**Phi-4 Mini 3.8B (~3 GB VRAM)**
+
+Best reasoning-per-VRAM model; leaves ~5 GB free for other applications. Strong on math,
+logic, and structured output. Good for agentic sub-tasks requiring tight reasoning. Not the
+strongest at raw code synthesis but excellent for reasoning-heavy parts of a coding loop.
+Viable as the autocomplete model in a two-model Continue.dev setup.
+
+```
+ollama pull phi4-mini
+```
+
+**DeepSeek-R1 8B (~5–6 GB VRAM)**
+
+Strong reasoning model for logic-heavy code (algorithms, correctness proofs). The full
+DeepSeek-Coder-V2 (236B MoE) is impractical here — only the 8B distilled variants are
+relevant. Outperforms Gemma 4 E4B on reasoning-heavy benchmarks; weaker on raw code
+generation than Qwen2.5-Coder 7B.
+
+**Codestral — not viable at 8 GB**
+
+The top FIM autocomplete model on HumanEval-FIM benchmarks, but requires 12–16 GB VRAM
+minimum. Not an option here. Worth revisiting if upgrading to a 12 GB+ card (RTX 4070
+Super or newer).
+
+### RAM offloading: does 30 GB help?
+
+Yes, meaningfully. Ollama automatically splits layers between GPU and system RAM when
+VRAM is exceeded. With 30 GB RAM, models up to ~14B at Q4_K_M run with partial offloading.
+The tradeoff is a 2–5× throughput penalty (8–18 tok/sec vs 35–55 tok/sec). Acceptable
+for batch tasks (reviewing a PR, generating an algorithm); too slow for live autocomplete.
+
+### Recommended setup
+
+**Autocomplete (fast, always-in-VRAM):** `qwen2.5-coder:7b`
+- Configure in Continue.dev as the tab-completion model
+- FIM-capable; 35–55 tok/sec; fits with 2–3 GB VRAM to spare
+
+**Chat / agent loop (quality-first):** `qwen2.5-coder:14b` or `gemma4:e4b`
+- 14B for strongest multi-file coding; expect 8–18 tok/sec with RAM offload
+- Gemma 4 E4B if you want vision + general reasoning + coding in one model; ~60 tok/sec
+
+**Two-model Continue.dev config (lower VRAM pressure):**
+`phi4-mini` (autocomplete) + `qwen2.5-coder:7b` (chat) — both fit simultaneously with
+~1–2 GB to spare, keeping the OS and IDE from contending for VRAM.
+
+---
+
+## Sources
+
+- [Ollama on Proxmox: GPU Passthrough for LXC and VM AI Workloads](https://linuxprofessional.ie/article.php?slug=ollama-proxmox-gpu-passthrough-lxc-vm)
+- [Run Ollama with NVIDIA GPU in Proxmox VMs and LXC containers](https://www.virtualizationhowto.com/2025/05/run-ollama-with-nvidia-gpu-in-proxmox-vms-and-lxc-containers/)
+- [Ollama Performance Tuning: Getting Maximum Speed from Local LLMs](https://dasroot.net/posts/2026/01/ollama-performance-tuning-gpu-acceleration-model-quantization/)
+- [Pros and Cons: Containerized Ollama vs. Local Setup](https://alain-airom.medium.com/pros-and-cons-using-containerized-ollama-vs-local-setup-d9bdf225bbb5)
+- [Best Local Coding Models Ranked: Every VRAM Tier (2026)](https://insiderllm.com/guides/best-local-coding-models-2026/)
+- [Best Local LLMs for RTX 4060, RTX 3070, and RTX 5060](https://aiagentskit.com/blog/best-local-llms-rtx-4060-3070-5060/)
+- [Best Local LLMs for 8GB VRAM: Real Hardware Benchmarks (2026)](https://localllm.in/blog/best-local-llms-8gb-vram-2025)
+- [Self-Hosted AI Coding Agent: Ollama + Continue + Open WebUI Setup in 2026](https://www.web3aiblog.com/blog/self-hosted-ai-coding-agent-ollama-continue-2026)
+- [Best Local-First AI Coding Tools 2026: 14 Compared](https://nimbalyst.com/blog/best-local-first-ai-coding-tools-2026/)
+- [OpenCode + Ollama: Private Local AI Coding Agent Setup](https://lushbinary.com/blog/opencode-ollama-local-ai-coding-privacy-guide/)
+- [Gemma 4: Google DeepMind](https://deepmind.google/models/gemma/gemma-4/)
+- [Running Gemma 4 Locally: VRAM Requirements](https://knightli.com/en/2026/05/01/gemma-4-local-vram-quantization-table/)
+- [Phi-4 Mini vs. Gemma 3 vs. Qwen 2.5: Best SLM for Coding Tasks in 2026](https://botmonster.com/ai/phi-4-mini-vs-gemma-3-vs-qwen-25-best-slm-coding-2026/)
+- [Qwen2.5-Coder 14B VRAM Requirements Guide](https://willitrunai.com/blog/qwen-2-5-coder-14b-vram-requirements)
+- [Comparing AI Harnesses: OpenCode, Ollama, LM Studio, Claude Code, Open WebUI, and VS Code](https://jace.pro/blog/comparing-ai-harnesses-opencode-ollama-lm-studio-claude-code-open-webui-and-vs-code/)