Skip to content

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 dedicated namespaces:

refs/points/nodes/<point-id>          immutable Point address
refs/points/heads/<branch>            local movable Point Branch
refs/points/remotes/<remote>/<branch> fetched Point Branch
refs/points/published/<remote>/<id>   local publication marker

The default accepted context lives at refs/points/heads/master. It does not conflict with refs/heads/main or refs/heads/master.

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:

  1. project changes are staged;
  2. the Agent provides the new Session JSONL to point _prepare-commit;
  3. Point records the current Git HEAD, staged tree, active parents, and Point Branch Tip under .git/point/;
  4. normal git commit runs;
  5. post-commit verifies that the new Commit matches the prepared base and tree;
  6. 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 pushes the immutable node Refs plus the Point Branch Ref. Unreachable local Point directions are excluded.

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 imports remote Point nodes and Point Branches into the dedicated local namespaces without changing 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.