{"id":46039915,"url":"https://github.com/jrialland/claudemd-loader","last_synced_at":"2026-03-01T06:10:06.418Z","repository":{"id":339950174,"uuid":"1163951819","full_name":"jrialland/claudemd-loader","owner":"jrialland","description":"A Python library for loading and processing CLAUDE.md project context files. Supports @import syntax for multi-file composition, YAML frontmatter for conditional loading, RAG chunking for vector databases, smart caching, and seamless integration with Claude Code's memory system. PEP 517 compliant with full type safety.","archived":false,"fork":false,"pushed_at":"2026-02-22T12:51:29.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-22T18:09:18.478Z","etag":null,"topics":["agentic-ai","claude-code","codeassistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jrialland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-22T12:12:37.000Z","updated_at":"2026-02-22T13:07:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jrialland/claudemd-loader","commit_stats":null,"previous_names":["jrialland/claudemd-loader"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jrialland/claudemd-loader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrialland%2Fclaudemd-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrialland%2Fclaudemd-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrialland%2Fclaudemd-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrialland%2Fclaudemd-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrialland","download_url":"https://codeload.github.com/jrialland/claudemd-loader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrialland%2Fclaudemd-loader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29962004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","claude-code","codeassistant"],"created_at":"2026-03-01T06:10:04.017Z","updated_at":"2026-03-01T06:10:06.401Z","avatar_url":"https://github.com/jrialland.png","language":"Python","readme":"# claudemd-loader\n\nA library that implements the [CLAUDE.md conventions](https://www.buildcamp.io/guides/the-ultimate-guide-to-claudemd) to ease loading prompts and project context for AI coding assistants.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Overview\n\nThis library provides utilities for loading file content using CLAUDE.md conventions. It does not perform AI operations itself - it focuses solely on loading and organizing project context according to the CLAUDE.md specification.\n\n### Project Goals\n\nThe primary goal of this project is to provide an **alternative implementation** of the CLAUDE.md conventions established by Claude Code. By offering a standalone, well-documented library that follows these conventions, we aim to:\n\n1. **Enable adoption by alternative AI coding agents** - Any coding assistant can implement these conventions, not just Claude Code\n2. **Establish common standards** - Create interoperability between different AI coding tools through shared conventions\n3. **Promote best practices** - Demonstrate how to properly implement features like:\n   - YAML frontmatter for conditional loading\n   - Project context search locations (`~/.claude/projects/\u003cproject\u003e/`)\n   - Memory integration (`~/.claude/projects/\u003cproject\u003e/memory/`)\n   - Import syntax and recursive file loading\n   - **RAG Support**: Semantic chunking of context files with overlap for vector databases\n\nBy following the conventions edicted by Claude Code, implementers of alternative coding agents can provide a consistent user experience and leverage the same project structure patterns.\n\n## Usage\n\nFor detailed usage examples and API documentation, see [USAGE.md](USAGE.md).\n\n## What is CLAUDE.md?\n\nCLAUDE.md is a convention for structuring project instructions and context for Claude AI assistants. It allows you to define rules, import files, and scope instructions to specific parts of your project.\n\n## YAML Frontmatter\n\nYAML frontmatter is an **optional** metadata block placed at the top of `.md` files in `.claude/rules/`, delimited by `---`. It enables conditional scoping of rules to specific file paths.\n\n### Features\n\n- **Optional**: Not requiredif absent, the rule loads unconditionally\n- **Conditional Loading**: Only applies rules when working with matching file paths\n- **Modular Organization**: Makes rules more specific and maintainable\n\n### Example\n\n```yaml\n---\npaths:\n  - \"src/api/**/*.ts\"\n---\n# API Development Rules\n\n- All API endpoints must include input validation\n- Use the standard error response format\n- Include OpenAPI documentation comments\n```\n\nWhen the `paths:` field is present, Claude only loads the rule file when working with files matching those patterns. If the field is missing, the rule applies to all tasks.\n\n**Using with claudemd-loader**: Pass relevant file paths via the `context_files` parameter to `load_claudemd()` to enable conditional loading:\n\n```python\nfrom claudemd_loader import ClaudeMdLoaderContext\n\nctx = ClaudeMdLoaderContext(\"/path/to/project\")\n# Load only rules relevant to API files\ncontent = ctx.load_claudemd(context_files=[\"src/api/users.py\"])\n```\n\n## Multi-File Loading\n\nThe library automatically loads and concatenates CLAUDE.md files from multiple conventional locations. This allows you to layer context from user-wide preferences down to project-specific details.\n\n### Loading Order\n\nFiles are loaded in this specific order (if they exist):\n\n1. **User global**: `~/.claude/CLAUDE.md` - Personal preferences for all projects\n2. **Project-specific user**: `~/.claude/projects/\u003cproject-name\u003e/CLAUDE.md` - Project context at user level\n3. **Project root**: `\u003cproject_dir\u003e/CLAUDE.md` - Main project context (checked into git)\n4. **Project .claude directory**: `\u003cproject_dir\u003e/.claude/CLAUDE.md` - Alternative project location (checked into git)\n5. **Project rules**: `\u003cproject_dir\u003e/.claude/rules/**/*.md` - Scoped rules loaded recursively (checked into git)\n6. **Local personal**: `\u003cproject_dir\u003e/CLAUDE.local.md` - Personal notes (not in git)\n7. **Extra files**: Via `extra_claude_files` parameter - Explicitly specified files\n\nAll existing files are loaded and concatenated with double newlines (`\\n\\n`) between them.\n\n**Note**: Rule files in `.claude/rules/` are loaded recursively in alphabetical order. They support YAML frontmatter with `paths:` patterns to conditionally load based on `context_files`.\n\n### Example\n\n```python\nfrom claudemd_loader import ClaudeMdLoaderContext\n\nctx = ClaudeMdLoaderContext(\"/path/to/myproject\")\n\n# Loads ALL existing files in order\ncontent = ctx.load_claudemd()\n\n# Optionally specify additional files to load after conventional ones\nextra_content = ctx.load_claudemd(\n    extra_claude_files=[\"docs/api-guide.md\", \"docs/style-guide.md\"]\n)\n```\n\n### Use Cases\n\nThis layered approach supports different use cases:\n\n- **User global** (`~/.claude/CLAUDE.md`): Your personal coding standards, preferred tools, and conventions\n- **Project-specific user** (`~/.claude/projects/\u003cproject\u003e/`): Project notes and instructions stored separately\n- **Project root** (`./CLAUDE.md`): Team-shared project context (version controlled)\n- **Project .claude** (`./.claude/CLAUDE.md`): Alternative location for shared project context\n- **Project rules** (`./.claude/rules/**/*.md`): Modular, scoped rules organized by topic (e.g., `api/`, `database/`, `frontend/`)\n- **Local personal** (`./CLAUDE.local.md`): Your private notes and overrides (add to `.gitignore`)\n- **Extra files**: Session-specific documentation or guidelines\n\n### Project Name\n\nThe `\u003cproject-name\u003e` used for `~/.claude/projects/\u003cproject-name\u003e/` is automatically derived from the project directory name. You can override this:\n\n```python\n# Default: uses directory name\nctx = ClaudeMdLoaderContext(\"/path/to/myproject\")  # project name = \"myproject\"\n\n# Custom: specify project name explicitly\nctx = ClaudeMdLoaderContext(\"/path/to/myproject\", project_name=\"shared-context\")\n```\n\n## Claude Code Memory Integration\n\nClaude Code can write session notes to `~/.claude/projects/\u003cproject-name\u003e/memory/MEMORY.md`. When enabled, the library can automatically load these notes into your context.\n\n**Usage:**\n\n```python\nfrom claudemd_loader import ClaudeMdLoaderContext\n\n# Memory loading is enabled by default\nctx = ClaudeMdLoaderContext(\"/path/to/project\")\ncontent = ctx.load_claudemd()\n\n# Or explicitly disable it\nctx = ClaudeMdLoaderContext(\"/path/to/project\", use_memory=False)\n```\n\n**Features:**\n\n- **Enabled by default**: Set `use_memory=False` to disable\n- **First 200 lines**: Only the first 200 lines of MEMORY.md are loaded\n- **Prepended content**: Memory content appears before the main CLAUDE.md content\n- **Graceful handling**: Missing MEMORY.md files are silently ignored\n\nThis feature is designed to work with Claude Code's automatic note-taking functionality, allowing you to maintain session context across conversations.\n\n## Import Syntax\n\nThe CLAUDE.md convention supports importing additional files using the `@` prefix syntax:\n\n```\n@path/to/file\n```\n\n### Supported Import Paths\n\n- **Relative paths**: `@README`\n- **Subdirectories**: `@docs/git-instructions.md`\n- **Package files**: `@package.json`\n- **Home directory**: `@~/.claude/my-project-instructions.md`\n\n### Import Rules\n\n| Location | Allowed? | Notes |\n|----------|----------|-------|\n| Normal text |  Yes | Fully processed |\n| Markdown lists |  Yes | Treated as normal text |\n| Headings |  Yes | Treated as normal text |\n| Code blocks |  No | Not evaluated |\n| Inline code |  No | Not evaluated |\n\n**Important**: Imports are recursively loaded up to **5 levels deep**.\n\n### Valid Import Examples\n\n```markdown\n# Project Overview\nSee @README for a full description.\n\n## Build Instructions\nRefer to @docs/build.md for setup steps.\n```\n\n### Invalid Import Examples\n\nImports **do not work** inside code blocks or inline code spans:\n\n````markdown\n```\nRun the build script:\n@docs/build.md\n```\n````\n\nOr within inline code:\n\n```markdown\nUse the `@docs/api.md` file for API documentation.\n```\n\n## References\n\nThis documentation incorporates information from:\n- [The Ultimate Guide to CLAUDE.md](https://www.buildcamp.io/guides/the-ultimate-guide-to-claudemd) - buildcamp.io\n- [Notes on CLAUDE.md Structure and Best Practices](https://callmephilip.com/posts/notes-on-claude-md-structure-and-best-practices/) - callmephilip.com\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrialland%2Fclaudemd-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrialland%2Fclaudemd-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrialland%2Fclaudemd-loader/lists"}