{"id":50439962,"url":"https://github.com/grnbtqdbyx-create/contextforge","last_synced_at":"2026-05-31T19:00:32.265Z","repository":{"id":361654684,"uuid":"1255265460","full_name":"grnbtqdbyx-create/contextforge","owner":"grnbtqdbyx-create","description":"Self-learning token and context optimizer for Codex and Claude Code.","archived":false,"fork":false,"pushed_at":"2026-05-31T18:16:47.000Z","size":250,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T18:21:27.296Z","etag":null,"topics":["ai","ai-security","claude-code","cli","codex","coding-agents","context-engineering","developer-tools","github-actions","llm","llm-agents","open-source","prompt-caching","token-usage","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grnbtqdbyx-create.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-31T16:05:08.000Z","updated_at":"2026-05-31T18:15:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grnbtqdbyx-create/contextforge","commit_stats":null,"previous_names":["grnbtqdbyx-create/contextforge"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/grnbtqdbyx-create/contextforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grnbtqdbyx-create%2Fcontextforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grnbtqdbyx-create%2Fcontextforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grnbtqdbyx-create%2Fcontextforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grnbtqdbyx-create%2Fcontextforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grnbtqdbyx-create","download_url":"https://codeload.github.com/grnbtqdbyx-create/contextforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grnbtqdbyx-create%2Fcontextforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33744447,"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-05-31T02:00:06.040Z","response_time":95,"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","ai-security","claude-code","cli","codex","coding-agents","context-engineering","developer-tools","github-actions","llm","llm-agents","open-source","prompt-caching","token-usage","typescript"],"created_at":"2026-05-31T19:00:13.974Z","updated_at":"2026-05-31T19:00:32.243Z","avatar_url":"https://github.com/grnbtqdbyx-create.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ContextForge\n\n**Self-learning token and context optimizer for Codex and Claude Code.**\n\n[![CI](https://github.com/grnbtqdbyx-create/contextforge/actions/workflows/ci.yml/badge.svg)](https://github.com/grnbtqdbyx-create/contextforge/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)\n[![Built in public](https://img.shields.io/badge/built%20in-public-0e8a16.svg)](docs/build-in-public.md)\n[![DCO](https://img.shields.io/badge/DCO-required-7057ff.svg)](CONTRIBUTING.md)\n[![npm publish ready](https://img.shields.io/badge/npm-publish%20ready-cb3837.svg)](docs/npm-publish.md)\n\nAI coding agents burn tokens by re-reading noisy context, huge tool outputs,\nunstable cache prefixes, and bloated root or nested `AGENTS.md` / `CLAUDE.md` files.\nContextForge shows where those tokens go, reduces context bloat, audits cache\nstability, scans repo instructions for prompt/context poisoning, and creates\ntask-specific context packs.\n\nRun it before a PR, release, or long Codex/Claude session to answer one practical\nquestion: **is this repository ready for an agent to work efficiently and safely?**\n\n\u003e Built in public by Ogün Keskin. Early APIs may change.\n\n![ContextForge terminal demo](assets/demo-terminal.svg)\n\n## Report Preview\n\nGenerated from the built CLI with `contextforge report --demo`:\n\n![ContextForge HTML report screenshot](assets/contextforge-report.png)\n\n## Quickstart\n\n```bash\npnpm install\npnpm build\npnpm contextforge doctor --demo\npnpm contextforge scan --demo\npnpm contextforge usage --demo\npnpm contextforge report --demo\n```\n\nExample output:\n\n```text\nContextForge scan complete: 9 records\nProviders: claude, codex\n\nTotal tokens: 12582\nInput: 8832  Output: 3750  Cached: 3328\n```\n\nFor CI or agent workflows:\n\n```bash\ncontextforge init --github-action\ncontextforge doctor --json\ncontextforge audit --min-context-score 70 --min-cache-score 70 --min-security-score 70 --sarif contextforge.sarif --summary contextforge-summary.md\ncontextforge pack --task \"review auth regression\" --budget 20000 --sessions\n```\n\nOr use the GitHub Action before npm publishing is complete:\n\n```yaml\n- uses: grnbtqdbyx-create/contextforge@v0.16.1\n  with:\n    min-context-score: 60\n    min-cache-score: 60\n    min-security-score: 60\n```\n\n## Why ContextForge?\n\n- **See token waste:** identify expensive sessions, tool outputs, and context files.\n- **Improve cache stability:** catch volatile prefixes, timestamps, and large tool dumps.\n- **Audit repo instructions:** keep root and nested `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.clinerules` useful instead of bloated.\n- **Catch context poisoning:** flag instruction overrides, secret exfiltration, unsafe shell, hidden directives, and permission escalation.\n- **Generate explainable context packs:** give Codex or Claude only the files needed for a task, with \"why included\" reasons.\n- **Evolve safely:** suggest improved repo-level rules before writing anything.\n\nIf this saves you tokens or helps your agent work better, please star the repo.\n\n## What Makes It Different?\n\n| Tool category | What it usually does | ContextForge focus |\n| --- | --- | --- |\n| Repository packers | Put many files into one AI-readable prompt. | Build smaller task packs and explain why each file was included. |\n| Token usage dashboards | Show cost after a session happened. | Connect usage, cache stability, and repo context hygiene to next actions. |\n| Agent security scanners | Detect prompt injection or risky agent components. | Audit repo instruction files and ship public malicious-context fixtures. |\n| CI prompt evaluators | Run model or prompt tests in pipelines. | Gate repository context quality with JSON, HTML, SARIF, and Markdown job summaries. |\n\nThe goal is not to replace Repomix, ccusage, promptfoo, or security scanners.\nContextForge is the missing maintainer layer between them: local-first, CI-ready,\nand tuned for Codex/Claude repository work.\n\n## Before / After\n\n| Before ContextForge | After ContextForge |\n| --- | --- |\n| Agents reread noisy logs and broad repo instructions. | Agents get a task-specific context pack. |\n| Token spend is visible only after the session is over. | Token waste is summarized by provider, project, and record kind. |\n| Cache misses are hard to diagnose. | Volatile prefixes and large tool outputs are flagged. |\n| `AGENTS.md` / `CLAUDE.md` grows by guesswork. | Repo instructions get measurable health checks and suggestions. |\n| Malicious repo instructions hide in plain Markdown. | Context security findings fail CI before an agent trusts them. |\n| Context packs are opaque file dumps. | Each selected file includes score reasons such as task term, path, manifest, or instruction file. |\n\n## Commands\n\n```bash\ncontextforge scan [--demo] [--codex] [--claude]\ncontextforge usage [--demo] [--codex] [--claude]\ncontextforge cache-audit [--demo]\ncontextforge security-audit [--demo] [--min-security-score 60]\ncontextforge security-benchmark [--benchmark-dir fixtures/security-benchmark]\ncontextforge agents-md-audit [--demo]\ncontextforge pack --task \"fix auth bug\" --budget 20000 [--demo] [--sessions] [--codex] [--claude]\ncontextforge improve [--demo] [--write] [--open-pr]\ncontextforge report [--demo] [--output contextforge-report.html]\ncontextforge audit [--demo] [--output contextforge-audit.json] [--report contextforge-report.html] [--sarif contextforge.sarif] [--summary contextforge-summary.md] [--min-security-score 60]\ncontextforge doctor [--demo] [--json] [--benchmark-dir fixtures/security-benchmark]\ncontextforge init --github-action [--action-ref grnbtqdbyx-create/contextforge@v0.16.1] [--force]\n```\n\nLocal session scans are bounded by default. Use `--max-session-files` and\n`--max-session-file-mb` when you need a wider or narrower Codex/Claude history\nwindow.\n\n## CI / Dogfood Mode\n\nUse `contextforge audit` in CI to produce a JSON gate, HTML artifact,\nGitHub Code Scanning SARIF file, and Markdown job summary:\n\n```bash\ncontextforge audit --min-context-score 60 --min-cache-score 60 --min-security-score 60 \\\n  --output contextforge-audit.json \\\n  --report contextforge-report.html \\\n  --sarif contextforge.sarif \\\n  --summary contextforge-summary.md\n```\n\nSee [docs/github-action.md](docs/github-action.md) for a complete GitHub Actions\nworkflow. ContextForge also runs this audit against itself.\n\nBy default, `audit` is repo-first and does not scan local session history. Add\n`--codex`, `--claude`, or `--demo` when you want session usage included.\n\nSecurity audit details live in [docs/security-audit.md](docs/security-audit.md).\nPublic malicious-context benchmark details live in\n[docs/security-benchmark.md](docs/security-benchmark.md).\nCodex JSONL parser coverage is documented in\n[docs/codex-session-formats.md](docs/codex-session-formats.md).\nnpm publish preparation is documented in [docs/npm-publish.md](docs/npm-publish.md).\nFirst-run readiness checks are documented in [docs/doctor.md](docs/doctor.md).\n\n## Research-backed Positioning\n\nContextForge learns from popular tools like Repomix, ccusage, AGENTS.md,\ncontext-mode, Claude Context, and LLMLingua, but focuses on a narrower gap:\n**CI-ready context quality audits for coding-agent repositories.**\n\nSee [docs/research/adjacent-tools.md](docs/research/adjacent-tools.md).\n\n## Current Status\n\nContextForge v0.16.1 is a public MVP CLI with:\n\n- Claude Code and Codex JSONL fixture scanners\n- bounded local session scanning fallbacks\n- first-run `contextforge doctor` readiness report with JSON output\n- token usage summaries\n- context health audit with nested monorepo instruction discovery\n- context security audit with nested monorepo instruction discovery\n- public malicious-context benchmark fixtures\n- cache stability audit\n- task-specific Markdown context packs with session-derived scoring\n- HTML report generation\n- SARIF output for GitHub Code Scanning\n- Markdown summaries for GitHub Actions job summaries\n- real README report screenshot generated from the CLI\n- DCO-based contribution flow\n- CI-ready `contextforge audit` dogfood workflow\n- reusable GitHub Action entrypoint\n- `contextforge init --github-action` scaffolding for one-command CI setup\n- manual npm publish workflow draft with OIDC/trusted-publishing preparation\n\n## Roadmap\n\n- **v0.1.0:** CLI MVP, demo mode, scanners, audits, report.\n- **v0.2.0:** CI-ready audit command, GitHub Actions dogfood, adjacent-tool positioning.\n- **v0.3.0:** context-file security audit for malicious repo instructions.\n- **v0.4.0:** explainable context pack scoring with per-file inclusion reasons.\n- **v0.5.0:** real generated HTML report screenshot and packaged README assets.\n- **v0.6.0:** public malicious-context benchmark fixtures and `security-benchmark` command.\n- **v0.7.0:** session-derived context pack scoring from failure/read/edit signals.\n- **v0.8.0:** broader modern Codex rollout JSONL parsing and bounded local scans.\n- **v0.9.0:** manual npm publish workflow draft with dry-run default and OIDC preparation.\n- **v0.9.1:** bounded session scan CLI option forwarding fix.\n- **v0.10.0:** first-run `doctor` command for repo readiness and launch-friendly onboarding.\n- **v0.11.0:** machine-readable `doctor --json` output and sharper README positioning.\n- **v0.12.0:** SARIF output and GitHub Code Scanning dogfood workflow.\n- **v0.13.0:** reusable GitHub Action entrypoint before npm publishing is complete.\n- **v0.14.0:** Markdown audit summaries in GitHub Actions job summaries.\n- **v0.15.0:** recursive monorepo instruction discovery for nested agent files.\n- **v0.16.0:** `contextforge init --github-action` one-command GitHub Action scaffolding.\n- **Next:** first approved npm publish and public launch post.\n\nRelease preparation lives in [docs/release-checklist.md](docs/release-checklist.md).\n\n## Built for Open Source Maintainers\n\nContextForge is designed for maintainers using coding agents to triage issues,\nreview PRs, prepare releases, and preserve code quality without wasting context.\nSee [docs/codex-for-oss.md](docs/codex-for-oss.md).\n\n## Contributing\n\nContributions are welcome. Start with issues labeled `good first issue`.\nAll commits should use DCO sign-off:\n\n```bash\ngit commit -s -m \"Add scanner fixture\"\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License and Trademarks\n\nCode is licensed under Apache-2.0.\n\nCopyright (c) 2026 Ogün Keskin.\n\nThe ContextForge name, logo, domain names, and related branding are trademarks\nof Ogün Keskin. See [TRADEMARKS.md](TRADEMARKS.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrnbtqdbyx-create%2Fcontextforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrnbtqdbyx-create%2Fcontextforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrnbtqdbyx-create%2Fcontextforge/lists"}