ContextForge

Agent Context Gate for Codex, Claude Code, GitHub Copilot, MCP, Cursor, Cline, Gemini, and Windsurf repos.

AI coding agents do not fail only because the model is weak. They fail because repositories feed them noisy instructions, unstable cache prefixes, giant tool outputs, over-broad tool configs, and unsafe Markdown they treat as trusted context.

ContextForge is a local-first CI gate for that layer. Run it before a PR, release, or long agent session to answer one practical question: is this repository ready for an agent to work efficiently, cheaply, and safely?

30-second proof

contextforge doctor --summary contextforge-doctor.md
contextforge scorecard --output contextforge-scorecard.md
contextforge audit --min-context-score 70 --min-cache-score 70 --min-security-score 80
contextforge surface-map --output contextforge-agent-surface-map.md
contextforge surface-inventory --output contextforge-agent-surface-inventory.md
contextforge surface-diff --base main --output contextforge-agent-surface-diff.md

The doctor report now gives one first-readiness answer across context health, security benchmark fixtures, MCP exposure, Claude Code settings, agentic workflows, GitHub Actions hardening, public proof, launch assets, and community health. The scorecard is the one-screen README/PR view. The audit gates context health, cache stability, and prompt/context poisoning. The surface map shows exactly which agent-facing files are covered before a maintainer has to read every doc. The inventory shows the agent-readable files that are actually present in the current repository. The diff shows which agent-readable files changed in a PR before reviewers trust the new context.

Agent stack	Surfaces ContextForge checks
Codex	AGENTS.md, root instructions, MCP configs, context packs, session traces
Claude Code	CLAUDE.md, .claude/settings*.json, skills, subagents, slash commands, traces
GitHub Copilot	custom instructions, prompt files, custom agents, hooks, workspace settings
MCP / Cursor / Cline / Gemini / Windsurf	tool configs, .cursor/rules/**/*.mdc, .clinerules/**/*.{md,txt}, GEMINI.md, .windsurfrules, repo-local guidance

If you are...	ContextForge gives you...
Reviewing AI-written PRs	changed-file review kits, PR comments, proof packs, and artifact maps
Maintaining an agent-heavy repo	CI gates for context health, cache stability, and prompt-injection risk
Launching an OSS tool	generated proof surfaces that visitors, Codex, Claude, and Copilot users can verify

Open the current launch snapshot for the why-now, adjacent-category, proof-first story behind the project.

Built in public by Ogün Keskin. Apache-2.0 code, trademarks reserved, early APIs may change.

Report Preview

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

Real Output

The checked-in demo output is generated by the CLI, not hand-written: examples/demo-output.md. The PR-ready audit comment preview is generated too: examples/pr-comment.md. For review workflows, inspect the generated Codex/Claude brief: examples/review-kit.md. Coding agents can start from llms.txt or the expanded llms-full.txt project map. For concrete maintainer workflows, see docs/use-cases.md. For the current launch snapshot, see docs/launch-snapshot.md. For a first-time evaluator page, see docs/adoption.md. For the generated artifact catalog, see docs/artifacts.md. For adjacent-tool positioning, see docs/comparison.md. For GitHub Copilot customization coverage, see docs/copilot-instructions.md. For the one-screen Codex/Claude readiness snapshot, see contextforge-scorecard.md. For the cross-agent support matrix, see contextforge-agent-surface-map.md. For the repo-specific agent surface inventory, see contextforge-agent-surface-inventory.md. For the PR-specific changed agent surface diff, see contextforge-agent-surface-diff.md. For committed MCP config risk checks, see contextforge-mcp-audit.md. For committed Claude Code settings risk checks, see contextforge-claude-audit.md. For the agentic workflow risk model and command details, see docs/workflow-audit.md. For agentic GitHub workflow injection risk, see contextforge-workflow-audit.md. For GitHub Actions hardening risk, see contextforge-actions-audit.md and docs/actions-audit.md. For session trace efficiency, see contextforge-trace-audit.md. For configurable session cost estimates, see contextforge-cost-estimate.md. For a demo context pack with a visible budget ledger, see contextforge-pack.md. CI can also upload a structured suggestions file and compact status badge: contextforge-suggestions.json and contextforge-badge.svg. First-run readiness can be published as Markdown with contextforge doctor --summary contextforge-doctor.md, or bundled into a single proof packet with contextforge proof-pack --output contextforge-proof-pack.md.

