# gitstack
[](https://crates.io/crates/gitstack)
[](LICENSE)
> **Git history viewer focused on analysis and insights**
>
> *Built for the AI-assisted development era - optimized for Claude Code and similar tools*
## Why gitstack?
| lazygit | Git operations | Staging, rebasing, cherry-picking |
| tig | Log browsing | Quick commit viewing |
| keifu | Graph visualization | Beautiful branch display |
| **gitstack** | **Analysis & Insights** | **Understanding your codebase** |
gitstack answers questions like:
- *"Who has been working on this module?"*
- *"Which files are changed most frequently?"*
- *"Which commits had the biggest impact?"*
- *"Are there any stale branches that should be cleaned up?"*
- *"How healthy is this project overall?"*
## Install
```bash
cargo install gitstack
```
Or build from source:
```bash
git clone https://github.com/Hiro-Chiba/gitstack
cd gitstack
cargo install --path .
```
## Features
### Analysis Suite
Press a single key to get instant insights:
| `A` | Author Stats | Commits, lines added/deleted per author |
| `H` | Heatmap | Most frequently changed files |
| `T` | Timeline | Commit activity by hour/day |
| `O` | Ownership | Code ownership by file/directory |
| `I` | Impact Score | Commit impact scores (0.0-1.0) |
| `t` | Topology | Branch health and recommendations |
| `D` | Health Dashboard | Project health score (0-100) with alerts |
### Smart Filter
Powerful filtering with intuitive syntax:
```
/author:john # Filter by author
/since:7days # Recent commits
/until:2024-01-01 # Before date
/message:fix # Search commit messages
/file:src/main.rs # Commits touching specific file
/hash:abc123..def456 # Commit range
```
Combine filters: `/author:john since:1week file:*.rs`
### Adaptive Layout (v3.0+)
Toggle with `v` to cycle through view modes:
| Normal | 80+ cols | Full-featured view with graph |
| Focus | 30-39 cols | Narrow pane with compact risk signals |
| Compact | 40-79 cols | 2-pane layout with details |
| UltraCompact | 20-29 cols | Minimal view for Claude Code split panes |
Compact mode shows commit details alongside the graph:
```
┌─ Graph ─────────────────┬─ Details ────────────────────┐
│ ● abc123 feat: auth │ Author: John Doe │
│ │ │ Date: 2024-01-15 10:30 │
│ ○ def456 fix: bug │ │
│ │ │ feat: add authentication │
│ ◆ ghi789 Merge │ │
│ │ │ - Add login endpoint │
│ ○ jkl012 init │ - Add JWT validation │
└─────────────────────────┴──────────────────────────────┘
```
### Branch Graph
Color-coded branch visualization with smart color assignment:
- Adjacent lanes never share the same color
- Branches from the same fork point get distinct colors
- Clear merge visualization with proper line connections
### Project Health Dashboard (v3.0+)
Press `D` to see overall project health:
```
┌─ Health Dashboard ─────────────────────────────────┐
│ Overall Score: 78 / 100 (Good) │
│ ████████░░ │
│ │
│ Quality ████████░░ 82% │
│ Test Health ██████░░░░ 65% │
│ Bus Factor █████████░ 90% │
│ Tech Debt ███████░░░ 75% │
│ │
│ ⚠ Warning: 3 stale branches need attention │
│ ℹ Info: Test coverage could be improved │
└────────────────────────────────────────────────────┘
```
### Branch Recommendations (v3.0+)
The Topology view (`t`) now shows recommended actions for each branch:
| 🗑 | Delete | Merged or inactive for 60+ days |
| ↻ | Rebase | Far behind main branch |
| ⤵ | Merge | Ready to merge (has commits ahead) |
| 👁 | Review | Long-lived branch needs attention |
### CLI Mode (Non-Interactive)
For AI coding assistants (Claude Code, etc.) and scripting, gitstack provides JSON output:
```bash
gitstack --stats # Author statistics
gitstack --heatmap # File change frequency
gitstack --impact # Commit impact scores
gitstack --coupling # File change coupling
gitstack --health # Project health score
gitstack --summary # Current context summary
gitstack --pack # AI-ready insight pack
gitstack --review-pack # AI review decision pack
gitstack --next-actions # Prioritized next actions
gitstack --verify # Risk verdict with confidence
gitstack --why act-add-tests # Explain recommendation
gitstack --handoff --target codex # AI handoff context
gitstack --log -n 5 # Recent commits
```
Example output (`--stats`):
```json
{
"generated_at": "2026-02-03T10:30:00+0900",
"total_commits": 150,
"author_count": 3,
"authors": [
{"name": "Alice", "commit_count": 80, "insertions": 5000, ...}
]
}
```
| `--stats` | Author statistics as JSON |
| `--heatmap` | File heatmap as JSON |
| `--impact` | Impact scores as JSON |
| `--coupling` | Change coupling as JSON |
| `--health` | Project health score as JSON |
| `--summary` | Current context summary as JSON/Markdown |
| `--pack` | AI-ready insight pack as JSON/Markdown |
| `--review-pack` | AI review decision pack as JSON/Markdown |
| `--next-actions` | Prioritized action list as JSON/Markdown |
| `--verify` | Patch risk verdict as JSON/Markdown |
| `--why ID` | Explain recommendation by action ID |
| `--handoff --target ...` | Build handoff context for Claude/Codex/Copilot |
| `--log -n N` | Latest N commits as JSON (default: 10, max: 10000) |
| `--clear-cache` | Clear analysis cache files |
| `--layout auto\|micro\|wide` | TUI layout preset (`micro` for narrow panes, `wide` for split-panel) |
| `--pane-width N` | Width hint for TUI layout decisions (valid: 20-400) |
| `--focus risk\|review\|history\|files` | Startup focus preset for interactive TUI |
| `--quick-action ID` | Execute AI quick action (`risk-summary`, `review-pack`, `next-actions`, `verify`, `handoff-*`) |
| `--quick-action-format compact\|full` | Output density for `--quick-action` (default: compact) |
| `--help` | Show help |
| `--version` | Show version |
### MCP Server (v3.0+)
gitstack includes an MCP (Model Context Protocol) server for AI assistants like Claude Code.
```bash
# Build the MCP server
cargo build -p gitstack-mcp --release
# Add to Claude Code's MCP configuration
```
**Available Resources:**
| `gitstack://stats/authors` | Author statistics |
| `gitstack://stats/heatmap` | File change frequency |
| `gitstack://stats/ownership` | Code ownership |
| `gitstack://stats/quality` | Commit quality scores |
| `gitstack://stats/impact` | Commit impact scores |
| `gitstack://stats/coupling` | Change coupling |
| `gitstack://stats/bus-factor` | Bus factor analysis |
| `gitstack://stats/tech-debt` | Technical debt |
| `gitstack://health/dashboard` | Project health score |
| `gitstack://branch/recommendations` | Branch recommendations |
| `gitstack://summary/now` | Current summary |
| `gitstack://insight/pack` | AI-ready insight pack |
| `gitstack://signals/risk` | Commit risk signals |
| `gitstack://review/pack` | AI review pack |
| `gitstack://review/compact` | Compact AI review summary for narrow panes |
| `gitstack://review/actions` | Prioritized actions |
| `gitstack://review/why/<id>` | Explanation for recommendation |
| `gitstack://handoff/context` | AI handoff context |
**Available Tools:**
| `get_file_history` | File commit history |
| `get_author_commits` | Commits by author |
| `get_file_owners` | File/directory owners |
| `get_hot_files` | Most changed files |
| `get_project_health` | Project health score |
| `get_coupled_files` | Co-changed files |
| `get_branch_recommendations` | Branch action recommendations |
| `get_context_pack` | AI context pack |
| `get_risk_summary` | Current risk summary |
| `get_review_pack` | Review decision pack |
| `get_next_actions` | Prioritized next actions |
| `verify_patch_risk` | Risk verdict for current patch |
| `explain_recommendation` | Why an action is recommended |
## Comparison
| Author statistics | ✅ | ❌ | ❌ | ❌ |
| File heatmap | ✅ | ❌ | ❌ | ❌ |
| Code ownership | ✅ | ❌ | ❌ | ❌ |
| Impact score | ✅ | ❌ | ❌ | ❌ |
| **Health dashboard** | ✅ | ❌ | ❌ | ❌ |
| Branch health / recommendations | ✅ | ❌ | ❌ | ❌ |
| Smart filter syntax | ✅ | ❌ | ❌ | ❌ |
| Adaptive layout (20+ cols) | ✅ | ❌ | ❌ | ❌ |
| Commit range filter | ✅ | ❌ | ❌ | ❌ |
| Branch graph | ✅ | ✅ | ✅ | ✅ |
| Staging/commit | ✅ | ❌ | ✅ | ✅ |
| Pull/Push | ✅ | ✅ | ✅ | ✅ |
| Branch create/delete | ✅ | ✅ | ✅ | ✅ |
| Interactive rebase | ❌ | ❌ | ✅ | ❌ |
| CLI/JSON output | ✅ | ❌ | ❌ | ❌ |
| MCP server | ✅ | ❌ | ❌ | ❌ |
## Keybindings
### Navigation
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `g` | Go to top |
| `G` | Go to bottom |
| `Ctrl+d` | Page down |
| `Ctrl+u` | Page up |
### Views
| `Enter` | Show commit details / diff |
| `P` | Show file patch (in detail view) |
| `v` | Cycle view mode (Normal → Compact → Focus → UltraCompact) |
| `S` | Toggle summary line |
| `A` | Author statistics |
| `H` | File heatmap |
| `T` | Commit timeline |
| `O` | Code ownership |
| `I` | Impact scores |
| `t` | Branch topology with recommendations |
| `D` | Project health dashboard |
### Actions
| `/` | Open filter |
| `Esc` | Clear filter / close view |
| `y` | Copy commit hash |
| `Y` | Print insight pack to stdout |
| `b` | Show blame view |
| `s` | Open status view |
| `F` | Fetch from remote |
| `?` | Show help |
| `q` | Quit |
### Status View (s)
| `Space` | Stage/unstage file |
| `a` | Stage all |
| `A` | Unstage all |
| `c` | Commit |
| `l` | Pull from remote |
| `p` | Push to remote |
### Branch Select (b)
| `Enter` | Checkout branch |
| `n` | Create new branch |
| `d` | Delete branch |
## Configuration
Config file: `~/.config/gitstack/config.toml`
```toml
[display]
date_format = "relative" # or "absolute"
show_stats = true
[keybindings]
quit = "q"
help = "?"
```
## License
MIT
---
[日本語版](README.ja.md) · [Design Doc](docs/DESIGN.md)