docs: add comprehensive subdirectory CLAUDE.md files and update root - #589
Merged
Merged
Conversation
The repo has grown significantly. This adds module-level CLAUDE.md files for the five most complex subsystems, and updates the root CLAUDE.md to reflect the actual current state of the codebase. New files: - src/agent/CLAUDE.md — full module map (19 files), session/thread/turn model, agentic loop flow, compaction strategies with correct thresholds, scheduler invariants, self-repair details, complete submission command reference table - src/channels/web/CLAUDE.md — complete API route table (50+ endpoints), SSE event type reference, auth/rate limiting gotchas, connection limits, CORS headers, step-by-step endpoint addition guide - src/db/CLAUDE.md — dual-backend build commands, sub-trait structure (7 sub-traits, ~67 methods), SQL dialect differences, boolean/timestamp gotchas, complete schema table, in-memory test helper, shared handle pattern - src/llm/CLAUDE.md — corrected LlmProvider trait signatures, provider chain decorator order, NEAR AI dual-auth and session renewal details, circuit breaker thresholds, previously undocumented smart_routing.rs and recording.rs - tests/e2e/CLAUDE.md — conftest fixtures and async scoping, environment injected into the binary, mock_llm canned responses, writing guide with correct asyncio usage, gotchas section Root CLAUDE.md updates: - Added E2E test setup and integration test commands - Documented ~15 undocumented modules: cli/, registry/, hooks/, tunnel/, observability/, webhook_server.rs, cost_guard.rs, job_monitor.rs, etc. - Corrected libSQL backend path (libsql/ directory, 8 sub-modules) - Updated Database trait method count (~67, split across 7 sub-traits) - Fixed stale references: config.rs → config/channels.rs, main.rs → app.rs - Added Hook, Observer, Tunnel traits to extensibility section - Added tunnel and observability env vars to Configuration section - Removed resolved TODO (webhook trigger is now shipped) - Added Module Specifications entries for all 5 new CLAUDE.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
Bot
added
scope: agent
Contributor
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation by adding detailed, module-level Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a significant and much-needed documentation update, adding comprehensive CLAUDE.md files for several complex subsystems and bringing the root documentation up to date. The new documents are thorough and will be a great resource for developers. My review focuses on a few minor inconsistencies in the new documentation to ensure its accuracy.
Note: Security Review has been skipped due to the limited scope of the PR.
| # Run E2E tests (Python/Playwright — requires a running ironclaw instance) | ||
| # See tests/e2e/CLAUDE.md for full setup instructions | ||
| cd tests/e2e | ||
| python -m venv .venv && source .venv/bin/activate |
Contributor
There was a problem hiding this comment.
The source .venv/bin/activate command is specific to Unix-like shells. For completeness, it would be helpful to add a note for Windows users, similar to the one in tests/e2e/CLAUDE.md.
Suggested change
| python -m venv .venv && source .venv/bin/activate | |
| python -m venv .venv && source .venv/bin/activate # On Windows, use .venv\Scripts\activate |
| │ | ||
| ├── db/ # Database abstraction layer | ||
| │ ├── mod.rs # Database trait (~60 async methods) | ||
| │ ├── mod.rs # Database supertrait + 6 sub-traits (~67 async methods) |
Contributor
There was a problem hiding this comment.
The Database supertrait is composed of 7 sub-traits, but this line says 6. The sub-traits are ConversationStore, JobStore, SandboxStore, RoutineStore, ToolFailureStore, SettingsStore, and WorkspaceStore.
Suggested change
| │ ├── mod.rs # Database supertrait + 6 sub-traits (~67 async methods) | |
| │ ├── mod.rs # Database supertrait + 7 sub-traits (~67 async methods) |
|
|
||
| | File | Role | | ||
| |------|------| | ||
| | `mod.rs` | `Database` supertrait + 6 sub-traits (~67 async methods total) — add new ops here first | |
Contributor
There was a problem hiding this comment.
The Database supertrait is composed of 7 sub-traits, but this line says 6. The table of sub-traits below correctly lists 7.
Suggested change
| | `mod.rs` | `Database` supertrait + 6 sub-traits (~67 async methods total) — add new ops here first | | |
| | `mod.rs` | `Database` supertrait + 7 sub-traits (~67 async methods total) — add new ops here first | |
|
|
||
| ## Trait Structure | ||
|
|
||
| The `Database` supertrait is composed of six sub-traits. Leaf consumers can depend on the narrowest sub-trait they need rather than the full `Database`: |
Contributor
There was a problem hiding this comment.
The Database supertrait is composed of seven sub-traits, not six.
Suggested change
| The `Database` supertrait is composed of six sub-traits. Leaf consumers can depend on the narrowest sub-trait they need rather than the full `Database`: | |
| The `Database` supertrait is composed of seven sub-traits. Leaf consumers can depend on the narrowest sub-trait they need rather than the full `Database`: |
Comment on lines
+45
to
+53
| | Sub-trait | Methods | Covers | | ||
| |-----------|---------|--------| | ||
| | `ConversationStore` | 11 | Conversations, messages | | ||
| | `JobStore` | 14 | Agent jobs, actions, LLM calls, estimation | | ||
| | `SandboxStore` | 13 | Sandbox jobs, job events | | ||
| | `RoutineStore` | 14 | Routines, routine runs | | ||
| | `ToolFailureStore` | 4 | Self-repair tracking | | ||
| | `SettingsStore` | 8 | Per-user key-value settings | | ||
| | `WorkspaceStore` | 13 | Memory documents, chunks, hybrid search | |
Contributor
There was a problem hiding this comment.
The method counts for some of the sub-traits in this table appear to be out of date. Based on src/db/mod.rs, the counts are:
ConversationStore: 12 (not 11)JobStore: 13 (not 14)RoutineStore: 15 (not 14)
The total method count is closer to 78, not ~67. Updating these numbers would improve the accuracy of this excellent documentation.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive module-level CLAUDE.md documentation files for five complex subsystems (src/agent/, src/channels/web/, src/db/, src/llm/, tests/e2e/) and updates the root CLAUDE.md to reflect the current state of the codebase — adding previously undocumented modules, correcting stale file paths, and updating structural descriptions.
Changes:
- Added 5 new CLAUDE.md files covering module maps, key patterns, configuration, gotchas, and how-to guides for the agent, web gateway, database, LLM, and E2E test subsystems
- Updated root CLAUDE.md with ~15 previously undocumented modules (cli/, registry/, hooks/, tunnel/, observability/, etc.), corrected stale paths (config.rs → config/, libsql_backend.rs → libsql/), and added E2E/integration test commands
- Removed a resolved TODO (webhook trigger) and added new extensibility traits (Hook, Observer, Tunnel) and environment variables to the configuration section
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
src/agent/CLAUDE.md |
New: 20-file module map, session/thread/turn model, agentic loop flow, compaction strategies, scheduler invariants, submission command reference |
src/channels/web/CLAUDE.md |
New: Complete API route listing (~59 routes), SSE event types, auth details, connection limits, CORS, step-by-step guides |
src/db/CLAUDE.md |
New: Backend file map, trait structure, SQL dialect differences, schema tables, libSQL limitations, testing helpers |
src/llm/CLAUDE.md |
New: Provider selection, NEAR AI gotchas, circuit breaker/retry/failover details, provider chain construction, trait definition |
tests/e2e/CLAUDE.md |
New: Setup instructions, fixture documentation, mock LLM usage, scenario table, gotchas |
CLAUDE.md |
Updated: Added undocumented modules, corrected file paths, added test commands, updated trait/method counts, added extensibility traits and env vars |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| │ └── allowlist.rs # DomainAllowlist validation | ||
| │ | ||
| ├── secrets/ # Secrets management | ||
| │ ├── mod.rs # SecretsStore trait, public API |
There was a problem hiding this comment.
The secrets/ file tree listing is missing types.rs (which exists at src/secrets/types.rs and contains core types like Secret, SecretRef, SecretMetadata, etc.). The old CLAUDE.md listed it but this update drops it while adding mod.rs and keychain.rs.
Suggested change
| │ ├── mod.rs # SecretsStore trait, public API | |
| │ ├── mod.rs # SecretsStore trait, public API | |
| │ ├── types.rs # Core types (Secret, SecretRef, SecretMetadata, etc.) |
Comment on lines
+25
to
+37
| | File | Role | | ||
| |------|------| | ||
| | `mod.rs` | `Database` supertrait + 6 sub-traits (~67 async methods total) — add new ops here first | | ||
| | `postgres.rs` | PostgreSQL backend — delegates to `Store` + `Repository` in `history/` | | ||
| | `libsql/mod.rs` | libSQL/Turso backend struct, connection helpers, row parsing utilities | | ||
| | `libsql/conversations.rs` | `ConversationStore` impl | | ||
| | `libsql/jobs.rs` | `JobStore` impl | | ||
| | `libsql/sandbox.rs` | `SandboxStore` impl | | ||
| | `libsql/routines.rs` | `RoutineStore` impl | | ||
| | `libsql/settings.rs` | `SettingsStore` impl | | ||
| | `libsql/tool_failures.rs` | `ToolFailureStore` impl | | ||
| | `libsql/workspace.rs` | `WorkspaceStore` impl (FTS5 + vector search) | | ||
| | `libsql_migrations.rs` | Consolidated libSQL schema (CREATE IF NOT EXISTS, no ALTER TABLE) | |
There was a problem hiding this comment.
The file map is missing tls.rs — src/db/tls.rs exists (87 lines) and contains the TLS connector factory for PostgreSQL (create_pool() with rustls + system root certificates). It should be listed alongside the other files in this table.
|
|
||
| | File | Role | | ||
| |------|------| | ||
| | `mod.rs` | `Database` supertrait + 6 sub-traits (~67 async methods total) — add new ops here first | |
There was a problem hiding this comment.
The file map says "6 sub-traits (~67 async methods total)" but the actual src/db/mod.rs defines 7 sub-traits (ConversationStore, JobStore, SandboxStore, RoutineStore, ToolFailureStore, SettingsStore, WorkspaceStore). The total method count is also off — a precise count yields approximately 78 async methods (including run_migrations), not ~67. The "7 sub-traits" number is correctly stated in the trait structure table on line 43 of this same file, so this is an internal inconsistency within the document.
Comment on lines
+48
to
+50
| | `JobStore` | 14 | Agent jobs, actions, LLM calls, estimation | | ||
| | `SandboxStore` | 13 | Sandbox jobs, job events | | ||
| | `RoutineStore` | 14 | Routines, routine runs | |
There was a problem hiding this comment.
Two method counts in this table are incorrect:
JobStore: documented as 14 methods, butsrc/db/mod.rsdefines 13 methods (save_job, get_job, update_job_status, mark_job_stuck, get_stuck_jobs, list_agent_jobs, agent_job_summary, get_agent_job_failure_reason, save_action, get_job_actions, record_llm_call, save_estimation_snapshot, update_estimation_actuals).RoutineStore: documented as 14 methods, butsrc/db/mod.rsdefines 15 methods (create_routine, get_routine, get_routine_by_name, list_routines, list_all_routines, list_event_routines, list_due_cron_routines, update_routine, update_routine_runtime, delete_routine, create_routine_run, complete_routine_run, list_routine_runs, count_running_routine_runs, link_routine_run_to_job).
Suggested change
| | `JobStore` | 14 | Agent jobs, actions, LLM calls, estimation | | |
| | `SandboxStore` | 13 | Sandbox jobs, job events | | |
| | `RoutineStore` | 14 | Routines, routine runs | | |
| | `JobStore` | 13 | Agent jobs, actions, LLM calls, estimation | | |
| | `SandboxStore` | 13 | Sandbox jobs, job events | | |
| | `RoutineStore` | 15 | Routines, routine runs | |
| │ | ||
| ├── db/ # Database abstraction layer | ||
| │ ├── mod.rs # Database trait (~60 async methods) | ||
| │ ├── mod.rs # Database supertrait + 6 sub-traits (~67 async methods) |
There was a problem hiding this comment.
Same inconsistency as in src/db/CLAUDE.md: the actual source (src/db/mod.rs) defines 7 sub-traits (not 6), and the total method count is approximately 78 (not ~67).
Suggested change
| │ ├── mod.rs # Database supertrait + 6 sub-traits (~67 async methods) | |
| │ ├── mod.rs # Database supertrait + 7 sub-traits (~78 async methods) |
- Fix 7-sub-trait count (was 6) and ~78 async methods (was ~60/~67) in both CLAUDE.md and src/db/CLAUDE.md - Add missing types.rs to secrets/ file tree (CLAUDE.md) - Add missing tls.rs to src/db/CLAUDE.md Files table - Fix method counts: ConversationStore 12, JobStore 13, RoutineStore 15 - Add Windows venv activation note to E2E setup commands - Collapse agent/, web/, llm/, db/ file trees to one-liners (detail lives in their respective CLAUDE.md files) - Replace verbose Database and LLM Providers sections with summaries linking to src/db/CLAUDE.md and src/llm/CLAUDE.md - Root CLAUDE.md: 43,868 → 35,270 chars (fixes >40k perf warning) [skip-regression-check] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ilblackdragon
approved these changes
Mar 7, 2026
This was referenced Mar 7, 2026
Closed
Merged
bkutasi
pushed a commit
to bkutasi/ironclaw
that referenced
this pull request
Mar 28, 2026
…earai#589) * docs: add comprehensive subdirectory CLAUDE.md files and update root The repo has grown significantly. This adds module-level CLAUDE.md files for the five most complex subsystems, and updates the root CLAUDE.md to reflect the actual current state of the codebase. New files: - src/agent/CLAUDE.md — full module map (19 files), session/thread/turn model, agentic loop flow, compaction strategies with correct thresholds, scheduler invariants, self-repair details, complete submission command reference table - src/channels/web/CLAUDE.md — complete API route table (50+ endpoints), SSE event type reference, auth/rate limiting gotchas, connection limits, CORS headers, step-by-step endpoint addition guide - src/db/CLAUDE.md — dual-backend build commands, sub-trait structure (7 sub-traits, ~67 methods), SQL dialect differences, boolean/timestamp gotchas, complete schema table, in-memory test helper, shared handle pattern - src/llm/CLAUDE.md — corrected LlmProvider trait signatures, provider chain decorator order, NEAR AI dual-auth and session renewal details, circuit breaker thresholds, previously undocumented smart_routing.rs and recording.rs - tests/e2e/CLAUDE.md — conftest fixtures and async scoping, environment injected into the binary, mock_llm canned responses, writing guide with correct asyncio usage, gotchas section Root CLAUDE.md updates: - Added E2E test setup and integration test commands - Documented ~15 undocumented modules: cli/, registry/, hooks/, tunnel/, observability/, webhook_server.rs, cost_guard.rs, job_monitor.rs, etc. - Corrected libSQL backend path (libsql/ directory, 8 sub-modules) - Updated Database trait method count (~67, split across 7 sub-traits) - Fixed stale references: config.rs → config/channels.rs, main.rs → app.rs - Added Hook, Observer, Tunnel traits to extensibility section - Added tunnel and observability env vars to Configuration section - Removed resolved TODO (webhook trigger is now shipped) - Added Module Specifications entries for all 5 new CLAUDE.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: address PR review comments and reduce CLAUDE.md size - Fix 7-sub-trait count (was 6) and ~78 async methods (was ~60/~67) in both CLAUDE.md and src/db/CLAUDE.md - Add missing types.rs to secrets/ file tree (CLAUDE.md) - Add missing tls.rs to src/db/CLAUDE.md Files table - Fix method counts: ConversationStore 12, JobStore 13, RoutineStore 15 - Add Windows venv activation note to E2E setup commands - Collapse agent/, web/, llm/, db/ file trees to one-liners (detail lives in their respective CLAUDE.md files) - Replace verbose Database and LLM Providers sections with summaries linking to src/db/CLAUDE.md and src/llm/CLAUDE.md - Root CLAUDE.md: 43,868 → 35,270 chars (fixes >40k perf warning) [skip-regression-check] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
drchirag1991
pushed a commit
to drchirag1991/ironclaw
that referenced
this pull request
Apr 8, 2026
…earai#589) * docs: add comprehensive subdirectory CLAUDE.md files and update root The repo has grown significantly. This adds module-level CLAUDE.md files for the five most complex subsystems, and updates the root CLAUDE.md to reflect the actual current state of the codebase. New files: - src/agent/CLAUDE.md — full module map (19 files), session/thread/turn model, agentic loop flow, compaction strategies with correct thresholds, scheduler invariants, self-repair details, complete submission command reference table - src/channels/web/CLAUDE.md — complete API route table (50+ endpoints), SSE event type reference, auth/rate limiting gotchas, connection limits, CORS headers, step-by-step endpoint addition guide - src/db/CLAUDE.md — dual-backend build commands, sub-trait structure (7 sub-traits, ~67 methods), SQL dialect differences, boolean/timestamp gotchas, complete schema table, in-memory test helper, shared handle pattern - src/llm/CLAUDE.md — corrected LlmProvider trait signatures, provider chain decorator order, NEAR AI dual-auth and session renewal details, circuit breaker thresholds, previously undocumented smart_routing.rs and recording.rs - tests/e2e/CLAUDE.md — conftest fixtures and async scoping, environment injected into the binary, mock_llm canned responses, writing guide with correct asyncio usage, gotchas section Root CLAUDE.md updates: - Added E2E test setup and integration test commands - Documented ~15 undocumented modules: cli/, registry/, hooks/, tunnel/, observability/, webhook_server.rs, cost_guard.rs, job_monitor.rs, etc. - Corrected libSQL backend path (libsql/ directory, 8 sub-modules) - Updated Database trait method count (~67, split across 7 sub-traits) - Fixed stale references: config.rs → config/channels.rs, main.rs → app.rs - Added Hook, Observer, Tunnel traits to extensibility section - Added tunnel and observability env vars to Configuration section - Removed resolved TODO (webhook trigger is now shipped) - Added Module Specifications entries for all 5 new CLAUDE.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: address PR review comments and reduce CLAUDE.md size - Fix 7-sub-trait count (was 6) and ~78 async methods (was ~60/~67) in both CLAUDE.md and src/db/CLAUDE.md - Add missing types.rs to secrets/ file tree (CLAUDE.md) - Add missing tls.rs to src/db/CLAUDE.md Files table - Fix method counts: ConversationStore 12, JobStore 13, RoutineStore 15 - Add Windows venv activation note to E2E setup commands - Collapse agent/, web/, llm/, db/ file trees to one-liners (detail lives in their respective CLAUDE.md files) - Replace verbose Database and LLM Providers sections with summaries linking to src/db/CLAUDE.md and src/llm/CLAUDE.md - Root CLAUDE.md: 43,868 → 35,270 chars (fixes >40k perf warning) [skip-regression-check] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
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
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
The IronClaw repo has grown significantly — many modules existed in code with no documentation. This PR adds module-level CLAUDE.md files for the five most complex subsystems and brings the root CLAUDE.md up to date.
Process: Initial docs were written by reading the existing CLAUDE.md and key source files. Then 6 parallel sub-agents each read all source files in their assigned directory to verify and correct the docs. A final review pass caught cross-file consistency issues (misattributed features, incomplete listings, stale method counts).
New files
src/agent/CLAUDE.mdsrc/channels/web/CLAUDE.mdsrc/db/CLAUDE.mdLibSqlBackend::new_memory()test helpersrc/llm/CLAUDE.mdLlmProvidertrait (was entirely wrong), provider chain decorator order, NEAR AI session renewal mechanics, circuit breaker thresholds, previously undocumentedsmart_routing.rsandrecording.rstests/e2e/CLAUDE.md@pytest.mark.asynciowarningRoot CLAUDE.md changes
cli/,registry/,hooks/,tunnel/,observability/,cost_guard.rs,job_monitor.rs,webhook_server.rs, new tool builtins, etc.libsql_backend.rs→libsql/directory with all 8 sub-modulesconfig.rs→config/channels.rs,main.rs→app.rsHook,Observer,Tunneltraits to the extensibility section🤖 Generated with Claude Code