contextforge examples --output examples/demo-output.md
contextforge launch-snapshot --output docs/launch-snapshot.md
contextforge adoption-brief --output docs/adoption.md
contextforge artifact-map --output docs/artifacts.md
contextforge scorecard --output contextforge-scorecard.md
contextforge surface-map --output contextforge-agent-surface-map.md
contextforge surface-inventory --output contextforge-agent-surface-inventory.md
contextforge surface-diff --base main --output contextforge-agent-surface-diff.md
contextforge mcp-audit --summary contextforge-mcp-audit.md --sarif contextforge-mcp.sarif
contextforge claude-audit --summary contextforge-claude-audit.md --sarif contextforge-claude.sarif
contextforge workflow-audit --summary contextforge-workflow-audit.md --sarif contextforge-workflow.sarif
contextforge actions-audit --summary contextforge-actions-audit.md --sarif contextforge-actions.sarif
contextforge trace-audit --demo --summary contextforge-trace-audit.md
contextforge cost-estimate --demo --summary contextforge-cost-estimate.md --input-price-per-mtok 2 --cached-input-price-per-mtok 0.2 --output-price-per-mtok 10
contextforge pack --demo --task "review auth regression" --budget 600 --output contextforge-pack.md
contextforge publish-readiness --summary contextforge-publish-readiness.md
contextforge review-kit --demo --base main --output examples/review-kit.md
contextforge doctor --summary contextforge-doctor.md
contextforge proof-pack --output contextforge-proof-pack.md
contextforge launch-kit --output docs/launch-post.md
contextforge compare --output docs/comparison.md
contextforge audit --demo --comment examples/pr-comment.md --badge contextforge-badge.svg --base main

Which Artifact Should I Open?

Need	Open
30-second agent readiness proof	contextforge-scorecard.md
Why this project matters now	docs/launch-snapshot.md
First-time maintainer evaluation	docs/adoption.md
Cross-agent surface coverage	contextforge-agent-surface-map.md
Actual repo agent surfaces	contextforge-agent-surface-inventory.md
Changed PR agent surfaces	contextforge-agent-surface-diff.md
MCP config risk	contextforge-mcp-audit.md
Claude Code project settings risk	contextforge-claude-audit.md
Agentic workflow injection risk	contextforge-workflow-audit.md
GitHub Actions hardening risk	contextforge-actions-audit.md
Agent trace efficiency	contextforge-trace-audit.md
Session cost estimate	contextforge-cost-estimate.md
Context pack budget proof	contextforge-pack.md
PR review	contextforge-pr-comment.md -> contextforge-review-kit.md
Launch or OSS proof	contextforge-proof-pack.md
First npm publish	contextforge-publish-readiness.md
Agent fix plan	contextforge-agent-plan.md
Full artifact catalog	docs/artifacts.md

60-Second Proof

Run these commands and get both the short snapshot and deeper proof packet:

contextforge scorecard --output contextforge-scorecard.md
contextforge proof-pack --output contextforge-proof-pack.md

The scorecard is the short README-ready snapshot. The proof pack combines doctor checks, audit scores, evidence commands, and a Codex/Claude handoff note. It is designed for launch posts, PR descriptions, OSS applications, and README updates where people need to verify the project without reading the whole repository first.

For the shorter first-run checklist:

contextforge doctor --summary contextforge-doctor.md

That Markdown file shows context health, cache stability, context security, public proof files, launch profile assets, community health files, and next actions. It is designed to drop into a launch issue, PR description, README update, or build-in-public post without asking contributors to trust a screenshot.

For a PR review handoff to Codex, Claude, or a human reviewer:

contextforge review-kit --base main --output contextforge-review-kit.md

That file lists changed files, infers review focus areas, includes rerun commands, and writes a copyable Codex/Claude review prompt. It is designed for agent-written PRs, workflow changes, README/AGENTS/CLAUDE edits, and any branch where green CI alone is not enough proof.

For a PR-specific view of changed agent instructions, rules, settings, and tool configs:

contextforge surface-diff --base main --output contextforge-agent-surface-diff.md

That file names the changed agent-readable surfaces, affected ecosystems, and follow-up checks before a reviewer lets Codex, Claude, Copilot, Cursor, Cline, Gemini, or Windsurf trust the branch.

For a quick map of which generated file to open first:

contextforge artifact-map --output docs/artifacts.md

That file explains every ContextForge JSON, Markdown, SARIF, SVG, and HTML artifact, including fast paths for PR reviewers, Codex/Claude fix sessions, and public launch proof.

For a first-time maintainer or OSS reviewer deciding whether the project is worth trying:

contextforge adoption-brief --output docs/adoption.md

That file gives the 30-second proof path, adjacent-tool positioning, try-it commands before npm publish, and the proof checklist visitors should inspect before starring or wiring ContextForge into CI.

For the shortest shareable why-now page:

contextforge launch-snapshot --output docs/launch-snapshot.md

That file gives README visitors and launch readers the adjacent-category map, what proof to open first, and copy they can share without trusting screenshots.

For committed MCP server configuration risk:

contextforge mcp-audit --summary contextforge-mcp-audit.md --sarif contextforge-mcp.sarif

That file flags hardcoded MCP secrets, remote shell installers, and unpinned package launches before Codex, Claude, or another coding agent loads the repo's tooling.

For committed Claude Code project settings risk:

contextforge claude-audit --summary contextforge-claude-audit.md --sarif contextforge-claude.sarif

That file flags risky project defaultMode, broad Bash allow rules, remote shell hooks, wildcard HTTP hook destinations, and missing sensitive-file deny rules before Claude Code users trust shared repo settings.

For repeated tool calls, bulky tool output, and low cache reuse in Codex/Claude traces:

