Install and use

Up and running in minutes.

The CLI ships two commands. codegraph-trace records and reads history. tracer handles encrypted team sync. You need Python 3.10 or newer and git.

01Install the CLI

From the GitTRACE repository root, create a virtual environment and install. No API key is needed for local recording.

bash

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e ".[dev,panel,languages]"

codegraph-trace --help
tracer --help

02Create your org and register

One admin creates the entity once. Everyone logs in with four credentials and registers an encryption key. The private half of the key stays on your machine.

bash

tracer entity create        # one time, creates your org, you become admin
tracer login                # entity name, entity password, username, password
tracer keys setup           # generates and registers your encryption key
tracer entity add-user      # admins add teammates, --role admin for more admins

03Record steps and read history

Capture any edit between two commits with its reasoning attached. Then open the story of any file.

bash

codegraph-trace record step-1 --author human \
    --reasoning "wrote login() by hand" \
    --before <sha> --after <sha> --repo .

codegraph-trace history auth.py --repo .
codegraph-trace versions --repo .

04Branch, merge and review

Fork a lineage from any recorded version and fold it back later. The review command bundles the diff with the reasoning log and the decision ledger.

bash

codegraph-trace branch create feat-oauth --from 3 --repo .
codegraph-trace branch merge feat-oauth --repo .
codegraph-trace review feat-oauth --repo .  # add --json for agents
codegraph-trace branches show --repo .

05Push and pull, encrypted end to end

A push encrypts on your device to all registered member keys and uploads ciphertext. A pull decrypts locally with your private key.

bash

tracer push --repo . -m "initial trace"
tracer pull --repo .
tracer review                              # changes awaiting review
tracer status                              # entity, members, keys, versions

06Explore it visually

The local panel serves the same codegraph and decision ledger the front page walks through.

bash

codegraph-trace panel --port 8765 --repo .
# open http://127.0.0.1:8765

If the console scripts are not on your PATH after install, every command also works as python -m codegraph_trace.cli <subcommand>. Agent recording currently supports OpenHands sessions out of the box. Human commits are recorded with record.