@gitdamnit/opencode-git-that-shit

"Oh Shit Git" is what you say after the disaster. Git That Shit is what the tool does before the disaster.

Automatic pre-disaster snapshots for OpenCode AI coding agent config and state files.

What is Git That Shit?

Git That Shit is a safety plugin for OpenCode AI coding agent sessions. It automatically snapshots fragile configuration and agent state files into a separate shadow git repository before risky operations.

The product exists because one malformed JSON edit, one extra whitespace-sensitive config mistake, one bad agent command, or one accidental overwrite can break an entire coding environment. Git That Shit makes those failures recoverable.

Why it exists

AI coding agents (OpenCode, Claude Code, Aider, Codex) operate with elevated privileges over project files. Unlike human developers who hesitate before destructive acts, agents execute commands confidently — and sometimes catastrophically.

Why project git is not enough:

• Git is not always present
• Config files are often in .gitignore or untracked
• Git records changes after they happen, not before
• Most users don't commit before every risky operation

Git That Shit is inspired by etckeeper — the Linux tool that automatically commits /etc to git before package manager operations.

What it protects

By default, Git That Shit tracks:

• opencode.json - OpenCode main config
• .opencode/state/checkpoint.json - Session state
• .opencode/state/handoff.md - Handoff document
• .opencode/state/checkpoint-history.json - Checkpoint history
• package.json, tsconfig.json - Project configs
• Build configs (vite.config.ts, webpack.config.js, rollup.config.js, etc.)
• Docker configs (Dockerfile, docker-compose.yml)
• .env.example, .env.sample, .env.template - Env templates (NOT actual .env files)

What it does NOT protect

• Not a replacement for project git — use project git for code
• Not a general backup system — focused on config/state files only
• Not secret management — excludes .env by default (actual secrets)
• Not cloud sync — local git only
• Not for other AI agents — only tested with OpenCode

---

Installation

npm install @gitdamnit/opencode-git-that-shit

OpenCode Plugin Setup

Create opencode.json in your project:

{
  "plugins": [
    "@gitdamnit/opencode-git-that-shit"
  ]
}

Or use the local path for development:

{
  "plugins": [
    "./node_modules/@gitdamnit/opencode-git-that-shit"
  ]
}

---

How It Works

Shadow Git Repository

Git That Shit creates an isolated shadow git repository that is completely separate from your project's .git:

• Location: .git-that-shit/snapshots/
• Config: .git-that-shit/config.json
• Never touches your real git — completely independent

This means:

• Your project's git history stays clean
• Git That Shit's commits don't appear in your normal git log
• The shadow repo only stores config/state file snapshots

Auto-Triggers

Git That Shit automatically creates snapshots before risky operations:

Trigger Type	Commands/Events Detected
Destructive Git	git reset --hard, git reset --mixed, git clean -fd, git stash drop, git checkout -f, git rebase --abort (during conflict)
Risky Package Ops	npm install, npm ci, yarn install, yarn add, pnpm install, pnpm add, bun install
Config File Edits	Writing to .json, .yaml, .yml, .toml, .ini files that match tracked patterns
Session Events	On new session start, on context compaction

Hooks

Git That Shit uses these OpenCode-compliant hooks:

• tool.execute.before - Fires before any bash/shell command runs
• file.edited - Fires after file modifications
• session.created - Fires when a new session starts
• session.compacted - Fires when context window is compacted

Plugin Execution Order

Git That Shit runs after other plugins in the hook chain. This is important:

1. Other plugins (like Stranger Danger) process tool arguments first
2. Git That Shit snapshots the result after other plugins have modified things

This means Git That Shit captures the "safe" version of files after other security plugins have redacted secrets.

---

IMPORTANT: What NOT to Use With This

Other AI Coding Agents (Not Compatible)

Git That Shit is specifically built for OpenCode and may conflict with or not work properly with:

• Claude Code (has its own safety mechanisms)
• Aider (different hook system)
• Codex (different architecture)
• Cursor (has built-in git integration)
• Windsurf (has built-in safety)

If you're using OpenCode in a project that also uses other AI agents, Git That Shit's snapshots may not capture changes made by those other agents.

Other OpenCode Plugins

Git That Shit should work fine with most other OpenCode plugins, but be aware:

1. Plugin order matters — Git That Shit's snapshots happen after other plugins process
2. Disk space — If you have many plugins creating files, the shadow repo will grow
3. Lock conflicts — Only one snapshot can run at a time; subsequent triggers wait

Not for Production CI/CD

This plugin is designed for interactive AI coding sessions. Do not:

• Use in automated CI/CD pipelines
• Rely on it for production disaster recovery
• Use as your only backup solution

---

CLI Usage

Run these commands in your terminal (not inside OpenCode):

gts status              # Show status
gts list                # List recent snapshots
gts diff <hash>         # Show what changed
gts restore <hash>     # Restore (dry-run by default)
gts snapshot            # Manual snapshot
gts prune               # Prune old snapshots (dry-run)
gts config              # Show configuration
gts init                # Initialize shadow repo
gts doctor              # Run health checks
gts version             # Show version

Restore examples

# Dry-run (default) - shows what would happen
gts restore abc1234

# Real restore - actually overwrites files
gts restore abc1234 --yes

# List first to find the hash
gts list
gts diff 719ab88

---

Configuration

Config is stored at .git-that-shit/config.json:

