Cost and Usage Optimization

Understanding token usage

Every interaction with an AI model is measured in tokens. A token is roughly 4 characters of English text, or about three-quarters of a word. When you send a prompt to a model, you pay for two things: the tokens you send in (input tokens) and the tokens the model generates back (output tokens).

Input tokens are typically cheaper than output tokens. For example, Claude Sonnet charges around $3 per million input tokens and $15 per million output tokens. That 5x difference matters because it changes how you should think about optimization.

The biggest driver of input token cost is your context window. Every message in your conversation, every file the agent has read, and every tool result contributes to the context that gets sent with each new request. As your session grows, so does the cost of each interaction.

How context size affects cost

Here is a concrete example. Suppose you are using Claude Sonnet at $3 per million input tokens:

The difference between a lean session and a bloated one can be 20x or more. The rest of this guide focuses on keeping that context lean.

Context compaction

Context compaction is the single most effective tool for reducing costs during a session. When your context grows too large, you can compress it without losing the important information the agent needs to keep working.

Use the /cc slash command to trigger compaction manually:

# Compact the current context
/cc

# Autohand will summarize the session so far,
# keeping key decisions, file states, and task context
# while removing redundant conversation history

Compaction tiers

Autohand supports three compaction levels. Each one trades more context detail for a greater reduction in token count.

Automatic compaction

Autohand can compact automatically when your context reaches a threshold. Enable this in your config:

// ~/.autohand/config.json
{
  "contextCompaction": {
    "auto": true,
    "threshold": 0.8,
    "tier": "medium"
  }
}

With this configuration, Autohand will automatically compact when the context reaches 80% of the model's maximum window. This prevents you from hitting the limit unexpectedly and avoids the cost spike that comes with very large contexts.

Model selection for cost

Not every task needs the most powerful model. Using a smaller, cheaper model for simple work can cut your costs dramatically without affecting quality.

When to use cheaper models

• Formatting code, fixing indentation, adding semicolons
• Generating boilerplate (interfaces, types, test scaffolds)
• Simple find-and-replace across files
• Answering quick factual questions about syntax
• Writing commit messages and changelogs

When to use premium models

• Architecture decisions and system design
• Debugging complex race conditions or memory leaks
• Security reviews and vulnerability analysis
• Refactoring large interconnected modules
• Writing business logic with edge cases

Price comparison

A session that costs $5 with Claude Sonnet might cost $0.15 with Claude Haiku for the same number of turns. Use the /model command to switch mid-session when the task complexity changes.

Auto-mode cost controls

Auto-mode runs the agent in a loop, which means it can accumulate costs quickly if left unchecked. Autohand includes several built-in safeguards to prevent runaway spending.

The maxCost setting

Every auto-mode session has a maximum cost limit. When the total API cost reaches this limit, the loop stops.

# Set a $5 cost limit for this run
autohand --auto-mode "Add input validation to all API endpoints" --max-cost 5

# Set a global default
autohand config set automode.maxCost 10

The default is $10. For exploration or experimental tasks, consider lowering this to $2 or $3 until you have a feel for how many iterations the task requires.

Checkpoint intervals

Autohand creates git checkpoints at regular intervals during auto-mode. If you stop a session early because of cost, you still have the work completed up to the last checkpoint.

# Checkpoint every 3 iterations instead of the default 5
autohand --auto-mode "Migrate tests to vitest" --checkpoint-interval 3

Iteration limits

Set a maximum number of iterations to cap how long the agent works. Fewer iterations means less total cost.

# Limit to 20 iterations
autohand --auto-mode "Fix all TypeScript errors" --max-iterations 20

Circuit breaker

The circuit breaker detects when the agent is stuck and not making progress. It stops the loop if it sees three consecutive iterations with no file changes, or five iterations producing the same error. This prevents the agent from burning tokens on a problem it cannot solve in its current state.

Pipe mode efficiency

Pipe mode runs Autohand non-interactively, which means no back-and-forth conversation. The agent receives input, produces output, and exits. This is naturally cheaper because each run starts with a fresh, minimal context.

# Analyze a file without session overhead
cat src/auth.ts | autohand -y --prompt "List all exported functions"

