Keep your AI agent sharp through long sessions — no hallucinations, no repetition, no context rot.
Most agents start degrading after 50–100 tool calls. Terminal output, file contents, web responses — all of it piles into the same context the agent uses to think. Eventually it loses track, repeats itself, or hallucinates.
CleanContext stops that from happening.
Without CleanContext With CleanContext
Agent calls terminal("find .") Agent calls terminal("find .")
│ │
▼ ▼
Context fills with [Boundary intercepts]
2000 lines of output │
│ Worker runs find, sees 2000 lines
▼ Worker returns: "47 log files found"
Agent gets drunk │
at 250K tokens ▼
Agent receives summary only
Context stays clean
Tool calls are split into two categories:
- Reasoning tools — memory, delegation, clarification. Low noise. Stay in the main context.
- Operational tools — terminal, files, web, browser. High noise. Routed to a worker that executes silently and returns only a clean summary.
The agent's reasoning context never sees raw tool output. It only sees results.
| Without | With CleanContext | |
|---|---|---|
| Context after 50 tool calls | Full of raw output | Clean summaries only |
| Behavior after heavy use | Degrades, repeats, hallucinates | Stays sharp |
| Session length | Limited by context window | Limited by worker budget |
| Token waste | High (reprocessing raw output) | Low (summaries only) |
pip install cleancontextOr copy cleancontext.py into your project. Zero external dependencies.
fromcleancontextimportshould_delegate_tool, build_delegate_args, format_delegate_result# In your agent's tool execution loop:ifshould_delegate_tool(
function_name,
boundary_enabled=True,
routing_policy="delegate",
allowed_mind_tools=MIND_TOOLS,
direct_ops_tools=OPS_TOOLS,
):
args=build_delegate_args(function_name, function_args, ops_cfg, workdir)
worker_response=your_worker_call(args)
result=format_delegate_result(function_name, worker_response)
else:
result=run_tool_directly(function_name, function_args)→ Claude Code, Claude agents (Anthropic)
→ Codex, GPT-4o agents (OpenAI)
→ Hermes, DeepSeek, Qwen — local models via Ollama
→ Any custom agent loop — if it dispatches tool calls, CleanContext fits
boundary:
enabled: truedirect_operations_policy: delegatemind:
provider: openai # openai | anthropic | ollama | deepseekmodel: gpt-4o # claude-sonnet-4-6 | hermes3:8b | deepseek-chatoperations:
provider: openai # use a smaller/cheaper model heremodel: gpt-4o-mini # claude-haiku-4-5-20251001 | qwen2.5:3ballowed_mind_tools:
- clarify
- delegate_task
- memoryblocked_direct_tools:
- terminal
- write_file
- web_search
- browser_navigateSee config.example.yaml for a full reference.
| Approach | Strategy |
|---|---|
| Context compaction | Shrink context after it fills |
| RAG / summarization | Offload memory to external stores |
| Multi-agent (CrewAI, AutoGen) | Split tasks across agents |
| CleanContext | Block noise at the boundary before it enters |
CleanContext is complementary to all of the above. Use it with compaction, RAG, or multi-agent setups.
MIT © Oscar Osuna, 2026