{"id":51018659,"url":"https://github.com/ashlrai/ashlr-core-efficiency","last_synced_at":"2026-06-21T14:01:32.399Z","repository":{"id":351485690,"uuid":"1211085882","full_name":"ashlrai/ashlr-core-efficiency","owner":"ashlrai","description":"Token-efficiency primitives for Claude Code: genome, compression, provider-aware budgeting.","archived":false,"fork":false,"pushed_at":"2026-04-24T04:07:28.000Z","size":81,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T06:14:54.745Z","etag":null,"topics":["ai","anthropic","bun","claude-code","context-compression","genome","library","rag","token-efficiency","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/masonwyatt23/ashlr-plugin","language":"TypeScript","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/ashlrai.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-15T03:49:57.000Z","updated_at":"2026-04-24T04:07:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ashlrai/ashlr-core-efficiency","commit_stats":null,"previous_names":["masonwyatt23/ashlr-core-efficiency","ashlrai/ashlr-core-efficiency"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ashlrai/ashlr-core-efficiency","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlr-core-efficiency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlr-core-efficiency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlr-core-efficiency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlr-core-efficiency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashlrai","download_url":"https://codeload.github.com/ashlrai/ashlr-core-efficiency/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashlrai%2Fashlr-core-efficiency/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34610832,"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-21T02:00:05.568Z","response_time":54,"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":["ai","anthropic","bun","claude-code","context-compression","genome","library","rag","token-efficiency","typescript"],"created_at":"2026-06-21T14:01:30.301Z","updated_at":"2026-06-21T14:01:32.388Z","avatar_url":"https://github.com/ashlrai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @ashlr/core-efficiency\n\nToken-efficiency primitives for AI coding agents — genome RAG, multi-tier context compression, provider-aware budgeting, and prompt-caching helpers.\n\nExtracted from [ashlrcode](https://github.com/ashlrai/ashlrcode) and shared by the `ashlrcode` CLI and the [ashlr-plugin](https://github.com/ashlrai/ashlr-plugin) for Claude Code.\n\n**Platform support:** macOS / Linux / Windows on Bun \u003e= 1.0 and Node \u003e= 20.\n\n---\n\n## Modules\n\n| Subpath | LOC | Purpose |\n|---------|-----|---------|\n| [`/genome`](./src/genome) | ~2,342 | Self-evolving project specs via RAG + scribe protocol. Manifest CRUD, TF-IDF/Ollama retrieval, fitness-based strategy evolution, mutation audit trail. |\n| [`/compression`](./src/compression) | ~470 | 3-tier context compression: `autoCompact` (LLM summarize old turns), `snipCompact` (truncate tool results \u003e 2 KB), `contextCollapse` (drop short/dup). `PromptPriority` enum. |\n| [`/budget`](./src/budget) | ~50 | Provider-aware prompt budgeting. `getProviderContextLimit`, `systemPromptBudget`. |\n| [`/tokens`](./src/tokens) | ~50 | Token estimation: `estimateTokensFromString`, `estimateTokensFromMessages`. |\n| [`/anthropic`](./src/anthropic) | ~200 | Anthropic SDK helpers: `withGenome`, `cacheBreakpoints`, `ashlrMcpConfig`. |\n| [`/session-log`](./src/session-log) | ~150 | Structured session event log (tool calls, costs, savings). |\n| [`/local`](./src/local) | ~120 | Context-window manager for small-context local models. |\n| [`/types`](./src/types) | ~60 | Shared types: `Message`, `ContentBlock`, `LLMSummarizer`, `StreamEvent`. |\n\n---\n\n## Install\n\n```bash\n# Bun (primary runtime)\nbun add @ashlr/core-efficiency\n\n# npm / pnpm / yarn\nnpm install @ashlr/core-efficiency\n```\n\nFor local development against a checkout:\n\n```bash\nbun add file:../ashlr-core-efficiency\n```\n\nThe package ships TypeScript source in `src/`. Bun runs it directly. For Node.js, compile first with `bun run build` (outputs to `dist/`).\n\n---\n\n## Quickstart\n\n### compression\n\n```typescript\nimport {\n  autoCompact,\n  snipCompact,\n  contextCollapse,\n  PromptPriority,\n} from \"@ashlr/core-efficiency/compression\";\n\n// Truncate any tool result that exceeds 2 KB (head + tail elided middle).\nconst trimmed = snipCompact(messages, { maxBytes: 2048 });\n\n// Drop short or duplicate messages to reduce prompt size.\nconst collapsed = contextCollapse(messages);\n\n// LLM-summarize old turns when approaching the context limit.\nconst compacted = await autoCompact(messages, summarizer, {\n  targetTokens: 50_000,\n  priority: PromptPriority.High,\n});\n```\n\n### budget\n\n```typescript\nimport {\n  getProviderContextLimit,\n  systemPromptBudget,\n} from \"@ashlr/core-efficiency/budget\";\n\nconst limit = getProviderContextLimit(\"anthropic\");     // 200_000\nconst budget = systemPromptBudget(\"anthropic\", 0.05, 50_000);  // 5% floor, 50K cap\n```\n\n### tokens\n\n```typescript\nimport {\n  estimateTokensFromString,\n  estimateTokensFromMessages,\n} from \"@ashlr/core-efficiency/tokens\";\n\nconst n = estimateTokensFromString(\"Hello, world!\");\nconst total = estimateTokensFromMessages(messages);  // walks ContentBlock[] incl. tool results\n```\n\n### genome\n\n```typescript\nimport {\n  retrieveSectionsV2,\n  injectGenomeContext,\n  genomeExists,\n} from \"@ashlr/core-efficiency/genome\";\n\nif (await genomeExists(process.cwd())) {\n  const sections = await retrieveSectionsV2(\"architecture overview\", process.cwd(), {\n    maxTokens: 2000,\n  });\n  const system = injectGenomeContext(baseSystem, sections);\n}\n```\n\n### anthropic\n\n```typescript\nimport Anthropic from \"@anthropic-ai/sdk\";\nimport { withGenome, cacheBreakpoints } from \"@ashlr/core-efficiency/anthropic\";\n\nconst client = new Anthropic();\nconst system = await withGenome(\"You are a senior engineer.\", process.cwd());\n\nconst req = cacheBreakpoints({\n  system,\n  messages: [\n    { role: \"user\", content: projectContext, cache: true },\n    { role: \"user\", content: \"What does login.ts do?\" },\n  ],\n});\n\nawait client.messages.create({ ...req, model: \"claude-sonnet-4-6\", max_tokens: 1024 });\n```\n\nFor stdio MCP tools via the Agent SDK:\n\n```typescript\nimport { query } from \"@anthropic-ai/claude-agent-sdk\";\nimport { ashlrMcpConfigRecord } from \"@ashlr/core-efficiency/anthropic\";\n\nconst mcpServers = ashlrMcpConfigRecord({ plugins: [\"efficiency\"] });\nfor await (const msg of query({ prompt: \"...\", options: { mcpServers } })) {\n  // ...\n}\n```\n\nSee [`examples/anthropic-sdk/`](./examples/anthropic-sdk/) for runnable scenarios.\n\n### session-log\n\n```typescript\nimport { SessionLog } from \"@ashlr/core-efficiency/session-log\";\n\nconst log = new SessionLog();\nlog.record({ type: \"tool_call\", tool: \"ashlr__read\", inputTokens: 120 });\nconsole.log(log.summary());\n```\n\n### local\n\n```typescript\nimport { LocalContextManager } from \"@ashlr/core-efficiency/local\";\n\nconst mgr = new LocalContextManager({ contextWindow: 4096 });\nconst messages = mgr.fit(allMessages);  // drops oldest turns to stay within window\n```\n\nRoot barrel export (all subpaths re-exported):\n\n```typescript\nimport {\n  autoCompact,\n  getProviderContextLimit,\n  retrieveSectionsV2,\n  estimateTokensFromString,\n} from \"@ashlr/core-efficiency\";\n```\n\n---\n\n## Compatibility\n\n| Runtime | macOS | Linux | Windows |\n|---------|-------|-------|---------|\n| Bun \u003e= 1.0 | Yes | Yes | Yes |\n| Node \u003e= 20 | Yes (compile first) | Yes (compile first) | Yes (compile first) |\n\nPath separators are normalized internally; no Unix-only assumptions.\n\n---\n\n## Development\n\n```bash\nbun install\nbun test          # ~17 unit tests (budget + tokens)\nbun run typecheck\nbun run build     # emit dist/ for Node consumers\n```\n\nIntegration tests live in the [ashlrcode repo](https://github.com/ashlrai/ashlrcode) where 700+ tests run against real-world consumers.\n\n---\n\n## Design notes\n\n- **`LLMSummarizer` interface**: `autoCompact` and genome `scribe` depend on a minimal `{ stream(ProviderRequest): AsyncGenerator\u003cStreamEvent\u003e }` contract, not a concrete router. Consumers inject their own provider.\n- **`PromptPriority` enum**: 12 named slots (`Core=0` through `Undercover=95`). Numeric values are stable — raw-int callers continue to work across versions.\n- **`estimateTokens`**: previously duplicated in three places. Now one implementation, two entry points: `FromString` and `FromMessages` (walks `ContentBlock[]` including `tool_use`/`tool_result`).\n- **Source-first exports**: `main` and `exports` point to `src/`. Bun resolves `.ts` imports directly. For Node.js, run `bun run build` and consume from `dist/`. A `module` field mirrors `main` for bundlers that inspect it.\n\n---\n\n## Versioning\n\nFollows semver. Breaking changes (removed exports, changed interfaces) go to major versions. Additive exports and bug fixes are minor/patch.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashlrai%2Fashlr-core-efficiency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashlrai%2Fashlr-core-efficiency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashlrai%2Fashlr-core-efficiency/lists"}