Skip to content

INSTALL-AND-RESTORE.md

Latest commit

 

History

History
89 lines (62 loc) · 5.11 KB

INSTALL-AND-RESTORE.md

File metadata and controls

89 lines (62 loc) · 5.11 KB
Raw

Inject and restore

The installer writes the pack's rule files and records every destination in a timestamped manifest. Existing files are copied before replacement. Uninstall restores replaced files and removes files created by the installer, but it does not overwrite edits made after installation.

Rule loading and precedence

CUSTOM.md is a companion file, not a universal agent-standard filename. The installer uses the harness-specific entry points:

  • Claude Code: $CLAUDE_CONFIG_DIR/CLAUDE.md is the durable entry point when CLAUDE_CONFIG_DIR is set; otherwise use ~/.claude/CLAUDE.md. $CLAUDE_CONFIG_DIR/rules/common/CUSTOM.md is the active Claude Code rule copy, and $CLAUDE_CONFIG_DIR/CUSTOM.md is retained as a readable companion. Do not assume Claude Code loads an arbitrary root-level CUSTOM.md by name.
  • Codex: ~/.codex/AGENTS.md is the durable entry point. ~/.codex/CUSTOM.md is a readable companion; Codex's documented durable entry point is AGENTS.md, so do not assume the companion is loaded unless the harness explicitly supports it.
  • Repository scope: with --repo, the installer writes CLAUDE.md, AGENTS.md, and CUSTOM.md at the Git root. The first two are the harness entry points; CUSTOM.md documents the personal layer and is not relied on as an automatic entry point.

The user's current request is the highest-priority user-level instruction. Within this pack, CUSTOM.md records that policy and is the highest-priority user policy: the entry points direct the agent to load it before generic defaults, and when both are loaded it takes precedence over conflicting pack defaults and lower-priority guidance. This is a pack convention, not a claim that it can override system/developer instructions, platform safety or tool-permission boundaries, or a later explicit user request.

What gets written

Target File
Claude Code user $CLAUDE_CONFIG_DIR/CLAUDE.md (default: ~/.claude/CLAUDE.md)
Claude Code active rules copy $CLAUDE_CONFIG_DIR/rules/common/CUSTOM.md (default: ~/.claude/rules/common/CUSTOM.md)
Claude Code companion $CLAUDE_CONFIG_DIR/CUSTOM.md (default: ~/.claude/CUSTOM.md)
Codex user ~/.codex/AGENTS.md
Codex companion ~/.codex/CUSTOM.md
Git root (--repo) CLAUDE.md, AGENTS.md, CUSTOM.md
Optional (--effort) $CLAUDE_CONFIG_DIR/settings.json (default: ~/.claude/settings.json) effortLevel → medium if it was xhigh/max/ultra

The pack does not copy a duplicate rules/ tree. The Claude Code rules/common/CUSTOM.md copy exists because .claude/rules is a supported Claude Code loading surface; it is intentionally the only duplicated content.

Install

cd lean-coding-agent-pack
chmod +x install.sh uninstall.sh
./install.sh --dry-run          # print actions without writing
./install.sh                    # user-level Claude / Codex when detected
CLAUDE_CONFIG_DIR=/path ./install.sh  # use a custom Claude config dir
./install.sh --repo --effort    # also repo root + maybe lower effort

Each non-dry run creates a unique directory, even when two installs occur in the same second:

~/.gpt56-sol-agent-pack-backups/<YYYYMMDDTHHMMSS[-N]>/
  manifest.tsv
  <original files>
  <installed snapshots>
~/.gpt56-sol-agent-pack-backups/latest -> that stamp

Manifest columns are:

destination<TAB>created|replaced<TAB>original-backup-or-<TAB>installed-snapshot

The destination and backup paths are emitted by the installer for the current shell environment. Treat the manifest as data, not as a shell script; quote paths when using them manually.

Restore / uninstall

./uninstall.sh
# or a specific stamp
./uninstall.sh ~/.gpt56-sol-agent-pack-backups/20260826T153000

Uninstall:

  • replaced → restores the original only if the destination still matches the installer snapshot.
  • created → removes the file only if it still matches the installer snapshot.
  • A file changed after installation is skipped and reported, so later user edits are not silently destroyed.

It does not delete the backup directory. Keep it until you are sure.

Manual restore

cat ~/.gpt56-sol-agent-pack-backups/latest/manifest.tsv
cp ~/.gpt56-sol-agent-pack-backups/latest/<original-backup-name> "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md"

For a created row, remove the file only after checking that it has not been edited since installation.

Earlier local rule edits

This installer only manages the destinations listed in its current manifest. Older manifests have no installed snapshots, so the current uninstall.sh skips those rows rather than risking an overwrite; inspect and restore them manually from their recorded backups. The installer does not invent backups for files changed before this backup scheme existed. Restore older $CLAUDE_CONFIG_DIR/rules/common/* edits (default: ~/.claude/rules/common/*) from editor history, system backup, or version control if available.

New session required

Claude Code and Codex load durable instructions at session start. Install and uninstall do not rewrite an already-running conversation's context.