Using it with Claude

localexec works best when Claude does the thinking and the local model does the typing.

• The loop
• Write a spec
• Size tasks for a small model
• Read the result
• Review and undo
• When Claude should write the code itself

The loop

1. Plan. Explore the code, then split the change into tasks of one or two files each.
2. Write a spec for each task in the fixed format below.
3. Delegate each step with implement_task. Do not re-read files after a passed result: the compact result is the source of truth.
4. Read the result and act on its status (see the table below).
5. Review with show_patch and leave the changes in the working tree. localexec never commits.

Call status once at the start of a session. After losing context, call list_tasks instead of guessing what is done.

Write a spec

Pass the spec as the spec parameter. Keep the fields in this order.

task_id:        T3-retry-backoff              # unique, [A-Za-z0-9._-]
files_to_edit:  [src/client.py]               # 1-2 files; new files must be listed too
context_files:  [src/errors.py]               # optional, read-only reference
checks:         [ruff, pytest]                # optional; default is all configured checks

spec: |
  GOAL: <one sentence>
  FILES: <each file and what changes in it>
  STEPS:
    1. <concrete change>
    2. <concrete change>
  SIGNATURES (exact):
    def fetch(url: str, *, retries: int = 3) -> bytes: ...
  EDGE CASES:
    - <input -> expected behaviour>
  DO NOT: <things to leave alone>
  ACCEPTANCE: <which checks must pass, observable behaviour>

Four habits make the difference:

• Name the function or class to change, and give exact signatures.
• List edge cases as input and output pairs.
• Say what not to touch.
• If a test must be added, put the test file in files_to_edit and give the cases.

Size tasks for a small model

List only the one or two files to change in files_to_edit, and only the files the model must see in context_files. Before writing a spec, look for an existing helper to reuse with find, and name it in the spec. Ask for new helpers by name and signature so functions stay short. If a task would push a file past about 300 lines, plan the split first and make the new file its own task.

Large files

Instead of sending a whole file, pass symbols such as src/a.py::parse or web/App.tsx::App.render. Use outline to get the exact names. The model then sees only those symbols plus five lines of context. Edits elsewhere in the file are still located by their search text, and whole-file rewrites of excerpted files are refused.

Read the result

A result with a warnings list is a hint to plan a split soon. failed_check: standards with escalate: true means a file is over its limit: split it instead of retrying.

Review and undo

show_patch returns the changed lines with one line of context, capped, so reviewing is cheap. revert_task restores the files a task changed and removes the files it created. Use dry_run first if you want to see what would happen. Files edited after the task are skipped unless you pass force.

When Claude should write the code itself

Write it yourself when escalate is true and a better spec has not helped, or when the task is security-sensitive: authentication, permissions, migrations, concurrency, secrets or cryptography. Those are not good candidates for a small local model.