{
  "version": "0.1",
  "tracking": {
    "include": ["opencode.json", ".opencode/state/*.json", "*.config.js"],
    "exclude": [],
    "allowSensitiveFiles": false
  },
  "destructiveOps": {
    "riskyPackageManagerOps": true,  // Snapshot before npm/yarn/pnpm install
    "configWrites": true              // Snapshot before config file edits
  },
  "fileEdits": {
    "mode": "pre-if-available",       // pre-if-available, post-edit, or disabled
    "debounceMs": 2000                // Wait 2s before snapshot on file edits
  },
  "secrets": {
    "redactKeys": ["token", "apiKey", "password", "secret", "credential"],
    "warnOnSensitive": true
  },
  "snapshot": {
    "maxFileSizeMb": 10,             // Skip files larger than 10MB
    "minDiskSpaceMb": 100             // Fail if less than 100MB free
  },
  "restore": {
    "autoPreRestoreSnapshot": true   // Create snapshot before restore
  }
}

Configuration Options Explained

Option	What it does
tracking.include	Glob patterns for files to snapshot
tracking.exclude	Additional patterns to skip
destructiveOps.riskyPackageManagerOps	Enable/disable npm/yarn snapshots
destructiveOps.configWrites	Enable/disable config file write snapshots
fileEdits.mode	When to snapshot: before, after, or disabled
secrets.redactKeys	JSON keys to redact in snapshots
snapshot.maxFileSizeMb	Skip files larger than this
restore.autoPreRestoreSnapshot	Auto-snapshot before each restore

---

Secret Handling

Git That Shit takes secrets seriously:

1. .env files are EXCLUDED — actual env files with secrets are never tracked
2. Sensitive file patterns blocked — *.pem, *.key, id_rsa, credentials.json, etc.
3. JSON value redaction — Values with keys like token, apiKey, password are replaced with [REDACTED]
4. Warning system — Alerts if you try to track sensitive files

To explicitly allow sensitive files (NOT RECOMMENDED):

{
  "tracking": {
    "allowSensitiveFiles": true
  }
}

---

Restore Workflow

When something breaks:

1. Identify the problem — "My opencode.json is corrupted!"
2. List snapshots — gts list
3. Preview changes — gts diff <hash>
4. Dry-run restore — gts restore <hash> (shows what would happen)
5. Confirm restore — gts restore <hash> --yes

Restore always defaults to dry-run — it's safe by default.

---

Doctor Command

Run health checks:

gts doctor

Checks:

• Git availability and version
• Config file validity
• Shadow repo exists and is valid git
• Manifest file readable
• No lock file conflicts (means no snapshot in progress)
• Sufficient disk space
• No sensitive files accidentally tracked
• Project git untouched (shadow repo is independent)

---

Plugin Tools (Direct Use in OpenCode)

You can call these directly in your OpenCode conversations:

@tool gts_status
@tool gts_list
@tool gts_diff hash=<hash>
@tool gts_restore hash=<hash>
@tool gts_snapshot
@tool gts_prune
@tool gts_config
@tool gts_doctor

---

Limitations & Known Issues

v0.1.0 Limitations

1. Prune not implemented — gts prune shows preview but doesn't actually delete
2. No cross-machine restore — Snapshots are local only
3. No selective restore — Restores all files, not single files
4. Hook timing — The file.edited hook timing from OpenCode should be verified in production
5. Large files skipped — Files over 10MB are not snapshot (configurable)
6. Disk space check — Requires 100MB free or snapshot fails

What Could Go Wrong

Scenario	What Happens
Disk full	Snapshot fails with error, but command still runs
Git not installed	Plugin warns but doesn't break OpenCode
Lock file present	Waits for previous snapshot to finish
Network issues	N/A — all local, no network required
Corrupt shadow repo	Run gts doctor to diagnose

---

Uninstalling

To remove Git That Shit:

1. Remove from opencode.json:

{
  "plugins": []
}

1. Optionally delete the shadow repo:

rm -rf .git-that-shit

---

Testing

npm run build
npm test

v0.2.0 Test Results

Test Suite	Tests	Status
CLI (cli.test.ts)	20	✅ All pass
Tracker (tracker.test.ts)	29	✅ All pass
Restore (restore.test.ts)	6	✅ All pass
Snapshot (snapshot.test.ts)	14	✅ All pass
Security (security.test.ts)	15	✅ All pass
Detector (detector.test.ts)	29	✅ All pass
Config (config.test.ts)	12	✅ All pass
Disk (disk.test.ts)	8	✅ All pass
Git (git.test.ts)	16	✅ All pass
Lock (lock.test.ts)	11	✅ All pass
Manifest (manifest.test.ts)	10	✅ All pass
Paths (paths.test.ts)	30	✅ All pass
Redactor (redactor.test.ts)	18	✅ All pass
Total	238	✅ 238 pass, 0 fail

Test framework: bun test (bun 1.3.11). All tests are hermetic, use isolated /tmp directories, no real git remotes.

---

Roadmap

Future versions may include:

• Bundle export for portability (share snapshots as archive)
• Selective restore (single file restore)
• Snapshot comparison UI
• Integration with more coding agents
• Cloud backup option

---

License

Apache-2.0

---

Support

If you encounter issues:

1. Run gts doctor for diagnostics
2. Check .git-that-shit/snapshots/.git-that-shit/manifest.jsonl for snapshot history
3. Review .git-that-shit/config.json for configuration issues