contextforge trace-audit --demo --summary contextforge-trace-audit.md

That file gives a compact efficiency readout before you start another long agent session or publish a build-in-public proof packet.

For configurable session cost estimates without stale hardcoded pricing:

contextforge cost-estimate --demo --summary contextforge-cost-estimate.md --input-price-per-mtok 2 --cached-input-price-per-mtok 0.2 --output-price-per-mtok 10

That file separates uncached input, cached input, output, provider buckets, and project buckets so token dashboards and ContextForge proof files can meet in one place.

For a launch-ready public narrative, generate the repo's shareable post and topic checklist:

contextforge launch-kit --output docs/launch-post.md

To explain where ContextForge fits next to Repomix, ccusage, promptfoo, and agent security scanners:

contextforge compare --output docs/comparison.md

Quickstart

pnpm install
pnpm build
pnpm contextforge doctor --demo
pnpm contextforge launch-snapshot
pnpm contextforge scan --demo
pnpm contextforge usage --demo
pnpm contextforge report --demo
pnpm contextforge plan --demo
pnpm contextforge artifact-map
pnpm contextforge adoption-brief
pnpm contextforge scorecard
pnpm contextforge surface-map
pnpm contextforge surface-diff
pnpm contextforge mcp-audit
pnpm contextforge publish-readiness
pnpm contextforge proof-pack --demo
pnpm contextforge review-kit --demo
pnpm contextforge examples
pnpm contextforge launch-kit
pnpm contextforge compare

Example output:

ContextForge scan complete: 9 records
Providers: claude, codex

Total tokens: 12582
Input: 8832  Output: 3750  Cached: 3328

For CI or agent workflows:

contextforge init --all --project-name "My Repo"
contextforge doctor --json --summary contextforge-doctor.md
contextforge launch-snapshot --output docs/launch-snapshot.md
contextforge artifact-map --output docs/artifacts.md
contextforge adoption-brief --output docs/adoption.md
contextforge scorecard --output contextforge-scorecard.md
contextforge surface-map --output contextforge-agent-surface-map.md
contextforge surface-inventory --output contextforge-agent-surface-inventory.md
contextforge surface-diff --base main --output contextforge-agent-surface-diff.md
contextforge mcp-audit --summary contextforge-mcp-audit.md --sarif contextforge-mcp.sarif
contextforge claude-audit --summary contextforge-claude-audit.md --sarif contextforge-claude.sarif
contextforge workflow-audit --summary contextforge-workflow-audit.md --sarif contextforge-workflow.sarif
contextforge trace-audit --demo --summary contextforge-trace-audit.md
contextforge cost-estimate --demo --summary contextforge-cost-estimate.md --input-price-per-mtok 2 --cached-input-price-per-mtok 0.2 --output-price-per-mtok 10
contextforge publish-readiness --summary contextforge-publish-readiness.md
contextforge proof-pack --output contextforge-proof-pack.md
contextforge review-kit --base main --output contextforge-review-kit.md
contextforge audit --min-context-score 70 --min-cache-score 70 --min-security-score 70 --sarif contextforge.sarif --summary contextforge-summary.md --plan contextforge-agent-plan.md --comment contextforge-pr-comment.md --suggestions contextforge-suggestions.json --badge contextforge-badge.svg --base main
contextforge plan --output contextforge-agent-plan.md
contextforge pack --task "review auth regression" --budget 20000 --sessions --output contextforge-pack.md

Or use the GitHub Action before npm publishing is complete:

- uses: grnbtqdbyx-create/contextforge@v0.73.0
  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.
