Skip to content

Get started

The natural Point workflow happens inside the conversation: tell an Agent to save, resume, or publish context. The Skill translates that intent into the Git-native CLI protocol.

Requirements

  • Git
  • Python 3.9 or newer
  • a Git repository

Install the CLI

python3 -m pip install "git+https://github.com/guix4ever/point.git"
point --version

Install the Agent Skill

npx skills add guix4ever/point --skill point

Install it globally with -g when several projects should use it:

npx skills add guix4ever/point --skill point -g

Stash unfinished context

Tell the Agent:

Stash this unfinished Session as a Point.

The Skill exports the newly produced, participant-visible Session event stream as JSONL and invokes point stash. This is independent of git commit. The first Point creates the context branch master and remains local.

The underlying CLI form is:

point stash --title "Failure recovery" --session-file session.jsonl

A minimal input looks like:

{"id":"e1","type":"message","role":"user","content":"Retries must stay bounded."}
{"id":"e2","type":"message","role":"assistant","content":"I will inspect the current failure path."}

You normally do not build this file by hand. It is the open handoff format between Agent adapters and Point.

Resume accepted context

In a later Session or another Agent, say:

Resume the project context.

The Skill runs:

point resume

Point resolves master, walks the reachable parent DAG from oldest to newest, and loads every saved Session once. The next Point stores only events produced after this Resume; restored history remains referenced through its parents.

Revisit history without moving master

point list
point show <point-id> --full
point resume <point-id>

An exact historical ID resumes detached. Name a new direction only when it should stay addressable:

point resume <point-id> --branch experiment

Continue from several directions

point resume <point-a> <point-b> --branch master

The next real Session evaluates both sources. Its saved Point has both as parents; Point does not synthesize a natural-language merge.

Connect context to a Git Commit

Install the repository integration once:

point hooks install
point hooks status

When an Agent performs an approved commit, the Skill stages the intended project changes, prepares the newly produced Session events, and runs normal git commit. The Hook creates a Commit Point linked to the resulting Git Commit.

Without a prepared Session, the Hook does nothing. Point never writes placeholder context.

Publish to the team

point push master --remote origin

To publish the current Git Branch and context lineage atomically:

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

Another clone can continue with:

point fetch --remote origin
point resume

Only the selected Point Branch and its required ancestors are published. Other local experiments remain local.

Next