OpenCode Shadow Git

> Sistema de checkpoints automáticos usando Shadow Git Repository, similar ao Cursor


🎯 O que é?

Uma biblioteca TypeScript que implementa checkpoints automáticos para seus projetos usando um Shadow Git Repository. Permite criar pontos de restauração sem interferir com o Git principal do projeto.

$3

- ✅ Checkpoints automáticos em cada edição
- ✅ Restaurar para qualquer ponto no tempo
- ✅ Não interfere com o Git do projeto
- ✅ Cleanup automático de checkpoints antigos
- ✅ API TypeScript completa e tipada
- ✅ Zero runtime dependencies
- ✅ Performance otimizada (<200ms por operação)

🚀 Quick Start

``bash


Install

npm install opencode-shadowgit

Use in your code

import { ShadowGitManager } from 'opencode-shadowgit';

const manager = new ShadowGitManager('/path/to/your/project');
await manager.init();

// Create checkpoint
const checkpoint = await manager.createCheckpoint('manual', 'my-work', 'Completed feature X');

// List checkpoints
const checkpoints = await manager.listCheckpoints();

// Restore
await manager.restoreCheckpoint(checkpoint.id);
`

→ Full API Documentation

🏗️ How it Works

$3

`
your-project/
├── .git/ # Your main Git (untouched)
├── .opencode/
│ └── checkpoints/ # Shadow Git Repository
│ ├── .git/ # Separate Git for checkpoints
│ ├── checkpoints.json # Checkpoint metadata
│ └── .gitignore # Excluded patterns
└── src/ # Your source code
`

Key concept: The shadow Git repo uses core.worktree config to track files from your project root without interfering with your main Git repository.

📦 Features

$3

- ShadowGitManager: Main class for checkpoint management
- init() - Initialize shadow repository
- createCheckpoint() - Create new checkpoint
- listCheckpoints() - List all checkpoints
- restoreCheckpoint() - Restore to a checkpoint
- getDiff() - Show differences
- cleanup() - Remove old checkpoints
- getStatus() - Get system status

- Debouncer: Smart debouncing to prevent excessive commits
- MetadataStore: Persistent checkpoint metadata storage
- TypeScript Types: Full type definitions included

⚙️ Configuration

Default configuration with sensible defaults:

`typescript
const manager = new ShadowGitManager('/path/to/project', {
enabled: true,

auto: {
enabled: true,
debounceMs: 5000, // Wait 5s after last edit
onEvents: ['file.edited'],
excludePatterns: [
'node_modules/**',
'.git/**',
'*.log'
]
},

retention: {
maxAutoCheckpoints: 50, // Keep last 50 auto checkpoints
maxManualCheckpoints: 100, // Keep up to 100 manual checkpoints
maxAgeDays: 7, // Delete auto checkpoints older than 7 days
maxTotalSizeMB: 500, // Max 500 MB total storage
preserveNamed: true // Always keep manual checkpoints
},

performance: {
enableCompression: true, // Git compression
enableDelta: true, // Delta compression
maxConcurrentOps: 1 // Sequential operations
}
});
`

🧪 Testing

`bash


Build the project

npm run build

Run proof of concept

npx tsx src/poc.ts

Run full example

node dist/example.js
`

Tests included:
- ✓ Shadow repository initialization
- ✓ Checkpoint creation (auto, manual, emergency)
- ✓ Checkpoint listing
- ✓ Checkpoint restoration
- ✓ Diff generation
- ✓ Cleanup algorithm
- ✓ Status reporting

📈 Performance

$3

`
Init shadow repo: ~50ms
Create checkpoint: ~100ms
List checkpoints: ~5ms
Restore checkpoint: ~150ms
Cleanup: ~300ms (with git gc)
`

$3

- Debouncing: Groups rapid edits (5s default)
- Git Compression: Level 9 (maximum)
- Delta Compression: Stores only changes
- Auto-cleanup: Removes old checkpoints automatically
- Efficient metadata: JSON-based persistence

🔄 Comparação com Cursor

| Feature | Cursor | OpenCode Plugin | Status |
|---------|--------|-----------------|--------|
| Auto-checkpoints | ✅ | ✅ | Implementado |
| Manual checkpoints | ✅ | ✅ | Implementado |
| Restore com preview | ✅ | ✅ | Implementado |
| Cleanup automático | ✅ | ✅ | Implementado |
| UI visual | ✅ | ⚠️ CLI only | Futuro |
| Timeline view | ✅ | ❌ | Planejado |
| Diff viewer | ✅ | ⚠️ Text only | Futuro |

📚 Documentation

- USAGE.md - Complete API documentation
- SPEC.md - Technical specification
- VIABILITY.md - Feasibility analysis
- IMPLEMENTATION.md - Implementation summary
- DONE.md - Project completion report

🛣️ Roadmap

$3

- [x] Shadow repository setup
- [x] Checkpoint creation (auto, manual, emergency)
- [x] List and restore checkpoints
- [x] Diff generation
- [x] Cleanup algorithm
- [x] Debouncing
- [x] TypeScript types
- [x] Documentation

$3

- [ ] OpenCode plugin integration
- [ ] Custom tools for OpenCode
- [ ] CLI commands
- [ ] Visual UI in TUI

$3

- [ ] Timeline view
- [ ] Branch-aware checkpoints
- [ ] Export/import checkpoints
- [ ] Sync between machines

🤝 Contributing

Contributions are welcome! This is an open source project.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "Add: my feature"
4. Push to the branch: git push origin feature/my-feature`
5. Open a Pull Request

📝 License

MIT License - Feel free to use and modify!

🔗 Links

- OpenCode
- OpenCode Docs
- Plugin API

---

Built for the OpenCode community 🚀