• Check public trust surfaces: verify README, license, contributing, changelog, demo output, and LLM discovery docs from contextforge doctor.
• Verify launch profile surfaces: check demo assets, artifact map, launch kit, and comparison guide from contextforge doctor.
• Check community health surfaces: verify Code of Conduct, security policy, issue templates, and PR template files before asking contributors to help.
• Explain why the project matters now: generate docs/launch-snapshot.md with the current adjacent-category map, proof-first path, and share copy for README visitors.
• Share one proof packet: combine doctor checks, audit scores, evidence commands, and Codex/Claude handoff guidance with contextforge proof-pack.
• Map generated artifacts: write a maintainer-friendly guide for every JSON, Markdown, SARIF, SVG, and HTML output with contextforge artifact-map.
• Guide first-time evaluators: generate docs/adoption.md so maintainers can decide quickly whether ContextForge is worth trying, starring, or wiring into CI.
• Show a one-screen readiness scorecard: publish contextforge-scorecard.md so README visitors, reviewers, Codex, and Claude can see the repo's agent readiness quickly.
• Show exactly which agent surfaces are covered: publish contextforge-agent-surface-map.md so visitors can scan Codex, Claude Code, GitHub Copilot, MCP, Cursor, Cline, Gemini CLI, and Windsurf coverage in one table.
• Show which agent surfaces actually exist: publish contextforge-agent-surface-inventory.md so visitors and CI readers can see the real repo-local instructions, rules, settings, and tool configs ContextForge found.
• Show which agent surfaces changed in a PR: publish contextforge-agent-surface-diff.md so reviewers can see whether AGENTS.md, CLAUDE.md, Copilot prompts, MCP configs, Cursor/Cline/Gemini/Windsurf rules, or README entrypoints moved before trusting agent output.
• Audit MCP exposure: publish contextforge-mcp-audit.md and contextforge-mcp.sarif so committed MCP configs cannot quietly ship hardcoded secrets, remote shell installers, unpinned package launches, auto-approval, broad tool permissions, or symlinked config files.
• Audit Claude Code settings: publish contextforge-claude-audit.md and contextforge-claude.sarif so repo-committed Claude settings cannot quietly ship bypass modes, broad Bash permissions, remote shell hooks, or missing sensitive-file denies.
• Audit agentic workflows: publish contextforge-workflow-audit.md and contextforge-workflow.sarif so GitHub workflows cannot quietly feed untrusted issue, PR, review, comment, title, input, or branch text into privileged agents.
• Audit GitHub Actions hardening: publish contextforge-actions-audit.md and contextforge-actions.sarif so agent-authored workflows cannot quietly ship mutable action tags, missing permissions, pwn-request checkout, or shell interpolation of untrusted GitHub context.
• Audit trace efficiency: publish contextforge-trace-audit.md so repeated tool calls, huge outputs, tool-output-heavy traces, and low cache reuse are visible before the next long agent session.
• Estimate session cost: publish contextforge-cost-estimate.md with runtime price inputs for uncached input, cached input, and output tokens.
• Publish the artifact map from CI: attach contextforge-artifact-map.md beside proof-pack and review-kit outputs in reusable and generated GitHub workflows.
• Prove npm readiness before publishing: generate contextforge-publish-readiness.md so package metadata, provenance links, Trusted Publishing workflow safety, GitHub tarball attestation, and human setup are visible separately.
• Prepare GitHub Actions for Node 24: dogfood and generated workflows opt into FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 before GitHub's JavaScript action runtime migration.
• Prepare review handoffs: generate a changed-file review kit with focus areas, evidence commands, and a copyable Codex/Claude prompt.
• Publish first-run proof: write contextforge-doctor.md from doctor --summary for issues, PRs, launch posts, or README updates.
• Generate a launch kit: write a one-liner, proof commands, suggested GitHub topics, launch post draft, and maintainer checklist.
• Explain the category: generate a comparison guide that shows where ContextForge complements Repomix, ccusage, promptfoo, and security scanners.
• Improve cache stability: catch volatile prefixes, timestamps, and large tool dumps.
• Audit repo instructions, hooks, agents, commands, and workspace settings: keep root README.md, nested AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, .github/prompts/**/*.prompt.md, .github/agents/**/*.md, .github/agents/**/*.agent.md, project SKILL.md files, .claude/agents/**/*.md, .claude/commands/**/*.md, .github/hooks/*.json, committed .github/copilot/settings*.json, .vscode/settings.json, committed *.code-workspace, .cursor/rules/**/*.mdc, .cursorrules, .clinerules/**/*.{md,txt}, .clinerules, .windsurfrules, and .windsurf/rules/**/*.{md,mdc,txt} useful instead of bloated or unsafe.
• Bootstrap minimal context files: scaffold concise AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md files without filling the repo with vague prompt folklore.
• Catch context poisoning: flag instruction overrides, secret exfiltration, unsafe shell, hidden directives, and permission escalation.
• Generate budgeted context packs: give Codex or Claude only the files needed for a task, with "why included" reasons and a visible budget ledger.
• Create agent action plans: turn audit findings into prioritized Markdown that Codex or Claude can execute from.
• Show PR-ready evidence: emit a compact deterministic Markdown comment that review workflows can publish or archive, including changed agent-surface summaries and pointers to contextforge-proof-pack.md, contextforge-review-kit.md, and contextforge-agent-surface-diff.md.
• Publish visible proof: emit contextforge-badge.svg so CI can expose a compact agent-context status badge.
• Expose LLM-readable docs: ship llms.txt and llms-full.txt so coding agents can orient quickly.
• 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.
Agent handoff notes	Leave scattered instructions in PR comments or chats.	Emit a repeatable contextforge-agent-plan.md artifact plus a compact PR-ready comment.

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, Copilot prompts, custom agents, or skills grow by guesswork.	Repo instructions get measurable health checks and suggestions.
New repos copy giant agent prompts from the internet.	contextforge init --agents-md --claude-md starts from a minimal, test-oriented template.
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.
A failed audit leaves humans to infer the fix order.	contextforge plan produces a prioritized agent-readable fix plan.
CI evidence stays hidden in artifacts.	--comment contextforge-pr-comment.md creates a review-surface summary.
Reviewers miss deeper proof hidden in artifact lists.	PR comments point at contextforge-proof-pack.md for shareable doctor/audit evidence.
Reviewers miss the agent review brief.	PR comments point at contextforge-review-kit.md for Codex/Claude review focus.
Agent-written PRs get shallow review prompts.	review-kit gives Codex, Claude, and humans the changed files, risk focus, proof commands, and review prompt.
Reviewers do not know which artifact to open first.	artifact-map catalogs every generated output and gives fast paths for PR review, agent fixes, and public launch proof.
CI runs upload many files with no index.	Reusable and generated workflows publish contextforge-artifact-map.md beside the proof pack and review kit.
README visitors need the why-now story quickly.	launch-snapshot writes a shareable page with adjacent categories, first proof artifacts, and launch copy.
First-time visitors need a decision path.	adoption-brief writes a one-page evaluator guide with proof commands and adjacent-tool positioning.
README visitors need a fast answer before reading docs.	scorecard writes a one-screen Codex/Claude readiness snapshot.
Visitors ask whether their agent stack is covered.	surface-map writes a Codex, Claude Code, GitHub Copilot, MCP, Cursor, Cline, Gemini CLI, and Windsurf surface matrix.
Visitors ask what this repo actually exposes to agents.	surface-inventory writes the detected repo-local agent surfaces and matching proof commands.
Reviewers miss when a PR changes agent behavior.	surface-diff writes the changed agent-readable files, affected ecosystems, and follow-up checks for the branch.
Agent tool configs can hide supply-chain risk.	mcp-audit checks committed MCP configs for hardcoded secrets, remote shell installers, unpinned package launches, auto-approval, broad tool permissions, and symlinked config files.
MCP findings should show up in GitHub Security.	mcp-audit --sarif writes contextforge-mcp.sarif with mcp-exposure/* rule ids for Code Scanning.
Claude Code settings can over-trust a repo.	claude-audit checks shared .claude/settings.json permissions, hooks, bypass modes, and sensitive-file denies.
Agentic GitHub workflows can ingest attacker-controlled text.	workflow-audit checks whether issue, PR, review, comment, title, workflow input, or branch/ref text flows into agentic jobs with write permissions or secrets.
Agent-authored CI can weaken the release path.	actions-audit checks workflow SHA pins, token permissions, Node 24 runtime opt-in, pull_request_target, pwn-request checkout, and direct script interpolation.
Claude Code subagents and custom slash commands can hide powerful project prompts.	security-audit, context health, and context packs include .claude/agents/**/*.md and .claude/commands/**/*.md.
Copilot hooks can run shell commands during agent workflows.	security-audit scans .github/hooks/*.json and committed .github/copilot/settings*.json for unsafe shell, exfiltration, hidden directives, and permission weakening.
VS Code workspace settings can carry Copilot instructions.	security-audit scans .vscode/settings.json and committed *.code-workspace files for risky Copilot review, commit, and PR instruction text.
First npm publish is a vague manual checklist.	publish-readiness separates verified repo setup, provenance metadata, GitHub tarball attestation, npm account state, and environment steps that require the maintainer.
Coding agents guess which docs matter.	llms.txt points them at the important project surfaces.
Agents need structured fixes, not copied bullets.	contextforge improve --json emits parseable rule suggestions.
Repo visitors need instant proof.	--badge contextforge-badge.svg creates a compact audit status badge.
OSS launch readiness is scattered.	contextforge doctor checks public proof surfaces in one report.
README launch assets go stale.	contextforge doctor checks demo assets, launch kit, and comparison guide in the first-run report.
Maintainers need to prove readiness outside CI.	proof-pack writes one shareable Markdown packet with doctor, audit, commands, and agent handoff.
Contributors do not know how to help safely.	contextforge doctor checks community health files in the same first-run report.
First-run proof is trapped in terminal output.	doctor --summary writes a Markdown report for README, issues, PRs, or launch posts.
Launch copy drifts from the real CLI.	launch-kit generates a public post and topic checklist from the current project framing.
Visitors cannot tell why another tool exists.	compare generates a positioning guide against adjacent agent-context tools.

Commands

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] [--output contextforge-pack.md]
contextforge improve [--demo] [--json] [--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] [--plan contextforge-agent-plan.md] [--comment contextforge-pr-comment.md] [--suggestions contextforge-suggestions.json] [--badge contextforge-badge.svg] [--base main] [--min-security-score 60]
contextforge doctor [--demo] [--json] [--summary contextforge-doctor.md] [--benchmark-dir fixtures/security-benchmark]
contextforge plan [--demo] [--output contextforge-agent-plan.md] [--min-context-score 60] [--min-cache-score 60] [--min-security-score 60]
contextforge examples [--output examples/demo-output.md]
contextforge launch-kit [--output docs/launch-post.md] [--project-name "My App"]
contextforge launch-snapshot [--output docs/launch-snapshot.md] [--project-name "My App"]
contextforge adoption-brief [--output docs/adoption.md] [--project-name "My App"]
contextforge compare [--output docs/comparison.md]
contextforge proof-pack [--demo] [--output contextforge-proof-pack.md]
contextforge scorecard [--demo] [--json] [--output contextforge-scorecard.md]
contextforge surface-map [--output contextforge-agent-surface-map.md]
contextforge surface-inventory [--json] [--output contextforge-agent-surface-inventory.md]
contextforge surface-diff [--base main] [--json] [--output contextforge-agent-surface-diff.md]
contextforge mcp-audit [--demo] [--json] [--summary contextforge-mcp-audit.md] [--sarif contextforge-mcp.sarif]
contextforge claude-audit [--demo] [--json] [--summary contextforge-claude-audit.md] [--sarif contextforge-claude.sarif]
contextforge workflow-audit [--demo] [--json] [--summary contextforge-workflow-audit.md] [--sarif contextforge-workflow.sarif]
contextforge actions-audit [--json] [--summary contextforge-actions-audit.md] [--sarif contextforge-actions.sarif]
contextforge trace-audit [--demo] [--json] [--summary contextforge-trace-audit.md]
contextforge cost-estimate [--demo] [--json] [--summary contextforge-cost-estimate.md] [--input-price-per-mtok 0] [--cached-input-price-per-mtok 0] [--output-price-per-mtok 0]
contextforge review-kit [--demo] [--base main] [--output contextforge-review-kit.md]
contextforge artifact-map [--output docs/artifacts.md]
contextforge publish-readiness [--json] [--summary contextforge-publish-readiness.md]
contextforge init [--all] [--github-action] [--pr-comment-workflow] [--agents-md] [--claude-md] [--copilot-instructions] [--project-name "My App"] [--action-ref grnbtqdbyx-create/contextforge@v0.73.0] [--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: It can also emit an agent-readable action plan artifact:

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 \
  --plan contextforge-agent-plan.md \
  --comment contextforge-pr-comment.md \
  --suggestions contextforge-suggestions.json \
  --badge contextforge-badge.svg \
  --base main
contextforge artifact-map --output docs/artifacts.md
contextforge adoption-brief --output docs/adoption.md
contextforge scorecard --output contextforge-scorecard.md
contextforge surface-map --output contextforge-agent-surface-map.md
contextforge surface-inventory --output contextforge-agent-surface-inventory.md
contextforge surface-diff --base main --output contextforge-agent-surface-diff.md
contextforge mcp-audit --summary contextforge-mcp-audit.md --sarif contextforge-mcp.sarif
contextforge claude-audit --summary contextforge-claude-audit.md --sarif contextforge-claude.sarif
contextforge proof-pack --output contextforge-proof-pack.md
contextforge review-kit --base main --output contextforge-review-kit.md

See docs/github-action.md for a complete GitHub Actions workflow. ContextForge also runs this audit against itself.

For repositories that want a sticky PR comment, run:

contextforge init --all --project-name "My Repo"

--all writes the audit workflow, optional PR comment workflow, AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md. The PR comment workflow remains a separate file because posting comments requires pull-requests: write.

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. Practical maintainer scenarios live in docs/use-cases.md. Public malicious-context benchmark details live in docs/security-benchmark.md. The evaluator adoption brief lives in docs/adoption.md. Codex JSONL parser coverage is documented in docs/codex-session-formats.md. npm publish preparation is documented in docs/npm-publish.md. Run contextforge publish-readiness --summary contextforge-publish-readiness.md before the first publish attempt. First-run readiness checks are documented in docs/doctor.md. Proof pack generation is documented in docs/proof-pack.md. Scorecard generation is documented in docs/scorecard.md. Surface inventory generation is documented in docs/surface-inventory.md. Surface diff generation is documented in docs/surface-diff.md. Review-kit generation is documented in docs/review-kit.md. MCP exposure audits are documented in docs/mcp-audit.md. Claude Code settings audits are documented in docs/claude-audit.md. GitHub Copilot customization coverage is documented in docs/copilot-instructions.md. The artifact map is documented in docs/artifacts.md. Agent-readable fix plans are documented in docs/agent-action-plan.md. Minimal agent context scaffolding is documented in docs/agent-context-init.md.

Research-backed Positioning

ContextForge learns from popular tools like Repomix, ccusage, GitHub Copilot custom instructions, 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.

Current Status

ContextForge v0.73.0 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
• shareable contextforge doctor --summary Markdown reports
• doctor, proof-pack, and scorecard hardening checks for Claude settings, agentic workflows, and GitHub Actions release safety
• shareable contextforge proof-pack readiness packets for launch, PR, and OSS evidence
• generated contextforge adoption-brief evaluator pages for first-time maintainers
• one-screen contextforge scorecard readiness snapshots for README, PR, and CI artifact readers
• contextforge surface-map support matrices for audited Codex, Claude Code, GitHub Copilot, MCP, Cursor, Cline, Gemini CLI, and Windsurf repo surfaces
• contextforge surface-inventory repo-specific inventories for the actual agent-readable files present in a repository
• contextforge surface-diff PR-specific changed-surface reports for agent-readable files and follow-up checks
• committed MCP config exposure audits for hardcoded secrets, unsafe shell installers, unpinned package launches, auto-approval, broad tool permissions, and symlinked config files
• committed Claude Code settings audits for bypass modes, broad Bash allow rules, remote shell hooks, wildcard HTTP hooks, and missing sensitive-file denies
• Claude Code project subagent and custom slash-command discovery for .claude/agents/**/*.md and .claude/commands/**/*.md
• GitHub Copilot customization discovery for .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, .github/prompts/**/*.prompt.md, .github/agents/**/*.md, .github/agents/**/*.agent.md, and project skills under .github/skills, .claude/skills, and .agents/skills
• VS Code chat.instructionsFilesLocations discovery for repo-relative custom Copilot instruction folders
• GitHub Copilot path-scoped instruction checks that flag .github/instructions/**/*.instructions.md files missing applyTo frontmatter
• GitHub Copilot hook security scanning for .github/hooks/*.json and committed .github/copilot/settings*.json
• VS Code Copilot workspace settings security scanning for .vscode/settings.json and committed *.code-workspace files
• adjacent agent rule discovery and security scanning for .cursor/rules/**/*.mdc, .clinerules/**/*.{md,txt}, GEMINI.md, .windsurfrules, and .windsurf/rules/**/*.{md,mdc,txt} files
• agent trace efficiency audits for redundant tool calls, bulky tool output, tool-output-dominant traces, and low cache reuse
• configurable session cost estimates with caller-provided per-1M token prices
• deterministic contextforge review-kit briefs for Codex, Claude, and human PR review
• reusable GitHub Action and dogfood workflow support for contextforge-proof-pack.md
• reusable GitHub Action and dogfood workflow support for contextforge-scorecard.md
• reusable GitHub Action and dogfood workflow support for contextforge-agent-surface-map.md
• reusable GitHub Action and dogfood workflow support for contextforge-agent-surface-inventory.md
• reusable GitHub Action and dogfood workflow support for contextforge-agent-surface-diff.md
• reusable GitHub Action and dogfood workflow support for contextforge-mcp-audit.md and contextforge-mcp.sarif
• reusable GitHub Action and dogfood workflow support for contextforge-claude-audit.md and contextforge-claude.sarif
• reusable GitHub Action and dogfood workflow support for contextforge-workflow-audit.md and contextforge-workflow.sarif
• reusable GitHub Action and dogfood workflow support for contextforge-actions-audit.md and contextforge-actions.sarif
• reusable GitHub Action and dogfood workflow support for contextforge-review-kit.md
• reusable GitHub Action and dogfood workflow support for contextforge-artifact-map.md
• PR-ready comments that summarize changed agent-readable surfaces and point reviewers at contextforge-proof-pack.md, contextforge-review-kit.md, and contextforge-agent-surface-diff.md
• generated contextforge artifact-map catalogs for reviewers, agents, and launch visitors
• generated contextforge launch-snapshot pages for first-time visitors and build-in-public posts
• generated contextforge publish-readiness checks for npm Trusted Publishing preparation and GitHub tarball attestation setup
• npm provenance metadata checks for repository, homepage, and issue tracker links
• GitHub workflow Node 24 JavaScript action runtime opt-in for dogfood and generated workflows
• actions-audit checks for missing GitHub Actions Node 24 JavaScript runtime opt-ins before hosted-runner defaults change
• generated contextforge launch-kit build-in-public launch posts
• generated contextforge compare adjacent-tool positioning guides
• Public proof surfaces doctor check for OSS trust/readiness files
• Launch profile surfaces doctor check for demo assets, artifact map, launch kit, and comparison guide
• Community health surfaces doctor check for contributor-readiness files
• token usage summaries
• machine-readable contextforge improve --json repo-rule suggestions
• CI-ready contextforge-suggestions.json improvement artifacts
• compact contextforge-badge.svg audit status badges
• context health audit with nested monorepo and GitHub Copilot customization discovery
• context security audit with nested monorepo, GitHub Copilot customization discovery, Claude subagent and command discovery, project skill, hook, workspace settings scanning, and root README injection checks
• public malicious-context benchmark fixtures
• cache stability audit
• task-specific Markdown context packs with session-derived scoring and real budget ledgers
• HTML report generation
• SARIF output for GitHub Code Scanning
• Markdown summaries for GitHub Actions job summaries
• PR-ready Markdown comments for review surfaces
• agent-readable action plans for Codex/Claude handoff
• deterministic public demo output generated from fixture data
• LLM-readable llms.txt and llms-full.txt project maps
• practical maintainer use cases with commands, artifacts, and success signals
• 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
• contextforge init --pr-comment-workflow scaffolding for opt-in sticky PR comments
• contextforge init --all scaffolding for the full recommended setup
• contextforge init --agents-md --claude-md --copilot-instructions scaffolding for minimal Codex/Claude/Copilot context files
• manual npm publish workflow draft with OIDC/trusted-publishing readiness checks and attested npm tarballs

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.
• v0.17.0: agent-readable action plans from contextforge plan and audit --plan.
• v0.18.0: minimal AGENTS.md and CLAUDE.md scaffolding.
• v0.19.0: root README prompt-injection scanning and benchmark coverage.
• v0.20.0: deterministic public demo output for README and repo visitors.
• v0.21.0: PR-ready deterministic audit comment artifact.
• v0.22.0: opt-in sticky PR comment workflow scaffolding and init --all.
• v0.23.0: LLM-readable llms.txt and llms-full.txt discovery docs.
• v0.24.0: maintainer use-case guide for first PR gates, security defense, cache triage, and context packs.
• v0.25.0: machine-readable improve --json suggestions for agent and bot consumption.
• v0.26.0: audit-level contextforge-suggestions.json artifact for CI and reusable actions.
• v0.27.0: SVG audit badge artifact for visible repo proof.
• v0.28.0: public proof surface checks in contextforge doctor.
• v0.29.0: community health surface checks in contextforge doctor.
• v0.30.0: shareable Markdown doctor summaries for issues, PRs, README updates, and launch posts.
• v0.31.0: generated launch kit with proof commands, topics, launch copy, and maintainer checklist.
• v0.32.0: generated comparison guide for adjacent agent-context tools.
• v0.33.0: launch profile surface checks in contextforge doctor.
• v0.34.0: shareable proof packs that combine doctor, audit, commands, and Codex/Claude handoff guidance.
• v0.35.0: proof-pack artifacts in the reusable GitHub Action, generated workflow, and dogfood workflow.
• v0.36.0: proof-pack visibility in PR-ready comments for reviewer handoff.
• v0.37.0: review kits with changed files, risk focus, proof commands, and Codex/Claude prompts.
• v0.38.0: review-kit artifacts in the reusable GitHub Action, generated workflow, and dogfood workflow.
• v0.39.0: PR-ready comments point reviewers at both proof-pack and review-kit artifacts.
• v0.40.0: generated artifact maps for reviewer, agent, and public launch handoffs.
• v0.41.0: artifact-map artifacts in the reusable GitHub Action, generated workflow, and dogfood workflow.
• v0.42.0: npm publish-readiness checks and summary artifacts before first publish.
• v0.43.0: npm provenance metadata checks and Node 24 GitHub Actions runtime opt-in.
• v0.44.0: README-ready agent readiness scorecards in CLI and CI artifacts.
• v0.45.0: MCP exposure audits in CLI, doctor, scorecard, reusable action, generated workflow, and dogfood artifacts.
• v0.46.0: MCP permission exposure checks for auto-approved and broadly permitted agent tools.
• v0.47.0: Symlinked MCP config detection before agents load tool definitions.
• v0.48.0: Evaluator adoption briefs for first-time maintainers and OSS reviewers.
• v0.49.0: MCP exposure SARIF for GitHub Code Scanning.
• v0.50.0: Claude Code project settings audit and SARIF for shared permissions and hooks.
• v0.51.0: Agent trace efficiency audit for repeated tools, bulky outputs, and cache reuse.
• v0.52.0: Configurable session cost estimates for input, cached input, and output tokens.
• v0.53.0: Context pack budget ledger with final-content token enforcement.
• v0.54.0: GitHub Copilot repository and path-scoped instruction audit/scaffold support.
• v0.55.0: GitHub Copilot prompt file, custom agent, and project skill audit support.
• v0.56.0: GitHub Copilot hook config security scanning.
• v0.57.0: VS Code Copilot workspace settings security scanning.
• v0.58.0: Claude Code project subagent and custom slash-command auditing.
• v0.59.0: Cross-agent surface map artifact for Codex, Claude Code, GitHub Copilot, MCP, Cursor, and Cline coverage.
• v0.60.0: README first-viewport positioning with a 30-second proof path and cross-agent coverage table.
• v0.61.0: Adjacent agent rule discovery for modern Cursor, Cline, Gemini CLI, and Windsurf repo-local instruction files.
• v0.62.0: Repo-specific agent surface inventory for the actual instruction, rule, settings, and tool files present in a repository.
• v0.63.0: PR-specific agent surface diffs for changed instruction, rule, settings, and tool files.
• v0.64.0: PR comments embed changed agent-surface summaries using the same base ref as the surface-diff artifact.
• v0.65.0: npm publish workflow packs, attests, uploads, and publishes the same release tarball.
• v0.66.0: launch snapshots explain the why-now, adjacent-category, and proof-first story for README visitors.
• v0.67.0: agentic workflow audits catch untrusted GitHub event text flowing into privileged AI workflows.
• v0.68.0: workflow audits expand attacker-controlled coverage to titles and branch/ref text.
• v0.69.0: GitHub Actions audits catch mutable action refs, pwn-request checkout, missing permissions, and direct script interpolation.
• v0.70.0: doctor, proof-pack, and scorecard reports surface Claude settings, agentic workflow, and GitHub Actions hardening evidence in one readiness path.
• v0.71.0: GitHub Actions audits catch missing Node 24 JavaScript action runtime opt-ins and document the known runner annotation behavior.
• v0.72.0: Context health audits catch path-scoped Copilot instruction files missing applyTo frontmatter.
• v0.73.0: Context discovery follows repo-relative VS Code chat.instructionsFilesLocations folders for custom Copilot instruction files.
• Next: first approved npm publish and external launch outreach.

Release preparation lives in 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.

Contributing

Contributions are welcome. Start with issues labeled good first issue. All commits should use DCO sign-off:

git commit -s -m "Add scanner fixture"

See 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.