How LemonCrow works

Keep the model. Change the working loop.

LemonCrow is a runtime underneath your coding agent. Its recipe is simple: find the right code first, expose less irrelevant text, carry only useful state, and verify the change before the agent stops.

Host

Claude · Codex · Cursor · opencode · Pi

Protocol

MCP + host hooks

Grounding

LemonGraph + ranked retrieval

Working set

exact reads + bounded output + memory

Finish

edit + verify + measure

No code map to maintain

Your repository changes. The index changes with it.

You should not have to keep a separate markdown hierarchy, symbol map, or pseudo-index up to date just so an agent can navigate a large codebase. LemonCrow builds and refreshes that structure automatically, then ranks the relevant symbols and relationships at query time.

Read the source architecture → See benchmark evidence →

The runtime, step by step

Install once

LemonCrow sits underneath the coding agent you already use.

The installer adds the LemonCrow runtime, host integration, MCP configuration, skills, personas, and hooks supported by that host. The model does not change; the working environment around it does.

Without LemonCrow

Agent starts with its normal broad tool surface.

With LemonCrow

Agent gets a small grounded tool surface plus runtime hooks.

curl -fsSL https://install.lemoncrow.com | bash

Map the repository

The repo becomes a code graph before the agent starts exploring it.

You do not maintain a hand-written code map, architecture hierarchy, or pseudo-index for the agent. Tree-sitter parses symbols across languages, LemonGraph resolves definitions, callers, callees, and usages, and ranking surfaces the code that matters. Content hashes keep the index fresh automatically, so only changed files are reprocessed as the repository evolves.

Without LemonCrow

Maintain repo maps / grep notes / hand-written hierarchy → search → open files → infer relationships manually

With LemonCrow

automatic live index → ranked symbol → definition + callers + callees + exact source ranges

lc init

Search before reading

The first tool call should identify the right neighborhood, not dump text.

code_search combines lexical relevance, symbol structure, and graph relationships. It returns ranked matches with precise ranges and related symbols so the agent can usually decide what to read next from one result.

Without LemonCrow

Grep / Glob / repeated search queries

With LemonCrow

code_search("chargeCard") → definition · callers · callees · ranges

code_search("where is card charging retried?")

Read only the useful slice

Finding the right file is not permission to send the whole file to the model.

read projects source into the smallest useful representation: summary, outline, exact range, compact, minified, or full source when full source is actually needed. The same budget-first idea applies to documents and fetched web pages.

Without LemonCrow

Read 1,200 lines because the symbol is somewhere inside.

With LemonCrow

Read the outline, then :L184-L236.

read src/payments.py:L184-L236

Change the code in one grounded batch

Once the relevant surface is known, make the complete change rather than patching file by file.

edit applies multiple grounded hunks across files in one call. LemonCrow uses deterministic patching plus structural checks around edits and renames so parallel references are surfaced instead of silently missed.

Without LemonCrow

edit file A → inspect → edit file B → inspect → edit file C

With LemonCrow

one edit call → all known hunks → contract check

edit([{ path: "a.py", ... }, { path: "b.py", ... }])

Bound noisy execution

Tests and shell commands should return the failure, not a transcript of everything that happened.

bash output passes through a compaction pipeline: ANSI removal, duplicate collapsing, failure extraction, anomaly windows, and bounded head/tail output. Oversized output spills to a recoverable file instead of filling context. web_fetch similarly strips page chrome into clean Markdown.

Without LemonCrow

10,000 lines of pytest/npm/docker output enter context.

With LemonCrow

relevant failure + small context + path to the complete spill file

bash("pytest tests/payments -q")

Carry decisions, not the transcript

Long tasks need continuity without replaying every exploratory turn.

LemonCrow keeps useful repo and session facts in local memory, deduplicates repeated tool results, and can preserve compact handover state across compaction or session boundaries. The goal is to retain decisions and evidence while letting dead exploration disappear.

Without LemonCrow

Keep every search, log, and failed path in the conversation.

With LemonCrow

Keep the chosen approach, relevant symbols, evidence, and next action.

recall → relevant prior facts only

Verify before declaring done

A plausible edit is not a finished task.

Post-edit checks look for references the change may have missed. Runtime hooks notice code changes that have not been followed by tests or checks and nudge the agent before it stops. Repeated failing tool behavior is supervised rather than allowed to loop forever.

Without LemonCrow

edit succeeded → agent says done

With LemonCrow

edit → references/contracts → tests/checks → done

change → verify → finish

Measure the loop

The runtime can account for what it kept out of the working set.

LemonCrow tracks actual tool usage and savings counters so you can inspect saved tokens, avoided calls or turns, time, and model cost. The public savings surface aggregates anonymous telemetry; local session replay lets you inspect your own history without rerunning the model.

Without LemonCrow

It feels faster, but you cannot tell why.

With LemonCrow

inspect where turns, context, output, time, and cost changed

lemoncrow session stats
lemoncrow session replay

What gets replaced

Fewer primitives. Each one does more useful work.

LemonCrow	Instead of	Result
code_search	Grep / Glob loops	Ranked symbols, relationships, exact ranges
read	whole-file Read	Summary, outline, range, compact, or full on demand
edit	per-file Edit / Write	Grounded multi-file batch edits
bash	unbounded Bash output	Executed normally; output compacted and recoverable
web_fetch	raw page dumps	Clean, bounded Markdown

Host capabilities differ. Claude Code and Codex can replace more of the built-in surface; hosts such as Cursor may keep their own built-ins alongside LemonCrow. The runtime still applies the strongest controls the host exposes.

Recipes

The useful pattern is usually the same.

Understand an unfamiliar subsystem

01 code_search the concept or symbol
02 follow returned callers/callees
03 read only the exact ranges that explain the path
04 stop when the graph answers the question

Fix a failing test

01 run the narrow test with bash
02 use the compact failure to search the responsible symbol
03 read the implementation + nearby callers
04 batch the fix with edit
05 rerun the narrow test, then the relevant broader check

Make a cross-file refactor

01 search the symbol and its usages
02 read the affected interfaces, not every file
03 apply all known hunks in one edit call
04 run structural/reference verification
05 run typecheck/tests before completion

Resume a long task

01 recall the compact task state
02 search only what changed or is still uncertain
03 continue from the last verified decision
04 do not rebuild context from the old transcript

The point

LemonCrow does not make the model bigger. It makes the loop smaller.

Ranked retrieval reduces exploration. Exact reads reduce carried context. Bounded execution keeps logs from taking over the session. Memory preserves decisions. Verification closes the loop. That is the mechanism the benchmark results are measuring.

Read BENCHMARKS.md Inspect architecture