Skip to content

stevesolun/ctx / docs

skill-router

Flagged

Repo-aware recommendation manager for ctx. Scans the active repository, identifies stack and workflow signals, recommends a capped set of skills, agents, and MCP servers, and unloads helpers that no longer match the current work after user confirmation. Harnesses are recommended by the custom-model onboarding flow or loop adapters and then attach to the same recommendation layer.

FileKindSize
SKILL.mdskill md9.3 KB
assets/javascripts/catalog.jsscript2.5 KB
assets/javascripts/repo-stats-refresh.jsscript3.2 KB
backup-hook-install.mdmarkdown9.2 KB
catalog.mdmarkdown10.3 KB
ctx-fit/ARCHITECTURE_CANDIDATES.mdmarkdown12.9 KB
ctx-fit/ARCHITECTURE_GAP_ANALYSIS.mdmarkdown10.7 KB
ctx-fit/CTX_AUDIT.mdmarkdown11.6 KB
ctx-fit/CURRENT_STATE.mdmarkdown16.3 KB
ctx-fit/DECISIONS.mdmarkdown15.7 KB
ctx-fit/GOOD_FIRST_ISSUES.mdmarkdown20.6 KB
ctx-fit/IMPLEMENTATION_TRACKER.mdmarkdown697 B
ctx-fit/MAP.mdmarkdown7.8 KB
ctx-fit/PRD.mdmarkdown9.7 KB
ctx-fit/STATE.mdmarkdown60.9 KB
ctx-fit/milestones/M1_SPIKE_FRICTION_LOG.mdmarkdown5.5 KB
ctx-fit/milestones/MILESTONE_00_AUDIT.mdmarkdown5.1 KB
ctx-fit/planned_tasks.mdmarkdown17.7 KB
dashboard.mdmarkdown24.7 KB
enterprise-readiness-review.mdmarkdown8.7 KB
entity-onboarding.mdmarkdown18.0 KB
harness/attaching-to-hosts.mdmarkdown16.2 KB
harness/clean-host-contract.mdmarkdown4.5 KB
harness/loopflow-adapter-demo.mdmarkdown11.1 KB
huggingface-publish.mdmarkdown3.3 KB
index.mdmarkdown22.4 KB
knowledge-graph.mdmarkdown22.7 KB
marketplace-registry.mdmarkdown4.0 KB
memory-anchor.mdmarkdown2.7 KB
plans/ctx-agent-reviewer-workbench.mdmarkdown12.4 KB
plans/unified-capability-engine.mdmarkdown59.0 KB
qa/dashboard-user-story-status.csvother26.0 KB
qa/feature-user-story-status.csvother92.5 KB
research/context-engineering-guidance-audit.mdmarkdown10.4 KB
services/macos/com.claude.backup.watchdog.plistother1.7 KB
services/systemd/claude-backup-watchdog.serviceother1.3 KB
skill-lifecycle-and-dashboard.mdmarkdown6.2 KB
skill-quality-install.mdmarkdown6.2 KB
skill-router/index.mdmarkdown2.5 KB
skill-stack-matrix.mdmarkdown5.5 KB
skills-health.mdmarkdown3.5 KB
stack-signatures.mdmarkdown6.2 KB
telemetry.mdmarkdown24.7 KB
threat-model.mdmarkdown15.0 KB
toolbox/behavior-miner.mdmarkdown2.6 KB
toolbox/configuration.mdmarkdown4.0 KB
toolbox/council-runner.mdmarkdown2.4 KB
toolbox/hooks.mdmarkdown2.6 KB
toolbox/index.mdmarkdown3.0 KB
toolbox/intent-interview.mdmarkdown3.0 KB
toolbox/starters.mdmarkdown3.0 KB
toolbox/templates/docs-review.jsonconfig599 B
toolbox/templates/fresh-repo-init.jsonconfig533 B
toolbox/templates/refactor-safety.jsonconfig634 B
toolbox/templates/security-sweep.jsonconfig636 B
toolbox/templates/ship-it.jsonconfig676 B
toolbox/verdicts.mdmarkdown4.0 KB

backup-hook-install.md

View on GitHub
# Change-triggered backup — hook install

One page on wiring the `backup_on_change.py` PostToolUse hook into Claude
Code so a new snapshot fires automatically whenever you edit a tracked
config file (`~/.claude/settings.json`, agents, skills, top-level
manifests, etc.).

