Expand README with agent loop diagram and comprehensive feature docs#6
Merged
Expand README with agent loop diagram and comprehensive feature docs#6
Conversation
The README jumped straight into usage examples without explaining what the project actually is. Added a "What is ra?" section that covers the core value prop: a single-binary agent framework with full control over the agentic loop, multi-provider support, and multiple interfaces. https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ
Reworded the intro to focus on what ra offers without contrasting against other frameworks. https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ
Major additions: - Agent loop diagram showing the middleware pipeline visually - Extended thinking section (low/medium/high budgets, streaming) - File attachments section (images, PDFs, multi-file) - Sessions section (JSONL persistence, resume, auto-prune, TTL) - REPL slash commands documented (/skill, /attach, /context, /resume, /clear) - HTTP API endpoint table with request/response formats - MCP sidecar mode (--mcp-server-enabled alongside other interfaces) - Built-in tools expanded: update_file description, ask_user suspension flow across interfaces, platform-aware shell tools, fixed count to 15 - Tool timeout configuration - Middleware context column showing what each hook receives - Second middleware example (token budget enforcement) - Scripting section for --exec flag - Stdin piping in intro and quick start - Recipes expanded with actual config details - Provider base URL flags documented - Compaction defaults per provider noted https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ
ra ships with 6 ready-to-use skills (code-review, architect, planner, debugger, code-style, writer) — document them with usage examples. https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ
Verified every claim against the source code: - Tool count: 14, not 15 (shell tool is platform-specific) - Context discovery: patterns default to empty, not 5 hardcoded files - --no-builtin-tools flag doesn't exist; use config instead - Thinking budgets vary by provider, not universally 1k/8k/32k - Base URL flags only exist for Anthropic/OpenAI/Google - Built-in skill descriptions now match actual SKILL.md frontmatter - Agent loop diagram now shows ask_user suspension path https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR significantly expands the README documentation to provide clearer guidance on ra's architecture, features, and usage patterns. The changes reorganize content for better discoverability and add detailed explanations of key concepts like the agent loop, middleware hooks, and session management.
Key Changes
Added "The Agent Loop" section with ASCII diagram showing the complete agent execution flow, including all middleware hook points and control flow (beforeLoopBegin → beforeModelCall → streaming → tool execution → afterLoopIteration)
Restructured introduction with new "What is ra?" section that clearly explains ra as an AI agent framework with full control over the agentic loop, replacing the previous "Why ra" section with more concrete feature descriptions
Expanded middleware documentation with detailed hook descriptions including context available at each phase (messages, loop state, usage tracking, error information)
Added comprehensive sections for:
--execflag for programmatic usageEnhanced interface documentation with specific examples for CLI, REPL, HTTP API, and MCP server modes, including endpoint specifications and request/response formats
Improved quick-start examples with piped stdin usage, skill activation, and file attachment patterns
Added configuration examples for compaction thresholds, thinking budgets, storage settings, and MCP client/server setup
Clarified tool behavior including platform-specific shell tools (bash on Linux/macOS, PowerShell on Windows) and the
ask_usertool's behavior across different interfacesAdded token tracking and budget enforcement examples in middleware section
Notable Details
https://claude.ai/code/session_013y4NidSKrnraDXhYY38vPZ