PyGitTools

Hooks, tooling, and pygit2 workflows used by PyGitWeb. Can be used headless for many purposes.

PGT

pgt is a terminal UI for commits, branches, tasks, and worktrees. The home page has Status, Log, Tasks, and Worktrees tabs. H / L switch tabs, J / K move the selection, Q or Ctrl-C quits, and ? opens help. On Status, ! or the Actions row runs project scripts from pyproject.toml or actions.toml. Full key bindings are in the in-app help (src/pygittools/help.md).

To run from the repo root, use uv run pgt.

Task objects may include points, a Fibonacci story-point value: 0, 1, 2, 3, 5, 8, 13, or 21. Leave it unset when the task is unestimated.

Hook framework

pygittools.hooks provides a thin Hook base class plus one subclass per git hook type (client- and server-side). Receive-pack hooks (PreReceive, PostReceive) parse their ref-update lines via parse_ref_updates(stdin).

pygittools.hooks_notify adds PreReceiveNotify / PostReceiveNotify: minimal hook variants that POST ?project=<name> to a pygitweb /_internal/notify endpoint so its long-poll updates=true subscribers wake up immediately on each push. Notification failures never reject the push.

See hook_samples/ for ready-to-use scripts.

MCP task server

Boards, tasks, and comments stored in Git can be exposed to AI tools via MCP.

Configure the repository path with PYGITTOOLS_REPO, or set PYGITWEB_PROJECTROOT and pass a project argument to each tool. When neither is set, the server discovers a repo from the current working directory.

Run locally:

PYGITTOOLS_REPO=/path/to/repo uv run pygittools-mcp

Cursor project config (.cursor/mcp.json):

{
  "mcpServers": {
    "pygittools-tasks": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pygitweb", "pygittools-mcp"],
      "env": {
        "PYGITTOOLS_REPO": "/path/to/your/repo"
      }
    }
  }
}

Tools: list_boards_tool, list_tasks_tool, get_task_tool, board_by_status_tool. Resources: board://{board_name}, task://{task_ref}.