{ "markdown": "

\n \"Codemium\n

\n\n

Codemium

\n\n

Persistent coding intelligence for AI coding agents.

\n\n

\n The engineering layer that helps coding agents understand the project, avoid wasteful investigation, make justified changes, and stop when the task is proven.\n

\n\n

\n \"Codemium\n \"Version\n \"MIT\n

\n\n---\n\n## What Codemium does\n\nCodemium is a host-agnostic engineering layer for long-running software projects.\n\nIt helps coding agents:\n\n- reuse verified project knowledge instead of relearning the repository;\n- narrow investigation to the right files, symbols, dependencies, and tests;\n- avoid repeated probes, builds, deployments, and guesses that add no new evidence;\n- make the minimum justified engineering change;\n- verify the real impact before completion;\n- preserve necessary complexity such as security, validation, transactions, retries, compatibility, and tests.\n\n> **Positioning:** the senior engineer who already knows your codebase.\n>\n> **Core law:** Every action must buy information or produce the solution.\n\n## Current release: v0.10.0 — Execution Intelligence\n\nCodemium v0.10.0 focuses on controlling the engineering process itself, not only the final diff.\n\nThe normal loop is:\n\n```text\nTASK\n ↓\nPROJECT BRAIN\n ↓\nSTRUCTURAL INTELLIGENCE\n ↓\nOBSERVE\n ↓\nHYPOTHESIS\n ↓\nCONTRADICTION GATE\n ↓\nEVIDENCE DELTA GATE\n ↓\nCHANGE ONLY IF JUSTIFIED\n ↓\nVERIFY\n ↓\nSLOP GUARD\n ↓\nDONE\n```\n\n### Execution Intelligence\n\nExecution Intelligence prevents zero-information investigation loops.\n\nKey behavior:\n\n- **Contradiction Gate** — conflicting observations must be resolved before mutation.\n- **Hypothesis Ledger** — rejected hypotheses cannot silently cycle back without new evidence.\n- **Evidence Delta Gate** — equivalent probes, builds, deployments, or checks stop when the evidence and repository state have not materially changed.\n- **UI stabilization** — an early negative screenshot does not override stronger DOM/runtime/accessibility evidence.\n- **Action outcomes** — investigation actions are classified as `NEW_EVIDENCE`, `NECESSARY_MUTATION`, `REQUIRED_VERIFICATION`, or `NO_GAIN`.\n\nExample:\n\n```text\nDOM says dropdown is open\n+ screenshot taken too early says not visible\n= contradiction\n\nDo not change z-index yet.\nStabilize the UI, inspect runtime evidence, then decide.\n```\n\nThe goal is the **minimum justified investigation surface**, without arbitrary token or action limits.\n\n### Anti-Slop Intelligence\n\nCodemium also protects the final engineering surface through **Anti-Slop Intelligence** and the **Justified Change Gate**, exposed as **Slop Guard**.\n\nEvery changed surface should be attributable to the task as:\n\n- `DIRECT`\n- `DEPENDENCY`\n- `CLEANUP`\n- `TEST`\n\nInternal `UNJUSTIFIED` work must be explained or removed before completion.\n\nSlop Guard also tracks **finding provenance** such as `introduced`, `worsened`, `pre_existing`, and `unknown`, so historical debt does not automatically become part of the current task.\n\nThe **Underengineering Counter-Gate** prevents “simplification” from removing necessary security, validation, transactions, locking, idempotency, retry behavior, compatibility, data-integrity checks, or tests.\n\n### Polyglot Intelligence\n\n**Polyglot Intelligence** provides deterministic repository understanding across supported languages.\n\nStructural Graph v3 can map:\n\n```text\nDEFINES\nIMPORTS\nIMPORTS_SYMBOL\nCALLS\nREFERENCES\nINHERITS\nIMPLEMENTS\nTESTS\nDEPENDS_ON\n```\n\nPython uses standard-library AST extraction. JavaScript, JSX, TypeScript, and TSX can use Tree-sitter when the optional runtime is installed.\n\nThe graph guides navigation and impact analysis. Source code and runtime/test evidence remain authoritative.\n\n### Project Brain\n\nProject Brain preserves durable, source-backed project knowledge between tasks and hosts.\n\nIt stores useful engineering knowledge such as:\n\n- decisions;\n- constraints;\n- interfaces;\n- architecture patterns;\n- known bugs and risks.\n\nIt does **not** store secrets, raw tool transcripts, temporary execution observations, speculative hypotheses, or full chat history.\n\nKnowledge is freshness-qualified as `FRESH`, `NEEDS_REVALIDATION`, `SUPERSEDED`, or `UNKNOWN`.\n\n## Quick start\n\n### OpenAI Codex\n\n```sh\ncodex plugin marketplace add ahfaruq/codemium --ref main\ncodex plugin add codemium@codemium\n```\n\nThen use Codemium naturally:\n\n```text\n@Codemium fix the profile save bug\n@Codemium deeply investigate why this websocket disconnects intermittently\n@Codemium review this change for unnecessary engineering\n```\n\nAfter upgrading the marketplace/plugin, start a fresh Codex session if plugin inventory is cached.\n\n### Other supported hosts\n\n| Host | Status | Primary invocation |\n| --- | --- | --- |\n| OpenAI Codex | Stable | `@Codemium` |\n| Claude Code | Beta | `/codemium:cm` |\n| Gemini CLI | Beta | `/cm` |\n| Cursor | Beta | `/cm` / skill picker |\n| OpenCode | Beta | `/cm` / skill tool |\n\nSee [`INSTALL.md`](INSTALL.md) and [`HOSTS.md`](HOSTS.md) for host-specific installation details.\n\n## Deterministic helpers\n\nNormal users do not need to run these manually, but they are useful for diagnostics and host integrations:\n\n```sh\npython plugins/codemium/engine/project_brain.py --root . init\npython plugins/codemium/engine/repo_graph.py build --root .\npython plugins/codemium/engine/working_set.py --root . --query \"auth refresh\" --top 8\npython plugins/codemium/engine/impact.py --root . --git-diff\npython plugins/codemium/engine/execution_guard.py --root . status\npython plugins/codemium/engine/slop_guard.py --root . --json --write-state\npython plugins/codemium/engine/health.py --root .\n```\n\n## Design principles\n\n```text\nRepository source → implementation truth\nRuntime/tests → behavioral proof\nStructural graph → navigation and impact evidence\nProject Brain → durable verified knowledge\nExecution Guard → investigation discipline\nSlop Guard → changed-surface discipline\n```\n\nCodemium optimizes for:\n\n> **minimum justified investigation surface + minimum justified engineering surface**\n\nnot minimum LOC, minimum reasoning, or artificial token quotas.\n\n## Verification and benchmarks\n\nCodemium keeps deterministic release-quality checks separate from competitive AI performance claims.\n\nCurrent validation covers engine syntax, Project Brain behavior, Structural Graph v3, Polyglot Intelligence, Execution Intelligence, Evidence Delta Gate, Contradiction Gate, Hypothesis Ledger, Slop Guard, finding provenance, and the Underengineering Counter-Gate.\n\nNo numeric v0.10 token/cost/time improvement claim is published from deterministic fixtures alone. Competitive performance claims require representative measured agent runs.\n\n## Documentation\n\n- [`PRD-v0.10.md`](PRD-v0.10.md) — current Execution Intelligence specification\n- [`RELEASE_NOTES-v0.10.0.md`](RELEASE_NOTES-v0.10.0.md) — current release notes\n- [`INSTALL.md`](INSTALL.md) — installation\n- [`HOSTS.md`](HOSTS.md) — host integration contract\n- [`CHANGELOG.md`](CHANGELOG.md) — complete release history\n- [`benchmarks/`](benchmarks/) — benchmark and calibration material\n\nOlder implementation details are intentionally kept out of this README. Use the changelog and archived PRDs when historical version context is needed.\n\n## Support\n\nCodemium is open source. If it helps your workflow, you can support continued development through GitHub Sponsors.\n\n❤️ [Sponsor Codemium](https://github.com/sponsors/ahfaruq)\n\n## License\n\nMIT\n", "bytes": 7931, "sha": "bc8321496db59bcb0bb0c5d89359cbe51693dd91d64eb6847b15f434b409d992", "repo_slug": "ahfaruq/codemium", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_ahfaruq_codemium_65244338/readme" }