codeforerunner

codeForerunner

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

Install

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

# From a cloned repo
./install.sh

# One-liner (auto-detects Claude Code, Codex, Gemini CLI)
curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash

# npm
npx -y codeforerunner
npm install -g codeforerunner

# Windows
irm https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.ps1 | iex

# Via Python CLI
pip install codeforerunner
forerunner install --all claude
forerunner install --all codex

Then in your agent:

/forerunner-scan        ← scan the repo first
/forerunner-readme      ← generate README
/forerunner-check       ← detect doc drift
/forerunner-refresh     ← scan + update all stale docs

Slash commands

Command	Task	Purpose
/forerunner-scan	scan	Collect repo evidence (run first)
/forerunner-readme	readme	Generate or refresh README.md
/forerunner-api-docs	api-docs	Generate API reference docs
/forerunner-diagrams	diagrams	Generate Mermaid architecture diagrams
/forerunner-flows	flows	Document system flows
/forerunner-arch-review	arch-review	Rank architecture improvement candidates, inspired by Matt Pocock's /improve-codebase-architecture
/forerunner-stack-docs	stack-docs	Stack-specific developer docs
/forerunner-version-audit	version-audit	Audit pinned versions vs EOL
/forerunner-check	check	Check docs for staleness
/forerunner-review	review	Doc-impact summary for PR review
/forerunner-audit	audit	Security and dependency audit
/forerunner-changelog	changelog	Generate changelog from git log
/forerunner-init	init-agent-onboarding	Bootstrap or refresh AGENTS.md
/forerunner-refresh	refresh	Scan + check + update all stale docs in one pass

Slash command availability depends on the agent CLI. Claude Code, Codex, and Gemini CLI support all commands after install.

Skill install options

Flag	Effect
./install.sh	Auto-detect agents, prompt for global vs local, prompt which agents to install
./install.sh --global	Skip location prompt, install to global agent dirs (all projects)
./install.sh --local	Skip location prompt, install to .claude/skills/ and .agents/skills/ in cwd
./install.sh --non-interactive	Skip all prompts, install globally to all detected agents (useful in CI / curl|bash)
./install.sh --only claude	Claude Code only (skips agent selection prompt)
./install.sh --only codex	Codex only
./install.sh --only gemini	Gemini CLI only
./install.sh --dry-run	Preview, write nothing
./install.sh --list	Show detected agents + skill list
./install.sh --uninstall	Remove all installed skills

CLI

pip install codeforerunner

Command	Purpose
forerunner init	Resolve agent-onboarding bundle to stdout.
forerunner scan	Resolve scan bundle to stdout.
forerunner doc <task>	Resolve base + partials + task bundle to stdout.
forerunner refresh	Output scan + check + all doc-task bundles in sequence for a full doc refresh.
forerunner check	Run drift-detection rules; no-op without forerunner.config.yaml.
forerunner doctor	Health report: skill parity, config. Add --fix to write a starter config.
forerunner mcp-server	Serve prompt bundles as MCP tools over stdio (JSON-RPC 2.0).
forerunner install <agent>	Install canonical skill into agent-specific directory. Add --all for all per-task skills.

Quick start

# Install skills into Claude Code
curl -fsSL https://raw.githubusercontent.com/derek-palmer/codeforerunner/main/install.sh | bash

# Or via npm
# npx -y codeforerunner

# In Claude Code:
# /forerunner-scan     → scans your repo
# /forerunner-readme   → generates README.md
# /forerunner-refresh  → updates all stale docs
# /forerunner-check    → checks for doc drift

GitHub Action

Add doc-drift detection to any repo's CI — fails the PR if docs contradict repo state.

# .github/workflows/doc-check.yml
name: Doc Check
on: [push, pull_request]

jobs:
  doc-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.0.2
      - uses: derek-palmer/codeforerunner@v0.4.7
        with:
          fail-on-drift: "true"   # set "false" to warn-only

No-op when forerunner.config.yaml is absent — safe to add before configuring rules.

Inputs

Input	Default	Description
version	latest	codeforerunner version to install
python-version	3.11	Python version
repo	workspace root	Path to check
fail-on-drift	true	Exit non-zero on drift

Configuration

Copy forerunner.config.yaml.example to forerunner.config.yaml to opt in to drift rules. Generate a starter config with:

forerunner doctor --fix

Config fields

approaching_eol_threshold_months: 6

tasks:
  check:
    enabled_rules:
      - R1-no-cli
      - R2-no-pre-commit
      - R3-no-ci
      - R4-no-installer
      - R5-no-python-package
      - R7-no-mcp
      - R8-no-marketplace
      - RI1-missing-cli
      - RI5-missing-python-package
      - RI7-missing-mcp
      - RV1-version-drift
    ignore_paths:
      - docs/legacy/**/*.md

Drift rules

Rule	Fires when
R1-no-cli	Doc denies having a CLI, but cli.py is present
R2-no-pre-commit	Doc denies having pre-commit hooks, but .pre-commit-hooks.yaml present
R3-no-ci	Doc denies having CI, but .github/workflows/*.yml present
R4-no-installer	Doc denies having an installer, but installer.py present
R5-no-python-package	Doc denies having a Python package, but pyproject.toml present
R6-no-docker	Doc denies having Docker, but Dockerfile/compose.yml present
R7-no-mcp	Doc denies having an MCP server, but mcp_server.py present
R8-no-marketplace	Doc denies having a marketplace, but marketplace.json present
RI1-missing-cli	Doc references forerunner subcommands but cli.py absent
RI5-missing-python-package	Doc shows pip install codeforerunner but pyproject.toml absent
RI7-missing-mcp	Doc references forerunner mcp-server but mcp_server.py absent
RV1-version-drift	Doc pins codeforerunner==X.Y.Z differing from current version

MCP Server

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.

See examples/mcp/ for Claude Desktop and mcp-cli wiring examples.

Prompt pack

Prompts are bundled inside the package at src/codeforerunner/prompts/.

prompts/
├── system/base.md
├── partials/
│   ├── context-format.md
│   ├── output-rules.md
│   └── stack-hints.md
└── tasks/
    ├── scan.md          api-docs.md    audit.md
    ├── readme.md        diagrams.md    changelog.md
    ├── check.md         flows.md       version-audit.md
    ├── review.md        stack-docs.md  arch-review.md
    ├── refresh.md
    └── init-agent-onboarding.md

Docs

• docs/getting-started.md — manual prompt use
• docs/prompt-guide.md — how system, partial, and task prompts compose
• docs/editor-agent-setup.md — adapting prompts to local agents
• docs/roadmap.md — human-readable roadmap
• docs/agent-distribution-design.md — packaging and installer design