AGENT SKILL

offline-code

Offline code snippet search + generation using local Ollama models. Search a curated corpus (run `offline_code stats` for the live count) across 30+ topics and 25 languages with nomic-embed-text:v1.5, generate code with qwen2.5:3b (single fleet model, also used for judging; CODING_MODEL env pin wins). No internet needed.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 4
Forks
1

01 前言 Front Matter

name
offline-code
author
Steadfaste Fleet
license
MIT
version
1.0.0
category
devops
metadata
{ "hermes": { "tags": [ "offline", "code", "rag", "search", "generation", "nomic", "qwen" ] } }
description
Offline code snippet search + generation using local Ollama models. Search a curated corpus (run `offline_code stats` for the live count) across 30+ topics and 25 languages with nomic-embed-text:v1.5, generate code with qwen2.5:3b (single fleet model, also used for judging; CODING_MODEL env pin wins). No internet needed.

03 SKILL.md 正文

Offline Code — Local Snippet Search & Generation

A two-tier local coding assistant: search a curated corpus of algorithms and patterns, then generate code using Ollama. All data stays on your machine.

                        offline_code
                       /            \
              search                   gen
                 │                       │
                 ▼                       ▼
      nomic-embed-text:v1.5        qwen2.5:3b
      (embeds query,              (RAG: top-3 snippets
       cosine similarity           + user prompt → code)
       → ranked snippets)

Installation

# Step 1: Symlink the CLI wrapper
ln -sf ~/steadfaste-fleet/ops/offline/offline_code.sh ~/.hermes/bin/offline_code

# Step 2: Verify CLI
offline_code stats

# Step 3: (Re)build the search index if needed
offline_code index --force

# Step 4: Ensure models are pulled
ollama pull nomic-embed-text:v1.5        # already pulled by install.sh
ollama pull qwen2.5:3b                   # single fleet model — serves both judge and code gen

Usage

Search for code patterns

offline_code search "flask rest api"
offline_code search "binary search tree rust"
offline_code search "retry pattern with backoff"

Returns top-matching snippets from the corpus, ranked by cosine similarity.

Generate code using RAG

offline_code gen "binary search tree in rust"
offline_code gen "flask api with sqlalchemy"
offline_code gen "terraform aws vpc with subnets"

The generator: (1) finds top-3 matching snippets via search, (2) injects them as context, (3) sends everything to qwen2.5:3b for generation. Result: small model + good context ≈ much larger model's quality.

Agent-friendly JSON check (for scripting)

offline_code check "flask rest api"            # JSON: hit/miss verdict, no prose
offline_code search --learn-on-miss "flask"    # on miss, output a learnable template

check is the right tool for cron/agent gating (parse JSON, branch on hit/miss). search supports --limit N and --lang <language> filters.

Index management

offline_code index            # incremental index (skips if current)
offline_code index --force    # full rebuild
offline_code stats            # corpus + index stats

Agent Workflow — MANDATORY: Check Offline Before Web

This workflow is mandatory for all LLM cron jobs and coding sessions. Before calling web_search(), you MUST follow this order:

1. offline_code search "<your pattern>"
     └── hit? → Use the snippet directly or adapt it. ZERO API COST.
     └── miss? → Go to step 2

2. offline_code gen "<your request>"
     └── Generates code using RAG + qwen2.5
     └── Good for: algorithms, patterns, glue code

3. web_search (LAST RESORT — only if offline has nothing useful)

### Self-Learning: Fill Gaps
When `web_search()` finds something useful that the corpus missed:
1. **`offline_code learn "<title>" --lang <lang> --tags "<tags>" --desc "<desc>" --code "<code>"`**
2. This creates a new `.md` snippet in the correct language directory
3. **Next index refresh** (weekly cron or manual `offline_code index --force`) bakes it in
4. Future searches will find it — the corpus improves over time

Without explicit `--code`, you can pipe via stdin: `echo "code" | offline_code learn "Title"`

Skipping the offline check and going straight to web_search() is a quality gate failure — it wastes API credits on questions the corpus can answer for free.

This saves API costs, works offline, and is faster than web search.

How It Works

Component Model Size Purpose
Search indexing nomic-embed-text:v1.5 261 MB Embed snippets into 768-dim vectors
Query embedding nomic-embed-text:v1.5 — Embed your search query for cosine comparison
Code generation qwen2.5:3b 1.9 GB Single fleet model — also used for judge, classification, routing, quality gates

The model prefers an installed model and honors a CODING_MODEL env pin (a pin wins — never auto-upgraded past it). If CODING_MODEL is unset, it uses qwen2.5:3b if installed. You can override per-call with --model:

offline_code gen "binary search tree" --model qwen2.5:3b

The corpus lives at ~/steadfaste-fleet/ops/offline/code-corpus/ (per-language snippet modules in code-corpus/snippets/; regenerate .md files with python3 ops/offline/code-corpus/generate.py after editing modules). Index stored at ~/offline/code-index.json. Run offline_code stats for the current snippet count — the corpus grows via learn, so never hardcode a count in scripts.

Troubleshooting

Symptom Fix
offline_code: command not found ln -sf ~/steadfaste-fleet/ops/offline/offline_code.sh ~/.hermes/bin/offline_code (and ensure ~/.hermes/bin is on PATH)
nomic-embed-text:v1.5 not found ollama pull nomic-embed-text:v1.5
qwen2.5 not found ollama pull qwen2.5:3b (single fleet model; CODING_MODEL env pin wins)
Index is current on --force Use --force flag to rebuild
Corpus empty / no snippets Run offline_code index --force to build from scratch
Slow search First run indexes all snippets — subsequent runs use cached index
connection refused / urllib error on gen Ollama not running — start it (ollama serve or the system service), then retry
learn says nothing saved Provide --code or pipe code via stdin: `echo "..."

04 同仓库更多 Skills