{"id":49775215,"url":"https://github.com/molefrog/lilmd","last_synced_at":"2026-05-11T14:37:13.673Z","repository":{"id":350624033,"uuid":"1204967345","full_name":"molefrog/lilmd","owner":"molefrog","description":"Agent-friendly CLI for reading large Markdown files","archived":false,"fork":false,"pushed_at":"2026-04-24T23:10:21.000Z","size":281,"stargazers_count":29,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T01:24:35.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/molefrog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-08T14:02:42.000Z","updated_at":"2026-04-25T00:59:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/molefrog/lilmd","commit_stats":null,"previous_names":["molefrog/lilmd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/molefrog/lilmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molefrog%2Flilmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molefrog%2Flilmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molefrog%2Flilmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molefrog%2Flilmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/molefrog","download_url":"https://codeload.github.com/molefrog/lilmd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molefrog%2Flilmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32899552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-11T14:37:13.103Z","updated_at":"2026-05-11T14:37:13.663Z","avatar_url":"https://github.com/molefrog.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"lilmd-logo.webp\" alt=\"lilmd logo\" width=\"400\" /\u003e\n\n## `lilmd` - Markdown as a Database for Agents\n`lilmd` is a CLI for working with large MD files designed for agents.\n\n*Wait, but why?* Agent knowledge, docs, memory keeps growing. \nlilmd allows you to dump it all in one file and effeciently read/write/navigate its contents.\n\nFeatures:\n- fast navigation, complex read selectors, link extraction\n- complex section selectors \n- designed to save as much context as possible\n- can write, append, remove entire sections\n- can run in Node/Bun\n- optimized for speed\n- can be used by humans and **agents**\n- uses Bun as tooling: to test, control deps etc.\n\n### Install\n\n```bash\n# global install\n\u003e npm i -g lilmd\n\n# or run without installing\n\u003e npx lilmd file.md\n\u003e bunx lilmd file.md\n```\n\n### Help\n\n```bash\n# start here!\n# both commands print short documentation for the agent\n\u003e lilmd\n\u003e lilmd --help\n```\n\n### Overview \u0026 table of contents\n\nFirst, the agent gets file overview and table of contents.\n\n```bash\n# renders toc + stats; line ranges are inclusive, 1-indexed\n# --depth=N to limit nesting, --flat for a flat list\n\u003e lilmd file.md\n\nfile.md  L1-450  12 headings\n# lilmd                     L1-450\n  ## Getting Started        L5-80\n    ### Installation        L31-80\n  ## Community              L301-450\n```\n\n### Reading sections\n\n```bash\n\u003e lilmd read file.md \"# lilmd\"\n\u003e lilmd file.md \"# lilmd\"           # alias!\n# prints the contents of the lilmd section\n\n# descendant selector (any depth under the parent)\n\u003e lilmd file.md \"Getting Started \u003e Installation\"\n\n# direct child only\n\u003e lilmd file.md \"Getting Started \u003e\u003e Installation\"\n\n# level filter (H2 only)\n\u003e lilmd file.md \"##Installation\"\n\n# exact match (default is fuzzy, case-insensitive)\n\u003e lilmd file.md \"=Installation\"\n\n# regex\n\u003e lilmd file.md \"/install(ation)?/\"\n\n# by default no more than 25 matches are printed; if more, lilmd prints a hint\n# about --max-results=N\n# --max-lines=N truncates long bodies (shows \"… N more lines\")\n# --body-only skips subsections, --no-body prints headings only\n```\n\n### For humans only\n\n```bash\n# --pretty renders the section body as syntax-highlighted terminal markdown\n#   (for humans; piped output stays plain unless FORCE_COLOR is set)\n\u003e lilmd file.md --pretty \"Installation\"\n\n# nicely formatted markdown\n```\n\n### Searching \u0026 extracting\n\n```bash\n\u003e lilmd ls file.md \"Getting Started\"        # direct children of a section\n\u003e lilmd grep file.md \"pattern\"               # regex search, grouped by section\n\u003e lilmd links file.md [\"selector\"]           # extract links with section path\n\u003e lilmd code file.md \"Install\" [--lang=ts]   # extract code blocks\n```\n\n### Writing\n\n`lilmd` treats sections as addressable records: you can replace, append,\ninsert, move, or rename them without rewriting the whole file. Every write\nsupports `--dry-run`, which prints a unified diff instead of touching disk —\nperfect for agent-authored edits that a human (or another agent) reviews\nbefore applying.\n\n```bash\n\u003e lilmd set    file.md \"Install\" \u003c body.md  # replace section body\n\u003e lilmd append file.md \"Install\" \u003c body.md\n\u003e lilmd insert file.md --after \"Install\" \u003c new.md\n\u003e lilmd rm     file.md \"Old\"\n\u003e lilmd mv     file.md \"From\" \"To\"          # re-parent, fixes heading levels\n\u003e lilmd rename file.md \"Old\" \"New\"\n\u003e lilmd promote|demote file.md \"Section\"    # shift heading level ±1\n```\n\n### Vector search (experimental)\n\n```bash\n\u003e lilmd index file.md                    # embed sections into .lilmd/vectors.db\n\u003e lilmd retrieve \"how do I install\"      # semantic search; --max-results=N (default 5)\n\n# experimental: CLI and index format may change\n# uses Xenova/all-MiniLM-L6-v2 (384-dim, ~23MB, English-leaning) — small \u0026 fast, not SOTA\n# model downloads on first use, cached under ~/.cache/huggingface/\n```\n\n### Output\n\n```bash\n# human-readable by default; --json for machine output\n# use - as filename to read from stdin\n\u003e cat big.md | lilmd - \"Install\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolefrog%2Flilmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmolefrog%2Flilmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolefrog%2Flilmd/lists"}