Docs
Configuration
You never need a config file to start — the setup wizard writes one for
you. Everything below lives in keepitmovin.config.json in your
project directory and is optional.
Your tools and fallback order
The config lists your enabled tools and the order keepitmovin falls back
through them. Edit both interactively with kim providers
rather than by hand.
Usage probes
Keyword detection reacts after a tool prints a limit banner. When
a tool records its own remaining usage on disk, keepitmovin can read it
and switch before the wall — a usage probe. Today only Codex
exposes this; probes are read-only and fail safe. Configure under
harness.usageProbe:
| Field | Default | Meaning |
|---|---|---|
enabled | true | Master switch for all usage probes. |
thresholdPercent | 95 | Switch when a tool's highest usage window reaches this percent. |
pollIntervalMs | 30000 | How often to re-check while a tool runs. |
Warning-only watchdog
Loop, abnormal Codex burn, and streaming-stall signals produce local
warnings only. They never stop or switch a tool. Configure under
harness.watchdog:
| Field | Default | Meaning |
|---|---|---|
enabled | true | Enable conservative loop, burn, and stall warnings. |
action | "warn" | Warning-only; automatic switching is intentionally unavailable. |
A single tool can override the threshold with its own
usageProbe.thresholdPercent. Run kim doctor to
see current usage for probed tools.
Handoff refresh
keepitmovin keeps the mechanical sections of the
handoff file fresh on a timer and nudges the
active tool if the narrative goes stale. Configure under
harness.handoffRefresh:
| Field | Default | Meaning |
|---|---|---|
enabled | true | Master switch for the refresh/nudge system. |
intervalMs | 60000 | How often the mechanical sections are refreshed. |
nudge.enabled | true | Whether to type the stale-handoff reminder into the tool. |
nudge.staleAfterMs | 300000 | How long the narrative can go unchanged before it's stale. |
nudge.idleForMs | 10000 | The tool must be idle this long before a nudge is sent. |
nudge.minTranscriptGrowthChars | 2000 | Output required before a nudge is warranted. |
Task routing
Opt-in during setup. When enabled, keepitmovin classifies your task locally and picks a model and reasoning effort within your fallback order. It never changes your order and makes no network calls for routing.
kim "Investigate the intermittent auth failure"
kim --tier deep "Implement the approved plan"
kim --model gpt-5.6-sol --effort high "Review the payment migration"
kim --no-route "Use the tool defaults for this task"
Tiers are light, standard, deep,
and max, mapped to appropriate models per tool. Automatic
routing never selects ultra effort — pass
--effort ultra explicitly when the model supports it.
Tool updates
On start, keepitmovin checks your selected tools and asks
before running a tool's own verified updater. It never guesses
an installer. Configure under updates:
| Field | Default | Meaning |
|---|---|---|
checkOnStart | true | Check your tools for updates each time keepitmovin starts. |
mode | "prompt" | "always" runs updates without asking; "off" skips the check. |
includeDisabledProviders | false | Also check tools outside your fallback order. |