packages/kilo-docs/pages/getting-started/cost-controls-and-usage-safeguards.md
How much you spend with Kilo Code is shaped by several factors working together:
No single control eliminates cost on its own. The most effective approach combines model selection, context management, task scope, and account-level monitoring together.
This page covers the controls currently available in Kilo Code. For a direct overview of Auto Model tiers and token optimization tips, see Cost Efficiency & Model Selection.
When the agent enters a repeated failure cycle — attempting the same action multiple times without making progress — Kilo pauses and asks for permission before continuing. This is controlled by the doom_loop permission, which defaults to ask.
Where to configure: Settings → Auto Approve (VS Code) or the permission.doom_loop key in kilo.jsonc (CLI).
When to use: Leave this at ask (the default) unless you are running fully unattended automation in a controlled environment. Setting it to deny blocks recovery entirely; allow lets loops continue without interruption.
Every action Kilo takes — reading files, editing code, running shell commands, launching sub-agents — is governed by the permission system. Each tool can be set to allow, ask, or deny. When set to ask, Kilo pauses before executing and you can approve or reject that specific action.
Where to configure: Settings → Auto Approve (VS Code) or the permission section in kilo.jsonc (CLI). See Auto-Approving Actions for the full list of available permissions.
When to use: Keep bash set to ask by default for unfamiliar tasks. You can allow specific safe command prefixes (e.g. git *, npm *) while keeping everything else at ask. This prevents the agent from running expensive or destructive commands in a loop without oversight.
A shield button in the prompt controls lets you toggle auto-approve on and off at runtime without opening Settings. When enabled, pending permission prompts are approved automatically. The state stays synced across the sidebar and open Kilo tabs.
When to use: Turn it on when working on a well-understood, low-risk task that does not need step-by-step review. Turn it off as soon as you want to pause and review the agent's next actions.
Individual accounts stop spending when their balance reaches zero — further requests to paid models return an error and prompt you to add credits. This acts as a hard ceiling on total spend.
Organization accounts can additionally configure per-user daily spending limits. When a member reaches their daily cap, subsequent requests are blocked until midnight UTC, when the limit resets.
Where to configure: Organization spending limits are managed in the organization dashboard at app.kilo.ai. Individual credit top-up is at Settings → Adding Credits.
Requests to free models (kilo-auto/free and other free-tier models) are rate-limited to 200 requests per hour. If you exceed this, requests return HTTP 429 and you must wait before continuing.
processData" generates far fewer steps than "keep fixing everything that looks wrong." Specificity reduces both steps and cost.Conversation history accumulates with every turn. When you finish a task and move on to something unrelated, starting a new session resets the context to just your system prompt and instructions — significantly cheaper than carrying the full prior conversation.
Concise, specific prompts cost fewer tokens. Instead of pasting large blocks of background, describe what you need in plain terms and let the agent ask for files if it needs them. Repeating context you already provided earlier in the session is rarely necessary.
@file and @folder mentions selectivelyAttaching an entire folder sends every file in it as input tokens, even if only one or two files are relevant. Use @file with specific paths rather than broad directory mentions. When reviewing a bug, include only the file containing the bug and its closest dependencies.
Kilo automatically skips a set of directories including node_modules, dist, build, .git, __pycache__, .cache, and vendor. You can add additional paths using permission deny rules in kilo.jsonc or using a .kilocodeignore file at your workspace root.
{
"permission": {
"read": {
"coverage/**": "deny",
".next/**": "deny",
"*": "allow"
}
}
}
Where to configure: kilo.jsonc (VS Code / CLI). See .kilocodeignore for full details.
When a conversation grows long, use /compact in the chat (also searchable as smol or condense) to summarize the history and free up context space. Kilo replaces older conversation turns with an anchored summary that captures your goal, constraints, progress, and next steps.
Auto-compaction is enabled by default — Kilo automatically compacts when approaching the context window limit so you do not need to intervene manually.
Where to configure: Toggle auto-compaction in Settings → Context (VS Code) or set compaction.auto in kilo.jsonc. Configure the trigger threshold with compaction.threshold_percent (e.g. 80 to compact at 80% of the model's context window).
You can also configure a cheaper model specifically for compaction, so summarization does not consume frontier model tokens:
{
"agent": {
"compaction": {
"model": "anthropic/claude-haiku-4-5"
}
}
}
See Context Condensing for full configuration options.
Every token you allocate to model output reduces how much conversation history can remain in the context window. For routine coding tasks, keep Code mode at 16k max output tokens or below. Raise the limit only in Architect or Debug modes where extended reasoning is useful.
Where to configure: Model settings in the Kilo Code UI, or the limit.output key in custom model configuration.
Encode recurring guidance — coding standards, project conventions, preferred libraries — in your AGENTS.md or custom instructions once. This avoids repeating the same context in every prompt, and prompt caching means stable instructions are served from cache at a discounted rate on supported providers.
MCP tool definitions are included in the system prompt sent with every request. If you are not using MCP features, disable MCP servers in Settings → Agent Behaviour → MCP Servers. This can meaningfully reduce per-request system prompt size.
See MCP Overview for details.
Kilo automatically applies prompt caching on supported providers. Repeated context — your system prompt, stable file contents, and tool definitions — is reused from cache at a discounted rate. No configuration is required to benefit from this.
Different tasks benefit from different model characteristics. Routing work to the right model reduces cost without sacrificing quality. Kilo has auto-models that can help you control costs; more information is available in Auto Model.
| Task type | Suggested approach |
|---|---|
| Quick questions, syntax lookups, simple formatting | kilo-auto/efficient or a lightweight model |
| Routine edits, test generation, straightforward refactors | kilo-auto/efficient or a mid-tier model |
| Complex debugging, tracing unexpected behavior | kilo-auto/frontier or a strong reasoning model; Debug mode |
| Architecture planning, design decisions | kilo-auto/frontier; Architect mode |
| Repository-wide analysis or search | A model with a large context window (256K+); Architect mode |
| Code review and summarization | kilo-auto/efficient or a cost-effective model |
| Automated background tasks (CI, scripting) | kilo-auto/efficient or kilo-auto/free |
Use the model selector dropdown in the Kilo Code chat interface to switch models for the current session. In the CLI, pass the --model flag to kilo run or use the model picker in the TUI (Ctrl+X m or /models).
You can set a default model for each agent (Code, Architect, Debug, Plan, or a custom subagent) independently:
kilo.jsonc directly.agent.<name>.model in kilo.jsonc.{
"agent": {
"code": {
"model": "kilo-auto/efficient"
},
"architect": {
"model": "kilo-auto/frontier"
}
}
}
This lets you run cost-effective models for implementation while automatically routing planning tasks to a more capable model.
Enterprise organizations can restrict which models team members may use. See Enterprise Cost Controls below.
For full guidance on model selection, see the Model Selection Guide.
The following controls are available to organizations and, where noted, are exclusive to Enterprise plans.
Enterprise organization owners can block specific models or entire providers for all team members using the Providers & Models page in the dashboard. The system uses a blocklist approach — everything is allowed by default, and admins explicitly block what should not be accessible.
Blocking a provider blocks all current and future models from that provider. Filters are available for:
Only Owners can modify model access controls. Individual members cannot override organization-level restrictions.
Where to configure: Dashboard → Providers and Models (Enterprise only). See Model Access Controls.
How it helps: Prevents accidental use of high-cost frontier models; enforces data residency or compliance requirements; limits cost surface by allowing only approved models.
All organization members draw from a single shared credit balance. Administrators can configure:
Where to configure: Dashboard → Billing.
The Usage tab of the organization dashboard provides:
This gives administrators visibility into which team members, models, and projects are driving the majority of spend.
Where to access: app.kilo.ai → Usage tab.
Dashboard administrative actions (model restrictions, spending limits, billing management) are gated by role. Only Owners can modify model access controls and organization-level settings. Owners and Admins can view per-user usage data.
kilo-auto/efficient as the default modelkilo-auto/free for low-stakes questions and explorationcompaction.threshold_percent: 80 to compact earlierdoom_loop permission at ask@file mentions with specific paths instead of @folder for whole directories@file mentions with specific paths instead of attaching whole directoriescoverage/**, .next/**, etc.)anthropic/claude-haiku-4-5 or equivalent)kilo-auto/efficient to Code and Debug agents for everyday workkilo-auto/frontier to Architect (or Plan) agent for planning taskskilo-auto/efficient as the compaction model for all agents{
"agent": {
"code": { "model": "kilo-auto/efficient" },
"debug": { "model": "kilo-auto/efficient" },
"architect": { "model": "kilo-auto/frontier" },
"compaction": { "model": "anthropic/claude-haiku-4-5" }
}
}
The snippet below is a ready-to-copy kilo.jsonc that turns on every available cost-control knob at its most restrictive setting. Drop it into your project root (or your global ~/.config/kilo/kilo.jsonc) and adjust individual values upward as you get comfortable with how each one behaves.
{% callout type="tip" %}
This configuration uses only kilo-auto/efficient.
{% /callout %}
{
"$schema": "https://app.kilo.ai/config.json",
// ── Model selection ──────────────────────────────────────────────────────
// Route all requests through the two lowest-cost Kilo Auto tiers.
// kilo-auto/efficient: lowest-cost paid tier (classifies each request by
// difficulty and routes to the cheapest benchmark-proven model).
"model": "kilo-auto/efficient",
"subagent_model": "kilo-auto/efficient", // default model for Task-tool subagents
// ── Per-agent model and step limits ─────────────────────────────────────
// Assign the cheapest suitable tier to each agent and cap how many
// agentic iterations it may take before it must produce a text-only reply.
// Raise `steps` for agents that need more room; lower it to tighten cost.
"agent": {
"code": {
"model": "kilo-auto/efficient",
"steps": 20 // hard cap on agentic iterations per turn
},
"plan": {
"model": "kilo-auto/efficient",
"steps": 10
},
"debug": {
"model": "kilo-auto/efficient",
"steps": 20
},
"ask": {
"model": "kilo-auto/efficient",
"steps": 5
},
"orchestrator": {
"model": "kilo-auto/efficient",
"steps": 10
},
"explore": {
"model": "kilo-auto/free",
"steps": 15
},
"general": {
"model": "kilo-auto/efficient",
"steps": 15
},
// Dedicated agents for background summarization
"compaction": { "model": "kilo-auto/free" },
"title": { "model": "kilo-auto/free" },
"summary": { "model": "kilo-auto/free" }
},
// ── Compaction (context management) ─────────────────────────────────────
// Auto-compact aggressively to keep conversation history short and cheap.
"compaction": {
"auto": true, // enable automatic compaction (default: true)
"threshold_percent": 50, // compact when context reaches 50% full (default: ~80%)
"prune": true, // prune old tool outputs to recover context space
"tail_turns": 1, // keep only 1 recent user-turn verbatim after compaction
"preserve_recent_tokens": 2000, // cap on tokens preserved verbatim from recent turns
"reserved": 8000 // token buffer reserved so compaction itself doesn't overflow
},
// ── Tool output truncation ───────────────────────────────────────────────
// Clip large tool responses early so they don't bloat the context window.
// Increase these if the agent needs more output (e.g. long test logs).
"tool_output": {
"max_lines": 500, // default: 2000 lines
"max_bytes": 10240 // default: 51200 bytes (~50 KB)
},
// ── Permission safeguards ────────────────────────────────────────────────
// "ask" means Kilo pauses and requires your approval before executing.
// This prevents runaway loops from autonomously consuming tokens or making
// irreversible changes. Flip individual entries to "allow" once you trust them.
"permission": {
"bash": "ask", // shell commands (highest risk of runaway cost)
"edit": "ask", // file writes and edits
"task": "ask", // launching sub-agents (each sub-agent = extra LLM requests)
"webfetch": "ask", // outbound HTTP fetches
"websearch": "ask", // web search calls
"doom_loop": "ask" // repeated-failure loop detection — always keep at "ask" or "deny"
},
}
Every field in this block is documented in the sections above. Use it as a starting point, then relax individual settings (for example, setting permission.edit to "allow" for a trusted project, or raising compaction.threshold_percent to 70 if compaction feels too aggressive) as you build confidence in how the agent behaves.
If your spend is higher than expected:
/compact to reset themdoom_loop guard removes the friction that normally slows down runaway loopsFor further reading: 4 Levers to Take Control of Your AI Spend