283 lines
7.3 KiB
Markdown
283 lines
7.3 KiB
Markdown
# Graphite Context-Optimized Plugin for Claude Code
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://code.claude.com)
|
|
|
|
**Stop drowning in verbose git/Graphite output.** This plugin automatically enables context-efficient workflows for all git and Graphite CLI operations in Claude Code.
|
|
|
|
## 🎯 What This Does
|
|
|
|
Transforms Claude Code's interaction with git/Graphite from context-polluting to context-efficient:
|
|
|
|
**Before (without plugin):**
|
|
```bash
|
|
You: "Check my Graphite stack"
|
|
Claude: [Returns 15KB of JSON → 4,000+ tokens consumed]
|
|
Context: Polluted, reasoning degraded
|
|
```
|
|
|
|
**After (with plugin):**
|
|
```bash
|
|
You: "Check my Graphite stack"
|
|
Claude: [Automatically delegates to Task subagent]
|
|
Subagent: [Processes 15KB in isolated context]
|
|
Claude: "✓ feature/auth | 3 PRs | Review #456"
|
|
Context: Clean, 18 tokens used (225x more efficient)
|
|
```
|
|
|
|
## ✨ Features
|
|
|
|
- **🔄 Automatic Delegation** - Task subagents handle verbose operations automatically
|
|
- **🎨 Colored Agent Support** - Optional custom agent with cyan terminal output
|
|
- **⚡ Zero Friction** - SessionStart hook activates patterns automatically
|
|
- **📦 Team-Ready** - Git-trackable configuration for team distribution
|
|
- **🎯 225x Efficiency** - Dramatic context window improvements
|
|
- **🔧 Flexible** - Supports both Task tool (simple) and custom agents (enhanced UX)
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone this repository
|
|
git clone https://github.com/your-username/carbon.git
|
|
cd carbon
|
|
|
|
# Option 1: Install globally (affects all projects)
|
|
./install.sh --global
|
|
|
|
# Option 2: Install in current project (recommended for teams)
|
|
./install.sh --project
|
|
|
|
# Option 3: Manual installation
|
|
mkdir -p .claude/plugins/carbon
|
|
cp -r hooks settings.json plugin.json .claude/plugins/carbon/
|
|
chmod +x .claude/plugins/carbon/hooks/session-start.sh
|
|
```
|
|
|
|
### Verification
|
|
|
|
```bash
|
|
# Test the installation
|
|
./test/verify-installation.sh
|
|
|
|
# Start Claude Code with debug mode
|
|
claude --debug hooks
|
|
|
|
# Test automatic delegation
|
|
claude
|
|
> "Check my Graphite stack"
|
|
# Should automatically use Task delegation ✓
|
|
```
|
|
|
|
## 📚 Documentation
|
|
|
|
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get running in 5 minutes
|
|
- **[User Guide](docs/USER-GUIDE.md)** - Complete usage documentation
|
|
- **[Architecture](docs/ARCHITECTURE.md)** - How it works under the hood
|
|
- **[Custom Agents](docs/CUSTOM-AGENTS.md)** - Optional colored agent setup
|
|
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
|
|
|
|
## 🎨 Two Approaches
|
|
|
|
### Task Tool (Default - Recommended for Most Users)
|
|
|
|
Zero setup, works immediately:
|
|
|
|
```bash
|
|
You: "Check my stack"
|
|
Claude: [Uses Task delegation automatically]
|
|
```
|
|
|
|
**Characteristics:**
|
|
- ⚡ No configuration needed
|
|
- 📦 Works universally
|
|
- 🎯 Full context isolation
|
|
- ⚪ Generic terminal output
|
|
|
|
### Custom Agent (Optional - Power Users)
|
|
|
|
Enhanced UX with colored output:
|
|
|
|
```bash
|
|
# One-time setup
|
|
/agents create
|
|
Name: graphite-ops
|
|
Color: cyan
|
|
Template: ./agents/graphite-ops-template.md
|
|
|
|
# Use with color
|
|
You: "graphite-ops check my stack"
|
|
graphite-ops [cyan]: ✓ feature/auth | 3 PRs | Review #456
|
|
```
|
|
|
|
**Characteristics:**
|
|
- 🎨 Colored terminal output
|
|
- 👤 Consistent persona
|
|
- 📁 Git-tracked definition
|
|
- 🎯 Same context isolation
|
|
|
|
See [Custom Agents Guide](docs/CUSTOM-AGENTS.md) for setup instructions.
|
|
|
|
## 🔧 How It Works
|
|
|
|
### SessionStart Hook
|
|
|
|
The plugin uses a SessionStart hook to inject context-optimization patterns into Claude's context window automatically:
|
|
|
|
```
|
|
1. Session starts → Hook fires
|
|
2. Hook detects: git repo, Graphite CLI, custom agent
|
|
3. Hook injects: ~800 tokens of patterns into context
|
|
4. Claude knows: Use Task delegation for verbose operations
|
|
5. User benefits: Automatic context efficiency, zero friction
|
|
```
|
|
|
|
### Automatic Delegation
|
|
|
|
When you request git/Graphite operations, Claude automatically:
|
|
|
|
1. Recognizes the operation will return verbose output
|
|
2. Delegates to Task subagent with explicit instructions
|
|
3. Subagent executes with `--json` and `2>/dev/null`
|
|
4. Subagent parses and returns summary <50 tokens
|
|
5. You receive concise, actionable summary
|
|
|
|
**No manual invocation needed - it just works!**
|
|
|
|
## 📊 Efficiency Metrics
|
|
|
|
| Metric | Before (Raw CLI) | After (Plugin) | Improvement |
|
|
|--------|------------------|----------------|-------------|
|
|
| Tokens consumed | 4,108 | 18 | **225x** |
|
|
| Context pollution | High | Minimal | **99.6% reduction** |
|
|
| Response quality | Degraded | Optimal | **Focused reasoning** |
|
|
| User effort | Manual patterns | Zero | **Automatic** |
|
|
|
|
## 🎯 Use Cases
|
|
|
|
### For Solo Developers
|
|
|
|
```bash
|
|
# Just use Claude naturally
|
|
"Check my stack"
|
|
"Show PRs needing review"
|
|
"Submit for review"
|
|
|
|
# Plugin handles context efficiency automatically
|
|
```
|
|
|
|
### For Teams
|
|
|
|
```bash
|
|
# One-time setup
|
|
git clone <your-repo>
|
|
./install.sh --project
|
|
git add .claude/
|
|
git commit -m "Add Graphite context-optimization"
|
|
|
|
# Team members pull and get:
|
|
# ✓ Automatic context optimization
|
|
# ✓ Consistent behavior
|
|
# ✓ Zero per-developer setup
|
|
```
|
|
|
|
### Supported Operations
|
|
|
|
**Graphite CLI:**
|
|
- `gt stack` - Stack status with delegation
|
|
- `gt pr list` - PR listing with filtering
|
|
- `gt pr info` - Detailed PR data with parsing
|
|
- `gt submit` - Submission with confirmation
|
|
- All other verbose gt commands
|
|
|
|
**Git:**
|
|
- `git log --graph` - Commit history with summarization
|
|
- `git diff` - Changes with statistics
|
|
- `git status` - Status with file grouping
|
|
- All other verbose git commands
|
|
|
|
## 🛠️ Configuration
|
|
|
|
### Default Configuration
|
|
|
|
The plugin works out-of-box with sensible defaults. No configuration required.
|
|
|
|
### Custom Configuration
|
|
|
|
Adjust behavior by editing `.claude/plugins/carbon/config.json`:
|
|
|
|
```json
|
|
{
|
|
"contextTokens": 800,
|
|
"delegationThreshold": 100,
|
|
"autoDetectGraphite": true,
|
|
"autoDetectCustomAgent": true,
|
|
"enableTaskDelegation": true,
|
|
"enableCustomAgent": true
|
|
}
|
|
```
|
|
|
|
See [Configuration Guide](docs/CONFIGURATION.md) for details.
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/your-username/carbon.git
|
|
cd carbon
|
|
|
|
# Install dependencies (jq required)
|
|
# Ubuntu/Debian: sudo apt install jq
|
|
# macOS: brew install jq
|
|
|
|
# Run tests
|
|
./test/run-tests.sh
|
|
|
|
# Make changes
|
|
# ...
|
|
|
|
# Test your changes
|
|
./test/verify-installation.sh
|
|
```
|
|
|
|
## 📝 License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- [Graphite](https://graphite.dev) - Excellent stacked diff workflow tool
|
|
- [Claude Code](https://code.claude.com) - Powerful AI-assisted development
|
|
- Community contributors who provided feedback and testing
|
|
|
|
## 📮 Support
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/your-username/carbon/issues)
|
|
- **Discussions**: [GitHub Discussions](https://github.com/your-username/carbon/discussions)
|
|
- **Documentation**: [docs/](docs/)
|
|
|
|
## 🚦 Status
|
|
|
|
- ✅ Production-ready
|
|
- ✅ Actively maintained
|
|
- ✅ Tested with Claude Code 2.0+
|
|
- ✅ Compatible with Graphite CLI 1.0+
|
|
|
|
## 📈 Roadmap
|
|
|
|
- [ ] Additional git workflow patterns
|
|
- [ ] Integration with other git tools (gh, lab)
|
|
- [ ] Advanced custom agent templates
|
|
- [ ] VSCode extension integration
|
|
- [ ] Metrics dashboard for context efficiency
|
|
|
|
---
|
|
|
|
**Install once → Benefit forever → Share with team → Zero-friction context efficiency!** 🚀
|
|
|