DevMirror CLI

Local-first engineering memory CLI that transforms git signals into credible daily and weekly performance-ready summaries (BYOK LLM).

A professional-grade tool that transforms git history into paste-ready engineering updates safe for performance reviews, manager sync-ups, and long-term recall.

Maintained at ugbechike/dev-mirror-cli. This is a fresh implementation and is not affiliated with any prior packages that used the devmirror name.

What's New in v0.5.x

• Dashboard UI: Local web interface for browsing 6-12 months of summaries
• Memory Continuity: Summaries reference previous days to emphasize change over time
• Stricter Narrative: Single-engineer perspective, no team/leadership inflation
• Initiative Limits: 1-3 initiatives for daily, 2-6 for weekly (anti-noise enforcement)
• Performance Optimized: Database indexes for fast dashboard queries
• v0.5.7: Optional Cursor hooks (prompt/secrets, shell guardrails, audit on install) and GitHub Actions CI (npm ci, build, test, audit)

Features

• Engineering Memory Infrastructure: Not just a summarizer—6-12 month recall via local dashboard
• Initiative-First: Groups work by branch/ticket/workstream, not file changes
• Evidence-Based: Every summary includes defensible proof (commits, file stats, metadata)
• Memory Continuity: Emphasizes what changed relative to recent history
• Local-first: Works entirely with local git repositories
• Privacy-focused: Safe mode (default) never sends code to LLMs
• BYOK: Bring Your Own OpenAI API Key
• Weekly Digests: Automatic aggregation with hybrid backfill
• npm-ready: Install globally or run via npx

Installation

Global installation

npm install -g devmirror

Run with npx (no installation)

npx devmirror --help

Quick Start

1. Set up your OpenAI API key (Recommended: Environment variable)

   Option A: Environment variable (recommended)

   export OPENAI_API_KEY=sk-your-key-here

   Option B: Global config file

   devmirror config set openai_api_key sk-your-key-here
   # Stored in ~/.config/devmirror/credentials

2. Initialize a repository

   cd /path/to/your/project
   devmirror init --label "Client: Acme Corp"

3. Add notes throughout the day (optional)

   devmirror note "Fixed authentication bug"
   devmirror note "Researched caching strategies"

4. Generate your daily summary

   devmirror summarize today

   Summaries are generated by sending the data described in Data shared with third parties to OpenAI; no other third parties receive your data.

5. Generate your weekly digest

   devmirror summarize week
   # Auto-backfills missing daily summaries from git history

6. Launch the dashboard (v0.5.0)

   devmirror dashboard
   # Opens local web UI at http://localhost:3000
   # Browse, search, and copy summaries from the past 6-12 months

7. Export your summary

   devmirror export --date today --format slack
   # Or export a range
   devmirror export --from 2026-01-01 --to 2026-01-07 --format md

What is DDIO?

DevMirror v0.5.0 implements the DDIO framework for engineering memory:

• Decision / Direction: What approach was chosen or progressed, and why (only when explicit)
• Impact: What changed as a result (system behavior, correctness, reliability, DX, UX)
• Oversight: Validation, reviews, risk mitigation, testing (only when explicit)

v0.5.0 Emphasis:

• Summaries emphasize what changed relative to recent history (memory continuity)
• No team/leadership language ("we", "team", "led")
• Initiative limits prevent noise (1-3 daily, 2-6 weekly)
• If rationale isn't explicit in notes/commits, summaries use neutral phrasing
• Impact and Oversight sections only appear when supported by evidence

Evidence Receipts

Every summary (daily and weekly) includes a proof bundle in metadata:

• Branch name and timezone
• Day boundary used (midnight in your local timezone)
• Commit shas + subjects
• Per-file statistics (insertions/deletions per path)
• Aggregate totals (files changed, lines added/removed)
• Staged/unstaged presence flags
• Notes count
• Whether diff mode was used
• Generation timestamp

Important: Diffs are never persisted. Only metadata signals are stored.

Commands

devmirror dashboard (v0.5.0)

Launch local web UI for browsing summaries.

