Tool reference
localexec exposes eight tools. Every result is a short JSON string. Full diffs and logs are written to <project>/.localexec/ instead of being returned.
implement_task
Has the local model implement one small step, then runs the project's checks. Failures go back to the model until max_attempts is reached. It never commits.
| Parameter | Type | Description |
|---|---|---|
task_id | string | Unique id such as T1-add-retry. Letters, digits, ., _ and -, up to 64 characters. |
spec | string | Precise instructions: goal, signatures, edge cases and acceptance. |
files_to_edit | list of paths | One or two project-relative paths. New files must be listed too. |
context_files | list of paths, optional | Read-only files the model should see. |
checks | list of names, optional | Checks from .localexec.json. Default: all of them. |
symbols | list of path::name, optional | Show the model only these functions or classes, plus nearby lines. Names may be Class.method or a unique suffix. |
A passing result:
{"status":"passed","attempts":1,"files":["calc.py"],"stat":"+1 -1 in 1 file","patch":".localexec/T1.patch","log":".localexec/T1.log","escalate":false,"why":"all checks passed"}Always present: status, attempts, escalate and why. Present when relevant: files, stat, patch, log, question (blocked), error, failed_check with the failing check's output, warnings, truncated (context files that were cut to fit) and note (an earlier attempt's changes remain in the tree). The statuses are explained in Using it with Claude.
run_checks
Runs configured checks and returns a pass or fail summary. It takes the same write lock as implement_task.
| Parameter | Type | Description |
|---|---|---|
names | list of names, optional | Checks to run. Default: all. |
task_id | string, optional | Run file-scoped checks on this task's files. Without it, they run on the files of all open tasks plus uncommitted tracked changes. |
{"status":"failed","results":[{"name":"standards","ok":true,"secs":0.1},{"name":"pytest","ok":false,"secs":4.2}],"log":".localexec/run_checks.log","failed_check":"pytest"}A check that was filtered out by files_filter is reported with "skipped":true. For a full run, configure a second check without {files}.
revert_task
Undoes a task by restoring its backups from .localexec/<id>.orig/. An interrupted run can be reverted too.
| Parameter | Type | Description |
|---|---|---|
task_id | string | The task to undo. |
dry_run | boolean, default false | Report what would happen without changing anything. |
force | boolean, default false | Also restore files that were edited after the task. |
{"status":"reverted","restore":["calc.py"],"remove":[]}Files skipped because they changed after the task are listed under skipped. Reverting an already reverted task returns already_reverted.
list_tasks
list_tasks(limit=20) returns total and a tasks list with one line per task: the id, the status, a reverted marker if it was undone, the attempts, the files and the start of the spec. Use it after losing context.
show_patch
show_patch(task_id, file=None, max_lines=60) returns a task's diff reduced to changed lines plus one line of context, with a note when lines were dropped. Pass file to see one file. max_lines is clamped between 5 and 300.
status
Health check with no parameters. It reports the project name, the configured model and checks, whether the model is installed and loaded in Ollama, and the number of recorded tasks. If the model is missing, the result includes a hint to run ollama list. If Ollama is unreachable or the config is invalid, status is error and the reason is included.
outline
outline(path, max_items=60) lists one file's functions, classes, methods and constants as start-end|kind|name|signature, capped at about 3,000 characters. It reads Python with ast and TypeScript, TSX, JavaScript and JSX with tree-sitter. Use it to plan, and to get exact names for symbols.
find
find(pattern, glob=None, max_results=30, ignore_case=False) searches the project with a regular expression and returns path:line:text lines. Ignored paths, binary files, files over 1 MB and non-UTF-8 files are skipped, and skipped counts them. Each line has a timeout, so a catastrophic pattern returns an error instead of hanging the server. Example glob: src/**/*.py.
Errors are always short JSON, never a traceback: {"status":"error","error":"...","escalate":false}.