Quickstart

Five minutes from clone to a working project.

What's real, what's stub

The commands marked ✓ works below run end-to-end today. The ones marked stub print a not implemented error — they're scaffolded but the implementations land in later milestones. See where we stand for the full picture.

1 · Scaffold a project — init ✓ works

local-agents init my-handbook

What happens:

1. Fetches the model recommendation manifest from llama-cpu-benchmarks.
2. Verifies the manifest (schema=1, tool-calling floor passed).
3. TTY: drops you into a Bubble Tea picker showing the top-ranked models with tool-call accuracy + p50 latency + size. Non-TTY (CI): uses the top-ranked model.
4. Creates my-handbook/ with config.yml, schema.md, wiki-instructions.md, README.md, plus data/, skills/, wiki/ subdirs.
5. Writes the chosen model.id to config.yml.
6. Downloads the GGUF + ONNX embedding to ~/.config/local-agents/ (with sha256 verification + cache-hit short-circuit).
7. Prints the next-steps hint.

Non-interactive variants:

local-agents init my-handbook --yes          # top-ranked, no prompt
local-agents init my-handbook --model gemma-4-e4b-q4_k_m
local-agents init my-handbook --manifest https://my.mirror/manifest.json

2 · Check the install — doctor ✓ works

cd my-handbook
local-agents doctor

Eight checks run, every time. Sample output:

pocket llm · doctor

project:  /Users/x/my-handbook
home:     /Users/x/.config/local-agents

✓ config.yml          valid (0 commands, 0 demo questions)
✓ model.gguf          gemma-4-e4b-q4_k_m.gguf (2.5 GiB)
✓ embedding           bge-small-en-v1.5-q8.onnx
✓ port :8080          available
✓ disk space          84 GiB free

For machine output (CI gating):

local-agents doctor --json

3 · Drop in sources

cp ~/Downloads/return-policy.pdf my-handbook/data/
echo "command output gets a wiki article too" >> my-handbook/data/notes.md

Edit config.yml to add shell commands whose output becomes wiki articles (any tool that outputs JSON: gh, kubectl, psql, …). See the config.yml schema →

4 · Generate the wiki — wiki generate 🚧 stub (M3)

local-agents wiki generate

The slow LLM step. Each file in data/ becomes one wiki/<name>.md article, using wiki-instructions.md as the prompt template. Pin a hand-edited article with frozen: true in its frontmatter — wiki generate skips it.

M3 not landed

This currently returns not implemented. The orchestrator (internal/wikigen) and the local backend that calls apps/llama in-process are slated for M3. The wiki-instructions.md template is portable — you can run it through claude-code or another LLM by hand today and drop the result into wiki/<name>.md. build doesn't care which path produced the article.

5 · Package + share — build 🚧 stub (M5)

local-agents build                                # → ./my-handbook.zip
local-agents build --self-contained --to s3://bucket/x.zip

build reads wiki/, data/, skills/, builds a RAG chunk index, writes a manifest, zips everything up. --self-contained also bundles the model (≈ 3–5 GiB for one of the top-3 recommended models). --to s3:// uploads instead of writing to disk.

By default, every demo: question in config.yml runs through the chat pipeline as a smoke test before the zip is sealed.

6 · Recipient flow — import + serve / chat 🚧 stub (M9 / M8 / M6)

local-agents import https://share.example.com/my-handbook.zip
cd my-handbook
local-agents serve     # opens dashboard at localhost:8080
local-agents chat      # OR terminal REPL

Zero outbound network calls at chat time. The dashboard is embedded into the same binary via embed.FS.

Next

• Project folder layout — what each file is for.
• Sharing a knowledge base — the offline-share story.
• Architecture overview — the three-apps-one-binary model.