docs: Update README with transparency statement#1
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the project README to position the repository as an educational, minimal C++ agent-loop skeleton and to add an explicit transparency/community-feedback statement to better set expectations.
Changes:
- Reframed the project description as a minimal “educational skeleton” with a transparency note about origins and intended use.
- Added a “What Actually Is This?” section and an “Addressing Community Feedback” section outlining limitations (notably lack of permissions).
- Simplified Windows prerequisite/install and condensed the usage instructions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| A clean-room, highly-performant C++20 reimplementation of the **Claw Code AI Agent Harness**. | ||
|
|
||
| Rather than being a simple chatbot that stops after a single reply, this is an **agentic loop architecture**. It integrates deeply with the Anthropic Messages API, sending explicit tool schemas to the model, and recursively executing local tools (like Bash and File I/O) on behalf of the AI until a task is completed. | ||
| > **Transparency Note (Read First):** \ |
There was a problem hiding this comment.
The blockquote header uses \\ plus a trailing space to force a line break. In CommonMark this will render oddly (often as a literal backslash) and can break markdown linting. Consider removing the explicit backslash and just rely on the blank > line (or use a proper hard-break syntax consistently).
| > **Transparency Note (Read First):** \ | |
| > **Transparency Note (Read First):** |
| ### What is included: | ||
| - **The Agentic Loop:** A recursive runtime that sends prompts, parses `stop_reason: tool_use`, executes local tools, feeds results back, and repeats. | ||
| - **3 Minimal Tools:** | ||
| - `BashTool` (Uses `popen` to shell out. Capped at 50KB output to prevent hangs). |
There was a problem hiding this comment.
BashTool's 50KB cap truncates output, but it does not reliably "prevent hangs" (e.g., a command can block without producing output; Windows path also lacks a real timeout). Please reword this bullet to avoid implying the output cap is a hang-prevention mechanism, or document the actual timeout/truncation behavior per platform.
| - `BashTool` (Uses `popen` to shell out. Capped at 50KB output to prevent hangs). | |
| - `BashTool` (Uses `popen` to shell out. Output is truncated after ~50KB to limit log size; this does not guarantee commands won't hang). |
| ```powershell | ||
| winget install Kitware.CMake | ||
| winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" | ||
| winget install Microsoft.VisualStudio.2022.BuildTools |
There was a problem hiding this comment.
On Windows, winget install Microsoft.VisualStudio.2022.BuildTools alone typically doesn't install the C++ toolchain/workload needed to compile (MSVC, Windows SDK). The previous --override "--add Microsoft.VisualStudio.Workload.VCTools ..." (or an equivalent instruction to add the VC Tools workload) should be kept so the prerequisites are actionable.
| winget install Microsoft.VisualStudio.2022.BuildTools | |
| winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools" |
| ```bash | ||
| ./Release/claw-cpp prompt "List the files in this directory and tell me what they are." | ||
| ``` | ||
| Export your Anthropic API Key to the environment (`$env:ANTHROPIC_API_KEY="sk-ant-..."`), and run the built `claw-cpp` executable. |
There was a problem hiding this comment.
The inline PowerShell example escapes quotes inside a code span: $env:ANTHROPIC_API_KEY=\"sk-ant-...\". In Markdown code spans, quotes don't need escaping, so this will tell users to literally include backslashes. Update it to $env:ANTHROPIC_API_KEY="sk-ant-..." (without backslashes) and consider also documenting the macOS/Linux export ANTHROPIC_API_KEY=... form since this section is now otherwise Windows-specific.
| Export your Anthropic API Key to the environment (`$env:ANTHROPIC_API_KEY="sk-ant-..."`), and run the built `claw-cpp` executable. | |
| Export your Anthropic API Key to the environment (PowerShell on Windows: `$env:ANTHROPIC_API_KEY="sk-ant-..."`; macOS/Linux or other POSIX shells: `export ANTHROPIC_API_KEY="sk-ant-..."`), and run the built `claw-cpp` executable. |
A clean-room C++20 reimplementation skeleton of the Claw Code AI Agent Harness. Features a true agentic tool-use loop using Antigravity and claude code