Options:

• --port <number> - Port to run server on (default: 3000)
• --no-open - Don't auto-open browser

Features:

• Browse daily and weekly summaries
• Group daily summaries by week (accordion view)
• Date range filters (4w, 12w, 6mo, 12mo, All)
• Client-side search/filter
• Copy-to-clipboard for each summary
• Responsive design (mobile-friendly)
• Dark/light mode support

Security: Server binds to 127.0.0.1 only (localhost). No network exposure.

devmirror init

Register a local repository for tracking.

Options:

• --repo <path> - Repository path (default: current directory)
• --label <string> - Repository label (e.g., "Client: Acme")
• --diff-mode <true|false> - Enable diff mode (default: false)

devmirror summarize today

Generate today's work summary with memory continuity (v0.5.0: references previous day automatically).

Options:

• --repo <path> - Repository path (default: current directory)
• --format <md|slack|json> - Output format (default: md)
• --preview <true|false> - Preview without saving (default: false)
• --dry-run - Show collected signals without LLM call
• --safe-mode - Force safe mode (override config)
• --max-diff-kb <number> - Max diff size in KB (default: 250)

v0.5.0: Automatically fetches previous day's summary for memory continuity.

devmirror summarize week

Generate weekly digest from daily summaries with hybrid backfill.

Options:

• --repo <path> - Repository path (default: current directory)
• --from <YYYY-MM-DD> - Start date (default: 7 days ago)
• --to <YYYY-MM-DD> - End date (default: today)
• --format <md|slack|json> - Output format (default: md)
• --preview - Preview without saving
• --dry-run - Show coverage report without generating
• --backfill - Auto-generate missing daily summaries from git history
• --no-backfill - Fail if any daily summaries are missing

Hybrid backfill: If daily summaries are missing for the date range, DevMirror will:

1. Prompt you to generate them from git history (interactive mode)
2. Auto-generate if --backfill flag is used
3. Fail if --no-backfill flag is used

Backfilled summaries are marked with backfilled: true in metadata and use safe mode.

devmirror note "<text>"

Add a note for today.

Options:

• --repo <path> - Repository path (default: current directory)

devmirror list summaries

List saved summaries in a date range.

Options:

• --repo <path> - Repository path (default: current directory)
• --from <YYYY-MM-DD> - Start date (default: 30 days ago)
• --to <YYYY-MM-DD> - End date (default: today)
• --type <daily|weekly|all> - Filter by type (default: all)

Displays: date, type, mode, commit count, files changed, model, backfilled indicator.

devmirror export

Export a saved summary (single date or range).

Options:

• --repo <path> - Repository path (default: current directory)
• --date <today|YYYY-MM-DD> - Single date to export (default: today)
• --from <YYYY-MM-DD> - Start date for range export (use with --to)
• --to <YYYY-MM-DD> - End date for range export (use with --from)
• --format <md|slack|json> - Output format (default: md)
• --out <path> - Write to file instead of stdout

Note: --date and --from/--to are mutually exclusive.

devmirror config

Manage configuration.

Commands:

• devmirror config show - Show current configuration
• devmirror config set diff_mode <true|false> - Set diff mode
• devmirror config set model <model-id> - Set OpenAI model
• devmirror config set max_diff_kb <number> - Set max diff size
• devmirror config set openai_api_key <key> - Set API key

devmirror doctor

Run health checks and validate setup.

devmirror unset <key>

Remove a saved configuration value.

Currently supported keys:

• openai_api_key — Removes the stored API key from ~/.config/devmirror/credentials

After unsetting, you can reconfigure via the OPENAI_API_KEY environment variable or devmirror config set openai_api_key.

devmirror uninstall

Remove global config and display package manager commands to uninstall the CLI.

This command:

1. Deletes the global config directory (~/.config/devmirror/)
2. Prints the appropriate uninstall command for npm, pnpm, and yarn

Note: Project-local data (.devmirror/ directories) is not removed. Delete those manually if needed.

Privacy Modes

Safe Mode (Default)

Never sends raw code to the LLM. Only sends:

