peek-dev 0.1.0

AI-powered developer companion for understanding, monitoring, and maintaining AI-generated codebases

Peek

AI-powered developer companion — understand, monitor, and maintain your codebase.

Peek sits beside your AI coding tools (Copilot, ChatGPT, Cursor) and builds contextual intelligence about your repository. It tracks which prompt generated which code, maps your codebase architecture, and can trace bugs back to the exact prompt that introduced them.

---

Installation

pip install peek-dev

Or install from source:

git clone https://github.com/pramod/peek
cd peek
pip install -e .

Requirements: Python 3.9+, git (optional but recommended)

---

Quick Start

# 1. Initialise Peek in your project
cd your-project/
peek init

# 2. See your codebase as a feature map
peek map

# 3. Log the prompt you just used to generate code
peek log "Create the authentication module with JWT support"

# 4. Get a health score for your repo
peek health

# 5. Trace a bug back to its originating prompt
peek debug

---

Commands

peek init

Initialises Peek in the current directory. Creates .peek/peek.db for prompt tracking and scaffolds missing project files (src/, tests/, docs/, README.md).

$ peek init

╭─────── ** Peek Initialized ───────╮
│  Project     my-project            │
│  Type        python                │
│  Files found 12 Python file(s)     │
│                                    │
│  Created                           │
│  + src/                            │
│  + tests/                          │
│  + docs/                           │
╰────────────────────────────────────╯

---

peek map

Groups your Python files by folder and displays a feature map — your codebase at a glance.

$ peek map

  Feature Map
 ┌──────────────┬─────────────────────────────┬───────┐
 │ Feature      │ Files                       │ Count │
 ├──────────────┼─────────────────────────────┼───────┤
 │ cli          │ · cli/commands.py            │     1 │
 │ core         │ · core/repo_scanner.py       │     3 │
 │              │ · core/git_history.py        │       │
 │              │ · core/dependency_graph.py   │       │
 └──────────────┴─────────────────────────────┴───────┘

---

peek log "<prompt>"

Logs the AI prompt you just used and links it to the files that changed. This is the data that powers peek debug.

peek log "Add checkout flow with cart integration"

Run this immediately after using an AI tool to generate code.

---

peek debug

Peeks signature feature. Diffs recent git commits, finds which logged prompt touched the changed files, and shows the downstream blast radius through your import graph.

$ peek debug

Recently Changed Files
└── checkout_service.py

Suspect Prompts
╭─────────────────────────────────────────╮
│  Prompt #4  abc1234                      │
│  "Add checkout flow with cart integration"│
│  Touched: checkout_service.py, cart.py   │
╰─────────────────────────────────────────╯

Downstream Affected Files
  → order_service.py
  → payment_handler.py

---

peek health

Scores your repository out of 100 across four dimensions: test coverage, duplicate logic, documentation, and circular dependencies.

$ peek health

╭─────── Repository Health ──────────╮
│  Score:  72 / 100   Grade: C       │
│  ████████████████░░░░░░░░░░░░░░░░  │
╰────────────────────────────────────╯

 Category         Severity   Detail
 Test Coverage    MEDIUM     8 of 14 modules have no tests
 Duplicate Logic  LOW        1 duplicate function group detected

---

How It Works

peek log "prompt"   →  captures git state + links changed files
peek debug          →  git diff → prompt DB lookup → graph traversal
peek health         →  AST analysis → weighted score (no ML required)
peek map            →  file tree walk → feature grouping

All analysis is local and offline. No data leaves your machine.

---

Design Decisions

Choice	Reason
Python-only (v1)	AST module is built-in, no extra deps
SQLite storage	Built into Python, fast, queryable
Git diff + graph traversal	Deterministic debugging without ML
Typer + Rich	Beautiful terminal output, auto-generated help

---

Roadmap

• Phase 2: peek security, peek graph, peek clean, PyPI publishing
• Phase 3: peek architect (AI suggestions), peek monitor (background watcher), VS Code extension

---

License

MIT