Metadata-Version: 2.4
Name: ctx-git
Version: 0.1.0
Summary: Version control for your reasoning, alongside git.
Author-email: Rushil Reddy <rushilreddy000@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/RushilReddy909/Context-Tracking-Tool
Project-URL: Repository, https://github.com/RushilReddy909/Context-Tracking-Tool
Keywords: git,cli,notes,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ctx

Version control for your reasoning, alongside git.

`git commit -m` squeezes multi-part reasoning into one line. If you get
interrupted mid-task, the *why* behind a diff is gone — only the code state
survives. `ctx` is a small, optional companion to git that captures that
reasoning per-commit, using git's own `git notes` feature. It never touches
`git commit` itself, never blocks a commit, and never appears in a plain
`git log` unless you ask for it.

## How it fits alongside git

```
git commit -m "..."          (completely normal, unmodified)
      │
      └─► triggers a post-commit hook (installed once via `ctx init`)
                │
                └─► prints a nudge only — never blocks, never edits the commit

ctx note      → opens $EDITOR, pre-filled with auto-captured facts, saves as a git note on HEAD
ctx resume    → shows the last note, time gap, and uncommitted changes ("pick up where I left off")
ctx log       → timeline of recent commits with notes inline
```

## Install

No runtime dependencies — just Python 3 and git.

```bash
git clone <this repo>
cd <the cloned folder>
pip install -e .
```

This installs `ctx` as a real command on your PATH (an editable install, so
changes to the source take effect immediately without reinstalling). If pip
warns that the install location isn't on PATH, add it — see
[Deployment](#deployment) below.

## Commands

### `ctx init`
Installs a `post-commit` hook in `.git/hooks/` for the current repository. The hook
just calls `ctx nudge` — a one-line reminder printed after every commit. If a
`post-commit` hook already exists (e.g. from another tool), `ctx init` appends
to it rather than overwriting it. Running `ctx init` more than once is safe —
it detects its own hook and won't duplicate it.

### `ctx note [commit]`
Attaches a reasoning note to a commit (defaults to `HEAD` if no commit is given —
you can also pass a short hash, a branch name, `HEAD~2`, etc.). It gathers a
few facts automatically — files changed, line counts, time since your last
note — opens `$EDITOR` with a pre-filled Markdown template, and once you save
and close, parses what you wrote into a note stored via `git notes`.

The auto-captured facts appear as `<!-- HTML comments -->` in the template so
they're stripped out automatically when parsing — you never have to delete
them by hand. If `$EDITOR` isn't set, it falls back to `nano` on
Linux/macOS or `notepad` on Windows.

**`ctx note --ai`** pre-fills the Reasoning section with an AI-drafted
summary of the commit's diff (via the Google Gemini API), which you review
and edit before saving — a starting point, not a replacement for writing
your own reasoning. Without a key (or on any network/API failure),
`ctx note --ai` prints a one-line notice and falls back to the normal blank
template — it never blocks note-taking. This is entirely opt-in: plain
`ctx note` never makes a network call.

Add `.env` to your `.gitignore` (already done in this repo) so you never
accidentally commit your API key.

⚠️ Diffs are sent to Google's Gemini API to generate the draft. Don't use
`--ai` on repos containing sensitive or proprietary code unless you're
comfortable with that under Google's data usage terms for your account type
(the free tier in particular may use submitted content to improve their
models — check current terms before using this on private code).

### `ctx setkey <key>`
Saves your Gemini API key to `~/.ctx/config`, in your home directory —
outside any git repo, so it's never at risk of being accidentally
committed, and it's picked up automatically by `ctx note --ai` in every
project on your machine. Running it again overwrites the saved key.

`GEMINI_API_KEY` is looked up in this priority order: a real environment
variable, then a `.env` file at the current repo's root, then
`~/.ctx/config`. Each source only fills in what an earlier one left
missing — so a repo-specific `.env` still lets you override the key for
just that project if you ever need to.

### `ctx resume`
No arguments. Prints your current branch, HEAD, the most recent note found by
walking back through recent commit history, and any uncommitted changes — a
quick "where was I" snapshot after being away from a project.

### `ctx log [-n N]`
Prints a timeline of the last `N` commits (default 10), with each note's
first line shown inline, or `(no note)` if a commit has none.

### `ctx nudge` (internal)
Only ever called by the post-commit hook itself — not meant to be run by
hand. Its one rule: it must never fail or block a commit, since it always
runs after the commit has already succeeded.

## Storage design

Notes are stored on a **dedicated git notes ref**, `refs/notes/ctx` —
completely separate from git's default `refs/notes/commits`, so `ctx` never
collides with anything else using notes. Plain `git log` stays clean; notes
only show up via `ctx` commands (or `git log --show-notes=ctx` if you want to
see them through git directly).

You write and edit **Markdown** in your editor, but what actually gets
stored is **JSON**:

```json
{
  "commit": "<full hash>",
  "timestamp": "<ISO 8601>",
  "time_since_last_note_min": 47,
  "files_changed": [{"file": "x.py", "additions": 12, "deletions": 3}],
  "reasoning": "...",
  "next_steps": ["...", "..."]
}
```

## Design principles

- **Never intercept `git commit`.** Only a post-commit hook is used, which
  fires after the commit has already succeeded and cannot alter or block it.
- **Nudge, don't enforce.** The hook only prints a reminder. `ctx note` is
  always optional.
- **No external services by default.** No GitHub API, no database — the
  core workflow reads only the local `.git` folder via git plumbing commands
  (`git diff --numstat`, `git log --format=...`, `git notes`). Works
  offline, no auth required. The one opt-in exception is `ctx note --ai`
  (see below), which calls the Gemini API — plain `ctx note` never does.

## Known limitations

- **Notes don't sync automatically.** `git notes` aren't included in a plain
  `git push`/`git pull` — you'd need to explicitly run
  `git push origin refs/notes/ctx`. Left local-only for now.
- **Rebase/amend can orphan notes.** Since a note is attached to a specific
  commit hash, rewriting history (rebase, amend) creates a new hash and
  disconnects the old note, unless `notes.rewriteRef` is configured in git.
- **`--ai` requires a Gemini API key and sends your diff over the network.**
  See the warning under `ctx note` above before using it on sensitive repos.

## Project layout

```
pyproject.toml          package metadata + the `ctx` console-script entry point
ctx_tool/
  cli.py                 argparse setup and command dispatch; exposes main()
  commands.py            the five commands (init, note, resume, log, nudge)
  git_ops.py             all direct communication with git (run_git, get_note, GitError)
test_ctx.py             automated tests — each test runs against a fresh throwaway repo
```

## Running tests

```bash
python -m unittest test_ctx -v
```

## Deployment

`ctx` is installed as a pip console script (see `[project.scripts]` in
`pyproject.toml`), which is what turns `ctx_tool.cli:main` into a real `ctx`
command on your system after `pip install -e .`.

If running `ctx` right after installing says "command not found," pip's
install location for scripts isn't on your PATH yet:

- **Windows:** scripts land in something like
  `%APPDATA%\Python\Python3x\Scripts`, or your virtualenv's `Scripts\`
  folder if you're using one — add that folder to your PATH via System
  Properties → Environment Variables.
- **Linux/macOS:** scripts typically land in `~/.local/bin` — add
  `export PATH="$HOME/.local/bin:$PATH"` to your shell profile
  (`~/.bashrc`, `~/.zshrc`, etc.).

Using a virtual environment (`python -m venv .venv`, then activating it
before `pip install -e .`) avoids the PATH question entirely while that
environment is active, and is generally the cleaner way to develop this
project day-to-day.
