{"id":48794721,"url":"https://github.com/derek-palmer/codeforerunner","last_synced_at":"2026-05-26T21:01:07.383Z","repository":{"id":349355150,"uuid":"1201968179","full_name":"derek-palmer/codeforerunner","owner":"derek-palmer","description":"CodeForerunner is a model-agnostic documentation agent that acts as a guardian for your repository, automatically analyzing code and maintaining docs, diagrams, and architecture knowledge as your codebase evolves over time.","archived":false,"fork":false,"pushed_at":"2026-05-24T14:48:01.000Z","size":1091,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T15:24:09.317Z","etag":null,"topics":["ai","ai-agents","documentation"],"latest_commit_sha":null,"homepage":"","language":"Python","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/derek-palmer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-05T12:15:52.000Z","updated_at":"2026-05-24T14:48:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/derek-palmer/codeforerunner","commit_stats":null,"previous_names":["derek-palmer/codeforerunner"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/derek-palmer/codeforerunner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derek-palmer%2Fcodeforerunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derek-palmer%2Fcodeforerunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derek-palmer%2Fcodeforerunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derek-palmer%2Fcodeforerunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derek-palmer","download_url":"https://codeload.github.com/derek-palmer/codeforerunner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derek-palmer%2Fcodeforerunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33538660,"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":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-agents","documentation"],"created_at":"2026-04-13T22:34:59.180Z","updated_at":"2026-05-26T21:01:07.368Z","avatar_url":"https://github.com/derek-palmer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![codeForerunner — your codebase gets a Forerunner; your docs finally see the light](images/readme_banner.png)\n\n# codeForerunner\n\n[![Socket Badge](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)](https://badge.socket.dev/npm/package/codeforerunner/0.4.3)\n\nModel-agnostic repository documentation tooling. Ships a prompt pack for codebase analysis and doc generation, a thin Python CLI, an MCP server, drift-detection rules that keep docs honest — and native slash-command skills for Claude Code, Codex, Gemini CLI, and other agent CLIs.\n\n## Install\n\nInstall forerunner's prompt pack as skills into your agent CLI. Each documentation task becomes a slash command (`/forerunner-readme`, `/forerunner-check`, etc.) available inside Claude Code, Codex, Gemini CLI, and other agents. Authentication is handled by your existing agent subscription — no separate API key needed.\n\n```bash\n# From a cloned repo\n./install.sh\n\n# One-liner (auto-detects Claude Code, Codex, Gemini CLI)\ncurl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash\n\n# Windows\nirm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex\n\n# Via forerunner CLI (after pip install)\nforerunner install --all claude\nforerunner install --all codex\n```\n\nThen in your agent:\n\n```\n/forerunner-scan        ← scan the repo first\n/forerunner-readme      ← generate README\n/forerunner-check       ← detect doc drift\n/forerunner-refresh     ← scan + update all stale docs\n```\n\n## Slash commands\n\n| Command | Task | Purpose |\n|---------|------|---------|\n| `/forerunner-scan` | `scan` | Collect repo evidence (run first) |\n| `/forerunner-readme` | `readme` | Generate or refresh README.md |\n| `/forerunner-api-docs` | `api-docs` | Generate API reference docs |\n| `/forerunner-diagrams` | `diagrams` | Generate Mermaid architecture diagrams |\n| `/forerunner-flows` | `flows` | Document system flows |\n| `/forerunner-stack-docs` | `stack-docs` | Stack-specific developer docs |\n| `/forerunner-version-audit` | `version-audit` | Audit pinned versions vs EOL |\n| `/forerunner-check` | `check` | Check docs for staleness |\n| `/forerunner-review` | `review` | Doc-impact summary for PR review |\n| `/forerunner-audit` | `audit` | Security and dependency audit |\n| `/forerunner-changelog` | `changelog` | Generate changelog from git log |\n| `/forerunner-init` | `init-agent-onboarding` | Bootstrap or refresh AGENTS.md |\n| `/forerunner-refresh` | `refresh` | Scan + check + update all stale docs in one pass |\n\nSlash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all commands after install.\n\n## Skill install options\n\n| Flag | Effect |\n|------|--------|\n| `./install.sh` | Auto-detect all agents, prompt global vs local, install all skills |\n| `./install.sh --global` | Skip prompt, install to global agent dirs (all projects) |\n| `./install.sh --local` | Skip prompt, install to `.claude/skills/` and `.agents/skills/` in cwd |\n| `./install.sh --only claude` | Claude Code only |\n| `./install.sh --only codex` | Codex only |\n| `./install.sh --only gemini` | Gemini CLI only |\n| `./install.sh --dry-run` | Preview, write nothing |\n| `./install.sh --list` | Show detected agents + skill list |\n| `./install.sh --uninstall` | Remove all installed skills |\n\n## CLI\n\n```bash\npip install codeforerunner\n```\n\n| Command | Purpose |\n|---------|---------|\n| `forerunner init` | Resolve agent-onboarding bundle to stdout. |\n| `forerunner scan` | Resolve scan bundle to stdout. |\n| `forerunner doc \u003ctask\u003e` | Resolve `base + partials + task` bundle to stdout. |\n| `forerunner refresh` | Output scan + check + all doc-task bundles in sequence for a full doc refresh. |\n| `forerunner check` | Run drift-detection rules; no-op without `forerunner.config.yaml`. |\n| `forerunner doctor` | Health report: skill parity, config. Add `--fix` to write a starter config. |\n| `forerunner mcp-server` | Serve prompt bundles as MCP tools over stdio (JSON-RPC 2.0). |\n| `forerunner install \u003cagent\u003e` | Install canonical skill into agent-specific directory. Add `--all` for all per-task skills. |\n\n## Quick start\n\n```bash\n# Install skills into Claude Code\ncurl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash\n\n# In Claude Code:\n# /forerunner-scan     → scans your repo\n# /forerunner-readme   → generates README.md\n# /forerunner-refresh  → updates all stale docs\n# /forerunner-check    → checks for doc drift\n```\n\n## GitHub Action\n\nAdd doc-drift detection to any repo's CI — fails the PR if docs contradict repo state.\n\n```yaml\n# .github/workflows/doc-check.yml\nname: Doc Check\non: [push, pull_request]\n\njobs:\n  doc-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6.0.2\n      - uses: derek-palmer/codeforerunner@v0.4.3\n        with:\n          fail-on-drift: \"true\"   # set \"false\" to warn-only\n```\n\nNo-op when `forerunner.config.yaml` is absent — safe to add before configuring rules.\n\n**Inputs**\n\n| Input | Default | Description |\n|-------|---------|-------------|\n| `version` | `latest` | `codeforerunner` version to install |\n| `python-version` | `3.11` | Python version |\n| `repo` | workspace root | Path to check |\n| `fail-on-drift` | `true` | Exit non-zero on drift |\n\n## Configuration\n\nCopy `forerunner.config.yaml.example` to `forerunner.config.yaml` to opt in to drift rules. Generate a starter config with:\n\n```bash\nforerunner doctor --fix\n```\n\n### Config fields\n\n```yaml\napproaching_eol_threshold_months: 6\n\ntasks:\n  check:\n    enabled_rules:\n      - R1-no-cli\n      - R2-no-pre-commit\n      - R3-no-ci\n      - R4-no-installer\n      - R5-no-python-package\n      - R7-no-mcp\n      - R8-no-marketplace\n      - RI1-missing-cli\n      - RI5-missing-python-package\n      - RI7-missing-mcp\n      - RV1-version-drift\n    ignore_paths:\n      - docs/legacy/**/*.md\n```\n\n### Drift rules\n\n| Rule | Fires when |\n|------|-----------|\n| `R1-no-cli` | Doc denies having a CLI, but `cli.py` is present |\n| `R2-no-pre-commit` | Doc denies having pre-commit hooks, but `.pre-commit-hooks.yaml` present |\n| `R3-no-ci` | Doc denies having CI, but `.github/workflows/*.yml` present |\n| `R4-no-installer` | Doc denies having an installer, but `installer.py` present |\n| `R5-no-python-package` | Doc denies having a Python package, but `pyproject.toml` present |\n| `R6-no-docker` | Doc denies having Docker, but `Dockerfile`/`compose.yml` present |\n| `R7-no-mcp` | Doc denies having an MCP server, but `mcp_server.py` present |\n| `R8-no-marketplace` | Doc denies having a marketplace, but `marketplace.json` present |\n| `RI1-missing-cli` | Doc references `forerunner` subcommands but `cli.py` absent |\n| `RI5-missing-python-package` | Doc shows `pip install codeforerunner` but `pyproject.toml` absent |\n| `RI7-missing-mcp` | Doc references `forerunner mcp-server` but `mcp_server.py` absent |\n| `RV1-version-drift` | Doc pins `codeforerunner==X.Y.Z` differing from current version |\n\n## MCP Server\n\n`forerunner mcp-server` speaks JSON-RPC 2.0 over stdio and exposes one tool per `prompts/tasks/*.md`. A scan-first gate enforces SPEC V2: any tool except `scan` or `init-agent-onboarding` returns an error until `scan` has been called in the same session.\n\nSee `examples/mcp/` for Claude Desktop and mcp-cli wiring examples.\n\n## Prompt pack\n\nPrompts are bundled inside the package at `src/codeforerunner/prompts/`.\n\n```text\nprompts/\n├── system/base.md\n├── partials/\n│   ├── context-format.md\n│   ├── output-rules.md\n│   └── stack-hints.md\n└── tasks/\n    ├── scan.md          api-docs.md    audit.md\n    ├── readme.md        diagrams.md    changelog.md\n    ├── check.md         flows.md       version-audit.md\n    ├── review.md        stack-docs.md  refresh.md\n    └── init-agent-onboarding.md\n```\n\n## Docs and spec\n\n- `SPEC.md` — canonical phase/task tracker\n- `docs/getting-started.md` — manual prompt use\n- `docs/prompt-guide.md` — how system, partial, and task prompts compose\n- `docs/editor-agent-setup.md` — adapting prompts to local agents\n- `docs/roadmap.md` — human-readable roadmap\n- `docs/agent-distribution-design.md` — packaging and installer design\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderek-palmer%2Fcodeforerunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderek-palmer%2Fcodeforerunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderek-palmer%2Fcodeforerunner/lists"}