玄衡科技XUANHENG TECHNOLOGY
MENU

PROJECT 04 · OPEN SOURCE · GIT CONTEXT

Context Loader

Deterministic, bounded local Git context as Markdown or JSON.

Status: Open Source

GitHub

FOCUS

  • Repository Context
  • Deterministic Output
  • Agent Tooling
A real terminal capture: two project-context runs produce byte-identical output (cmp), followed by the first sections of the rendered Project Context document.
A real run against the public context-loader source at tag v1.3.0 — output shown verbatim.

01 · Overview

Overview

Context Loader renders deterministic, bounded context for one local Git working tree, reading repository state and a fixed set of root files without fetching, executing repository code, accessing the network or writing to the target.

The default Markdown output covers Git state, development instructions, project overview, declared commands, entry files, recent commits and a directory tree; a stable JSON interface serves machine callers with content hashes and status codes.

Byte-identical output for identical inputs keeps context reviewable and reproducible, while fixed file selection and size limits keep the transport bounded.

02 · Capabilities

Capabilities

  1. 01

    Bounded Root Context

    Reading only the fixed root candidates — AGENTS.md, README.md and declared entry files — under explicit size limits.

  2. 02

    Markdown & JSON Contracts

    Emitting stable Markdown sections or a versioned JSON document with content hashes and machine-readable statuses.

  3. 03

    Deterministic Rendering

    Producing byte-identical output for the same tool version, arguments and repository state.

  4. 04

    Sanitized Git Access

    Running Git from a fixed executable with a sanitized environment that ignores system, global and per-command configuration, attributes and hooks.

03 · Workflow

Workflow

  1. 01

    Locate Project Root

  2. 02

    Collect Fixed Root Files

  3. 03

    Select Relevant AGENTS

  4. 04

    Render Context

  5. 05

    Report Statuses & Hashes

04 · System View

System View

  1. 01

    CLI & Contract Layer

  2. 02

    Repository Collector Layer

  3. 03

    Render & Selection Layer

  4. 04

    Machine-readable Output Layer

System diagram: five pipeline stages from locating the Git root to statuses and hashes, the boundary of what never happens, the size budgets and the four layers.
The context pipeline, its boundaries and budgets; as of September 2026.

05 · Current State

Current State

Implemented

Release 1.3.0 on PyPI ships the context-loader distribution with the project-context command and three output formats — Markdown, JSON and compact JSON — using only the Python standard library.

Current Focus

Keeping the declared JSON schema and Markdown section contract stable for machine callers.

Next Direction

Remaining a bounded transport for repository-root context while instruction-hierarchy resolution stays with the calling agent harness.

06 · Principles

Principles

  1. 01

    Identical inputs produce byte-identical output; different checkouts or working trees can change it.

  2. 02

    Fixed selection is not redaction: inspect the output before sharing it.

  3. 03

    The tool collects and renders; it never fetches, executes repository code or accesses the network.