• File names that changed
• Per-file statistics (insertions/deletions via numstat)
• Aggregate totals
• Commit messages (with shas)
• Your notes
• Timezone and branch information

Diff Mode (Opt-in)

Sends raw diffs to the LLM for higher quality summaries. Must be explicitly enabled:

devmirror init --diff-mode true
# or
devmirror config set diff_mode true

You can always override with --safe-mode flag when running summarize today.

v0.3.0 Note: Diffs are never persisted in the database. Only metadata signals (file stats, totals, commit shas) are stored.

Security & Privacy

API Key Storage

DevMirror uses a secure, global credentials store for your OpenAI API key:

Storage location: ~/.config/devmirror/credentials

Your OpenAI API key is provided in two ways (priority order):

1. Environment Variable (Recommended)

   export OPENAI_API_KEY=sk-your-key-here

   • Best for CI/CD environments
   • Temporary (session-only)
   • Never written to disk

2. Global Config File

   devmirror config set openai_api_key sk-your-key-here

   • Stored in ~/.config/devmirror/credentials
   • File permissions: 0600 (owner read/write only)
   • Used across all your projects
   • Never stored in project directories

Project Data Storage

DevMirror stores project-specific data locally in each repository:

your-project/
├── .devmirror/
│   └── data.db      ← Summaries, notes, and repo info only
├── .git/
└── ...

Important:

• Each project has isolated data storage
• No secrets stored in project directory
• The .devmirror/ directory is in .gitignore by default
• Never commit the .devmirror/ folder to version control

Priority: Environment variable takes precedence over global config file.

Data shared with third parties

The only third party that receives data from DevMirror is OpenAI. DevMirror does not send data to any telemetry, analytics, or other external services.

When data is sent

Data is sent to OpenAI only when you run:

• devmirror summarize today
• devmirror summarize week (including during backfill of missing daily summaries)

No data is sent when you use dashboard, config, doctor, list summaries, export, note, or init (except when backfill runs as part of summarize week).

What is sent

| Mode | Data sent to OpenAI | |------|----------------------| | Safe mode (default) | Repository label, date, branch, timezone, commit hashes and subjects, file paths and numstat (insertions/deletions per file), aggregate totals, staged/unstaged presence flags, developer notes, and optionally the previous day's summary text for memory continuity. No raw source code or diffs. | | Diff mode (opt-in) | Same as safe mode plus full staged and unstaged diff content (source code changes). Enabling diff mode means raw code is sent to OpenAI. |

What is not sent

• Your API key is used only for authentication and is not included in the request body.
• No data is sent for any command other than summarization (see above).

For a standalone privacy document, see PRIVACY.md.

AI Usage & Privacy

DevMirror CLI uses a Bring Your Own Key (BYOK) approach:

• You provide your own OpenAI API key
• No shared keys or third-party services
• Your API key is stored globally in ~/.config/devmirror/credentials (never in project directories)

Privacy guarantee: DevMirror CLI never uploads anything except what you explicitly allow in diff mode (see Data shared with third parties).

Example Output

Daily Summary (v0.5.0 with v0.3.0 Format)

2026-02-06 — Client: Acme Corp

Authentication System Implementation

Implemented JWT-based authentication to replace session cookies. Chose this approach based on mobile client requirements documented in notes. Added token generation, validation middleware, and error handling for unauthorized requests.

**Impact:**
- API now supports stateless authentication
- Mobile app can authenticate using bearer tokens
- Error responses include clear 401 messages with guidance

**Oversight:**
- Added unit tests covering token validation, expiration, and malformed token scenarios
- Security review completed before merge

Status: partially committed
Evidence: 8 commits, 12 files changed

Key Features:

• Initiative-first (not file-first)
• Single-engineer perspective (no "we", "team")
• Bullet points with bold headers for Impact and Oversight
• Only includes sections when evidence supports them
• Factual decision statements

Weekly Digest (v0.5.0 with v0.3.0 Format)

2026-01-27..2026-02-02 — Client: Acme Corp (Weekly Digest)

