201 lines
3.7 KiB
Markdown
201 lines
3.7 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get context-efficient git/Graphite workflows running in 5 minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- Git repository
|
|
- Claude Code 2.0+
|
|
- (Optional) Graphite CLI
|
|
- (Optional) jq for JSON processing
|
|
|
|
## Installation
|
|
|
|
### Option 1: Automated Installation (Recommended)
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/your-username/carbon.git
|
|
cd carbon
|
|
|
|
# Run installer
|
|
./install.sh --project
|
|
|
|
# The installer will:
|
|
# - Copy files to .claude/plugins/
|
|
# - Configure SessionStart hook
|
|
# - Set up agent template
|
|
```
|
|
|
|
### Option 2: Manual Installation
|
|
|
|
```bash
|
|
# In your project
|
|
mkdir -p .claude/plugins/carbon/hooks
|
|
cd .claude/plugins/carbon
|
|
|
|
# Copy files
|
|
cp /path/to/plugin/hooks/session-start.sh hooks/
|
|
cp /path/to/plugin/settings.json .
|
|
cp /path/to/plugin/plugin.json .
|
|
|
|
# Make hook executable
|
|
chmod +x hooks/session-start.sh
|
|
|
|
# Copy agent template (optional)
|
|
mkdir -p .claude/agents
|
|
cp /path/to/plugin/./agents/graphite-ops-template.md .claude/agents/
|
|
```
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# Test hook execution
|
|
bash .claude/plugins/carbon/hooks/session-start.sh
|
|
|
|
# Should output JSON with hookSpecificOutput
|
|
|
|
# Test in Claude Code
|
|
claude --debug hooks
|
|
|
|
# Look for:
|
|
# [SessionStart] Executing hook: session-start.sh
|
|
# [SessionStart] Hook completed successfully
|
|
```
|
|
|
|
## First Use
|
|
|
|
```bash
|
|
# Start Claude Code
|
|
claude
|
|
|
|
# Try it out (hook automatically active)
|
|
> "Check my Graphite stack"
|
|
|
|
# Claude should automatically:
|
|
# 1. Recognize verbose operation
|
|
# 2. Delegate to Task subagent
|
|
# 3. Return concise summary
|
|
|
|
# Expected response:
|
|
# "✓ feature/auth | 3 PRs | Review #456"
|
|
# NOT: [15KB of JSON]
|
|
```
|
|
|
|
## Team Distribution
|
|
|
|
```bash
|
|
# Commit the configuration
|
|
git add .claude/
|
|
git commit -m "Add Graphite context-optimization plugin"
|
|
git push
|
|
|
|
# Team members pull and get automatic optimization
|
|
git pull
|
|
# Plugin activates automatically ✓
|
|
```
|
|
|
|
## Optional: Custom Agent Setup
|
|
|
|
For enhanced UX with colored terminal output:
|
|
|
|
```bash
|
|
# In Claude Code
|
|
claude
|
|
|
|
# Create agent
|
|
/agents create
|
|
Name: graphite-ops
|
|
Color: cyan
|
|
Scope: project
|
|
Prompt: Load from ./agents/graphite-ops-template.md
|
|
|
|
# Use it
|
|
> "graphite-ops check my stack"
|
|
|
|
# Output appears with cyan color:
|
|
graphite-ops [cyan]: ✓ feature/auth | 3 PRs | Review #456
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Hook not firing
|
|
|
|
```bash
|
|
# Check permissions
|
|
chmod +x .claude/plugins/carbon/hooks/session-start.sh
|
|
|
|
# Check settings.json exists
|
|
ls -la .claude/settings.json
|
|
|
|
# Test manually
|
|
bash .claude/plugins/carbon/hooks/session-start.sh | jq .
|
|
```
|
|
|
|
### Context not appearing
|
|
|
|
```bash
|
|
# Verify hook returns correct JSON
|
|
bash .claude/plugins/carbon/hooks/session-start.sh | \
|
|
jq '.hookSpecificOutput.hookEventName'
|
|
|
|
# Should output: "SessionStart"
|
|
```
|
|
|
|
### Patterns not applied
|
|
|
|
Start Claude with debug mode:
|
|
|
|
```bash
|
|
claude --debug hooks
|
|
|
|
# Check for:
|
|
# - Hook execution
|
|
# - Context injection
|
|
# - Any error messages
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- Read [User Guide](USER-GUIDE.md) for comprehensive usage
|
|
- Read [Custom Agents](CUSTOM-AGENTS.md) for agent setup
|
|
- See [examples/](../examples/) for configuration examples
|
|
- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
|
|
|
|
## Quick Reference
|
|
|
|
### Common Operations
|
|
|
|
```bash
|
|
# Stack status
|
|
"Check my stack"
|
|
→ ✓ feature/auth | 3 PRs | Review #456
|
|
|
|
# PR list
|
|
"Show PRs needing review"
|
|
→ 📋 2 PRs: #456 (Auth), #457 (Docs)
|
|
|
|
# Git log
|
|
"Show me recent commits"
|
|
→ Last 10: abc123 Feature, def456 Fix, ...
|
|
|
|
# Submit
|
|
"Submit my stack"
|
|
→ ✓ 3 PRs created | CI running | Ready for review
|
|
```
|
|
|
|
### Using Custom Agent
|
|
|
|
```bash
|
|
"graphite-ops check my stack"
|
|
"graphite-ops show review queue"
|
|
"graphite-ops submit"
|
|
"graphite-ops navigate to next branch"
|
|
```
|
|
|
|
---
|
|
|
|
**That's it! You're ready to use context-efficient git/Graphite workflows.** 🚀
|
|
|
|
For more details, see the [complete User Guide](USER-GUIDE.md).
|