Sweepr

Sweepr is an open-source documentation control plane for repositories.

Source: https://github.com/abritton2002/sweepr

The hosted app is scoped to documentation alignment only: sign into Sweepr, connect GitHub repositories, link repo docs and Notion pages by hand, then run $sweepr in Codex or /sweepr in Claude Code when docs need to match the live repository.

The local CLI package installs the Sweepr skill into Claude Code and Codex. When $sweepr in Codex or /sweepr in Claude Code runs in a local checkout, the skill initializes only lightweight .sweepr/config.json and .sweepr/context.md hints if they are missing, then the coding agent performs fast documentation triage before deciding whether deeper source verification is needed. The app product surface is only the link registry for connected repositories and documentation links; it is not a general automation dashboard, PR reviewer, branch cleanup tool, or approval inbox.

sweepr-code login is a one-time setup per machine. It opens the Sweepr platform login, stores the Sweepr session in ~/.sweepr/auth.json, then starts Notion OAuth unless --no-notion is set. Running it again reuses the stored session and skips browser login unless --force is passed. It also does not start Notion on repeat runs; use sweepr-code notion connect only when linked Notion docs need write access. sweepr-code registry --json refreshes the stored session when needed and fetches only your connected repositories and documentation links.

CLI Workflow

Ordinary Sweepr startup is intentionally small:

sweepr-code init
sweepr-code registry --json
sweepr-code check

sweepr-code init writes only .sweepr/config.json and .sweepr/context.md. It does not create repo-local .claude or .codex files. If a repository should carry local agent assets for a demo, template repo, or team convention, run the explicit full install:

sweepr-code repo-install

The skill starts with fast triage: preserve user changes, fetch the registry, inventory docs, inspect linked docs, and stop broad source ingestion unless a concrete stale doc claim needs verification. Searches should exclude generated and high-volume directories such as .next, node_modules, test-results, coverage, lockfiles, and build output.

Notion Setup

Sweepr supports three Notion connection paths:

• Sweepr Notion OAuth, default: sweepr-code notion connect opens Notion through the Sweepr app and stores the OAuth result in ~/.sweepr/notion.json.
• Notion MCP, optional for agents: sweepr-code notion connect --mcp configures the official remote Notion MCP server at https://mcp.notion.com/mcp. OAuth is completed by the MCP client, such as codex mcp login notion.
• Notion API token, for internal connections: sweepr-code notion connect --token ntn_... stores a user-provided token in ~/.sweepr/notion.json. You still need to share the target Notion pages or databases with that connection.

The npm lifecycle install does not force OAuth. Run the setup explicitly:

sweepr-code notion status
sweepr-code notion connect
sweepr-code notion refresh
sweepr-code notion doctor <url-or-page-id>
sweepr-code registry --json

If you already have an internal connection token:

sweepr-code notion connect --token ntn_...

Sweepr writes global Notion credentials to ~/.sweepr/notion.json. Sweepr platform auth is separate and lives in ~/.sweepr/auth.json. Keep both files private.

Use sweepr-code notion doctor <url-or-page-id> when a linked Notion page fails. It parses page IDs from Notion URLs, reports auth mode and workspace, tries the supplied target plus the parsed page ID, and distinguishes likely causes such as page not shared, wrong workspace, stale URL, expired token, MCP-only auth, and parser failure.

Use sweepr-code notion update <url-or-page-id> --file update.md --yes as Sweepr's default linked-page write path. The command appends simple Markdown as Notion blocks using the stored Sweepr Notion OAuth/token, which is the same auth path verified by sweepr-code notion doctor. Use --dry-run first to verify the parsed block count without writing.

The hosted app needs NOTION_OAUTH_CLIENT_ID, NOTION_OAUTH_CLIENT_SECRET, and NOTION_OAUTH_REDIRECT_URI for Sweepr Notion OAuth. The redirect URI should point at /api/cli/notion/callback on the hosted Sweepr app and match the URI configured in Notion.

Product Scope

• Link repositories from a GitHub App installation.
• Match local checkouts to connected repositories by Git remote.
• Link repository documentation such as README.md, docs/*.md, architecture notes, setup guides, and runbooks.
• Link Notion pages to the repository they describe. Sweepr reads only the linked pages, not the whole workspace.
• Store documentation drift reports with repo-doc and Notion updates.
• Track documentation update runs as reviewable, auditable work.
• Install a Sweepr skill that tells Claude Code and Codex how to run the full documentation alignment loop.
• Create local link-registry hints while leaving repo understanding to the coding agent.
• Create or update agent guidance files such as AGENTS.md only when they are missing, stale, or needed for future coding-agent work.

Runtime Configuration

The hosted app and CLI registry use Supabase auth plus the GitHub App integration:

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

GITHUB_APP_ID=
GITHUB_APP_SLUG=
GITHUB_APP_PRIVATE_KEY=
GITHUB_APP_WEBHOOK_SECRET=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_TOKEN=

Sweepr Notion OAuth is used by the CLI connection flow:

NOTION_OAUTH_CLIENT_ID=
NOTION_OAUTH_CLIENT_SECRET=
NOTION_OAUTH_REDIRECT_URI=https://sweepr-code.vercel.app/api/cli/notion/callback

Local CLI behavior can also be pointed at non-default paths or app URLs with SWEEPR_APP_URL, SWEEPR_HOME, SWEEPR_AUTH_PATH, and SWEEPR_NOTION_AUTH_PATH. NOTION_TOKEN or NOTION_API_KEY is accepted as a local fallback for agents that already have a shared Notion integration.

Out Of Scope

• Autonomous sweep dashboards.
• PR review queues.
• Branch cleanup automation.
• Slack nudges.
• Approval-first GitHub write actions unrelated to docs.
• General maintenance proposals.
• Repo-wide discovery from the dashboard.
• Creating documentation for its own sake.

Local Development

npm install
npm run dev

Open http://localhost:3000.

Verification

npm run typecheck
npm run lint
npm test
npm run build

Database Scope

The documentation-focused database should stay small:

• profiles
• github_installations
• github_installation_states
• github_repositories
• documentation_links
• documentation_drift_reports
• documentation_update_runs

Tables from previous product directions, including managed_sweeps, managed_action_items, managed_action_events, and project_folders, are removed by migrations.

Known Drift To Resolve

• vercel.json still contains a cron entry for /api/autonomous/run, but no matching route exists in the current documentation-control-plane app.
• middleware.ts still lists legacy protected paths and API guards for old autonomous, PR, sweep, and maintenance surfaces. They do not correspond to current app routes.
• src/lib/llm/* remains in the repository, but no current product route calls it. Treat it as dormant until a documentation-drift workflow uses it again.