AI-powered codebase summarization CLI with smart context optimization
npm install gsumgsum is a specialized command-line tool designed to optimize codebase context for agentic AI CLIs like Gemini CLI and Claude CLI. It dramatically reduces token usage, saves context windows, and minimizes tool calls by generating intelligent, compressed summaries of your codebase.
Agentic AI CLIs like Gemini CLI and Claude CLI are powerful, but they burn through tokens and context windows fast. gsum solves this by:
- š Reducing token usage by 80% - Generate compressed, relevant context instead of sending entire codebases
- ā” Minimizing tool calls - One gsum command replaces dozens of file reads and searches
- šÆ Saving context windows - Smart summarization keeps you under token limits
- š Caching results - Instant reuse of analysis to avoid repeated work
- š Optimizing for AI consumption - Output specifically designed for Claude Code, Gemini CLI, and other agentic tools
š” Primary Use Case: Run gsum within Claude Code to leverage Gemini CLI's large context window and free API tier. Instead of Claude Code burning through your limited Claude tokens reading 50+ files, gsum defers the heavy analysis work to Gemini's generous free tier, then provides Claude with the essential context in a single, optimized summary.
``bashš„ NEW USER? Start here! Zero learning curve:
gsum interactive
Features
šÆ Agentic AI CLI Optimization:
- ā” Claude Code Auto-Detection: Automatically optimizes output when running in Claude Code environment
- š 80% Token Reduction: Generate 3k-token contexts vs 5-7k standard summaries
- š¦ Smart Caching: Instant reuse (< 1 second) with incremental updates only when needed
- šÆ Import Graph Analysis: File centrality scoring to surface the most critical code
- š Gemini CLI Integration: Seamless integration with Google's Gemini CLI for AI generation
š Context Management:
- š Context Levels: Choose minimal (2-3k), standard (5-7k), or comprehensive (10k+) summaries
- š Focus Areas: Target specific areas like frontend, API, database, testing, deployment, tooling, or documentation
- š Path-Specific: Analyze specific directories instead of entire codebase
- š§ Smart File Inclusion: Automatically include the most relevant files based on git history and imports
š ļø Core Features:
- š Ephemeral Summaries: Generate fresh summaries on-demand for maximum context
- š¾ Persistent Summaries: Save summaries with intelligent git-aware regeneration
- š Implementation Planning: Create detailed, actionable plans for new features
- š® Interactive Mode: Zero-learning-curve guided configuration with intelligent project analysis
- šŗļø Codebase Fingerprint: Ultra-compressed project overview in seconds
- š Git-Aware: Only regenerates when significant changes occur (>500 lines)
- š”ļø Standalone: No external dependencies or MCP servers required
Installation
$3
- Node.js v16 or higher
- npm
- Git (for git-based installation)
- Gemini CLI (recommended) - for AI generation
$3
`bash
Global installation
npm install -g gsumOr use without installing
npx gsum
`$3
`bash
git clone https://github.com/jhurray/gsum.git
cd gsum
make install
`The git installer will:
- ā
Check prerequisites
- ā
Install dependencies
- ā
Create the gsum executable
- ā
Verify installation with
which gsum
- ā
Display the installed version$3
If you use Claude Desktop and installed via git, add slash commands for seamless integration:
`bash
make install-commands
`This enables:
-
/gsum - Generate ephemeral summary
- /gsum-save - Create/update persistent summary
- /gsum-plan - Generate implementation plans
- /gsum-interactive - š„ Interactive guided mode (works in any repo!)Note: Claude commands are only available with git installation. Commands are always overwritten on install/update to ensure you have the latest version.
How It Works
$3
gsum is designed to maximize efficiency for agentic AI CLIs by automatically adapting its behavior:
šÆ Primary Mode - Claude Code + Gemini CLI:
- Auto-detects Claude Code via
CLAUDE_CODE or CLAUDE_DESKTOP_TOOLS_ACTIVE environment variables
- Defers heavy work to Gemini CLI (gemini --yolo command) to leverage its large context window and free API tier
- Optimizes output for Claude consumption: 3k tokens vs 5-7k standard, structured for AI understanding
- Smart caching: Results cached for instant reuse, incremental updates only when needed
- Perfect for development workflows: Claude handles conversations, Gemini handles codebase analysisš§ Standalone Gemini Mode:
- Uses Gemini CLI as the default LLM provider when not in Claude Code
- Generates comprehensive markdown documentation via Gemini API
- Full project analysis with all documentation sections
- Standard token limits (no aggressive optimization)
š”ļø Fallback Options:
-
--fallback: Generates prompt you can copy to Claude manually (when Gemini quota exceeded)
- --claude-execute: Attempts to use local Claude CLI if installed
- --claude-only: Bypasses LLM entirely, generates analysis data onlyš” Key Insight: The tool is specifically architected so Claude Code users can offload expensive codebase analysis to Gemini's free tier while keeping their Claude tokens for actual development work.
$3
gsum analyzes your codebase locally:
- š Traverses directory structure (respects .gitignore patterns)
- š Detects programming languages and frameworks
- š Counts files and analyzes imports/exports
- šļø Identifies architecture patterns
- š¦ Extracts package.json, go.mod, requirements.txt, etc.
- šæ Captures git information (branch, last commit)$3
Gemini Mode (Default):
- š Builds comprehensive prompt for Gemini CLI
- š¤ Gemini analyzes and generates full documentation
- š Returns documentation sized for your needs (2-3k to 10k+ words)Claude Code Mode (Auto-Enabled):
- š Builds token-optimized context with smart file selection
- š¤ Returns structured, minimal context for Claude consumption
- š¾ Caches context for instant reuse on subsequent runs
$3
Depending on the command and environment:
- Default: Prints to terminal (ephemeral)
- Save: Writes to file with git metadata
- Plan: Outputs actionable implementation steps
- Claude Code: Returns optimized context for AI assistant consumptionUsage
$3
`bash
Generate ephemeral summary of current directory
gsumSave persistent summary (ARCHITECTURE.gsum.md)
gsum saveGenerate implementation plan
gsum plan "add user authentication"Plan with task-relevant files
gsum plan "fix auth bug" --smart-files 10Force fresh analysis (ignore cache)
gsum plan "refactor API" --freshClaude-optimized plan
gsum plan "add OAuth" --claude-optimizedUpdate gsum to latest version (from anywhere)
gsum updateShow usage guide for LLMs
gsum llm-usageShow detailed help
gsum --helpInteractive mode - guided configuration
gsum interactive
or short alias
gsum iUltra-compressed project overview
gsum fingerprint
or short alias
gsum fpFingerprint as JSON
gsum fingerprint --format json
`$3
`bash
Verbose output (see what gsum is doing)
gsum -vDebug mode (detailed logs)
gsum -dForce regeneration (ignore git checks)
gsum save --forceCustom output file
gsum save --file MY_DOCS.mdGenerate fallback prompt on quota error
gsum --fallbackTry Claude CLI on quota error (experimental)
gsum --claude-execute
`$3
gsum now provides better visibility and control when running AI operations:
`bash
Auto-verbose mode in Claude Code
When running through Claude Code, gsum automatically enables verbose mode
Set custom timeout (default: 5 minutes)
export GSUM_TIMEOUT=600000 # 10 minutes in milliseconds
gsum saveVerbose mode shows:
- š Execution start with working directory
- š Prompt length information
- ā³ Real-time progress with elapsed time
- ā
Completion status
- ā±ļø Timeout warnings if exceeded
`Progress indicators show animated dots with elapsed time:
`
ā³ Gemini is processing.... (45s)
`Benefits:
- No more hanging processes
- Clear visibility of what's happening
- Configurable timeouts for long operations
- Automatic verbose mode in AI assistants
$3
Control the depth and detail of generated summaries:
`bash
Minimal context (2-3k words) - Essential architecture only
gsum --context-level minimalStandard context (5-7k words) - Balanced detail [DEFAULT for gsum]
gsum --context-level standardComprehensive context (10k+ words) - Full documentation [DEFAULT for save]
gsum --context-level comprehensive
`When to use each level:
- minimal: Quick context for AI assistants with limited windows
- standard: Day-to-day development tasks and code reviews
- comprehensive: Full architectural documentation, onboarding
$3
Generate targeted summaries for specific parts of your codebase:
`bash
Focus on frontend components and UI
gsum --focus frontendFocus on backend API and endpoints
gsum --focus apiFocus on database models and schemas
gsum --focus databaseFocus on test structure and coverage
gsum --focus testingFocus on deployment and CI/CD
gsum --focus deploymentFocus on build tools and configuration
gsum --focus toolingFocus on documentation and guides
gsum --focus documentation
`How it works:
- Filters files based on directories, extensions, and keywords
- Adjusts document sections to match the focus area
- Reduces noise by excluding unrelated code
Example combinations:
`bash
Quick frontend overview
gsum --focus frontend --context-level minimalComprehensive API documentation
gsum save --focus api --context-level comprehensive
`$3
Generate summaries for specific directories:
`bash
Summarize a specific directory
gsum src/apiSummarize a subdirectory
gsum src/components/AuthSave summary for a specific path
gsum save backend/Combine with other options
gsum src/frontend --focus frontend --context-level minimal
`Benefits:
- Analyze only the parts you're working on
- Faster generation for large codebases
- More focused and relevant summaries
$3
gsum now includes special optimizations for Claude Code users:
`bash
Auto-enabled in Claude Code environment
gsum # Automatically uses Claude optimizationForce Claude optimization
gsum --claude-optimizedSave with Claude context cache
gsum save --claude-optimizedGenerate optimized implementation plan
gsum plan "add auth" --claude-optimized
`Features:
- Auto-detection: Automatically optimizes output when running in Claude Code
- Token efficiency: Generates 3,000-token contexts (vs 5,000-7,000 standard)
- Smart caching: Caches context in
.gsum/ for instant reuse
- Incremental updates: Only regenerates when significant changes occur
- Import graph analysis: Scores files by centrality for better contextCache structure:
`
.gsum/
āāā context.md # Claude-optimized context
āāā cache-metadata.json # Cache tracking info
āāā file-summaries/ # Individual file analysis
`Benefits for Claude Code:
- ā” Instant context (< 1 second with cache)
- š 80% reduction in discovery overhead
- šÆ More actionable, less verbose output
- š Smart incremental updates
$3
The most user-friendly way to use gsum! Not sure which options to use? Let gsum guide you step-by-step:
`bash
gsum interactive
or
gsum i
`š„ What makes Interactive Mode special:
- š§ Smart Analysis First - Analyzes your project structure and suggests optimal settings
- šÆ Guided Questions - Asks you exactly 3 simple questions, one at a time
- ⨠Intelligent Defaults - Recommends the best options based on your tech stack
- š§ Perfect Command Generation - Builds the exact gsum command for your needs
- ā
Safety First - Shows you the command before executing it
- ā” Zero Learning Curve - No need to memorize CLI flags or options
The interactive experience:
1. š Project Fingerprint - Instantly scans your repo structure and tech stack
2. ā Question 1 - Ephemeral (chat) or persistent (file) summary?
3. ā Question 2 - How detailed? (minimal/standard/comprehensive)
4. ā Question 3 - Focus area? (frontend/API/database/all areas/etc.)
5. š ļø Command Preview - Shows the exact command it will run
6. š One-Click Execute - Runs your perfectly configured gsum command
Perfect for:
- š First-time users - Learn gsum without reading docs
- š¤ Complex projects - Get intelligent recommendations
- ā” Quick setup - Faster than figuring out CLI flags
- šÆ Optimal results - Ensures you get the best possible summary
Interactive mode eliminates the guesswork and ensures you always get the perfect gsum configuration for your project!
$3
Automatically include the most relevant files in your summary:
`bash
Include 10 most relevant files
gsum --smart-files 10Include 5 most relevant files for a specific task
gsum plan "add authentication" --smart-files 5Combine with other options
gsum --focus api --smart-files 15
`How it works:
- Analyzes git history for recently changed files
- Identifies highly imported/central files
- Considers file type importance and complexity
- Automatically includes file contents in the summary
Perfect for:
- Getting AI to focus on the exact files that matter
- Task-specific planning with relevant code context
- Understanding core architecture through key files
$3
Get an ultra-compressed overview of any project:
`bash
Generate fingerprint
gsum fingerprintFingerprint for specific directory
gsum fingerprint src/Output as JSON
gsum fingerprint --format json
`Example output:
`
šŗļø Codebase Fingerprintš¦ my-app
š§ Tech: React/TypeScript/Node.js
šļø Structure: Monorepo with 3 packages
š Files: 127 (.ts: 89, .tsx: 38, .json: 15)
šÆ Patterns: Redux state, REST API, Unit tests
š Dependencies: 47 prod, 23 dev
šæ Git: main branch, 1,234 commits, 5 contributors
`Perfect for:
- Quick project assessment
- Sharing project overview in discussions
- Understanding new codebases at a glance
$3
`bash
Limit directory depth
gsum --depth 5Include only specific files
gsum --include ".js,.ts"Exclude patterns
gsum --exclude "test/*,.spec.js"Disable git integration
gsum --no-gitOutput as JSON
gsum --format json
`Git-Aware Intelligence
gsum save is smart about regeneration:
1. First Run: Generates and saves with git metadata
2. Subsequent Runs:
- Checks current git hash vs stored hash
- Counts lines changed with
git diff
- Only regenerates if >500 lines changed
- Use --force to overrideSaved files include:
`markdown
[Your documentation content]
`Handling Quota Limits
When Gemini quota is exceeded, gsum provides options:
1. Generate Fallback Prompt (
--fallback)
`bash
gsum --fallback
`
Creates a detailed prompt you can copy to Claude2. Try Claude CLI (
--claude-execute)
`bash
gsum --claude-execute
`
Experimental: Attempts to run with Claude CLI directly3. Wait for Reset
Gemini quotas typically reset daily
Architecture
gsum is a modular Node.js CLI application:
`
gsum/
āāā cli/
ā āāā gsum.js # Main CLI entry point
ā āāā lib/
ā ā āāā analyzer.js # Codebase analysis engine
ā ā āāā generator.js # Summary generation orchestrator
ā ā āāā git.js # Git integration and change tracking
ā ā āāā gemini.js # Gemini API client
ā ā āāā claude.js # Claude CLI client (experimental)
ā ā āāā fallback.js # Fallback prompt generator
ā ā āāā commands/ # Command implementations
ā āāā package.json # Dependencies
āāā install.sh # Smart installer script
āāā test.sh # Test suite
āāā Makefile # Build automation
`$3
- Standalone CLI: No MCP server dependencies
- Local Analysis: All file analysis happens locally
- AI Generation: Leverages Gemini's capabilities
- Git Integration: Smart caching and regeneration
- Extensible: Easy to add new commands
Examples
$3
`bash
$ gsum
Outputs comprehensive guide including:
- Component architecture
- State management approach
- Routing structure
- Build configuration
- Testing setup
`$3
`bash
$ gsum save
Creates ARCHITECTURE.gsum.md with:
- Service architecture
- API endpoints
- Database models
- Dependency injection
- Deployment configuration
`$3
`bash
$ gsum plan "add real-time notifications"
Generates step-by-step plan:
1. WebSocket server setup
2. Frontend integration points
3. Database schema changes
4. API modifications
5. Testing approach
`Integration with AI Tools
$3
After running make install-commands:
- Type /gsum in any conversation
- Claude runs gsum on your current directory
- Full analysis appears in chat$3
Use gsum llm-usage to see integration guide:
`bash
$ gsum llm-usage
Shows examples and best practices for LLMs
`Troubleshooting
$3
gsum: command not found
- Run
source ~/.bashrc (or ~/.zshrc)
- Check echo $PATH includes ~/binGemini quota exceeded
- Use
gsum --fallback for Claude prompt
- Or wait for daily resetSummary not updating
- Check git status:
git status
- Use gsum save --force to force updateCommand times out
- Default timeout is 5 minutes
- Increase timeout:
export GSUM_TIMEOUT=600000 (10 minutes)
- Enable verbose mode to see progress: gsum -v
- Large codebases may need longer timeoutsNo progress visible in Claude Code
- gsum auto-detects Claude Code and enables verbose mode
- If not working, manually use:
gsum -v
- Check for environment variable: echo $CLAUDE_CODESee docs/TROUBLESHOOTING.md for detailed solutions.
Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test locally:
`bash
make test # Run test suite
npm pack # Test npm package
`
5. Submit a pull request$3
- npm users: npm install -g gsum or npx gsum
- Developers: git clone + make install for full development setupLicense
MIT License - see LICENSE file for details.
Credits
Created by jhurray
Changelog
$3
- Progress Indicators: Real-time progress with elapsed time during AI operations
- Configurable Timeouts: Default 5-minute timeout, customizable via GSUM_TIMEOUT env var
- Claude Code Integration: Auto-detects Claude Code environment and enables verbose mode
- Enhanced Logging: Emoji-based status messages for better visibility
- Real-time Output: Shows AI output as it's generated in verbose mode
- Better Error Handling: Clear timeout messages and graceful process termination$3
- npm Distribution: Available via npm install -g gsum and npx gsum`