{"id":50992755,"url":"https://github.com/parcadei/bloks","last_synced_at":"2026-06-20T05:03:59.181Z","repository":{"id":352953513,"uuid":"1217175611","full_name":"parcadei/bloks","owner":"parcadei","description":"Context card generator — repo-first library knowledge for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-21T20:32:06.000Z","size":128,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T22:09:21.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/parcadei.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-04-21T16:10:09.000Z","updated_at":"2026-04-21T22:06:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parcadei/bloks","commit_stats":null,"previous_names":["parcadei/bloks"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/parcadei/bloks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fbloks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fbloks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fbloks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fbloks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parcadei","download_url":"https://codeload.github.com/parcadei/bloks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parcadei%2Fbloks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34557553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"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-06-20T05:03:57.709Z","updated_at":"2026-06-20T05:03:59.174Z","avatar_url":"https://github.com/parcadei.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bloks\n\nContext blok generator — repo-first library knowledge for AI agents.\n\nbloks indexes libraries from npm, PyPI, crates.io, or local repos and generates structured context bloks optimized for LLM consumption. It extracts APIs via [tldr](https://github.com/parcadei/tldr-code) AST analysis, scrapes documentation (including `llms.txt`), and serves it all through a progressive disclosure hierarchy: **deck → module → symbol**.\n\nBeyond libraries, bloks is a knowledge layer for anything an AI agent needs to remember. Use the card system to capture **design taste** (spacing, typography, color choices), **codebase-specific patterns** (how your team handles auth, state, errors), **component design rules** (always use compound components, never nest providers), and **architectural decisions** (why Drizzle over Prisma). Cards surface automatically alongside API context, so agents get your taste and constraints — not just docs.\n\n## Install\n\n```bash\ncargo install bloks\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/parcadei/bloks.git\ncd bloks \u0026\u0026 cargo build --release\nln -sf \"$(pwd)/target/release/bloks\" ~/.local/bin/bloks\n```\n\nRequires:\n- Rust 1.85+ (2024 edition)\n- [tldr](https://github.com/parcadei/tldr-code) on PATH (for source code analysis)\n\n## Quick start\n\n```bash\n# Index a library from a package registry\nbloks add hono              # npm (auto-detected)\nbloks add fastapi           # PyPI (auto-detected)\nbloks add clap              # crates.io (auto-detected)\n\n# Or force a specific registry\nbloks add express --registry npm\nbloks add pydantic --registry pypi --docs https://docs.pydantic.dev\n\n# Index a local repo\nbloks add-local ./my-project --name my-lib\n\n# List everything indexed\nbloks list\n```\n\n## Usage\n\n### Progressive disclosure\n\nbloks has three levels of detail. Use the shorthand — it's the fastest path:\n\n```bash\nbloks react                  # Deck: compact overview of all modules\nbloks react useState         # Symbol: signature, docs, SEE ALSO, user notes\nbloks card react --module ReactHooks   # Module: all APIs in one module\n```\n\n### Decks\n\nA deck is a bird's-eye view of a library — module names, API counts, public vs internal split:\n\n```bash\nbloks react\nbloks hono\nbloks pydantic\n```\n\n### Symbol cards\n\nDrill into a specific function, class, or type:\n\n```bash\nbloks hono Context           # Shows signature, SEE ALSO, user corrections\nbloks pydantic BaseModel     # Shows overview with method groupings\nbloks react useEffect        # Shows signature + relevant user notes\n```\n\nSymbol lookup is fuzzy within the library — it matches by short name, title, and content keywords.\n\n### Module cards\n\nGet all APIs in a specific module:\n\n```bash\nbloks card hono --module middleware/jwt\nbloks card react --module ReactHooks\nbloks card flask --module app\n```\n\nModule cards show only user notes relevant to that module (not the entire library).\n\n### Verbosity levels\n\n```bash\nbloks card react --level compact   # Names only, no signatures\nbloks card react --level default   # Signatures + first-line docstrings\nbloks card react --level docs      # Signatures + docs sections\nbloks card react --level full      # Everything: signatures, docs, examples\nbloks card react --docs            # Shorthand for --level docs\n```\n\n### Search\n\nFull-text search across all indexed documentation:\n\n```bash\nbloks search middleware auth --lib hono\nbloks search error handling\nbloks search \"dependency injection\" --lib fastapi --kind doc\nbloks search streaming --kind api -n 20\n```\n\nMulti-word queries work with or without quotes. Filter by `--lib`, `--kind` (api/doc/example), `--path`.\n\n### Recipes\n\nCompose docs, APIs, and user notes around a topic:\n\n```bash\nbloks recipe hono middleware auth\nbloks recipe react state management\nbloks recipe fastapi database sqlalchemy\n```\n\nReturns a focused guide section + matching APIs + matching user recipes.\n\n### Fuzzy library names\n\nYou don't need to remember exact package names:\n\n```bash\nbloks drizzle        # Finds drizzle-orm\nbloks expresss       # Finds express (typo-tolerant)\nbloks supabasejs     # Finds @supabase/supabase-js or supabase\n```\n\nIf nothing matches, bloks suggests similar names from your index.\n\n## User cards\n\nbloks has a local card system for storing your own knowledge — corrections, patterns, rules, decisions, tastes. Cards are `.card` files stored in `~/.cache/bloks/cards/`.\n\n### Quick learning\n\n```bash\n# Report an error you hit (creates a correction card automatically)\nbloks report hono wrong_syntax \"c.json() takes an object, not a string\"\n\n# Store a note with more control\nbloks learn hono \"cors middleware must be added BEFORE route handlers\"\n\n# Create any card type\nbloks new pattern \"React state patterns\" --tags react,state\nbloks new rule \"Never use any in TypeScript\" --tags typescript,types\nbloks new decision \"Chose Drizzle over Prisma\" --tags orm,drizzle\nbloks new taste \"8px grid spacing\" --tags design,layout\nbloks new recipe \"JWT auth flow\" --tags hono,auth --from ./jwt-notes.md\n```\n\n### Card kinds\n\n| Kind | Use for |\n|------|---------|\n| `fact` | Verified API behaviors, gotchas |\n| `correction` | Wrong imports, deprecated patterns |\n| `rule` | Hard constraints (always/never) |\n| `pattern` | Reusable approaches |\n| `taste` | Preferences, style choices |\n| `decision` | Architectural choices with rationale |\n| `recipe` | Multi-step workflows |\n| `snippet` | Code fragments to reuse |\n| `note` | Everything else |\n\n### Card lifecycle\n\nCards have a status (`observed` → `confirmed` → `archived`) and support lineage — a new card can `replaces:` an older one, forming a revision chain:\n\n```bash\nbloks cards                         # List all cards\nbloks cards --kind correction       # Filter by kind\nbloks cards --tag hono              # Filter by tag\nbloks cards --history \u003ccard-id\u003e     # Show revision lineage\n```\n\n### Feedback loop\n\nCards are scored by usage. When bloks shows a card, it logs a `view` event. You can then ack or nack:\n\n```bash\nbloks ack card-id-1 card-id-2      # These cards helped\nbloks nack card-id-3               # This card was wrong/stale\nbloks feedback --ack good1,good2 --nack bad1   # Both in one call\nbloks stats                         # See which cards are proven vs stale\n```\n\nCards with high ack rates get `[PROVEN]` badges. Cards with negative scores get `[STALE]` warnings and flag for review.\n\n## SEE ALSO\n\nWhen you view a symbol card, bloks shows related symbols:\n\n```\nbloks hono Context\n\nSEE ALSO\n  Hono, text, use, type, req\n```\n\nThis is powered by three relation signals mined at index time:\n\n1. **Call graph** (strength 3): Caller/callee relationships from `tldr calls`, resolved to specific symbols via file-path matching and import scoping.\n2. **Doc co-mention** (strength 2): When two API symbols appear in the same documentation section.\n3. **Namespace proximity** (strength 1): Symbols in the same module/package.\n\nThe top 5 related symbols (by combined strength, excluding those already shown) appear in the SEE ALSO section.\n\n## Project context\n\nGenerate a context blok for any project on disk:\n\n```bash\nbloks context .                    # Current directory\nbloks context ./my-app --budget 50 # Cap output lines\nbloks context . --project myapp    # Override project name for card matching\n```\n\nThis reads `package.json` / `Cargo.toml` / `pyproject.toml`, cross-references with your bloks index, and emits a compact dependency overview with matching user rules/tastes.\n\n## Other commands\n\n```bash\nbloks info react          # Detailed library metadata\nbloks modules hono        # List all modules with API counts\nbloks remove lodash       # Remove a library from the index\nbloks refresh --stale     # Re-index libraries with version drift\nbloks reindex             # Rebuild the card search index\n```\n\n## Output formats\n\n```bash\nbloks react --format text    # Default: human-readable\nbloks react --format json    # Machine-readable JSON\n```\n\n## Architecture\n\n```\n~/.cache/bloks/\n├── index.db          # SQLite with FTS5 — libraries, snippets, relations, events\n├── repos/            # Shallow clones of indexed libraries\n└── cards/            # User .card files (flat directory)\n```\n\n### Indexing pipeline\n\n```\nbloks add \u003cpackage\u003e\n  ├─ 1. Registry resolve (npm/PyPI/crates.io → version, repo URL, docs URL)\n  ├─ 2. Git clone (shallow, into ~/.cache/bloks/repos/)\n  ├─ 3. Source analysis (tldr surface → API snippets with signatures)\n  ├─ 4. Doc indexing (README, CLAUDE.md, AGENTS.md, docs/*.md → doc snippets)\n  ├─ 5. Web docs scraping (llms.txt → sitemap.xml → HTML → text → chunks)\n  ├─ 6. Call graph extraction (tldr calls → caller/callee edges)\n  ├─ 7. Per-file imports (tldr imports → import-scoped symbol resolution)\n  ├─ 8. Public API detection (entry-point re-exports mark visibility)\n  ├─ 9. Relation mining (call graph + doc co-mentions + namespace proximity)\n  └─ 10. FTS5 indexing (snippets_fts for search)\n```\n\n### Source files\n\n| File | Lines | Purpose |\n|------|-------|---------|\n| `main.rs` | ~3000 | CLI, all commands, symbol card generation, relation mining |\n| `analyze.rs` | ~1150 | Source analysis via tldr, call graph, imports, public symbol detection |\n| `db.rs` | ~760 | SQLite schema, CRUD, FTS5, card events, scoring |\n| `scrape.rs` | ~650 | Web docs scraping (llms.txt, sitemap, HTML extraction) |\n| `block.rs` | ~610 | Library/module card generation with progressive disclosure |\n| `cards.rs` | ~430 | User card CRUD, parsing, lineage, FTS indexing |\n| `docs.rs` | ~220 | Repo doc indexing (README, CLAUDE.md, test examples) |\n| `registry.rs` | ~200 | npm/PyPI/crates.io package resolution |\n| `search.rs` | ~100 | FTS5 search with library filtering |\n| `chunk.rs` | ~60 | Markdown chunking by heading |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcadei%2Fbloks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparcadei%2Fbloks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparcadei%2Fbloks/lists"}