# PJContext (pjctx)

Capture and restore AI coding context across sessions. Stop wasting 10-15 minutes re-explaining your project every time you start a new AI coding session.

## Installation

```bash
pip install pjctx
# or
pipx install pjctx
```

### Via npm (for Node.js developers)

```bash
npm install -g pjctx
```

> Requires Python 3.9+ and pip. The npm package automatically installs the Python package during setup.

For development:

```bash
git clone <repo-url>
cd pjctx
pip install -e ".[dev]"
```

## Quick Start

```bash
# Initialize in your git repo
pjctx init

# Save context (interactive)
pjctx save

# Save context (quick, one-liner)
pjctx save "Refactoring payment service to event sourcing"

# Save context (auto-detect from git)
pjctx save --auto

# Resume — copies prompt to clipboard, paste into any AI tool
pjctx resume

# Resume with specific format
pjctx resume --format xml
pjctx resume --format compact
pjctx resume --no-copy  # print to stdout
```

## Commands

### `pjctx init`
Initialize `.pjctx/` in the current git repo. Adds `.pjctx/` to `.gitignore`.

### `pjctx save [message]`
Save current coding context. Three modes:
- **Interactive** (no args): Rich prompts walk through task, approaches, decisions, next steps
- **Quick** (`pjctx save "message"`): Auto-fill git data, message only
- **Auto** (`--auto`): No prompts, git-detected changes, carries forward previous context

Options: `--auto`, `-t/--tag TAG` (repeatable)

### `pjctx resume`
Generate a resume prompt from the latest context and copy it to clipboard. Paste into any AI coding tool (Cursor, Claude Code, Copilot, Windsurf) to instantly restore context.

Options: `-f/--format [default|xml|compact]`, `--no-copy`, `-b/--branch BRANCH`

### `pjctx log`
Show context history as a table.

Options: `-b/--branch BRANCH`, `-n/--limit N`, `--all`

### `pjctx diff`
Show changes since last context save.

Options: `--stat` (default), `--full`

### `pjctx handoff [@user]`
Create a handoff context for another developer. Carries forward all context fields and adds handoff note.

### `pjctx share`
Remove `.pjctx/` from `.gitignore` and commit it to git for team sharing.

### `pjctx watch`
Watch for file changes and auto-save context at intervals.

Options: `-i/--interval SECONDS` (default: 300)

### `pjctx hook install|uninstall|status`
Manage git post-commit hook for automatic context saving after each commit.

## Storage

Context is stored locally in `.pjctx/` within your repo, scoped by branch:

```
.pjctx/
├── config.json
├── contexts/
│   ├── main/
│   │   ├── 2024-01-15T10-30-00.json
│   │   └── latest.json
│   └── feature/payment-refactor/
│       └── latest.json
└── hooks/
```

## Prompt Formats

- **default**: Markdown briefing document with headers
- **xml**: Structured XML for tools that parse it
- **compact**: Dense single paragraph for token-limited contexts

## License

MIT
