OlaProeis/dotfiles-coach: CLI tool that analyzes your shell history (Bash/Zsh/PowerShell) and uses GitHub Copilot CLI to suggest smart aliases, functions, and safety improvements tailored to your workflow. Privacy-first: secrets are scrubbed locally before anything leaves your machine.

AI-powered shell automation from your command history, built for the GitHub Copilot CLI Challenge.

Dotfiles Coach analyses your shell history (Bash, Zsh, PowerShell), finds repeated patterns, detects dangerous commands, and uses GitHub Copilot CLI to generate smart aliases, functions, and safety improvements — tailored to your actual workflow.

Privacy-first: All analysis happens locally. Secrets are scrubbed before any data touches Copilot.

# Install globally
npm install -g dotfiles-coach

# 1. Analyse your shell history (100% local, no network)
dotfiles-coach analyze

# 2. Generate Copilot-powered suggestions
dotfiles-coach suggest

# 3. Apply suggestions to a file
dotfiles-coach apply

# 4. Generate a summary report
dotfiles-coach report --output report.md

# No real history needed -- use bundled fixtures
dotfiles-coach analyze --shell bash --history-file tests/fixtures/sample_bash_history.txt --min-frequency 1

Note: The analyze and report commands work 100% offline. Only suggest requires GitHub Copilot.

Parse shell history and display frequency stats + safety alerts.

dotfiles-coach analyze [OPTIONS]

Send top patterns to GitHub Copilot CLI and display automation suggestions.

dotfiles-coach suggest [OPTIONS]

Write approved suggestions to a shell configuration file.

dotfiles-coach apply [OPTIONS]

Safety: The apply command never auto-sources files. It prints source instructions for you to run manually.

Generate a comprehensive markdown or JSON report of analysis and suggestions.

dotfiles-coach report [OPTIONS]

1. Analyze reads your shell history file and identifies repeated command patterns
2. Suggest scrubs all secrets, sends patterns to gh copilot suggest via a child process, and parses the structured response
3. Apply reads cached suggestions and writes them as valid shell code
4. Report combines analysis + suggestions into a shareable document

No API tokens needed. The tool piggybacks on your existing gh CLI authentication.

• All analysis happens locally on your machine
• Secrets are scrubbed through 13 regex filters before any data leaves via Copilot (env vars, tokens, passwords, SSH keys, AWS keys, npm auth tokens, URLs with credentials, base64 blobs, and more)
• Secret scrubbing is mandatory and cannot be disabled
• The tool sends data only through gh copilot CLI commands — no direct HTTP calls, no telemetry
• The apply command never auto-modifies your shell config without explicit --append-to

# Clone and install
git clone https://github.com/OlaProeis/dotfiles-coach.git
cd dotfiles-coach
npm install

# Build (required for manual testing)
npm run build

# Type-check
npm run typecheck

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Set the environment variable to use the mock client (no real Copilot subscription needed):

# PowerShell
$env:DOTFILES_COACH_USE_MOCK_COPILOT = "1"
node dist/cli.js suggest --shell bash --history-file tests/fixtures/sample_bash_history.txt --min-frequency 1

# Bash/Zsh
DOTFILES_COACH_USE_MOCK_COPILOT=1 node dist/cli.js suggest --shell bash --history-file tests/fixtures/sample_bash_history.txt --min-frequency 1

src/
├── cli.ts                    # Commander entry point
├── types/index.ts            # All shared interfaces
├── commands/                 # analyze, suggest, apply, report
├── parsers/                  # bash.ts (Bash+Zsh), powershell.ts, common.ts
├── analyzers/                # frequency.ts, patterns.ts, safety.ts
├── copilot/                  # client.ts, prompts.ts, response-parser.ts
├── formatters/               # table.ts, markdown.ts, json.ts
└── utils/                    # shell-detect.ts, history-paths.ts, file-operations.ts, secret-scrubber.ts

291 automated tests across 20 test files covering parsers, analyzers, formatters, commands, utilities, and end-to-end workflows.

npm test              # Run all 291 tests
npm run test:watch    # Watch mode
npm run typecheck     # Type-check without emitting

This project was built with significant assistance from AI tools, including GitHub Copilot and Cursor AI. The code, tests, documentation, and images were generated and refined through AI-assisted development. All output has been reviewed and tested by a human.

MIT