freshstate

Keep your AI workspace docs fresh.

Track document freshness, enforce cross-file consistency, and prevent stale docs in AI-assisted codebases.

The Problem

AI coding tools (Claude Code, Cursor, Copilot Workspace) maintain persistent context files: CLAUDE.md, .cursor/rules/, state files, decision logs, changelogs. As projects grow, these files drift out of sync. A decision gets recorded but the timeline doesn't update. A README describes features that were removed three sprints ago. Nobody notices until the AI agent gives stale advice.

freshstate catches this before it becomes a problem.

Quick Start

pip install freshstate

# Create a starter config
freshstate init

# Run checks
freshstate check

Configuration

Create a .freshstate.yml in your project root:

files:
  - path: README.md
    max_age: 30d
    severity: warning

  - path: "docs/*.md"
    max_age: 14d
    severity: error

rules:
  - name: decision-sync
    when: decisions.md
    then_also:
      - timeline.md
      - current-state.md
    within: same_commit
    severity: error

  - name: readme-sync
    when: "src/**/*.py"
    then_also: README.md
    within: 5_commits
    severity: warning

owners:
  - files: ["docs/*.md"]
    owner: docs-team
    checklist:
      - "Updated table of contents"
      - "Checked for broken links"

File Freshness

Track how old files are based on their last git commit. Set thresholds with human-readable durations:

• Nh (hours): 24h, 48h
• Nd (days): 7d, 30d
• Nw (weeks): 2w, 4w

Severity levels: info, warning, error, critical

Cross-Reference Rules (the killer feature)

Enforce that related files stay in sync:

• same_commit: Files must be modified in the same commit. Perfect for multi-file updates that should be atomic (e.g., a decision log + timeline + state snapshot).
• N_commits: Files must be modified within N commits of each other. Good for looser coupling (e.g., source code changes should update docs within a few commits). Maximum value: 1000.

Ownership Declarations

Document who owns what and what their update checklist includes. Currently informational; future versions will integrate with CI to enforce checklists.

Output Modes

Text (default)

freshstate check

Color-coded terminal output with freshness status and rule results.

JSON

freshstate check --json

Machine-readable output for dashboards and integrations.

CI Mode

freshstate check --ci

GitHub Actions annotations format. Exit code 1 if any error or critical severity findings.

CI Integration

GitHub Actions

name: Docs Freshness
on: [push, pull_request]

jobs:
  freshstate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history needed for git timestamps

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install freshstate

      - run: freshstate check --ci

CLI Reference

freshstate check [OPTIONS]
  --config, -c PATH    Config file path (default: .freshstate.yml)
  --ci                 CI mode with GitHub annotations and exit codes
  --json               JSON output
  --repo PATH          Git repository root (default: current directory)

freshstate init [OPTIONS]
  --path PATH          Output path (default: .freshstate.yml)
  --force              Overwrite existing config

Roadmap

• v0.2.0: MCP server for AI agent integration
• v0.3.0: Auto-fix suggestions
• v0.4.0: GitHub Action (no Python install needed)
• Cursor/Windsurf integration guides
• Dashboard web UI

License

MIT