Local coding and the cloud¶
Chapter 10 of the ResearchTools manual. Back to table of contents.
This chapter answers one question for any piece of coding: does it run on the cloud, through
local-coder, through aider, or on a session you switched by hand, and who decides. It also
says what the process costs, what stops it, and what the dashboard shows. The rules behind it are
R38 and R39 in .claude/rules/workflows.md, and they bind every project on a machine where
ResearchTools is installed. R39 says that no cloud model generates code: the cloud designs, and
a local model codes through the aider-setup kit (aider-plan.ps1 for one plan, aider-night.ps1 for several).
Why local coding exists¶
A local model generates code on your GPU, so that generation costs no cloud tokens. The cloud
still pays for the plan, for a small wrapper on a low-cost cloud model that drives the local
model, and for the review of the result. Local coding saves tokens only while four things hold: the plan is
dispatched to the local agent as a whole, the review loop is bounded, the explanation of the
mechanism is correct, and you can see what the local model is doing. Four failures defeated it
before this chapter: local-coder was never dispatched because it took one task per call, the
review loop of R35 repeated until no finding with no maximum (seven unbounded iterations were
measured on 2026-10-17), the documentation gave a wrong reason for the bridge, and local work
was barely visible in the dashboard.
The process¶
flowchart TD
A0["Coding request"] --> X["Consult both memories<br/>local-writer: vault and graph<br/>silent, distilled hits"]
X --> A["Brainstorm with the hits<br/>superpowers:brainstorming"]
A --> B{Single step, no deliverable?}
B -- yes --> C[Answer directly]
B -- no --> D["Write spec, plans and progress<br/>superpowers:writing-plans"]
D --> E[Ask the owner the bounds]
E --> F[Write the header: executor, tier, bounds]
F --> G{Which executor?}
G -- work that writes no code --> H["cloud: superpowers:executing-plans"]
G -- one plan --> J[local-coder: wrapper mounts the plan, runs the kit and reviews, the kit's writer model writes the code]
J --> K{Plan reply fits the coder window?}
K -- yes --> L[tier simple or standard]
K -- no --> M[tier large, session role]
G -- unattended night --> N[aider: writer and reviewer]
H --> O[Worktree branch]
L --> O
M --> O
N --> O
O --> P[Review round on the diff]
P --> Q{"Safe to merge?<br/>suite green, no Critical or High finding"}
Q -- yes --> Y["Memory upkeep<br/>local-writer writes lessons to the vault<br/>and updates the graph, silent"]
Y --> R[Pull request, owner merges]
R --> Z["After the merge: finish-branch skill<br/>finish-branch.ps1 -Refresh removes the worktree<br/>and the branches, moves the plans to done,<br/>then setup.ps1 -Update refreshes this machine"]
Q -- no --> S{Bound reached?}
S -- no --> T[Fix, failing test first] --> P
S -- yes --> U[Stop, report what remains, ask the owner]
F -.-> V[rt-observe follows every stage]
The source of this diagram is local-coding-flow.mmd, and a test fails when the two differ. Reading it from the top:
- Before the brainstorm,
local-writerconsults both memories, the Obsidian vault for past decisions and failures and the code graph for questions about this code, and returns distilled hits that are folded into the brainstorm. The session never reads either itself, and the consult prints nothing in the chat. - A request that is a single step with no deliverable of its own, such as reading one file, is answered directly. Anything larger gets plan files first.
- The session asks you for the review bounds before it writes the plan header, because the header carries them.
- The executor decision has three outcomes: the session itself runs work that writes no code,
one plan goes to
local-coder, and several plans or an unattended night go to aider. - For
local-coderthe question is whether each plan's prompt plus reply fits the coder window. If it does not and the plan cannot be split, the plan takes the large tier. - Every path ends in the same place: a worktree branch and a review round on its diff. The loop stops when the branch is safe to merge, meaning the full suite is green and a re-graded round leaves no Critical or High finding, minors being deferred and listed. Otherwise a round that still finds something is fixed with a failing test first, until a bound stops the loop and the session reports what remains and asks you.
- A safe branch gets a last memory upkeep:
local-writerwrites the lessons to the vault and updates the graph for the code that was added, then the pull request opens and you merge.
Choosing an executor¶
| Situation | Executor | Why it saves cloud tokens |
|---|---|---|
| Work that writes no code (R39): judgment, security review, design, prose, data files | The session itself, with executing-plans |
Nothing to save: the work needs the best model |
| One plan, a test per step | local-coder: aider-plan.ps1 on a small kit project mounted for that plan outside the repository, with the kit's writer model and its required reviewer audit |
The cloud pays for the plan and the review; the code is generated locally and no wrapper is needed to start |
| Several plans, or an unattended night with no interactive session | aider: aider-night.ps1 (spec, plan files, progress, a writer model and a reviewer model) |
No interactive harness is involved once the run starts |
| A whole session on Ollama or Augure | Your manual choice with claude-switch.ps1, never written in a plan |
The session itself is local |
Fit is measured with context_budget.py --role and token_count.py, never guessed. A fix found
by a review round is an - [ ] audit: line the kit runs again, or a small plan of its own,
and follows the same table. A plan that writes code on a machine where the kit has no model is
reported as not executed: the cloud does not write it in its place (R39).
Plan files come first¶
Any coding request beyond a single step gets spec.md, plan<N>.md and progress.md before the
first line of code, with the size ceilings below. Each plan opens with a header:
executor:local-coder,aiderorcloud.tier:simple,standardorlarge.bounds:max_rounds,max_tokensandplateau, positive integers.
The cloud model writes executor and tier after asking you the bounds with a question that
states what each choice costs. The bounds count input, cache creation and output tokens, with
cache reads excluded, because money is not readable from this machine. plan_contract.py
validate <plan> checks the header, the file limit of the tier and the size ceilings, and
plan_contract.py resolve <plan> maps the tier to a resolver role. No plan names a model: the
resolver names the tag at run time.
A skill for every step¶
Rule R36 says that all tasks, any task, need a skill, or an agent that itself uses one. The process of this chapter obeys it at each step, so no step is run from memory. A step with no skill is a gap to report, never a step run without one.
| Step | Skill | Notes |
|---|---|---|
| Request | superpowers:brainstorming |
Explores what is wanted before any plan exists |
| Plan files | superpowers:writing-plans |
Writes the spec, the plans and the progress ledger, with the header |
| Execution | superpowers:executing-plans |
Also loads test-driven development. A local-coder dispatch is made by a session that follows it |
| Review | code-review and security-review |
Under the bounds of R35 |
| Pull request | superpowers:finishing-a-development-branch |
You merge, never the session |
After the merge. The last step is the finish-branch skill (command /finish-branch, or just
say "clean the project"). It runs .claude/skills/finish-branch/scripts/finish-branch.ps1 from the
main clone. The script removes the branch's worktree, deletes the branch locally and on origin,
prunes, and moves the plans folder from docs/superpowers/todo/ to done/. With -Refresh it
then refreshes this machine with setup.ps1 -Update: the suite on the merged main, the mirrors
and the sync to ~/.claude. It also reminds you to publish the site when docs/ changed. It does
nothing until you add -Yes, and it never uses --force.
cd <main clone>
.\.claude\skills\finish-branch\scripts\finish-branch.ps1 -Branch feat/my-branch -Refresh # dry run: lists the steps
.\.claude\skills\finish-branch\scripts\finish-branch.ps1 -Branch feat/my-branch -Refresh -Yes -PlansFolder 2026-10-17-my-effort
It refuses, and says why, when gh finds no merged pull request for the branch, when the local
branch holds commits that were never pushed, when origin's branch has a commit pushed after the
merge or origin cannot be queried (an unreachable origin is never read as a branch that is gone), when the main clone has modified tracked files (R32), when the worktree has uncommitted files,
git-ignored files (add -DiscardIgnored once you have kept what you need) or holds a
junction or a symbolic link (removing it would follow the link and delete its target, R37), when
the main clone is not on main (it never switches the checked-out branch, R32), or when it was
started from inside the worktree it would remove. A second run finds nothing to clean and exits 0.
A similar toolset may replace the three process skills, for example the speckit-* skills
(speckit-specify, speckit-plan, speckit-tasks, speckit-implement), and the plan still
names the skill used at each step. ruflow was named by the owner and is not installed or
verified here, so no step relies on it. Aider is its own harness and sits outside this rule.
Size ceilings¶
The ceilings are not written in the rules. They are the ceilings of
.claude/skills/aider-setup/config/context-budget.json, the single source for every project,
read when this chapter was written on 2026-10-17. The operator cut them on 2026-09-05 because
every token of ceiling is reserved window, which is KV cache, which is model weights pushed off
a small GPU.
| File | Ceiling in tokens |
|---|---|
spec.md |
4000 |
plan.md |
4000 |
progress.md |
2048 |
audit.md |
4096 |
code_file |
16000 |
plan.md applies to each plan<N>.md. A test reads the budget file and fails when this table
drifts from it. To count, run python .claude/skills/loop-engineer/scripts/token_count.py
<file or folder>. With a tokenizer installed it uses the encoder aider uses and says the count
is exact for that encoder. Without one it estimates characters over four and multiplies by 1.25
before a ceiling check, because real over estimated tokens ranged from 0.99 to 1.20 on the
twelve files of this effort (measured 2026-10-17). It never calls an estimate exact. Three older
counters remain on purpose, because the aider kit is standalone: Get-TokenCount in
aider-plan-core.ps1, load_counter in aider-rules-check.py and estimate_tokens in
context_budget.py.
The four paths¶
The session runs the plan. The header says executor: cloud and the session follows
executing-plans in a worktree. This is the path for work that writes no code: judgment,
security review, design, prose and data files (R39).
One plan through local-coder. The plan is mounted as the only plan of a small kit
project outside the repository, created with the kit's own new-project.ps1 (spec.md, plan1.md, a
progress.md whose step lines name their files, and only the existing files the plan reads or changes);
the kit audits those few files, and only the files the plan names come back. aider-plan.ps1 runs it: the kit's writer
model receives the files described in the table below, writes the code and its test, runs the
plan's tests, fixes in its own loop and ticks progress.md with one of four marks and nothing
else (- [ ] open, - [x] done, - [~] done in part, - [!] blocked). The kit's reviewer model then audits the result;
that audit is required. The cloud session reviews the written files with code-review and
security-review under the R35 bounds of the plan header and writes each finding as an
- [ ] audit: line that the kit runs again. It never edits code and never commits. A [!] goes
back to the cloud, which revises the plan. No wrapper is needed to start the run.
An unattended night through aider. Aider keeps its own internal loop: a writer model codes and
tests, and a different reviewer model audits and never edits. It reads spec.md, each
plan<N>.md and progress.md, and a plan header does not change the files it names. See
chapter 14.
A whole session switched by hand. claude-switch.ps1 provides claude-ollama,
claude-augure and claude-cloud. This is your choice and is never written in a plan.
Roles, windows and speed¶
For a local-coder run the models are those of the owner's aider configuration, not a resolver
role: the writer and the reviewer are the ones named in the kit's model-settings.yml
(read by the kit itself, and by this chapter on 2026-11-06). The tier of a plan only sets its file limit. The window of
the writer, read from aider-plan.ps1 -DryRun on 2026-11-06, is 65536 tokens with 39414 left for
the working set after the two always-loaded files, the repository map, the reply reserve and the
harness. Decode speed is not measured here.
| Tier | Models | Window | Source and date |
|---|---|---|---|
| simple, standard, large | The kit's writer, then its reviewer | 65536 tokens (writer) | aider-plan.ps1 -DryRun, 2026-11-06 |
| any | The kit has no model | not applicable | Rule of 2026-11-06 (R39): the plan is reported not executed |
The session resolver role (262144 tokens, about 2.4 tokens per second) remains available to the
bridge for local-writer; it is not used by local-coder.
What the wrapper does and costs¶
local-writer runs on a low-cost cloud model. It assembles one self-contained prompt, checks it
fits the window, runs the bridge with the role and writes the result. local-coder no longer has
a wrapper to start the code: the aider kit builds the prompt itself and talks to Ollama, and the
kit refuses rather than substituting a weaker model or truncating a file. The cloud cost of a
local-coder run is the plan and the R35 review. Measured on 2026-11-05, hand-picked prompts of
1245 to 4225 tokens in a 16384 window cost 366K wrapper tokens on one plan and left the cloud
writing the code, which is why the kit submits aider-setup's full input instead.
What the kit submits for each plan, in this order, with the mandatory per-stage skills for the writer, the reviewer and the reopened plan, sized by the same context-budget.json and
skills.json as aider-setup (an item over its ceiling, or a prompt over the window, is refused and
never truncated):
| Item | Ceiling in tokens |
|---|---|
conventions.md of aider's folder |
2500 |
rules.md of aider's folder |
3500 |
spec.md |
4000 |
| The plan | 4000 |
The skill stage for the step (write, or reopen after a failure or an audit finding) |
per skills.json |
progress.md |
2048 |
| The files the plan names, as they are now | code_file 16000 each |
| Reply reserve | reserve.reply_tokens |
The ceilings are read from the same budget file as the table under Size ceilings (read on 2026-11-05). The reply reserve comes out of the window of the writer model.
The reasoning stays with an edge cloud model, which writes the plans and reviews the result.
This chapter names no model, because the process holds for any cloud model. One limit applies to
all of them: a subagent has no endpoint of its own, so a model from another provider is
reachable only by switching the whole session, which Claude Code does not support. The
claude-augure switch of the paths above is that case.
When memory is read and written¶
Both memories, the vault and the graph, are reached through local-writer and nothing else. The
full table, with how each result is verified, is the Memory rule of
workflows.md. The rows are:
| Event | Action | Target |
|---|---|---|
| Before brainstorming or planning a non-trivial task | Read | Vault: past decisions and failures on the subject. Graph: only for a question about this code |
| Loop start | Read | Vault, same scope as above |
| Checkpoint in a loop | Read | Vault, the project Decisions.md |
| Error recovery | Read | Vault lessons on the error signature |
| A failure with a root cause | Write | Atomic lesson note under the technology folder of the vault |
| Loop checkpoint | Write | Project Decisions.md, and CodeReview.md with the score |
| Significant review finding | Write | Project CodeReview.md, plus an atomic note when the pattern is reusable |
| Gate reached or loop finished | Write | Project index.md properties (score, release) |
| Correction or new method | Write | Atomic method note, and the project Revisions.md |
| Code added or changed | Write | Graph refresh with graphify update on the repository root, AST only unless a document changed |
| End of the task, before the pull request | Write | A last upkeep pass: the lessons, the project log, the graph |
Execution wrapper (executing-plans) and cloud review |
Never read | Nothing: the plan already carries the knowledge |
local-coder |
Never reads or writes | It reports a learning to the session, which hands it to local-writer |
The dispatch runs in the background, as one agent, sequential, never a fan-out. On success it
prints nothing in the chat except one short line of counts and paths, and the session says
nothing about it. The result reaches the session later. A failure is shown in full, and the
session then adapts: a missing note is a write to redo, and a lesson that changes the approach
changes the plan or the spec. A write that is never reported back is treated as not done. The
silence on success is tested in test_memory_silence.py, and the live effect needs the synced
settings of your machine, so it is unverified until a real session shows it.
Review bounds and the two hooks¶
Before the first review round the session asks you for the three bounds and runs
loop_bounds.py init. After each round it runs loop_bounds.py tick --findings N. Two
PreToolUse hooks enforce the contract, both declared in settings.template.json, and each exits
silently when its dependency is absent:
review-loop-guard.pyguards the review skills. It refuses with the command to run when no bounds are declared, and with the bound reached whenmax_rounds,max_tokensor the plateau is spent. A refused call does not consume a round.local-coder-dispatch-guard.pyguards the dispatch oflocal-coder. It refuses a prompt with noPLAN:line, a plan outside the repository or over a ceiling, a plan whose executor is notlocal-coder, and a plan whose tier has no qualified role.
Messages you will meet: "no review-loop bounds are declared for this branch" with the init command, "max_rounds reached for code-review", and "a local-coder dispatch must name its plan". When a bound stops the loop before a clean round, the session reports what remains and asks you whether to raise it. It never opens the pull request on its own.
Every project, and the cloud fallback¶
Once ResearchTools is installed the contract binds every project on the machine: the rule is in
the exported part of .claude/CLAUDE.md, the rules folder is shared, and the hooks come from
the settings template. On a machine with no qualified model for the tier, plan_contract.py
resolve returns the cloud executor with the reason, and the plan is executed in the session.
It never falls back to a weaker local model.
What the dashboard shows¶
rt-observe follows the work from three snapshot sections. local_calls reads a bounded tail of
the bridge log and shows each role with its model, window, calls, tokens and whether it is
active. rounds lists each plan of a round folder with its executor, tier and task counts, and
the review loop of every worktree as rounds used of the maximum. The Real-Time tab draws a lane
and a token ring for each active bridge role, and shows an aider run's fixed cost and task
budget. See chapter 10.
What is verified, unsupported and untried¶
Read from the Claude Code documentation on 2026-10-17:
- Claude Code has one API endpoint per process and no per-subagent endpoint, environment or provider, so a subagent cannot be pointed at Ollama while the main session stays on Anthropic. That, and not the subscription, is why local models go through the bridge.
- Switching the whole session with
claude-switch.ps1works and was measured here, but Anthropic documents that it does not support routing Claude Code to non-Claude models through a gateway, and Remote Control is unavailable while the base URL is not api.anthropic.com. - A model ID Claude Code does not recognise is assumed to have a 200K window unless
CLAUDE_CODE_MAX_CONTEXT_TOKENSis set. Whether that variable is capped at the model's own window is not documented and is untried here.
Also untried until one live firing on this machine: that both hooks fire on their matchers.
Troubleshooting¶
- A review is refused with no bounds: ask for the three bounds, then run the init command the
message names. Whether a review typed by hand reaches the hook is unverified, so declare
--max-rounds 1first as the one-shot. - A dispatch is refused: add the
PLAN:line, or fix the header key the message names. - The plan resolves to the cloud: no model is qualified for the tier's role. Qualify one with the resolver, or run the plan in the session.
- The session role has no window: adopt it again with
--num-ctx, then tryclaude-localonce. - The page shows no local lane: the bridge log has no record with a role yet, and the section says why instead of drawing an empty panel.
← 10 rt-observe & dashboard | Table of contents | 12 PCB design, mixed signals →