# Batch process multiple files
for file in src/api/*.ts; do
  cat "$file" | autohand -y --model claude-haiku \
    --prompt "Add JSDoc comments to all exported functions" > "${file}.documented"
done

# Quick code review on a diff
git diff HEAD~1 | autohand -y --prompt "Review for bugs and security issues"

Combine pipe mode with a cheaper model for batch operations. Processing 50 files with Claude Haiku in pipe mode costs a fraction of what an interactive session with Claude Sonnet would cost for the same work.

Extended thinking costs

Extended thinking lets the model reason through complex problems step by step before generating its response. This produces better results for hard tasks, but it uses significantly more tokens because the model generates its reasoning chain as output tokens.

A request that normally generates 500 output tokens might generate 2,000 to 5,000 tokens with extended thinking enabled. Since output tokens are the more expensive half of the equation, extended thinking can multiply the cost of a single request by 2x to 5x.

When to use extended thinking

• Debugging a complex issue with multiple possible root causes
• Planning an architecture that involves several interacting systems
• Analyzing security vulnerabilities that require tracing data flow
• Solving algorithmic problems with tricky edge cases

When to skip it

• Simple code generation or formatting
• Writing documentation or comments
• Straightforward find-and-replace refactoring
• Quick questions with factual answers

# Enable extended thinking for a specific task
autohand --extended-thinking "Debug why the payment webhook fails intermittently"

# Disable it (default) for routine work
autohand "Add error handling to the upload endpoint"

Leave extended thinking off by default and turn it on for specific tasks that need deep reasoning. This keeps your baseline costs low.

Reducing context size

Beyond compaction, there are several habits that help keep your context small from the start.

Write focused prompts

Instead of pasting an entire error log, paste only the relevant lines. Instead of asking the agent to read a whole directory, point it to the specific file you need help with.

# Less efficient: agent reads everything
autohand "Fix the bug in src/"

# More efficient: agent reads what it needs
autohand "Fix the null check in src/auth/validate.ts line 42"

Use /clear between tasks

When you finish one task and start another unrelated one, clear the context. There is no reason to carry the history of your database migration into a CSS debugging session.

# Clear context and start fresh
/clear

# Now start the new task with a clean slate
"Fix the mobile navigation dropdown"

Limit workspace scope

Use --add-dir to restrict which directories the agent can see. This prevents it from reading large files that are not relevant to your task.

# Only give the agent access to the API directory
autohand --add-dir src/api "Add rate limiting to all endpoints"

# Exclude build artifacts and node_modules
autohand --exclude "dist,node_modules,*.min.js" "Review the project structure"

Exclude large files

Lock files, generated code, and bundled assets can add thousands of tokens to context without providing useful information. Configure exclusions in your project's .autohand/config.json:

// .autohand/config.json (project level)
{
  "exclude": [
    "package-lock.json",
    "yarn.lock",
    "bun.lockb",
    "dist/**",
    "*.min.js",
    "*.map",
    "coverage/**"
  ]
}

Local models for zero cost

Running models locally eliminates API costs entirely. After the one-time setup, every request is free. The tradeoff is that local models are generally less capable than cloud frontier models, and they require decent hardware.

Quick setup with Ollama

# Install and start
brew install ollama
ollama serve

# Pull a good coding model
ollama pull qwen2.5-coder:14b

# Configure Autohand
autohand config set provider ollama
autohand config set model qwen2.5-coder:14b

Best local models for coding

Quality tradeoffs

Local models at 7-14B parameters handle single-file edits, code completion, and simple refactoring well. They struggle with multi-file reasoning, complex architecture decisions, and tasks that require broad knowledge of APIs and libraries. For those tasks, a cloud model is worth the cost.

A practical workflow: use a local model for day-to-day coding and switch to a cloud model when you hit something the local model cannot handle. This keeps your average cost very low while still giving you access to the best models when you need them.

Monitoring usage

Autohand tracks token usage and costs throughout your session so you can see exactly where your budget is going.

Session stats

# Check current session usage
/stats

# Output:
# Session Statistics
# ─────────────────────────────
# Duration:       45 minutes
# Requests:       23
# Input tokens:   412,500
# Output tokens:  38,200
# Total cost:     $1.81
# Model:          claude-sonnet-4
# Context size:   67,000 tokens (33% of limit)

Token counts in output

Enable token counting in your config to see per-request costs:

// ~/.autohand/config.json
{
  "showTokenUsage": true
}

With this enabled, each response will show a footer like [tokens: 2,340 in / 890 out / $0.012] so you can see which requests are expensive.

Tracking costs over time

Autohand logs session summaries to ~/.autohand/usage.log. You can review this file to understand your spending patterns:

# View recent usage
autohand usage --last 7d

# Output:
# Last 7 days
# ─────────────────────────────
# Sessions:      34
# Total cost:    $18.42
# Avg per session: $0.54
# Most used:     claude-sonnet-4 (28 sessions)
# Highest cost:  $3.20 (auto-mode: migrate tests)

Quick reference

Here is a summary of every optimization technique covered in this guide, ranked by how much impact it has and how easy it is to set up.

The highest impact change for most developers is combining context compaction with model switching. Compact your context regularly, and drop to a cheaper model when the task is simple. These two habits alone can reduce your monthly costs by 50% or more.