Comprehensive helper for working with the DevLoop development observability tool - both using it to analyze development patterns and contributing to its development. Use when running DevLoop commands, interpreting council mode analysis, understanding git activity patterns, reviewing Claude Code sessions, or working on DevLoop's hexagonal architecture codebase. Trigger for phrases like "run devloop", "analyze branch", "council mode", "development patterns", or when working on the DevLoop Rust codebase itself.
A comprehensive helper for working with the DevLoop development observability tool - both using it to analyze development patterns and contributing to its development.
DevLoop is a Rust-based development observability tool that provides a TUI for visualizing git activity and Claude AI sessions. This skill helps you:
Use this skill when you need to:
For using DevLoop:
just run works)OPENAI_API_KEY or ANTHROPIC_API_KEY (for AI analysis)For DevLoop development:
just command runnerQuick access to common DevLoop commands with context about when and how to use them.
Available Commands:
# AI branch analysis (single perspective)
just analyze [BRANCH]
# AI branch analysis (multi-role council mode)
just analyze --council [BRANCH]
# View Claude Code session transcripts
just logs [SESSION]
# Export timeline data as JSON
just export
# Start the interactive TUI
just run
# Development commands
just dev # Debug mode
just test # Run tests
just fmt # Format code
just check # Quick compile check
just relay # WebSocket relay server
When to use each command:
analyze - Quick health check on a branch before merginganalyze --council - Deep analysis from multiple AI perspectives (security, performance, creativity, etc.)logs - Review past Claude Code sessions and development historyexport - Get structured data for custom analysis or reportingrun - Interactive exploration of git activity and timelineCouncil Mode Perspectives:
DevLoop's council analysis provides insights from 5 different AI roles:
Interpreting Results:
Health scores range from 0.0 to 1.0:
Each analyst provides:
health_score - Numeric assessmentrisk_level - "low" | "medium" | "high"insights - Array of specific observationsrecommendations - Actionable suggestionsExample workflow:
# Run council analysis on current branch
just analyze --council
# Review different perspectives
# - Check Strict Critic for blockers
# - Review Security Reviewer for vulnerabilities
# - Consider Creative Explorer for enhancements
# - Use General Analyst for overall decision
# If health score < 0.6, address recommendations
# Then re-run analysis before merging
Git Activity Analysis:
DevLoop tracks:
Claude Session Metadata:
Located in:
~/.claude/projects/ - Project configurations~/.claude/transcripts/ - Session transcriptsDevLoop correlates sessions with git activity to:
Productivity Insights:
Architecture Overview:
DevLoop uses hexagonal (ports-and-adapters) architecture:
┌─────────────────────────────────────────┐
│ TUI Layer (crates/cli) │
│ - Ratatui UI components │
│ - App<T, B, I> generic over adapters │
└───────────────┬─────────────────────────┘
│ Trait boundaries
┌───────────────▼─────────────────────────┐
│ Domain Layer (crates/components) │
│ - Pure domain models (zero deps) │
│ - Trait-based ports: │
│ • TimelineProvider │
│ • BranchAggregator │
│ • InsightProvider │
└───────────────┬─────────────────────────┘
│ Trait implementations
┌───────────────▼─────────────────────────┐
│ Adapter Layer (crates/cli/adapters) │
│ - GitAdapter (git2-based) │
│ - BamlAdapter (AI analysis) │
│ - GkgAdapter (code structure) │
│ - UnifiedAdapter (composition) │
│ - CouncilAdapter (multi-role AI) │
└─────────────────────────────────────────┘
Key Design Principles:
components/src/domain.rs has zero external dependenciesApp receives trait objects, not concrete typescomponents/src/schema.rs for cross-runtime renderingWorkspace Crates:
crates/cli - Main TUI application (ratatui), entry point, adapterscrates/components - Domain models, ports (traits), git adaptercrates/baml - AI analysis schemas and generated clientcrates/slides - BAML-powered slide generation with ppt-rscrates/devloop-cli - Non-interactive CLI for agents/scriptingcrates/relay - WebSocket broadcast server for eventsBAML Development:
BAML files define AI analysis functions in crates/baml/baml_src/:
// Function definition
function AnalyzeBranch_StrictCritic(
branch_name: string
commits: string
sessions: string
commit_count: int
session_count: int
) -> BranchInsight {
client CustomGPT5Mini
prompt #"
You are a STRICT CRITIC reviewing a development branch.
Branch: {{ branch_name }}
Commits: {{ commit_count }}
Sessions: {{ session_count }}
Recent commits:
{{ commits }}
Recent sessions:
{{ sessions }}
Focus on risks, issues, and conservative assessment.
{{ ctx.output_format }}
"#
}
BAML Best Practices (from rules/baml.md):
@description annotations{{ ctx.output_format }}clients.baml for reusabilitytest analyze_active_feature_branchGKG Integration:
GitLab Knowledge Graph provides code structure:
// Fetch code definitions
let definitions = gkg_adapter.get_definitions("src/main.rs").await?;
// Fetch code references
let references = gkg_adapter.get_references("function_name").await?;
// Get repository map
let repo_map = gkg_adapter.get_repo_map().await?;
GKG Setup (v0.25.0+):
# Stop server before indexing
gkg server stop
# Index project
gkg index .
# Start server
gkg server start
Important: v0.25.0+ removed HTTP indexing API - use CLI directly.
Common Development Tasks:
# Run tests
just test
# Run specific package tests
cargo test -p devloop-cli
# Format all code
just fmt
# Lint
cargo clippy --workspace
# Quick compile check
just check
# Clean build artifacts
just clean
# Simultaneous relay + TUI dev
zellij --layout devloop-layout.kdl
# Scenario: About to merge feature/auth branch
# Goal: Ensure branch is ready for merge
# Step 1: Run council analysis
just analyze --council feature/auth
# Step 2: Review health scores
# - All analysts > 0.6? Proceed
# - Any analyst < 0.6? Address recommendations
# Step 3: Check specific concerns
# - Security Reviewer: Any vulnerabilities?
# - Performance Analyst: Any bottlenecks?
# - Strict Critic: Any blockers?
# Step 4: If issues found, fix and re-analyze
# ... make fixes ...
just analyze --council feature/auth
# Step 5: Merge when all green
# Scenario: Want to understand my development rhythm
# Goal: Identify productivity patterns
# Step 1: Start TUI to explore timeline
just run
# Step 2: Navigate to BranchList view
# - See all branches with activity
# - Note branch lifetimes and commit counts
# Step 3: Drill into specific branch
# - View timeline of commits and sessions
# - Identify session-to-commit lag
# - Detect context switches
# Step 4: Export data for custom analysis
just export > timeline.json
# Step 5: Analyze patterns
# - How often do I switch branches?
# - What's my session-to-commit lag?
# - Do I batch commits or commit frequently?
# Scenario: Want to add "Documentation Reviewer" role
# Goal: Extend council with docs-focused perspective
# Step 1: Create BAML function
# Edit crates/baml/baml_src/analysis.baml
function AnalyzeBranch_DocsReviewer(
branch_name: string
commits: string
sessions: string
commit_count: int
session_count: int
) -> BranchInsight {
client CustomGPT5Mini
prompt #"
You are a DOCUMENTATION REVIEWER.
Focus on:
- README updates
- Code comments
- API documentation
- User-facing docs
Branch: {{ branch_name }}
{{ commits }}
{{ sessions }}
{{ ctx.output_format }}
"#
}
# Step 2: Add test case
test analyze_docs_heavy_branch {
functions [AnalyzeBranch_DocsReviewer]
args {
branch_name "feature/docs"
commits "Add API docs\nUpdate README"
sessions "Planning docs structure"
commit_count 3
session_count 1
}
}
# Step 3: Regenerate BAML client
cd crates/baml
baml-cli generate
# Step 4: Update CouncilAdapter
# Edit crates/cli/src/adapters/council.rs
# Add DocsReviewer to council members
# Step 5: Test
just test-pkg devloop-cli
just analyze --council
# Scenario: GKG integration not working
# Goal: Diagnose and fix GKG connectivity
# Step 1: Check GKG server status
gkg server status
# If stopped, start it:
gkg server start
# Step 2: Verify indexing
gkg server stop
gkg index .
gkg server start
# Step 3: Test GKG connectivity
curl http://localhost:27495/health
# Step 4: Check environment variables
echo $GKG_SERVER_URL
# Should be http://localhost:27495 or unset (uses default)
# Step 5: Run DevLoop with GKG debug
RUST_LOG=devloop_cli::adapters::gkg=debug just run
# Step 6: Verify graceful degradation
# UnifiedAdapter should work even if GKG unavailable
# Check logs for "GKG unavailable" warnings vs errors
For Using DevLoop:
For DevLoop Development:
components/src/domain.rs@descriptionjust test before committingjust fmt to maintain consistency"Command not found: just"
just: cargo install just or brew install just"BAML client not found"
cd crates/baml && baml-cli generate"GKG server unavailable"
gkg server start"No API key found"
OPENAI_API_KEY or ANTHROPIC_API_KEYexport OPENAI_API_KEY=sk-..."Health score seems wrong"
"Tests failing after BAML changes"
cd crates/baml && baml-cli generatejust test-pkg devloop-cli for faster iterationProject Files:
/Users/joe/dev/devloop/CLAUDE.md - Main project documentation/Users/joe/dev/devloop/justfile - Command definitions/Users/joe/dev/devloop/TESTING_CHECKLIST.md - Comprehensive test guide/Users/joe/dev/devloop/crates/components/src/domain.rs - Core domain models/Users/joe/dev/devloop/crates/baml/baml_src/ - BAML schemas/Users/joe/.claude/rules/baml.md - BAML style guideKey Concepts:
External Documentation:
This skill should be updated when:
justfileVersion: 1.0.0 Last Updated: 2026-03-15 Maintained By: DevLoop contributors