## What it does

On every `Edit` / `Write` / `MultiEdit` tool call, the hook:

1. Reads the tool payload from stdin.
2. Resolves `tool_input.file_path` and checks if it sits under
   `~/.claude` in a file/tree/memory path tracked by `BackupConfig`.
3. If tracked, shells out to
   `python <repo>/src/backup_mirror.py snapshot-if-changed --reason <tool>:<basename>`.
4. `snapshot-if-changed` hashes the same eligible file set that capture would
   persist, including the size cap and tree/memory destination exclusions. It
   compares that state against the most recent snapshot's `manifest.json` and
   only creates a new folder when at least one SHA differs.

No-op edits don't create folders. The hook always exits 0 so a bug in
the backup layer cannot stall a Claude session.

## Register the hook

Edit `~/.claude/settings.json` and add the following under `hooks` (keep
any existing entries alongside it). Replace `<REPO>` with the absolute
path to this checkout, such as `/home/you/src/ctx` on Linux or
`/Users/you/src/ctx` on macOS.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python <REPO>/hooks/backup_on_change.py"
          }
        ]
      }
    ]
  }
}
```

Notes:

- The `matcher` is a regex against the tool name. The three names above are the
  supported direct file-edit events; use the watchdog below to catch changes
  made by Bash commands, external editors, or other processes.
- If `python` on your PATH is not the interpreter you want, give the
  absolute path instead (for example, `/Users/you/.pyenv/shims/python`).

## Verify it works

1. Reload Claude Code (the hook registration is read at session start).
2. Edit a tracked file, e.g. `~/.claude/CLAUDE.md`.
3. Watch `~/.claude/backups/` — a new folder named
   `<timestamp>__edit-claude-md` should appear within a second.
4. Edit the same file again with identical content — no new folder
   appears (SHA is unchanged).

If nothing shows up, run the verb manually to isolate the failure:

```bash
python -m backup_mirror snapshot-if-changed --reason smoke-test --json
```

The JSON output tells you which files the detector considered new,
changed, or removed.

## What gets backed up

See `src/backup_config.py` and the `backup` section of
`src/config.json` for the current defaults:

- **top_files** — `settings.json`, `skill-manifest.json`,
  `pending-skills.json`, `CLAUDE.md`, `AGENTS.md`, `user-profile.json`,
  `skill-system-config.json`, `skill-registry.json`. User overrides must be
  top-level filenames only: no path separators, absolute paths, drive letters,
  UNC paths, `.` entries, or `..` traversal.
- **trees** — `agents/`, `skills/`.
- **memory** — `projects/*/memory/**` when `memory_glob` is true.
- **max_file_bytes** — `5242880` (5 MiB) by default. Files exactly at the cap
  are included. For larger top-level, tree, and memory files, capture records a
  `too_large` manifest entry without storing the content, and change detection
  ignores the file.
- **excludes** — optional destination-relative patterns for tree and memory
  files. A pattern matches either the complete destination path or every file
  with the same basename. These custom patterns do not suppress an explicitly
  configured `top_files` entry; use `top_files` to control that list.
- **always excluded** — `.credentials.json`, `claude.json`, token
  caches; these are dropped even if a user config lists them.

To override per user, drop a partial config at
`~/.claude/backup-config.json`. Fields you omit fall back to the repo
default. Invalid `top_files` entries are ignored with a `[backup-config]`
stderr warning; if every supplied `top_files` entry is invalid, the effective
config falls back to the defaults instead of disabling top-level backups.
Example:

```json
{
  "retention": { "keep_latest": 100 },
  "top_files": ["settings.json", "CLAUDE.md"]
}
```

## Manual CLI

The same verb is available as a one-shot command:

```bash
# snapshot only when something changed
python -m backup_mirror snapshot-if-changed --reason manual-check

# force an unconditional snapshot with a reason label
python -m backup_mirror create --reason pre-upgrade
```

Both land under `~/.claude/backups/<timestamp>__<reason>/` and write a
`manifest.json` that records the reason alongside every file's SHA-256.

## Watchdog — snapshot on changes outside a Claude session

The PostToolUse hook only fires on `Edit` / `Write` / `MultiEdit` tool
calls *inside* a Claude session. If a Bash command, VS Code edit, `git pull`,
or another process updates a tracked file, the hook never sees it.

For that gap, run the polling watchdog — a simple loop that calls
`snapshot-if-changed` every N seconds:

```bash
python -m backup_mirror watchdog --interval 60
```

Flags:

| Flag | Meaning |
| --- | --- |
| `--interval N` | Seconds between polls. Clamped to `[5, 3600]`. Default 60. |
| `--reason-prefix LBL` | Prefix used for each snapshot's `--reason` label. Default `watchdog`. |
| `--once` | Run exactly one tick and exit. Useful for cron. |
| `--json` | Emit run stats as JSON on exit. |

Because change detection is SHA-gated, polling is cheap — a tick with
no real changes does zero disk writes.

### Running it as a background service

Ready-to-use service manifests live under
[`docs/services/`](https://github.com/stevesolun/ctx/tree/main/docs/services).
Each one expects you to edit a handful of paths — there's no installer
that guesses where you keep the checkout.

- **Linux (systemd user unit)** —
  [`docs/services/systemd/claude-backup-watchdog.service`](https://github.com/stevesolun/ctx/blob/main/docs/services/systemd/claude-backup-watchdog.service).
  Copy to `~/.config/systemd/user/`, set `CTX_REPO`, then
  `systemctl --user enable --now claude-backup-watchdog.service`.
- **macOS (launchd agent)** —
  [`docs/services/macos/com.claude.backup.watchdog.plist`](https://github.com/stevesolun/ctx/blob/main/docs/services/macos/com.claude.backup.watchdog.plist).
  Edit the `ProgramArguments` paths, drop into
  `~/Library/LaunchAgents/`, then
  `launchctl load -w ~/Library/LaunchAgents/com.claude.backup.watchdog.plist`.
Both manifests assume the watchdog runs as an **unprivileged
user** — no admin/root — because it only reads `~/.claude/` and writes
`~/.claude/backups/`.

The watchdog stops cleanly on SIGINT/SIGTERM, flushes its stats line
to stderr, and exits 0. Pair it with the hook: the hook handles
in-session edits in real time; the watchdog catches everything else.

## Retention — how old snapshots get pruned

Auto-pruning runs after every successful `snapshot-if-changed`, so the
hook cannot fill the disk. The active policy comes from
`BackupRetention` in `src/backup_config.py` (or your user override):

| Field | Default | Meaning |
| --- | --- | --- |
| `keep_latest` | `50` | Always keep the N most-recent snapshots. |
| `keep_daily` | `14` | For the M most-recent UTC days that have snapshots, keep the newest snapshot from each. |

A snapshot survives the sweep iff it's in the **union** of those two
sets. Snapshots whose `manifest.json` has a missing or zero
`created_at` are always protected — we never silently delete something
we can't place in time.

To override per user, add a partial config at
`~/.claude/backup-config.json`:

```json
{
  "retention": { "keep_latest": 100, "keep_daily": 30 }
}
```

### Manual prune

```bash
# Dry-run the configured policy — no deletions, JSON report.
python -m backup_mirror prune --policy --dry-run --json

# Apply the configured policy for real.
python -m backup_mirror prune --policy

# Legacy mode (still works): keep only the N newest.
python -m backup_mirror prune --keep 20 --dry-run
python -m backup_mirror prune --keep 20
```

The policy output tells you which snapshots were kept by `keep_latest`
versus `keep_daily`, so a surprising retention decision is easy to
audit. Legacy `--keep` dry-runs print the snapshot IDs that would be removed
without deleting their directories.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| Hook never fires | Settings not reloaded, or `matcher` typo. |
| Snapshot folder with no `reason` suffix | Called `create` without `--reason`. |
| Hook fires but no folder appears | Content hash matched — nothing actually changed. |
| Credentials appear in a snapshot | User put them in `top_files`; the `ALWAYS_EXCLUDE` filter would drop them — check you're on the current `backup_config.py`. |
| `ImportError: backup_config` from the hook | Repo moved; update the path in `settings.json`. |
| Snapshots pile up forever | `retention.keep_latest` / `keep_daily` too high. Run `prune --policy --dry-run --json` to see what the current policy would do, then lower the caps in `~/.claude/backup-config.json`. |
| Prune removed too much | Run `prune --policy --dry-run` *before* committing to a new policy. A snapshot with a missing/zero `created_at` is always protected, so if it's getting deleted the manifest is probably fine and the policy is genuinely too aggressive. |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall