codeboard 0.2.0

Git repository dashboard for your local codebase

CodeBoard

Git repository dashboard for your local codebase. Scans all git repos under a directory and shows status, activity, health — with batch operations and lazygit integration.

Features

• Dashboard — Overview of all repos: branch, last commit, dirty status, language, remote
• Activity — Cross-repo commit timeline
• Health — Find uncommitted changes, unpushed commits, repos behind remote, inactive repos
• Detail — Deep dive into a single repo: contributors, languages, recent commits
• Stats — Aggregate statistics: language distribution, weekly top, remote distribution
• Grep — Search code across all repos
• Batch ops — Pull all, push all, quick commit, stash
• lazygit — Open repos in lazygit, process dirty repos interactively
• Doc — Generate Obsidian project documentation (optional)
• Graph — Code graph analysis via GitNexus (optional)

Health Check

Activity Timeline

Install

pip install .

Or run directly:

python codeboard.py

Quick Start

# Main dashboard
codeboard

# Or use the short alias after pip install
cb

# Filter repos by name
cb --filter simona

# Sort by dirty file count
cb --sort changes

# Cross-repo commit timeline
cb activity --limit 50

# Health check
cb health

# Single repo details
cb detail myrepo

# Summary statistics
cb stats

# Search code across all repos
cb grep "TODO"

# Batch pull all repos
cb pull

# Push all repos with ahead commits
cb push

# Quick commit
cb commit myrepo -m "feat: something" -y

# Stash / unstash
cb stash myrepo
cb stash myrepo pop

# Open in lazygit
cb open myrepo log

# Process all dirty repos one by one
cb each

# JSON output for piping
cb --json | jq '.[]'

# Auto-refresh every 10 seconds
cb --watch 10

Configuration

Config file: ~/.config/codeboard/config.toml

Generate a default config:

cb config

# Directory to scan for git repositories
scan_dir = "~/Code"

# Additional individual repos to include (outside scan_dir)
extra_repos = ["~/Projects/special-repo"]

# UI language: "auto", "en", or "zh"
lang = "auto"

# Path to Obsidian vault (for 'doc' command, optional)
# obsidian_vault = "~/Documents/Obsidian Vault"

# Path to gitnexus binary (for 'graph' command, optional)
# gitnexus_bin = ""

Global Options

Flag	Description
--path <dir>	Scan directory (default: ~/Code or config)
--sort name|activity|commits|changes	Sort order
--filter <keyword>	Filter repos by name
--json	JSON output for piping
--watch N	Auto-refresh every N seconds
--lang en|zh|auto	UI language
--no-color	Disable colored output
-V, --version	Show version

Global options can be placed before or after the subcommand:

cb health --filter simona    # works
cb --filter simona health    # also works

Commands

View

Command	Description
cb / cb dashboard	Main dashboard with repo overview
cb activity [--limit N]	Cross-repo commit timeline (default 30)
cb health	Health check: uncommitted / unpushed / behind / no remote / inactive
cb detail <repo>	Single repo detail: languages, contributors, tags, recent commits
cb stats	Aggregate statistics
cb grep <pattern>	Search code across all repos (regex)

Operations

Command	Description
cb pull	Batch git pull --ff-only all repos with remote
cb push	Push all repos with ahead commits (requires confirmation)
cb commit <repo> -m "msg"	Quick git add -A && commit (use -y to skip confirmation)
cb stash <repo> [push|pop|list]	Quick stash operations

lazygit Integration

Command	Description
cb open <repo> [panel]	Open repo in lazygit (panel: status/branch/log/stash)
cb dirty	List dirty repos, select one to open in lazygit
cb each	Process all dirty repos one by one in lazygit

Optional

Command	Description	Requires
cb doc <repo>	Generate Obsidian project documentation	Obsidian vault path in config
cb graph <repo> [action]	Code graph analysis	gitnexus
cb config	Show or generate config file	—
cb completions [bash|zsh|fish]	Generate shell completion script	—
cb mcp	Run as MCP server for AI assistants	—

MCP Server (AI Integration)

CodeBoard can run as an MCP server, letting AI assistants (Claude Code, Cursor, etc.) query your repo status directly.

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codeboard": {
      "command": "cb",
      "args": ["mcp"]
    }
  }
}

Available tools:

Tool	Description
list_repos	Quick list of all repos with name, branch, dirty status
repo_status	Full dashboard data (branch, commits, language, remote)
health_check	Categorized health report (uncommitted, unpushed, inactive)
recent_activity	Cross-repo commit timeline
repo_detail	Deep dive into a single repo
search_code	Search code across all repos (regex)

No extra dependencies — uses stdio JSON-RPC 2.0, zero config.

Shell Completion

# Bash (add to ~/.bashrc)
eval "$(cb completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(cb completions zsh)"

# Fish (add to ~/.config/fish/completions/)
cb completions fish > ~/.config/fish/completions/cb.fish

Requirements

• Python ≥ 3.11
• rich (terminal formatting)
• git
• lazygit (optional, for open/dirty/each)
• gitnexus (optional, for graph)

Windows note: CodeBoard uses sh -c for batched git commands. On Windows, this requires Git for Windows which includes sh. WSL also works.

Performance

• Scans 48 repos in ~1 second
• Single shell call per repo (6-9 git commands batched into one sh -c)
• 8-way parallel scanning via ThreadPoolExecutor
• Lazy language detection (skipped for commands that don't need it)

Development

git clone https://github.com/shaoyiyang/codeboard.git
cd codeboard
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for details.

License

MIT