{"slug": "show-hn-contextforge-context-engineering-platform-for-ai-assisted-development", "title": "Show HN: ContextForge – context engineering platform for AI-assisted development", "summary": "ContextForge, a pre-alpha context engineering platform for AI-assisted development, released version 0.4.2 as its first public-release candidate. The tool scans local repositories to build deterministic structural maps, supports bounded task-aware discovery, and exports portable context packages and handoffs, without editing source code or executing arbitrary commands. It requires Python 3.12 or newer and is available via PyPI as contextforge-repo.", "body_md": "**Build bounded, reviewable repository context for coding agents.**\n\nContextForge scans local repositories, builds deterministic structural maps, supports bounded task-aware discovery, and produces portable context packages and handoffs. It helps you decide what an external coding agent should see without giving ContextForge permission to edit source code or run arbitrary commands.\n\n[Quick start](#quick-start) ·\n[CLI](#cli-overview) ·\n[Configuration](#configuration) ·\n[Wiki](https://github.com/waterflane/ContextForge/wiki) ·\n[Discussions](https://github.com/waterflane/ContextForge/discussions) ·\n[Contribution policy](/waterflane/ContextForge/blob/main/CONTRIBUTING.md)\n\nImportant\n\nContextForge is pre-alpha software. Version `0.4.2`\n\nis the first public-release\ncandidate. Discovery benchmarking is experimental and its results should be\nreviewed alongside the recorded provider, model, configuration, and source\nsnapshot.\n\n**Deterministic repository inventory.** Scan files with stable ordering, portable paths, hashes, language classification, ignore rules, and bounded reads.**Reviewable selection.** Choose exact files, directories, GitWildMatch patterns, or line ranges—or ask a configured model for a bounded suggestion.**Local repository intelligence.** Store immutable structural and optional semantic index generations under`.contextforge/index`\n\n.**Portable artifacts.** Export Markdown or JSON context packages, JSON task handoffs, and compiled Markdown prompts.**Explicit trust boundaries.** ContextForge does not edit repository source, execute repository code, expose shell tools, or mutate Git state.**Automation-friendly output.** Structured results stay on stdout while progress and diagnostics stay on stderr.\n\n``` php\nflowchart LR\n    R[\"Repository\"] --> S[\"scan / index\"]\n    S --> D[\"task-aware discovery\"]\n    D --> B[\"bounded selection\"]\n    B --> P[\"context package\"]\n    P --> A[\"external coding agent\"]\n```\n\nA model is optional for scanning, trees, manual context packages, and structural-only indexing:\n\n```\ncontextforge scan .\ncontextforge index build . --provider none\ncontextforge context create . \\\n  --include pyproject.toml \\\n  --directory src/contextforge/context \\\n  --exclude \"**/__init__.py\" \\\n  --format markdown \\\n  --output context.md\n```\n\nContextForge requires Python 3.12 or newer. Install the published distribution:\n\n```\npython -m pip install contextforge-repo\n```\n\nFor an isolated command-line installation, use either tool manager:\n\n```\npipx install contextforge-repo\n# or\nuv tool install contextforge-repo\n```\n\nThe PyPI distribution is named `contextforge-repo`\n\n; the import package remains\n`contextforge`\n\n, and the installed commands remain `contextforge`\n\nand `ctxf`\n\n.\nThe similarly named `context-forge-cli`\n\ndistribution is a different,\nunaffiliated project.\n\nTo install a checked-out source tree instead:\n\n```\ngit clone https://github.com/waterflane/ContextForge.git\ncd ContextForge\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install --upgrade pip\npython -m pip install .\n```\n\nWindows PowerShell:\n\n```\ngit clone https://github.com/waterflane/ContextForge.git\nSet-Location ContextForge\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npython -m pip install .\n```\n\nThe installation provides equivalent `contextforge`\n\nand `ctxf`\n\nconsole\ncommands. `python -m contextforge`\n\nis also supported.\n\nInspect a repository without writing ContextForge state:\n\n```\ncontextforge scan .\ncontextforge tree . --depth 2\ncontextforge context create . `\n  --include 'pyproject.toml' `\n  --directory 'src/contextforge/context' `\n  --exclude '**/__init__.py' `\n  --format json `\n  --output 'context.json'\ncontextforge context inspect 'context.json'\n```\n\nBuild a structural-only local index and inspect its status:\n\n```\ncontextforge index build . --provider none\ncontextforge index status .\n```\n\nTip\n\nStart with manual context creation when you already know the relevant files. Use discovery when the task spans unfamiliar code and you have configured a supported model provider.\n\n- create a compact review packet for an external coding agent;\n- map a repository without sending source to a model;\n- inspect stale, missing, or failed index records;\n- discover likely entry points, tests, configuration, and dependencies for a task;\n- preserve a validated handoff that can be reviewed without the original checkout;\n- benchmark discovery quality and repeatability against versioned manifests.\n\nEvery command supports `--help`\n\n; run group help before using advanced or\nmutating operations.\n\n| Command | Behavior | State |\n|---|---|---|\n`contextforge version` |\nPrint the installed version | Read-only |\n`contextforge doctor` |\nReport basic installation settings | Read-only |\n`contextforge scan [PATH]` |\nInventory repository files | Read-only unless `--output` is used |\n`contextforge tree [PATH]` |\nRender a project tree | Read-only unless `--output` is used |\n`contextforge context suggest [PATH]` |\nSuggest task-relevant context | Source/index read-only; records a safe run summary |\n`contextforge context create [PATH]` |\nBuild a manual package or automatic handoff | Reads source; optional artifact writes |\n`contextforge context inspect PACKAGE` |\nValidate a JSON context package offline | Read-only |\n`contextforge context review PACKAGE` |\nReview a JSON task handoff offline | Read-only |\n`contextforge index build [PATH]` |\nPublish a new local index generation | Mutates `.contextforge/index` |\n`contextforge index update [PATH]` |\nIncrement an existing index | Mutates `.contextforge/index` |\n`contextforge index status [PATH]` |\nInspect source/index drift and lock state | Read-only |\n`contextforge index clean [PATH]` |\nDelete generated index data | Destructive to index data only |\n`contextforge diagnostics last [PATH]` |\nShow the latest safe run summary | Read-only |\n`contextforge diagnostics show PATH ID` |\nShow one safe run summary | Read-only |\n`contextforge diagnostics config [PATH]` |\nExplain effective configuration | Read-only |\n`contextforge diagnostics provider [PATH]` |\nShow provider policy without probing it | Read-only |\n`contextforge mcp serve [PATH]` |\nRun the local read-only stdio MCP server | Read-only session |\n`contextforge benchmark discovery PATH` |\nRun manifest-driven discovery benchmarks | Repository/index read-only; experimental |\n\nGlobal diagnostic options are `--log-level`\n\n, `--log-format`\n\n, `--log-file`\n\n,\nrepeatable `--log-component`\n\n, `--no-log-file`\n\n, `--no-color`\n\n, and `-v`\n\n/`-vv`\n\n.\nDetailed syntax, defaults, streams, side effects, mistakes, and examples are in\nthe [Wiki CLI reference](https://github.com/waterflane/ContextForge/wiki/CLI-Overview).\n\nProject configuration is closed, versioned TOML. Resolution order is:\n\n- command-line option;\n- supported\n`CONTEXTFORGE_*`\n\nenvironment variable; `.contextforge/config.local.toml`\n\n;`.contextforge/config.toml`\n\n, or an explicit`--config PATH`\n\n;- built-in default.\n\nThe primary supported environment variables are:\n\n`CONTEXTFORGE_MODEL_CONTEXT_WINDOW`\n\n;`CONTEXTFORGE_MODEL_CONNECT_TIMEOUT`\n\n;`CONTEXTFORGE_MODEL_READ_TIMEOUT`\n\n;`CONTEXTFORGE_MODEL_OPERATION_TIMEOUT`\n\n;`CONTEXTFORGE_JSON_REPAIR_ATTEMPTS`\n\n;`CONTEXTFORGE_LOG_LEVEL`\n\n,`CONTEXTFORGE_LOG_FORMAT`\n\n,`CONTEXTFORGE_LOG_FILE`\n\n, and`CONTEXTFORGE_LOG_COMPONENTS`\n\n.\n\nThe default provider is local Ollama at\n`http://127.0.0.1:11434/api/chat`\n\nusing model `qwen2.5-coder:7b`\n\n. Use\n`--provider none`\n\nfor structural-only indexing. The `openai-compatible`\n\nprovider and its `lmstudio`\n\nCLI alias require an exact model ID and a suitable\n`base_url`\n\n.\n\nModel-backed discovery requires the configured provider to be running with the\nnamed model available. ContextForge's configured `context_window`\n\nmust not\nexceed the window actually loaded by that provider; inspect the resolved policy\nbefore a long run with `contextforge diagnostics provider PATH`\n\n.\n\nCredential configuration stores only the name of an environment variable in\n`credential_env`\n\n; the credential value is resolved at request time. See the\n[configuration guide](/waterflane/ContextForge/blob/main/docs/guides/configuration.md) and\n[Wiki configuration reference](https://github.com/waterflane/ContextForge/wiki/Configuration).\n\n**Fresh** builds current structural evidence in memory and does not load persisted semantic records or repository maps.**Indexed** requires a readable active index and uses current indexed structure, semantics, and maps.**Hybrid** is the default. It starts with current index evidence, fills structural gaps from the live snapshot, and explicitly falls back to fresh structure when no valid index exists.\n\nAll successful selections are verified against current source identities.\nModel-backed runs can produce different valid selections; ContextForge claims\ndeterministic rendering for the same validated result, not deterministic model\nbehavior. See [Discovery output and benchmarks](/waterflane/ContextForge/blob/main/docs/guides/discovery.md).\n\nManual packages use explicit selectors. With no include selector, all selectable snapshot files are included up to the configured limits:\n\n```\ncontextforge context create . --include README.md --format markdown\ncontextforge context create . --directory src --exclude \"**/__init__.py\"\ncontextforge context create . --glob \"tests/test_*.py\" --no-include-tree\ncontextforge context create . \\\n  --include pyproject.toml \\\n  --include-lines pyproject.toml:1-24 \\\n  --format json\n```\n\nAutomatic mode requires a non-empty task and does not accept manual directory, glob, or line-range selectors:\n\n```\ncontextforge context suggest . \\\n  --task \"Trace configuration precedence\" \\\n  --discovery hybrid \\\n  --format markdown\n\ncontextforge context create . \\\n  --task \"Trace configuration precedence\" \\\n  --discovery hybrid \\\n  --git-diff working \\\n  --format json \\\n  --output handoff.json \\\n  --prompt-output prompt.md\n```\n\n`context suggest`\n\ndoes not write source or index state, but current diagnostics\npolicy may write a safe summary under `.contextforge/runs`\n\n. Output artifacts are\nwritten atomically; existing destinations require `--force`\n\nwhere that option\nis available.\n\nNote\n\n`benchmark discovery`\n\nis experimental in `0.4.2`\n\n; model-backed repeatability\nmeasurements are observations for the recorded fixture state, not guarantees.\nStart the configured provider first and use the same context-window value in\nContextForge and the provider runtime.\n\n```\ncontextforge benchmark discovery 'C:\\Repositories' `\n  --tasks '.\\benchmarks\\discovery.json' `\n  --modes 'fresh,indexed,hybrid' `\n  --repeat 3 `\n  --format json `\n  --output '.\\benchmark-report.json'\n```\n\nThe runner is repository/index read-only, disables configured file logging, and\nrecords complete, failed, and cancelled runs in the result. Exit code `3`\n\nmeans\nthe command produced a complete benchmark report containing at least one task,\nexpectation, or budget failure. Do not discard stdout or the requested output\nfile when handling that code. Every run remains bounded by manifest limits,\nprovider retry limits, operation timeouts, and the configured context window.\n\n- scans:\n`table`\n\n,`json`\n\n; - trees:\n`text`\n\n,`markdown`\n\n,`json`\n\n; - suggestions:\n`text`\n\n, compatibility alias`table`\n\n,`markdown`\n\n,`json`\n\n; - context packages:\n`markdown`\n\n,`json`\n\n; - index status and diagnostics:\n`table`\n\n,`json`\n\n; - discovery benchmarks:\n`text`\n\n,`markdown`\n\n,`json`\n\n.\n\nWhen no output path is supplied, the selected result is written to stdout. Progress, logs, and errors use stderr, preserving parseable JSON stdout. Some commands print a confirmation to stdout after writing a file; benchmark output files are the exception and leave stdout empty.\n\nCommon process exit codes are `0`\n\nfor success, `1`\n\nfor operational failure, `2`\n\nfor invalid usage or configuration, and `130`\n\nfor cancellation. Exit code `3`\n\nhas command-specific meaning: unreadable entries with `scan --fail-on-error`\n\n, or\na completed discovery benchmark with regression failures.\n\nContextForge is a typed Python modular monolith. Core application and domain logic remain independent from Typer, FastAPI, model-provider implementations, storage adapters, and future editor integrations. The scanner creates a verified snapshot; intelligence extracts structural facts and optional semantic interpretations; discovery selects bounded candidates; context and handoff modules materialize portable artifacts; CLI, HTTP, and MCP are thin interfaces.\n\nRead the [architecture overview](/waterflane/ContextForge/blob/main/docs/architecture/overview.md) for dependency\nboundaries and the [security policy](/waterflane/ContextForge/blob/main/SECURITY.md) for trust and path-safety\ndetails.\n\n[CLI logging and diagnostics](/waterflane/ContextForge/blob/main/docs/guides/cli.md)[Configuration](/waterflane/ContextForge/blob/main/docs/guides/configuration.md)[Discovery and benchmarking](/waterflane/ContextForge/blob/main/docs/guides/discovery.md)[Development](/waterflane/ContextForge/blob/main/docs/guides/development.md)[Troubleshooting](/waterflane/ContextForge/blob/main/docs/guides/troubleshooting.md)[Architecture notes](/waterflane/ContextForge/blob/main/docs/architecture/overview.md)[Complete GitHub Wiki](https://github.com/waterflane/ContextForge/wiki)\n\nThe Wiki is maintained in its separate GitHub Wiki repository. A prepared local\n`wiki/`\n\nworkspace is intentionally ignored by the main repository.\n\n```\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npython -m pip install -e \".[dev]\"\npython -m ruff check .\npython -m mypy src\npython -m pytest\n```\n\nBuild validation and owner-only publication steps are in the\n[release checklist](/waterflane/ContextForge/blob/main/docs/RELEASE_CHECKLIST.md). Release publication is an\nowner-triggered workflow protected by GitHub environments and PyPI OIDC.\n\nContextForge is pre-alpha and under active solo-maintainer development. Manual scanning, trees, context packages, local indexing, diagnostics, and read-only MCP are implemented. Model-assisted discovery depends on the configured provider and its structured-output behavior. Remote MCP transport, autonomous source edits, shell/process tools, embeddings, IDE extensions, and coding-agent orchestration are not implemented.\n\nUse the Q&A category in GitHub Discussions for usage and support questions. Use GitHub Issues for reproducible bugs and focused feature suggestions. Do not post secrets, repository source, full prompts, or private logs in either place.\n\nExternal contributions are welcome through a fork and pull request into `dev`\n\n.\nDiscuss large changes in an Issue before implementation. Merges require owner\napproval and passing CI; contributors do not need direct repository write\naccess. See [CONTRIBUTING.md](/waterflane/ContextForge/blob/main/CONTRIBUTING.md).\n\nContextForge `0.4.2`\n\nand later are licensed under the\n[Apache License 2.0](/waterflane/ContextForge/blob/main/LICENSE). Earlier tagged releases remain available under\nthe license included in those release snapshots. See [NOTICE](/waterflane/ContextForge/blob/main/NOTICE) for the\nproject attribution notice.", "url": "https://wpnews.pro/news/show-hn-contextforge-context-engineering-platform-for-ai-assisted-development", "canonical_source": "https://github.com/waterflane/ContextForge", "published_at": "2026-08-21 11:14:08+00:00", "updated_at": "2026-08-21 11:44:44.404976+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["ContextForge", "PyPI", "Python"], "alternates": {"html": "https://wpnews.pro/news/show-hn-contextforge-context-engineering-platform-for-ai-assisted-development", "markdown": "https://wpnews.pro/news/show-hn-contextforge-context-engineering-platform-for-ai-assisted-development.md", "text": "https://wpnews.pro/news/show-hn-contextforge-context-engineering-platform-for-ai-assisted-development.txt", "jsonld": "https://wpnews.pro/news/show-hn-contextforge-context-engineering-platform-for-ai-assisted-development.jsonld"}}