Once you have completed Get Started, the daily loop is: work with your agent, save the conversation, inspect it, and resume when you return. Publish when you want a copy on the Hub.
The examples use alice/my-project@first-task. Replace it with the
owner/repo@branch shown by agit status for your session. These commands
manage the AgentGit conversation repository; your project’s code remains
in its own Git repository.
Ask your agent to handle it
After agit setup, your agent has instructions for using AgentGit. You can
ask it directly:
Check this conversation’s AgentGit status. If it is not adopted yet, identify its exact native ID and check whether it continues saved history before importing into alice/my-project@first-task. Ask me to choose any unresolved lineage. Save the milestone “Login flow works” and tell me which repository and branch you saved it to.
Read this session’s recent AgentGit history and summarize the decisions we made about authentication.
Show me which AgentGit sessions belong to this project and the command to resume the one about the login flow.
For publishing, make the destination and visibility explicit:
Check what would be published, then push this session to my private AgentGit repository alice/my-project.
The same operations are available in the terminal below.
Check where you are
agit status
Check the repository, session branch, and whether there is new conversation content to save. This is also the first command to use in an unfamiliar terminal or when a command reports ambiguous context.
AgentGit sets AGIT_SESSION when it launches a runtime. @ and commands with
an omitted session target use that variable. If it is missing or stale, use
the full owner/repo@branch target. A folder’s binding or an adopted runtime
link does not supply a missing target.
Save your conversation
Make sure the runtime conversation is adopted before its first save.
Working startup hooks register a conversation launched with agit new.
If agit status shows no adopted link for that exact conversation, identify
its native runtime session ID and import it explicitly:
agit import SESSION_ID --into alice/my-project@first-task --independent
Replace SESSION_ID with the runtime’s conversation ID, and use the repository
and branch you chose for it. Ask the agent to identify that exact ID; a folder
match or the newest transcript is not enough to choose a conversation.
This example explicitly imports without a prior saved base. For a conversation
that continues earlier history, choose its starting point
instead of assuming it is independent.
If you do not know the ID, exit the conversation and open the picker from an interactive terminal:
agit import
Select the inactive conversation, repository, and a new branch name, then choose
its lineage: a verified saved starting point or an independent import. If
first-task already exists from new, choose another name and substitute it
in the remaining commands. The picker saves the conversation, so do not
repeat the import by ID. Import does not change the environment of your
existing terminal or MCP server; explicit targets work in either case.
An already-adopted conversation can proceed directly to saving:
agit commit alice/my-project@first-task
This records new conversation content in the local AgentGit repository,
with a commit for each new user turn. It does not upload anything. Keep your
agit login credentials available; settlement requires a local identity.
At the end of a useful phase, give the last saved turn a readable milestone:
agit commit alice/my-project@first-task --milestone "Login flow works" --tag ms-login
Supported runtime hooks can save turns automatically after agit setup.
Other runtimes rely on the agent or you to run agit commit. Check
agit status and agit log when you want to confirm that a turn was saved;
see Supported runtimes for integration details.
If you also want to create a commit in the project’s code repository, add
--code. Review the code changes first: this option commits code as well as
conversation history.
Read what you saved
agit log alice/my-project@first-task
agit show alice/my-project@first-task
log lists the saved turns and milestones. show renders the conversation
at the selected branch head. To read a particular turn, copy its number from
the log:
agit show alice/my-project@first-task#3
See History and references for event selection, diffs, search, and export.
Continue later
Save the current conversation before closing the runtime. When you return, run these commands from the project directory:
agit log alice/my-project --branches
agit resume alice/my-project@first-task
The first command helps you find the right session branch; the second
restores and launches it. resume continues an existing branch. To try a
different approach from an older turn, use a fork.
For another task in the same repository, create a new session branch:
agit new alice/my-project -b next-task --as codex
This example uses Codex. Replace codex with any launchable runtime identifier,
including openclaw, hermes, or workbuddy. Without --as, new uses the
configured default, which may differ
from the runtime you used for the preceding conversation.
In the new conversation, check adoption and save a turn before exiting, using the save workflow above.
If you already started the conversation in your runtime, import it instead. For a conversation that is no longer running, use the interactive picker in your terminal. Select the conversation and repository, enter a new branch name, then confirm the intended lineage to complete the import:
agit import
Or, if you already know the runtime session ID, import it directly instead:
agit import SESSION_ID --into alice/my-project@next-task --independent
Replace SESSION_ID with that conversation’s runtime ID. Choose one path;
the picker completes the import, so you do not need to import again by ID.
There is no need to run agit init again for a repository that already exists.
Choose an import’s starting point
An imported conversation may be independent or may continue earlier saved context. Inspect local evidence before choosing a base when that relationship is unclear. Use the full native session ID and its actual runtime:
agit import SESSION_ID --from codex --into alice/my-project@imported-task \
--propose-lineage --json
This is a read-only local report, without fetching missing remote history or adopting the session. Candidate evidence can establish a matching saved prefix; it does not prove the external runtime’s actual Git ancestry. Missing or incomplete evidence does not prove that the conversation is independent.
After reviewing the report, choose one of these alternatives:
agit import SESSION_ID --from codex --into alice/my-project@imported-task --onto SAVED_COMMIT
agit import SESSION_ID --from codex --into alice/my-project@imported-task --independent
Replace SAVED_COMMIT with the verified frozen commit from the report. Run only
the alternative you intend. --onto selects a base in the destination Agent
repo; --independent imports without selecting a prior session base. These
options still enforce ownership, branch claims, and transcript integrity.
Without an explicit lineage decision, a new import asks in an interactive
terminal. In an agent shell, JSON mode, a pipe, or CI it returns exit code 8
and explicit actions to review; --yes does not select one. The interactive
choice defaults to cancellation. Repeating an import into the same active,
explicitly selected claim remains idempotent.
Local candidate inspection requires Git’s NUL-framed worktree output, normally
available in Git 2.36 or newer. Upgrade Git if the report says
git_worktree_format is unavailable. The explicit import paths retain their
ordinary checks.
Open a saved source
Use run when you have a saved branch, tag, or historical turn and want
AgentGit to choose between continuation and a new fork:
agit run alice/my-project@first-task
agit run 'alice/my-project@first-task#3' -b alternative --as codex
The @first-task#3 selector names the declared turn on that session branch.
Include the branch because a repository can contain many sessions. The Hub’s
turn copy button uses this syntax when the historical ordinal is verified and
keeps a version ID when the mapping is unavailable.
A writable, unsealed session branch head can resume; other saved conversation
points fork. Use --mine explicitly when you want a copy in your Hub namespace.
--no-launch prepares the
local session without starting its runtime, and requires a branch name when a
noninteractive operation needs to fork. It is a mutation, not a preview.
Keep reusable project memory
agit memory status --into alice/my-project@first-task
agit memory diff --into alice/my-project@first-task
Review session knowledge before promoting it to main with agit memory distill.
See Shared memory for the runtime collection boundaries and how
to publish reviewed files for a new conversation.
To continue from another device, follow Remote Control to pair the machine and open its workspace in a browser.
Publish and sync
First save the latest turns with agit commit. Then preview and publish
the selected branch:
agit push alice/my-project@first-task --private --dry-run
agit push alice/my-project@first-task --private
--dry-run runs the local checks and shows the proposed upload without
publishing. --private chooses private visibility when creating the remote
repository. Use --public if you want anyone to read the history. These
flags do not change the visibility of an existing remote repository.
Push scans the outgoing history for secrets. If it stops, follow the reported reason before publishing. See Sharing and collaboration for visibility, collaborators, and share links.
To bring back updates from the Hub:
agit pull alice/my-project@first-task
Pull fetches remote history and advances the local branch only when it can fast-forward. If both sides have new commits, it keeps them and reports the divergence. Follow the suggested merge or fork workflow.
When something needs attention
If the import picker still considers a closed conversation active, see troubleshooting for its wait and refresh procedure.
Run agit status to check identity and context, then agit doctor to check
local integrity and runtime support. agit doctor --check-backend also
checks connectivity to the Hub.
For a command’s arguments, use agit <command> --help. The
command reference groups the rest by task.