ClearLoop: Clear AI Control Plane for Coding Agents

ClearLoop is the user-facing VS Code layer between humans and AI coding agents. It is now a standalone sibling project at:

E:\1_agents_space\9_AGI\ClearLoop

BestQ-A remains the reasoning / memory / causal core. ClearLoop owns the VS Code extension, local Rust backend, agent UI, packaging, and smoke validation. The shared contract is explicit local records, starting with .bestqa/agent-runs/<run>/.

The product thesis is simple: AI is strong at discovering relevance, but humans need a stable handle on causality. ClearLoop turns relevant model output into explicit task state, causal hypotheses, evidence, verification, and reusable memory.

The first working scaffold is the CLI handoff smoke path:

ClearLoop: Create CLI Agent Handoff Smoke

It writes a durable .bestqa/agent-runs/<run>/ directory with handoff.md, manifest.json, README.md, and result.md so Codex CLI / Claude Code CLI work can be reviewed and replayed instead of disappearing into chat state. See docs/clear-ai-cli-handoff.md.

Core product documents:

• docs/product/relevance-to-causality.md
• docs/product/workflow-baseline.md
• docs/product/session-refactoring.md
• docs/architecture/run-ledger.md

loom.com/share/752aa7884c304b609b71b37e75e8ab74 Overview of the video - YouTube Video

Ollama Model Installation

Install the Ollama App in your system

Run this command from your terminal:

ollama run qwen2.5-coder

For running Second time

For Next time run:

ollama serve

In another terminal run:

ollama run qwen2.5-coder

For stoping the LLM:

ollama stop qwen2.5-coder

This project began as a simplified planning-layer VS Code extension. Its direction is now Clear AI: a local-first interface that helps people and AI collaborate through explicit state instead of opaque chat-only reasoning.

Built in TypeScript with a React-based webview UI and a local Rust backend. ClearLoop should stay local-first: API keys and agent credentials belong on the user's machine, and run evidence should be readable as files before it becomes any higher-level memory.

Why This Exists

• Human interface: ClearLoop is the layer where people can inspect, steer, and verify AI work.
• Explicit causality: Relevant observations become hypotheses, evidence, actions, outcomes, and verification records.
• Agent integration: Codex CLI, Claude Code CLI, and other local agents should run through auditable handoff records.
• Stable improvement: Good runs should become reusable memory only after evidence and verification pass.

This is still early. The current backend binary remains codesail-server as an internal implementation name until a later, isolated rename.

Current Product Surface

• CLI handoff scaffold: create an auditable handoff for Codex CLI, Claude Code CLI, or another local agent.
• Explicit workflow baseline: organize work as intent, clarification, plan, review, breakdown, execution, verification, and memory.
• Session refactoring: turn one-off AI/CLI sessions into reusable questions, answers, plans, evidence, verification, and causal patterns.
• Run ledger direction: capture task state, evidence, commands, outputs, diffs, verification, and memory gates as local records.
• VS Code control plane: expose agent work through a human-facing sidebar instead of hiding it inside chat state.

Requirements

• VS Code: v1.93.0+.
• Node.js: v20+ (for local dev/build).
• Rust toolchain: required when rebuilding the local backend.

Installation & Setup

1. Install Extension:

   • Search "ClearLoop" in VS Code Extensions view (Ctrl+Shift+X) after a package is published.
   • Install and reload VS Code.

2. Optional: GitHub Login:

   • In sidebar footer → "Sign In with GitHub" → Authorise in browser.
   • Shows your profile in the UI.

3. Usage:

   • Open ClearLoop sidebar.
   • Use ClearLoop: Create CLI Agent Handoff Smoke.
   • Inspect the generated .bestqa/agent-runs/<run>/ directory.
   • Run the chosen local agent explicitly, then record evidence and verification.

Changelog

2.0.0 (2025-10-13)

• Bundled deps for reliable publishing.
• Enhanced planning output for better agent integration.