Git integration¶

Point uses Git as its object store, graph, identity layer, and transport. It does not place generated context files in the project worktree.

Point object¶

Each Point is a real Git Commit with its own tree:

manifest.json
session.jsonl

manifest.json records:

{
  "version": 2,
  "kind": "stash",
  "title": "Bounded retry intent",
  "created_at": "2026-08-11T00:00:00+00:00",
  "parents": ["<point-commit-id>"],
  "source": {
    "agent": "codex",
    "session": "<opaque-id>"
  },
  "git": {
    "branch": "feature/retry",
    "head": "<git-commit-id>",
    "dirty": true,
    "commit": null
  }
}

session.jsonl stores the original participant-visible event stream in order. Event objects remain structured and carry stable IDs so Agent integrations can preserve their native semantics and future intent references can address them.

Point Commit parents form the context DAG. Git Commit IDs remain references inside manifest.json:

Point history                         Repository history
P0 ── P1 ── P2  ← Point master       C0 ── C1 ── C2  ← Git Branch
      ·      ·
      └──────┴── recorded Git Commit IDs

Git Commits are not Point parents. Keeping the graphs independent allows one context direction to inform several Git Branches and one later Session to reference several context directions.

Refs¶

Point uses ordinary Git Branches in a dedicated branch namespace:

refs/heads/point-context/v1/nodes/<point-id>             immutable Point address
refs/heads/point-context/v1/heads/<branch>                local movable Point Branch
refs/remotes/<remote>/point-context/v1/nodes/<point-id>   published detached Point
refs/remotes/<remote>/point-context/v1/heads/<branch>     fetched Point Branch

The default accepted context lives at refs/heads/point-context/v1/heads/master. Point does not use a hidden custom Ref format and does not convert Refs during publication. The namespace keeps Point Branches separate from code branches such as refs/heads/main.

Parent integrity¶

Every Point parent is stored both as a Git Commit parent and in manifest.json. Git parents are authoritative for reachability and push. The manifest mirror keeps the relation easy to consume from JSON.

Point validates equality when reading a node. A mismatch is treated as corruption instead of silently choosing one graph.

Resume reconstruction¶

point resume performs a topological traversal of all selected tips. Parents are returned before children and a shared ancestor is emitted once.

The content is not copied into the next Point. The Agent adapter marks Resume as a new boundary and later exports only events produced after it.

Commit handshake¶

Install the optional Hook once per Clone:

point hooks install
point hooks status

For an Agent-triggered commit:

project changes are staged;
the Agent provides the new Session JSONL to point _prepare-commit;
Point records the current Git HEAD, staged tree, active parents, and Point Branch Tip under .git/point/;
normal git commit runs;
post-commit verifies that the new Commit matches the prepared base and tree;
it creates a Commit Point, records the Git Commit ID, advances the Point Branch, and consumes the pending capture.

No pending capture means no Commit Point. A failed Git commit should be followed by point _cancel-commit; mismatched pending data is never attached automatically.

Point refuses to overwrite an unrelated existing .git/hooks/post-commit. Repositories with a composed Hook can invoke:

point _post-commit

Push and fetch¶

point push master --remote origin

Point walks master’s Point DAG and publishes only the selected lineage. A Point Branch Tip is pushed to refs/heads/point-context/v1/heads/<branch>; its Git parents carry the complete reachable Point DAG. A detached Point is published at refs/heads/point-context/v1/nodes/<point-id>.

The same ordinary branch layout is used locally and on every remote. There is no host detection, custom-Ref transport, compatibility mode, or publication mapping. These branches appear in repository branch listings and normal clones, and broad CI rules may match them. Repositories should exclude point-context/v1/* from code CI and prevent force-push or deletion when append-only team context is required.

point push master --remote origin --with-code

--with-code adds the current Git Branch to the same atomic Git push. The remote sees both histories or neither.

point fetch --remote origin

Fetch records remote tips under Git's normal remote-tracking namespace and creates local Point node branches for every reachable Point. It does not change the project worktree.

Format compatibility¶

Point writes format v2 (manifest.json and session.jsonl). It continues to read format v1 Points containing session.md and exposes them as a legacy Session event, so existing history remains resumable. New saves never write the old layout.