Authentication System

Completed JWT-based authentication system. Chose JWT tokens to support stateless API access for mobile clients. Implemented token generation, validation middleware, role-based access control, and password hashing with bcrypt.

**Impact:**
- Mobile app and API clients can now authenticate using bearer tokens
- API response times improved by 60% with Redis caching introduced alongside auth work
- Dashboard pagination bug fixed, affecting 10K+ records

**Oversight:**
- Security review completed for authentication flow
- Load testing conducted with 1000 concurrent users
- Documentation updated for new API endpoints

Redis Caching Strategy

Established Redis as primary caching layer after benchmarking against in-memory and file-based alternatives. Configured TTL policies and implemented cache invalidation patterns.

**Impact:**
- API server load reduced by 40%
- Response times down 60% for frequently accessed endpoints

Evidence: 42 commits, 87 files changed

Key Features:

• Consolidated initiatives (2-6 max per weekly digest)
• Bullet points with bold headers for sections
• No repetition across days
• Emphasizes direction and change over time
• Carryover and Risks only when explicitly indicated

Requirements

• Node.js >= 18.0.0
• Git installed and available in PATH
• OpenAI API key

Upgrading

From 0.5.6 to 0.5.7

New:

• Optional Cursor hooks in .cursor/hooks.json and .cursor/scripts/ (prompt secret check, shell guardrails, audit on install, credentials-file read block)
• GitHub Actions CI (.github/workflows/ci.yml) for build, test, and npm audit

No Breaking Changes: Same commands and behavior; hooks and CI are additive for contributors.

From 0.4.x to 0.5.0

New Features:

• Dashboard UI available via devmirror dashboard
• Memory continuity (summaries reference previous days automatically)
• Stricter narrative rules and initiative limits

No Breaking Changes:

• All existing summaries remain readable
• Commands work exactly as before
• Metadata schema updated to v0.5.0 (backward compatible)

From 0.3.x to 0.4.x

No breaking changes. Weekly digest and backfill features added.

From 0.2.x to 0.3.x

Breaking Change: API key storage moved from project-local to global.

If you used version 0.2.x:

1. Your API key is no longer in .devmirror/config.db
2. Set up your key using one of these methods:
   • Environment variable: export OPENAI_API_KEY=sk-your-key-here
   • Global config: devmirror config set openai_api_key sk-your-key-here
3. Your summaries and notes remain intact in .devmirror/data.db

From 0.1.x to 0.2.x

Breaking Change: Database location moved from global to project-local.

If you used version 0.1.x:

1. Remove old global database: rm -rf ~/.devmirror/
2. Remove any .env files with API keys: rm .env
3. Reinitialize each project: devmirror init
4. Reconfigure API key in each project or use environment variable

Development

Cursor Hooks (optional)

This repository includes optional Cursor hooks in .cursor/hooks.json and .cursor/scripts/ as guardrails when using Cursor in this project:

• beforeSubmitPrompt — Blocks submitting a prompt if it contains an OpenAI-style API key (sk-...) or the credentials path, to avoid leaking secrets into chat.
• beforeShellExecution — Blocks reading the devmirror credentials file from the shell; blocks npm publish / pnpm publish / yarn publish (run publish manually if intended); on npm install / pnpm add / yarn add, runs npm audit --audit-level=high and denies if high/critical vulnerabilities are reported.
• beforeReadFile — Blocks the agent from reading the devmirror credentials file (~/.config/devmirror/credentials).

Hooks run only inside Cursor and are for contributor safety; they are optional. The scripts are readable—review them before use. Scripts are written for macOS/Linux; on Windows you may need to disable hooks or use WSL. Changes to .cursor/hooks.json or scripts in a PR are reviewed like any other code.

CI

GitHub Actions run on push and pull requests to main/master (see .github/workflows/ci.yml):

• Checkout → Setup Node (v18, npm cache) → npm ci (lockfile must be present and in sync) → Build → Test → npm audit --audit-level=high.

So the lockfile is enforced via npm ci, and high/critical vulnerabilities fail the workflow.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT