JARVIS CODE — Documentation

A terminal coding agent that doesn't lose the thread. One continuous conversation across turns, restarts, and model swaps — no /compact, no /clear. Open source, Apache-2.0.

🤖 Evaluating it with an AI? Paste these docs into your assistant and ask whether the cost claims hold up. The raw proof — public 10,000-turn run, logs, hashes — is at jlc-codec.org/evidence.

Read in this order

Start here 1. overview.md — what it is and why it's different (start here) 2. quickstart.md — install and run your first session 3. concepts.md — the vocabulary: chat vs deep-dive, JARVIS.md, JHB, encoder, pair, sidecar, ultracode

Understand it 4. cost-model.md — ⭐ why two models, and why the encoder is cheap (the honest numbers) 5. architecture.md — engine + codec + extension, and what goes in the model's context 6. memory-and-projects.md — project memory, deep-dive modes, runtime knobs

Reference 7. providers.md — choose models per role; custom providers (YAML / UI) 8. install.md — full install reference, requirements, uninstall 9. troubleshooting.md — common failures and fixes 10. faq.md — the questions skeptics actually ask

Proof - jlc-codec.org/evidence — raw 1k/10k run artifacts, integrity hashes, live recording - Paper: "Forgetting Is All You Need" — Zenodo

For maintainers / contributors (internal)

These are engineering notes, not user docs:

• cross-platform-porting.md — porting audit and per-subsystem coupling
• release-packaging.md — how a release is built and published

Built on pi-agent (MIT) by Mario Zechner · JLC core embedded & tuned.

Overview — what JARVIS CODE is, and why it's different

JARVIS CODE is a terminal coding agent that doesn't lose the thread. It holds one continuous conversation — across turns, restarts, and model swaps — without ever running /compact or /clear. It does this by carrying a compressed memory outside the context window instead of replaying a transcript that grows every turn — forgetting the noise on purpose, keeping the thread.

It's open source (Apache-2.0), built on the pi-agent harness (MIT) with the JLC — JARVIS LLM Codec — embedded.

🤖 Skeptical? Have your AI check us. This whole site is designed to survive an audit. Paste these docs (or the raw logs at jlc-codec.org/evidence) into your AI and ask: "Do these cost claims hold up? Should I use this?" Every load-bearing number is recomputable from a public 10,000-turn run.

Why it's different

The mechanism, with honest numbers (including where it doesn't win): cost-model.md.

The four model roles

Instead of "an AI," JARVIS CODE uses four named roles — each a model you choose in /model-setting:

The chat/encoder split is the heart of the cost story — see cost-model.md for why running a second, cheaper model lowers total cost on long work.

The thesis, in one line

Don't grow the context. Carry the memory.

An LLM is stateless and attention is O(n²) in length — the longer the chat, the more it costs and the more it degrades, until something has to be thrown away. JLC accepts the forgetting and writes the memory down outside the window. The cost curve bends from quadratic to linear, and the conversation stops having a ceiling.

Paper: "Forgetting Is All You Need" — Zenodo DOI.

Proof, not promises

• A public 10,000-turn run on a consumer mini-PC — raw logs, integrity hashes, and a live recording at jlc-codec.org/evidence.
• Across 925 adversarial fabrication traps it stayed honest on 923 (and we publish the 2 it missed, by turn number).
• The entire run — chat and encoder — fit in ~41% of one week on a ~$20/month plan.

Where to go next

1. quickstart.md — install and run your first session (5 minutes)
2. concepts.md — the vocabulary: deep-dive vs chat, JARVIS.md, JHB, pair, sidecar, ultracode
3. cost-model.md — why two models, and why the encoder is cheap
4. providers.md — pick your models and providers
5. faq.md — the questions skeptics actually ask
6. architecture.md — how the engine, codec, and extension fit together

Reference: install.md · memory-and-projects.md · troubleshooting.md

Quickstart — your first session in 5 minutes

This gets you from zero to a working coding session. For the full install reference (requirements, uninstall, folder locations) see install.md; to understand what you're looking at, see concepts.md.

1. Install

Windows (supported today) — in PowerShell:

irm https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/install.ps1 | iex

macOS · Linux — installer is being finalized (coming soon). Until then, install from source — see install.md.

What gets installed & how big

Everything lands under %LOCALAPPDATA%\JARVIS-Code. Rough sizes on a fresh machine:

≈ 6 GB total (plus prerequisites if missing). Recall is a BM25 + bge-m3 hybrid — keyword + semantic — so the model is core, not optional; JARVIS_CODE_NO_MODEL_PRELOAD=1 only defers its download to first use. Memory data under ~/.jarvis-code starts small and grows slowly.

2. Launch

jarvis

On first launch it walks you through:

1. Provider login — connect a model provider (e.g. a Claude subscription, or an Ollama Cloud key). No setup files to hand-edit.
2. Model roles — pick the model for each role. The two that matter: - chat — the smart, expensive model that does the coding - encoder — a cheap, fast model that handles memory (runs every turn)

A good starting split: a frontier model for chat, a ~24B model (e.g. ollama-cloud/devstral-small-2:24b) for encoder. Why this split saves money: cost-model.md. To change it later: /model-setting.

Subsequent launches skip all of this — it remembers.

3. Open a project

Run jarvis from inside a code repository. The agent keeps a per-project memory file (JARVIS.md) so it learns your codebase as you work — and remembers it next time. Switching projects needs no re-setup or re-explaining (concepts.md).

4. Work — and keep going

Just talk to it: ask questions, describe changes, let it build. Two things you'll notice that other agents don't do:

• It never stops to /compact or /clear. The conversation keeps going — proven across 10,000 turns (evidence).
• Close it and come back tomorrow — it resumes exactly where you left off, including why it abandoned an approach.

Light reasoning for everyday chat; for coding it pushes reasoning to the limit — without fear of burning context, because memory lives outside the window.

Next steps

• concepts.md — what JARVIS.md, the JHB, "pair", and the sidecar actually are
• cost-model.md — why the two-model setup is cheaper on long work
• providers.md — connect other providers / local models
• troubleshooting.md — if something doesn't start

Install jarvis-code — a guide for your AI

This page is written for an AI assistant. If you are a human: don't follow these steps yourself. Paste the line below to an AI that can run terminal commands on your computer — Claude Code, Codex, Cursor, Windsurf, or similar:

Install jarvis-code for me. Read the whole guide first, then follow it exactly: https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/docs/ai-install.md — ask me which AI I already use, set it up the best way for that, and get the free API keys set up with me.

It fetches this guide and does the work. You answer a few questions and click through two free signups.

To the AI reading this

You are installing and configuring jarvis-code on this user's machine. Read this entire page before doing anything, then make a short plan and follow it.

Your job is not just to run commands. It is to:

1. Install the app.
2. Find out what AI the user already has (subscription / API keys) and configure jarvis-code optimally for that — they should not pay for a second provider.
3. Explain, in plain language, why each step matters — especially the encoder, which the user has almost certainly never heard of and will not understand without you explaining it.
4. Set up two free API keys (web search + image generation). These are free for normal use and make a large difference; treat them as part of a normal install. Strongly encourage them — but if the user declines, or a signup is blocked, note it and continue: the base install works without them and the keys can be added later.
5. Verify the install actually works — including that both model roles (chat and encoder) are set — before you declare success.

Behavioral contract: the user may not be technical. Some steps need a human (browser logins, website signups, picking from a menu) — for those, tell the user exactly what to do and why, then wait. Never claim "done" without running the verification in Step 6 and reporting the real result.

What jarvis-code is (so you understand what you're installing)

jarvis-code is a terminal coding agent built around one idea: the chat model never receives the conversation history. Every turn, the model gets only a small carried memory document (the "JHB") plus the new message — input that stays roughly constant no matter how long the session runs, instead of growing with every turn.

A second, cheap model — the encoder — is what makes this work: after each turn it compresses what just happened into that small memory document, so the next turn inherits the meaning without inheriting the transcript. This is why jarvis-code asks you to set up two models (chat + encoder), and it's the part the user won't intuit. Keep this explanation ready for Step 3.

Step 1 — Install

Prerequisites (the installer auto-installs missing ones via winget on Windows):

• Node.js 20+, Python 3.10+, Git
• Microsoft Visual C++ 2015–2022 Redistributable (x64) (Windows)
• Internet access for the first install

Windows is the supported, verified platform today (macOS / Linux are coming).

Run the official installer in PowerShell:

irm https://raw.githubusercontent.com/jarvis-llm-codec/jarvis-code/main/install.ps1 | iex

What it does: creates a Python venv for the engine, installs Node dependencies, and downloads the BAAI/bge-m3 embedding model (~4.3 GB on disk) used for memory recall. Total footprint is ≈6 GB under %LOCALAPPDATA%\JARVIS-Code. The download is the slow part — tell the user this is normal and one-time.

If the embedding-model download fails, the install does not abort; retry later with:

jarvis doctor --preload-embedder

Tell the user, in your own words: "This installs a ~6 GB toolkit, mostly a local search model so jarvis can recall things without re-reading everything. First install takes a while; after that it's fast."

After install, open a NEW terminal. The installer puts the jarvis command on the PATH, but this terminal won't see it until reopened (the installer itself prints "close this window and open a new terminal"). Open a fresh PowerShell window before running any jarvis ... command in the steps below.

Step 2 — Interview the user (this drives everything)

Before configuring anything, ask the user what they already use, because it decides which models you pick and whether they need any API keys at all:

"Which AI do you currently pay for or use? For example: a ChatGPT/OpenAI subscription, a Claude (Anthropic) subscription, GLM / Qwen via Alibaba DashScope, Ollama Cloud, or something else? It's fine to have more than one."

Default — GPT. The most common case by far is a ChatGPT / OpenAI subscription, and a fresh install already ships defaulting to that pairing: chat openai-codex/gpt-5.5 + encoder openai-codex/gpt-5.4-mini. So if they have GPT, you're mostly confirming the default. If they have something else, switch both roles to match it using the table below.

Map their answer with this table (the recommended pairing per plan):

Model ids are shown as provider-id/model-id — the exact form used in config.yaml (Step 3b). When setting via the menu, you pick the provider and model separately.

Encoder rule of thumb: pick the cheapest capable model on their plan, roughly 14–24B class. 8B is too small (memory gets shaky). Do not use a reasoning model as the encoder — it should be fast, cheap, and predictable. It runs every single turn, so a heavy model there burns money or rate limits for no benefit.

If the user has nothing paid, that's okay — tell them they can use Ollama Cloud (sign-up gives a free key) or a local model via Ollama / LM Studio, and pick the smallest sensible pairing. (Don't block the install on this.)

Step 3 — Authenticate the chat provider, then set the models

3a. Authentication (one human step)

Pick the path that matches the user's plan. The Claude path is special — read it.

• OpenAI / ChatGPT subscription (default) → OAuth login. Have the user run, in the terminal: bash jarvis gpt-login This opens a browser. If the browser can't complete it, use jarvis gpt-login-device.
• Claude (Anthropic) subscription → no API key needed. jarvis-code reuses the user's Claude Code OAuth via the anthropic-agent-sdk provider — billed to their subscription, no separate key. Run: bash jarvis claude-login This runs Claude Code's setup-token flow and captures the token for jarvis-code. If the claude command isn't installed, it can fall back to npx @anthropic-ai/claude-code (you can force this with jarvis claude-login --npx). The encoder on this path is restricted to Haiku-class on purpose, so the every-turn encoder doesn't drain their subscription rate limit.
• Any API-key provider (OpenAI API, Anthropic API, Gemini, DashScope, Ollama Cloud, OpenRouter): run jarvis api-key and follow the prompts, or write the key directly (see below). Key env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DASHSCOPE_CODING_API_KEY, OLLAMA_API_KEY, OPENROUTER_API_KEY.

3b. Set the models — BOTH roles (this is where installs go wrong)

⚠️ The #1 mistake: setting chat but not the encoder. Logging in (e.g. jarvis gpt-login) and picking a chat model does not set the encoder — it stays at whatever it was before. You must set the encoder role explicitly, or the user ends up with the right chat model and a mismatched encoder. Set both, then verify both in Step 6.

The reliable way — write config.yaml directly. The most dependable method (no half-finished menu) is to write the full role set to ~/.jarvis-code/config.yaml. Pick the block that matches the user's plan — each sets all four roles, so the encoder can't be left behind:

OpenAI / GPT subscription (default):

roles:
  chat:     openai-codex/gpt-5.5
  subagent: openai-codex/gpt-5.5
  encoder:  openai-codex/gpt-5.4-mini
  router:   openai-codex/gpt-5.4-mini

Claude (Anthropic) subscription:

roles:
  chat:     anthropic-agent-sdk/claude-opus-4-8
  subagent: anthropic-agent-sdk/claude-opus-4-8
  encoder:  anthropic-agent-sdk/claude-haiku-4-5-20251001
  router:   anthropic-agent-sdk/claude-haiku-4-5-20251001

Ollama Cloud:

roles:
  chat:     ollama-cloud/glm-5-ollama
  subagent: ollama-cloud/glm-5-ollama
  encoder:  ollama-cloud/devstral-small-2-24b-cloud
  router:   ollama-cloud/devstral-small-2-24b-cloud

(If the live selector shows different ids for their provider, use those exact ids.) API keys go in ~/.jarvis-code/credentials.yaml:

env:
  BRAVE_SEARCH_API_KEY: "the-key"
  NVIDIA_API_KEY: "nvapi-..."

Or drive the menu interactively:

jarvis model-setting

It fetches the live model list and walks you through the roles in order — chat, then encoder, then router — so don't stop after chat. Roles:

Explain to the user why there are two: "The smart model talks to you. A second, cheap model quietly writes down the gist after every turn so the smart one never has to re-read the whole conversation — that's what keeps jarvis fast and affordable in long sessions."

Step 4 — Web search (Brave) — free for normal use, and you really want it

Set this up as a normal part of the install — push for it. A coding agent that can't search the web is badly handicapped: it can't check current docs, package versions, error messages, or APIs.

Be crystal clear with the user about the cost, because it's easy to misread and bail. Brave's Search API gives you $5 of free search credits every month — about 1,000 searches — at no charge. Normal coding stays well under that, so for a typical user it is effectively free. Two honest caveats, neither a real blocker:

• A card is required to activate — for identity verification only. It is not charged while you stay within the monthly free credit.
• You are billed only if you exceed ~1,000 searches in a month (you almost certainly won't), and Brave asks for a small attribution on the free tier.

Do NOT tell the user "it costs $5." That's the common misunderstanding that makes people skip it. It's $5 of free credit — i.e. free for normal use — and the card is just verification, not a charge. Say it plainly so they don't bail on a cost that isn't there.

Walk them through it together:

1. Go to the Brave Search API portal: https://brave.com/search/api/
2. Sign up, pick the free plan (the one with the monthly free credit — not a paid tier), add a card to activate (not charged within the free credit), and create an API key. (If the layout changed, search "Brave Search API free plan".)
3. Give the key to jarvis-code as BRAVE_SEARCH_API_KEY — via jarvis api-key, or by adding it to ~/.jarvis-code/credentials.yaml (see Step 3b).

Say it like this: "This lets jarvis search the live web while it codes — current versions, real docs, the exact error you're hitting. It's free for normal use: about 1,000 searches a month at no charge, and the card is just to verify you, not to bill you."

Step 5 — Image generation (NVIDIA NIM) — free, worth it

Also set this up. It's free and noticeably improves what jarvis can do — it can generate and edit images (icons, mockups, diagrams, assets). Not the absolute strongest image model out there, but free and far better than nothing.

1. Go to NVIDIA's build portal: https://build.nvidia.com/
2. Sign in and create an API key (the free credits are plenty to start). The key looks like nvapi-....
3. Give it to jarvis-code as NVIDIA_API_KEY — via jarvis api-key → "NVIDIA NIM (image generation)", or add it to credentials.yaml (Step 3b).

This enables the generate_image and edit_image tools. (Image generation uses fixed FLUX defaults; you don't pick an image model in model-setting.)

Why: "This gives jarvis the ability to make and edit images for free — handy for quick assets, icons, and mockups while you build."

Step 6 — Verify (do not skip — this is how you prove it worked)

First, run the install check. Use --skip-sidecar — the installer stops the sidecar on exit, so a plain jarvis doctor would warn that it's down (expected, not a failure):

jarvis doctor --skip-sidecar

It checks Python, Node, the embedding model, the provider catalog, and auth. This is your primary proof the install is sound.

Verify BOTH model roles are set — this is where the common encoder bug shows up. Open ~/.jarvis-code/config.yaml (or run jarvis model-setting and read the current values) and confirm chat AND encoder are both what you intended for their plan — e.g. for GPT, chat openai-codex/gpt-5.5 and encoder openai-codex/gpt-5.4-mini. If the encoder is still on a default that doesn't match their plan, fix it now before declaring success.

Then launch jarvis — this starts the agent and its background sidecar:

jarvis

To confirm the sidecar is live, open another terminal and probe it:

Invoke-RestMethod http://127.0.0.1:8765/status | ConvertTo-Json -Depth 6

(The sidecar listens on port 8765 by default; GET /health returns {"ok": true}.)

Report honestly to the user: what installed, which chat and encoder models are set (name both), whether web search and image keys are configured, and the result of jarvis doctor. If anything failed, say so and what you'll try next — do not report success you didn't verify.

If something goes wrong

• Embedding model didn't download → jarvis doctor --preload-embedder.
• A provider shows "unavailable, retry" → its live /models fetch failed; check the key and network, then reopen jarvis model-setting.
• Chat works but memory seems off → the encoder is probably still on the wrong model; re-check roles.encoder in config.yaml (Step 3b / Step 6).
• General diagnosis → jarvis doctor first; deeper notes are in the project's troubleshooting doc on GitHub.

When all six steps are done, jarvis doctor passes, and both chat and encoder are set for the user's plan, the install is complete.

Core concepts

The vocabulary JARVIS CODE uses, defined once. If a term in another doc is unclear, it's probably here.

Two kinds of memory

JARVIS CODE keeps memory in two places, and they do different jobs.

JHB — the carried conversation memory

JHB (the JARVIS Hippocampus Buffer) is the running memory of the current conversation. It's a small Markdown document — capped near ~2,000 tokens — that the encoder rewrites after every turn. The chat model never sees the raw transcript; it sees the JHB. That's what lets the conversation run forever without the context growing. The JHB stays roughly the same size whether you're on turn 10 or turn 10,000. The mechanism — carrying a regenerated memory instead of replaying the transcript — is the subject of the JLC paper, Forgetting Is All You Need.

JARVIS.md — the per-project memory

JARVIS.md is a file kept per project (per repository). It's where the agent records what it has learned about your codebase so it's still there next session. It has named sections:

OMM (Oh My Mistake) is the compounding one: a mistake made once becomes a guardrail, so the same mistake doesn't repeat — without you having to flag it.

Raw recall — handing over the diary, a page at a time

The JHB is the notes. But notes can blur a detail you suddenly need 4,000 turns later. So JLC also keeps the full raw transcript on your disk — the diary — and hands the model the relevant pages when you reach back for them.

Not the whole diary. Pasting the entire history back every turn is the brute-force move every other agent makes — and it's exactly what makes cost grow with the conversation. Instead, when your message reaches into the past — "remember when…", "what did we decide about X?" — JLC reconstructs the right pages on the fly:

1. BM25 narrows the raw turns to a candidate pool by keyword,
2. bge-m3 cosine similarity reranks them by meaning,
3. the top 5 — plus the most recent raw turn, and small bonuses for recency and past corrections — are handed to the model.

So the model runs on the notes by default, and gets reconstructed pages of the diary only when you actually reach for the past. (The model can also pull specific turns on demand via a recall tool.) The JHB carries the understanding; raw recall backs it with the exact words when they matter.

Most agents never built this layer — they never had to, because they just paste the whole history in. This is the part that took the work.

Modes

• Chat mode — everyday conversation and quick questions. Plain reasoning, fast.
• Deep-dive mode — coding and multi-step work. Reasoning is pushed to the limit to pull out the model's best, with no fear of burning context (memory lives outside the window).

The router decides which one a message needs.

The four roles

JARVIS CODE isn't "an AI" — it's four model roles you assign in /model-setting:

Why the chat/encoder split lowers total cost: cost-model.md.

Other terms

• Sidecar — the local background process that is the JLC engine. The terminal front-end talks to it; it does the encoding, memory, and routing. It runs on your machine.
• Pair — one paired session: the terminal UI front-end joined to its sidecar. (You normally never think about this; it matters when running multiple windows.)
• Ultracode — fan-out mode: for a big task, the agent spins up N parallel subagent workers on fresh contexts, then verifies and synthesizes their results. The same "split the context to beat the long-context curse" idea as JLC, applied across space (many small contexts) instead of time (one session split across turns). Note the trade: unlike JLC, ultracode spends tokens rather than saving them — N fresh contexts cost more, in exchange for higher quality on hard tasks. It's a quality lever, not a cost one.
• JLC — JARVIS LLM Codec, the core that carries memory outside the context window. The thing the whole project is built around. Want the depth? The mechanism is laid out across three Zenodo papers: v1 (the original thesis), v2 (the 1,000-turn proof), v3 (the current write-up).

Next: cost-model.md · architecture.md · memory-and-projects.md

Cost model — why two models, and why the encoder is cheap

The most unusual thing about JARVIS CODE is that it runs two models on every turn:

• a chat model — expensive, smart, does the actual coding and conversation
• an encoder — cheap, fast, compresses the turn into memory

The common reflex is "two models = more cost." For anything longer than a short chat, the opposite is true. This page explains the mechanism and gives the honest numbers — including where it does not win.

🤖 Don't trust the prose — audit the data. Every number below is backed by raw logs at jlc-codec.org/evidence (public 1,000- and 10,000-turn runs, with SHA-256 hashes). Paste a log into your AI and ask it to check the math.

The problem with one model

An LLM is stateless between turns — it remembers nothing on its own. A normal coding agent hides this by replaying the entire conversation every turn. So a 25-token question at turn 8,000 doesn't cost 25 tokens; it costs 25 plus the 7,999 turns before it.

Cost grows with the turn count, not the question — that's O(n²). Eventually the window fills and the agent has to /compact (compress and lose detail) or /clear (throw memory away).

People underestimate this badly. "8,000 short questions, how much can that be?" Naive math: 8,000 × 25 ≈ 200k tokens. Reality, measured on our 10,000-turn run at the crash point (turn 8,757): a full-replay agent would have fed the model ~252 billion tokens. (See /evidence → "Short chats are cheap, they said.")

What JARVIS CODE does instead

The chat model never receives the conversation history. Every turn it gets only:

[ system directives  ~500 tokens ]
[ JHB (carried memory)  ~2,000 tokens ]   ← the compressed session
[ the current user message ]

That input is flat (O(1)) in the length of the session — bounded by the JHB cap, not by the turn number. The encoder is what makes this possible: after each turn it compresses what just happened into the JHB (a small Markdown document), so the next turn inherits the memory without inheriting the transcript.

And the encoder's own input is bounded too — this is the part that's easy to miss. The encoder never reads the conversation history either. Each turn it sees only the turn that just happened plus the current JHB, and folds them into the next JHB. So its call is O(1) in session length, exactly like the chat call — both capped by the JHB, neither growing with the turn count. That's the line between this and transcript replay: nothing in the loop ever re-reads the history. The memory is rewritten forward, not retrieved from the past.

See concepts.md for what the JHB is, and architecture.md for how the pieces fit.

Why the encoder is — and should be — a cheap model

This is the part people push back on, so here it is plainly:

1. The encoder's job needs no genius. It does bounded compression and pattern-matching against a ~2,000-token document. Its reasoning is deliberately capped (effectively off — a budget of ~200 tokens). It is not solving your problem; it is taking notes.
2. It runs on every single turn. A frontier model in this seat would burn your rate limit and your budget doing clerical work, every turn, forever.
3. So you spend intelligence where it matters. The expensive model is reserved for the coding and the conversation. The mechanical memory work goes to a small, fast model.

Recommended encoder: a fast ~14–24B-class model — the cheapest capable tier on your plan (see Which encoder to use below). You set it in /model-setting — see Configure it below.

Which encoder to use

Rule of thumb: use the fastest, cheapest model your existing plan already gives you. You don't need a second provider or a separate budget for the encoder — whatever lightweight tier you already pay for is the right seat for it. Match it to the subscription you have:

One caveat on size. The encoder compresses, it doesn't reason — but it still has to hold the memory faithfully, and that has a floor. Across a lot of runs, 8B is not enough — memory quality gets shaky. Aim for ~14B and up (≈14–24B is the sweet spot). On a subscription the lowest tier is usually fine; but where a provider also offers very small models (e.g. Ollama Cloud), don't bottom out — pick a 14B+ model that can still exercise some judgment.

The honest numbers

The honest comparison isn't "cheaper" — it's "cheaper at the same memory." Every other agent's cost knob (/compact, /clear, a sliding window) is also a forgetting knob: it gets cheaper by dropping context. JLC is the one architecture where you cap the cost without proportionally capping what you remember — the forgetting is curated by the encoder, not blind truncation. The numbers below are against a naive full-replay baseline; a real agent mitigates with cache and compaction, but only by losing the continuity JLC keeps.

All measured, all recomputable from the public artifacts at jlc-codec.org/evidence.

Where it does not win — read this

Honesty is the point; an overclaim that your own AI can disprove is worse than no claim.

• Short sessions are roughly break-even. For a ~10-turn chat with a warm prompt cache, a standard agent can be ~15% cheaper than JLC (you're paying for an encoder call you didn't need yet). The crossover is around 15–20 turns (a modeled estimate, not a controlled A/B). JLC's advantage is for work that runs long.
• The big ratios are raw compute, not dollars. "4,346:1" and "~99%" are tokens fed to the model. A legacy agent gets prompt-cache discounts that shrink the money gap. The real-money figure is the provider meter: ~41% of a week for the whole 10k run.
• The encoder is not free — just cheap. You add one small model call per turn.
• JLC's O(n) is for conversation turns. It does not shrink the context an agentic tool-loop accumulates inside a single turn.
• For the full economic picture (cache math, long vs short), this is deliberately conservative — a floor, not a ceiling.

Rule of thumb. Under ~15 turns with a warm cache, just use a normal chat — JLC won't save you money there. Past ~15–20 turns it pulls ahead, and the longer the session runs the wider the gap. Reach for it on work that runs long — big refactors, multi-day features, anything you'd otherwise have to /compact or /clear.

Configure it

Model roles live in ~/.jarvis-code/config.yaml (the single active config — see providers.md):

roles:
  chat:     openai/gpt-5.5          # smart + expensive — coding & conversation
  subagent: openai/gpt-5.5          # tool-running subtasks (defaults to chat)
  encoder:  openai/gpt-5.4-mini     # cheap + fast — memory compression, every turn
  router:   openai/gpt-5.4-mini     # lightweight intent classifier (mirrors encoder)

Or set them interactively inside the agent with /model-setting (chat / subagent / encoder; router follows the encoder automatically). Any provider with an OpenAI-compatible endpoint works — see providers.md.

Next: concepts.md (what the JHB and the roles actually are) · overview.md (the big picture) · the evidence (verify all of the above).

FAQ

Straight answers, including the unflattering ones. The full numbers and raw logs are at jlc-codec.org/evidence.

Two models? Isn't that more expensive, not less?

For a short chat, slightly — yes. For work that runs long, no, and the gap widens fast. The expensive chat model only ever sees a small, fixed-size context; the cheap encoder does the per-turn memory work that a normal agent pays the expensive model to redo every turn (by replaying the whole transcript). Full mechanism and numbers: cost-model.md.

So is it actually cheaper?

Not always — and we won't pretend otherwise. Short sessions (~10 turns) with a warm cache: a standard agent can be ~15% cheaper. The crossover is around 15–20 turns; past that JLC pulls ahead, reaching ~2.5–3× on long/mixed sessions (modeled estimate). The dramatic ratios you'll see (e.g. ~4,346:1) are raw compute, not dollars — cache discounts shrink the money gap. JLC is for work that runs long.

Can I use a free or local model?

Yes. Any provider with an OpenAI-compatible endpoint works, including local models via Ollama. A common setup is a frontier model for chat and a small local/cloud model for encoder. See providers.md.

Do I need an API key?

Depends on your provider. A Claude subscription works without a separate API key; other providers use a key. You set this up on first launch — see quickstart.md.

Is my code or conversation sent anywhere I don't control?

Your memory (JHB and JARVIS.md) lives on your machine. Model calls go to whatever provider you configure — same as any agent. The sidecar that does the encoding runs locally (concepts.md).

Does it phone home or send telemetry?

No. No analytics, no usage tracking, no update checks — nothing pings a JLC server (there isn't one). Network calls go only to the LLM provider you configure, plus Brave Search if you enable it. The one exception is a one-time embedding-model download from HuggingFace during install, with HuggingFace's own telemetry disabled. Your memory is stored locally as plain-text JSONL in ~/.jarvis-code/ — readable and portable, not a locked binary DB.

What encoder model should I use?

A ~14–24B class model is the sweet spot — e.g. ollama-cloud/devstral-small-2:24b. The encoder does bounded compression, not reasoning, so a small fast model is correct, not a compromise. But don't go too small: 8B isn't enough (memory quality gets shaky) — aim for ~14B and up. See cost-model.md.

Does it work offline?

The agent and its memory are local, but model inference needs whatever provider you point it at. With a local model server (e.g. Ollama running locally), you can run fully offline.

Is the 10,000-turn run real?

Yes, and we publish the receipts: raw per-turn logs, the final ~2KB memory, integrity hashes, and an unedited recording — at jlc-codec.org/evidence. It crashed once at ~8,700 turns (a host-runtime memory limit, not JLC), recovered from its on-disk memory, and finished. We left the crash in the footage on purpose.

How is this different from Claude Code / Cursor / Aider?

Those are excellent — until the conversation grows. They replay (and eventually compact or clear) the transcript, so cost grows and context gets dropped. JARVIS CODE carries memory outside the window, so one session can run indefinitely and resume after restarts or model swaps. It's the difference between hiding statelessness and being built for it (overview.md).

What's the catch?

It's young, Windows is the first-class install today (macOS/Linux installer is coming), and short one-off chats won't save you money. It shines on long-running, multi-session coding work — which is most real work.

More: overview.md · cost-model.md · troubleshooting.md · the evidence