Core concepts

You can use the Get started guide without learning the storage model. This page explains the terms you will see in the CLI and Hub.

Repositories, sessions, and turns

Term	What it means	Command to start with
Project workspace	The folder where your agent reads and edits code	Run agit status here
Agent repo	Conversation history, shared memory, skills, and instructions	agit init project-notes
Session branch	One conversation in an Agent repo	agit new owner/repo -b task
Turn commit	A saved user turn with the agent’s response and events	agit commit owner/repo@task
Workspace binding	The Agent repo this project folder routes to	Inspect with agit status

The Agent repo lives under ~/.agit/repos/<owner>/<name>/. It is separate from your project’s .git. Ordinary agit commit saves conversation history; agit commit --code also commits project code.

The shared main line

main holds shared files such as AGENTS.md, memory/, and skills/. It is a file line, not a conversation you can resume. Shared memory explains how to inspect and promote reviewed session knowledge onto it. Create a session branch with new, or adopt an existing conversation with import.

An Agent repo can contain several session branches. Initializing a folder selects the repo, but it does not create a session. Starting another task in the same repo usually needs a new branch, not another init.

Session branches retain shared files in their history. new materializes instructions and memory for the runtime, but does not install the Agent repo’s skills/ files into runtime skill folders. Keep project skills in the code repository’s .claude/skills/ or .agents/skills/ directory.

How saving works

A user turn and the agent’s response are recorded as a turn commit. Import saves the conversation so far. Later, agit commit saves new turns; hooks or a runtime supervisor may do this automatically, depending on how you run the agent.

Saving and publishing are separate: commit records local history, while push uploads existing saved history to the Hub. Neither an ordinary commit nor a push automatically commits your project’s code.

Saving after a restore

AgentGit distinguishes new work from context that has already been saved:

• Native continuation: AgentGit reads the original runtime transcript and checks that previously saved content still forms its prefix before recording new turns.
• Materialized baseline: When a VIEW is restored into a new runtime transcript, AgentGit records the baseline length (baseline_bytes) and hash. Later saves consider only content appended after that baseline. A transcript shorter than its baseline, or one that fails the recorded baseline hash check, is refused with exit code 7. Use agit doctor to check transcript continuity.

See Runtime support for what happens when restoring into a different agent runtime.

Which conversation a command uses

Use a full reference such as your-name/project-notes@first-task whenever the target might be ambiguous. Use the same explicit target when publishing: agit push your-name/project-notes@first-task.

For commands that need an existing session, selection follows this order:

1. Explicit command arguments.
2. The AGIT_SESSION environment variable.
3. Otherwise, request an explicit target.

@ selects the branch supplied by AGIT_SESSION. AgentGit sets this variable when it launches a runtime. In another terminal, you can select it for a single command:

AGIT_SESSION=your-name/project-notes@first-task agit log @

If a known runtime session conflicts with AGIT_SESSION, AgentGit refuses the stale value. Name the intended target explicitly or correct the environment; AgentGit does not automatically choose the runtime’s branch.

A workspace binding describes the repo associated with a folder. Adopted session links describe which transcripts have been saved there. agit status shows both, but neither supplies a missing session target. Interactive import and resume pickers let you choose explicitly.

Import takes a native runtime session ID, rather than an AgentGit branch reference. Use agit import SESSION_ID --into owner/repo@branch or the interactive agit import picker; import does not accept @ as a session ID.

Reference syntax

Reference	Meaning
task	A branch head in the repository supplied by AGIT_SESSION
owner/repo@task	A branch in a specific repo
task#12	Turn 12 on that branch
task#-1	The latest turn
task#12.3	Event 3 inside turn 12
task#4..#9	A range of turns
main:AGENTS.md	A shared file on the main line
@	The session branch supplied by AGIT_SESSION

These pieces combine: owner/repo@task#12.3 selects one event in one conversation. See History & versions for worked examples.

The context your agent sees

A VIEW is the ordered conversation context used when a session resumes. agit view owner/repo@task lets you inspect it. Forks, merges, and reverts change which events are in that context while preserving the recorded evidence.

A valid VIEW keeps every referenced event reachable in the evidence log and keeps merge markers paired and closed. agit doctor checks these properties, reads session metadata, and checks the continuity of locally available runtime transcripts. Its findings point to the affected session and the next action.

A merge reconciles two lines of conversation. A merge agent reads both sides, selects relevant turns, and writes a summary of the result. See Forks & merges when you are ready to combine work.