Metadata-Version: 2.4
Name: pithy-cli
Version: 0.1.0
Summary: Your pithy python pair programmer CLI tool
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.69.0
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: cryptography>=46.0.2
Requires-Dist: gitpython>=3.1.45
Requires-Dist: openai>=2.1.0
Requires-Dist: rich>=14.1.0
Requires-Dist: typer>=0.19.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# Pithy
Your pithy python pair programmer

## Dependencies
- uv
- Python version >=3.12
- pipx

## Build steps
- `uv build`
- `pipx install .`

## Features

### Code Summarization

Generate structured markdown summaries of your source code files and directories using AI.

#### Quick Start

```bash
# Summarize a single file
pithy summarize path/to/file.py

# Summarize an entire directory
pithy summarize src/

# Summarize current directory
pithy summarize .
```

#### Output Structure

Summaries are written to the `.pithy/` directory at your git repository root, mirroring your source tree structure:

- **File summaries**: `.pithy/<relative_path>.<ext>.md`
  - Example: `src/app.py` → `.pithy/src/app.py.md`
  - Contains AI-generated summary with key points, purpose, dependencies, and notes

- **Directory meta**: `.pithy/<relative_path>/_meta.md`
  - Aggregates immediate files with one-line synopses
  - References subdirectories via links to their `_meta.md` files
  - Generated programmatically (no LLM calls)

#### Options

| Option | Default | Description |
|--------|---------|-------------|
| `path` | `.` | File or directory to summarize |
| `--exclude`, `-x` | *(none)* | Glob patterns to exclude (repeatable) |
| `--depth` | `-1` | Maximum recursion depth (-1 = unlimited) |
| `--force` | `False` | Regenerate even if outputs are up-to-date |
| `--dry-run` | `False` | Show planned actions without writing files |
| `--max-file-bytes` | `120000` | Read limit per file (caps token usage) |
| `--quiet` | `False` | Reduce console output |
| `--include-ignored` | `False` | Process gitignored files |

#### Default Exclusions

**Gitignored files** are automatically excluded by default. The summarize command respects your `.gitignore` file(s) and skips any files or directories that git would ignore. Use `--include-ignored` to override this behavior.

Additionally, the following patterns are always excluded:
- `.git/`, `.pithy/`
- `node_modules/`, `dist/`, `build/`, `.venv/`
- `*.lock`, `*.min.*`

#### Examples

**Exclude specific files or patterns:**
```bash
pithy summarize . --exclude "tests/*" --exclude "*.tmp"
```

**Limit recursion depth:**
```bash
pithy summarize src/ --depth 2
```

**Force regeneration of all summaries:**
```bash
pithy summarize . --force
```

**Preview actions without writing:**
```bash
pithy summarize src/ --dry-run
```

**Quiet mode for scripting:**
```bash
pithy summarize . --quiet
```

**Include gitignored files:**
```bash
pithy summarize . --include-ignored
# Processes everything, including files matched by .gitignore
```

#### Gitignore Integration

By default, `pithy summarize` respects your `.gitignore` files:
- Files and directories matched by `.gitignore` patterns are automatically skipped
- Nested `.gitignore` files are respected (follows git's hierarchy)
- Works seamlessly with your existing git workflow
- Use `--include-ignored` to process ignored files when needed (e.g., for documentation of build artifacts)

**Example:**
```bash
# .gitignore contains:
# build/
# *.pyc
# .env

# Default behavior - skips build/, *.pyc, .env
pithy summarize .

# Process everything, including gitignored files
pithy summarize . --include-ignored
```

#### Incremental Updates

By default, summaries are only regenerated when the source file is newer than the existing summary. This saves API calls and time on repeated runs. Use `--force` to override this behavior.

#### Cost Control

- Only file-level summaries invoke the LLM
- Directory `_meta.md` files are generated programmatically (deterministic, free)
- `--max-file-bytes` caps the amount of content sent per file (default: 120KB)
- Binary files are detected and skipped automatically

#### API Key Setup

Before using summarization, configure your LLM provider API key:

```bash
# For Anthropic Claude
pithy keys set anthropic

# For OpenAI GPT
pithy keys set openai

# Check provider status
pithy keys providers
```
