Body

I’ve been playing with the current crop of AI agent runtimes and noticed the same pattern over and over:

• One process both reads untrusted content and executes tools
• API keys live in plaintext dotfiles
• There’s no audit log of what the agent actually did
• There’s no concept of the agent’s goal, so drift is invisible
• When something goes wrong, there is nothing to replay or verify

So I built ClearFrame, an open-source protocol and runtime that tries to fix those structural issues rather than paper over them with prompts.

What ClearFrame does differently

• Reader / Actor isolation Untrusted content ingestion (web, files, APIs) runs in a separate sandbox from tool execution. The process that can run shell, write_file, etc. never sees raw web content directly.
• GoalManifest + alignment scoring Every session starts with a GoalManifest that declares the goal, allowed tools, domains, and limits. Each proposed tool call is scored for alignment and can be auto-approved, queued for human review, or blocked.
• Reasoning Transparency Layer (RTL) The agent’s chain-of-thought is captured as structured JSON (with hashes for tamper‑evidence), so you can replay and inspect how it reached a decision.
• HMAC-chained audit log Every event (session start/end, goal scores, tool approvals, context hashes) is written to an append-only log with a hash chain. You can verify the log hasn’t been edited after the fact.
• AgentOps control plane A small FastAPI app that shows live sessions, alignment scores, reasoning traces, and queued tool calls. You can approve/block calls in real time and verify audit integrity.

Who this is for

• People wiring agents into production systems and worried about prompt injection, credential leakage, or goal drift
• Teams who need to show regulators / security what their agents are actually doing
• Anyone who wants something more inspectable than “call tools from inside the model and hope for the best”

Status

• Written in Python 3.11+
• Packaged as a library with a CLI (clearframe init, clearframe audit-tail, etc.)
• GitHub Pages site is live with docs and examples

Links

• Homepage / docs: https://ibrahimmukherjee-boop.github.io/ClearFrame/
• Code: https://github.com/ibrahimmukherjee-boop/ClearFrame

I’d love feedback from people building or operating agents in the real world:

• Does this address the actual failure modes you’re seeing?
• What would you want to plug ClearFrame into first (LangChain, LlamaIndex, AutoGen, something else)?
• What’s missing for you to trust an agent runtime in production?