Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/grnbtqdbyx-create/contextforge

Self-learning token and context optimizer for Codex and Claude Code.
https://github.com/grnbtqdbyx-create/contextforge

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

Last synced: 13 days ago
JSON representation

Self-learning token and context optimizer for Codex and Claude Code.

Awesome Lists containing this project

README 

          
# ContextForge



**Self-learning token and context optimizer for Codex and Claude Code.**



[![CI](https://github.com/grnbtqdbyx-create/contextforge/actions/workflows/ci.yml/badge.svg)](https://github.com/grnbtqdbyx-create/contextforge/actions/workflows/ci.yml)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

[![Built in public](https://img.shields.io/badge/built%20in-public-0e8a16.svg)](docs/build-in-public.md)

[![DCO](https://img.shields.io/badge/DCO-required-7057ff.svg)](CONTRIBUTING.md)

[![npm publish ready](https://img.shields.io/badge/npm-publish%20ready-cb3837.svg)](docs/npm-publish.md)



AI coding agents burn tokens by re-reading noisy context, huge tool outputs,

unstable cache prefixes, and bloated root or nested `AGENTS.md` / `CLAUDE.md` files.

ContextForge shows where those tokens go, reduces context bloat, audits cache

stability, scans repo instructions for prompt/context poisoning, and creates

task-specific context packs.



Run it before a PR, release, or long Codex/Claude session to answer one practical

question: **is this repository ready for an agent to work efficiently and safely?**



> Built in public by Ogün Keskin. Early APIs may change.



![ContextForge terminal demo](assets/demo-terminal.svg)



## Report Preview



Generated from the built CLI with `contextforge report --demo`:



![ContextForge HTML report screenshot](assets/contextforge-report.png)



## Quickstart



```bash

pnpm install

pnpm build

pnpm contextforge doctor --demo

pnpm contextforge scan --demo

pnpm contextforge usage --demo

pnpm contextforge report --demo

```



Example output:



```text

ContextForge scan complete: 9 records

Providers: claude, codex



Total tokens: 12582

Input: 8832  Output: 3750  Cached: 3328

```



For CI or agent workflows:



```bash

contextforge init --github-action

contextforge doctor --json

contextforge audit --min-context-score 70 --min-cache-score 70 --min-security-score 70 --sarif contextforge.sarif --summary contextforge-summary.md

contextforge pack --task "review auth regression" --budget 20000 --sessions

```



Or use the GitHub Action before npm publishing is complete:



```yaml

- uses: grnbtqdbyx-create/contextforge@v0.16.1

  with:

    min-context-score: 60

    min-cache-score: 60

    min-security-score: 60

```



## Why ContextForge?



- **See token waste:** identify expensive sessions, tool outputs, and context files.

- **Improve cache stability:** catch volatile prefixes, timestamps, and large tool dumps.

- **Audit repo instructions:** keep root and nested `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.clinerules` useful instead of bloated.

- **Catch context poisoning:** flag instruction overrides, secret exfiltration, unsafe shell, hidden directives, and permission escalation.

- **Generate explainable context packs:** give Codex or Claude only the files needed for a task, with "why included" reasons.

- **Evolve safely:** suggest improved repo-level rules before writing anything.



If this saves you tokens or helps your agent work better, please star the repo.



## What Makes It Different?



| Tool category | What it usually does | ContextForge focus |

| --- | --- | --- |

| Repository packers | Put many files into one AI-readable prompt. | Build smaller task packs and explain why each file was included. |

| Token usage dashboards | Show cost after a session happened. | Connect usage, cache stability, and repo context hygiene to next actions. |

| Agent security scanners | Detect prompt injection or risky agent components. | Audit repo instruction files and ship public malicious-context fixtures. |

| CI prompt evaluators | Run model or prompt tests in pipelines. | Gate repository context quality with JSON, HTML, SARIF, and Markdown job summaries. |



The goal is not to replace Repomix, ccusage, promptfoo, or security scanners.

ContextForge is the missing maintainer layer between them: local-first, CI-ready,

and tuned for Codex/Claude repository work.



## Before / After



| Before ContextForge | After ContextForge |

| --- | --- |

| Agents reread noisy logs and broad repo instructions. | Agents get a task-specific context pack. |

| Token spend is visible only after the session is over. | Token waste is summarized by provider, project, and record kind. |

| Cache misses are hard to diagnose. | Volatile prefixes and large tool outputs are flagged. |

| `AGENTS.md` / `CLAUDE.md` grows by guesswork. | Repo instructions get measurable health checks and suggestions. |

| Malicious repo instructions hide in plain Markdown. | Context security findings fail CI before an agent trusts them. |

| Context packs are opaque file dumps. | Each selected file includes score reasons such as task term, path, manifest, or instruction file. |



## Commands



```bash

contextforge scan [--demo] [--codex] [--claude]

contextforge usage [--demo] [--codex] [--claude]

contextforge cache-audit [--demo]

contextforge security-audit [--demo] [--min-security-score 60]

contextforge security-benchmark [--benchmark-dir fixtures/security-benchmark]

contextforge agents-md-audit [--demo]

contextforge pack --task "fix auth bug" --budget 20000 [--demo] [--sessions] [--codex] [--claude]

contextforge improve [--demo] [--write] [--open-pr]

contextforge report [--demo] [--output contextforge-report.html]

contextforge audit [--demo] [--output contextforge-audit.json] [--report contextforge-report.html] [--sarif contextforge.sarif] [--summary contextforge-summary.md] [--min-security-score 60]

contextforge doctor [--demo] [--json] [--benchmark-dir fixtures/security-benchmark]

contextforge init --github-action [--action-ref grnbtqdbyx-create/contextforge@v0.16.1] [--force]

```



Local session scans are bounded by default. Use `--max-session-files` and

`--max-session-file-mb` when you need a wider or narrower Codex/Claude history

window.



## CI / Dogfood Mode



Use `contextforge audit` in CI to produce a JSON gate, HTML artifact,

GitHub Code Scanning SARIF file, and Markdown job summary:



```bash

contextforge audit --min-context-score 60 --min-cache-score 60 --min-security-score 60 \

  --output contextforge-audit.json \

  --report contextforge-report.html \

  --sarif contextforge.sarif \

  --summary contextforge-summary.md

```



See [docs/github-action.md](docs/github-action.md) for a complete GitHub Actions

workflow. ContextForge also runs this audit against itself.



By default, `audit` is repo-first and does not scan local session history. Add

`--codex`, `--claude`, or `--demo` when you want session usage included.



Security audit details live in [docs/security-audit.md](docs/security-audit.md).

Public malicious-context benchmark details live in

[docs/security-benchmark.md](docs/security-benchmark.md).

Codex JSONL parser coverage is documented in

[docs/codex-session-formats.md](docs/codex-session-formats.md).

npm publish preparation is documented in [docs/npm-publish.md](docs/npm-publish.md).

First-run readiness checks are documented in [docs/doctor.md](docs/doctor.md).



## Research-backed Positioning



ContextForge learns from popular tools like Repomix, ccusage, AGENTS.md,

context-mode, Claude Context, and LLMLingua, but focuses on a narrower gap:

**CI-ready context quality audits for coding-agent repositories.**



See [docs/research/adjacent-tools.md](docs/research/adjacent-tools.md).



## Current Status



ContextForge v0.16.1 is a public MVP CLI with:



- Claude Code and Codex JSONL fixture scanners

- bounded local session scanning fallbacks

- first-run `contextforge doctor` readiness report with JSON output

- token usage summaries

- context health audit with nested monorepo instruction discovery

- context security audit with nested monorepo instruction discovery

- public malicious-context benchmark fixtures

- cache stability audit

- task-specific Markdown context packs with session-derived scoring

- HTML report generation

- SARIF output for GitHub Code Scanning

- Markdown summaries for GitHub Actions job summaries

- real README report screenshot generated from the CLI

- DCO-based contribution flow

- CI-ready `contextforge audit` dogfood workflow

- reusable GitHub Action entrypoint

- `contextforge init --github-action` scaffolding for one-command CI setup

- manual npm publish workflow draft with OIDC/trusted-publishing preparation



## Roadmap



- **v0.1.0:** CLI MVP, demo mode, scanners, audits, report.

- **v0.2.0:** CI-ready audit command, GitHub Actions dogfood, adjacent-tool positioning.

- **v0.3.0:** context-file security audit for malicious repo instructions.

- **v0.4.0:** explainable context pack scoring with per-file inclusion reasons.

- **v0.5.0:** real generated HTML report screenshot and packaged README assets.

- **v0.6.0:** public malicious-context benchmark fixtures and `security-benchmark` command.

- **v0.7.0:** session-derived context pack scoring from failure/read/edit signals.

- **v0.8.0:** broader modern Codex rollout JSONL parsing and bounded local scans.

- **v0.9.0:** manual npm publish workflow draft with dry-run default and OIDC preparation.

- **v0.9.1:** bounded session scan CLI option forwarding fix.

- **v0.10.0:** first-run `doctor` command for repo readiness and launch-friendly onboarding.

- **v0.11.0:** machine-readable `doctor --json` output and sharper README positioning.

- **v0.12.0:** SARIF output and GitHub Code Scanning dogfood workflow.

- **v0.13.0:** reusable GitHub Action entrypoint before npm publishing is complete.

- **v0.14.0:** Markdown audit summaries in GitHub Actions job summaries.

- **v0.15.0:** recursive monorepo instruction discovery for nested agent files.

- **v0.16.0:** `contextforge init --github-action` one-command GitHub Action scaffolding.

- **Next:** first approved npm publish and public launch post.



Release preparation lives in [docs/release-checklist.md](docs/release-checklist.md).



## Built for Open Source Maintainers



ContextForge is designed for maintainers using coding agents to triage issues,

review PRs, prepare releases, and preserve code quality without wasting context.

See [docs/codex-for-oss.md](docs/codex-for-oss.md).



## Contributing



Contributions are welcome. Start with issues labeled `good first issue`.

All commits should use DCO sign-off:



```bash

git commit -s -m "Add scanner fixture"

```



See [CONTRIBUTING.md](CONTRIBUTING.md).



## License and Trademarks



Code is licensed under Apache-2.0.



Copyright (c) 2026 Ogün Keskin.



The ContextForge name, logo, domain names, and related branding are trademarks

of Ogün Keskin. See [TRADEMARKS.md](TRADEMARKS.md).