Get Started with AgentGit — One Prompt to Save & Share a Session

Send the prompt above to the agent conversation you want to keep. Your agent installs AgentGit, saves that conversation as a private session, and replies with two links: one to open it and one to invite someone. Approve the sign-in if it asks. If this is the conversation’s first message, your agent may need one short follow-up before it can publish the completed turn.

If you are the agent: complete steps 1–9 in order, in the user’s project folder. Do not read other AgentGit docs or start other work until you have sent the user both links in step 8. Replace CAPS placeholders with real values.

1. Install or update

Install or refresh the latest CLI and its bundled skill:

npx -y create-agit@latest

If the user’s message has an Install command: line, run that command instead; it is the same installer.
The installer puts agit in ~/.local/bin and runs agit setup --yes. If agit is still not found or still reports the old version, use ~/.local/bin/agit in place of agit below.

Run agit --version to check the installed CLI before continuing.

2. Read the AgentGit skill

Read the whole skill file for the agent you are running in before you continue. Use it for command details, and keep following the order on this page.

Agent	Skill file
Claude Code	`~/.claude/skills/agit/SKILL.md`
Codex	`$CODEX_HOME/skills/agit/SKILL.md` (default `~/.codex`)
Cursor	`~/.cursor/skills/agit/SKILL.md`
OpenCode	`~/.config/opencode/skills/agit/SKILL.md`
OpenClaw	`$OPENCLAW_STATE_DIR/skills/agit/SKILL.md` (default `~/.openclaw`)
Hermes	`$HERMES_HOME/skills/agit/SKILL.md` (default `~/.hermes`)
WorkBuddy	`skills/agit/SKILL.md` under `$WORKBUDDY_CONFIG_DIR`, else `$CODEBUDDY_CONFIG_DIR`, else `~/.workbuddy-ai`

If the file is missing, run agit setup --yes and look again.

agit whoami --check --json

Exit code 0 means you are signed in; result.value.account is OWNER. Exit code 5 means you are not (or the saved sign-in has expired); exit code 6 means the Hub is unreachable, so check the network and retry. Then start a sign-in:

agit login --json

It exits with code 8 and returns result.value.authorization_url and result.value.complete_command. Send the URL to the user, ask them to sign in (or create an account) and approve access, and wait for their reply. Then run complete_command, a list of arguments, as one command:

agit login --hub HUB --complete STATE

HUB, STATE: the values in complete_command.
Exit code 8 again means approval is still pending: wait, then rerun the same command. Do not start a new sign-in unless the link has expired.
Finish signing in before step 4. A repo created while signed out is recorded under the owner local instead of the user’s account.

4. Find this conversation

Find this conversation’s session ID. Use the variable of the agent you are running in: another agent’s variable can be inherited from a parent process. For example, Codex started from Claude Code also sees CLAUDE_CODE_SESSION_ID.

Agent	`RUNTIME`	`SESSION_ID`
Claude Code	`claude-code`	`$CLAUDE_CODE_SESSION_ID` (not `CLAUDE_CODE_HOST_SESSION_ID`)
Codex	`codex`	`$CODEX_SESSION_ID` (or `$CODEX_THREAD_ID` if supplied by this runtime)
Hermes	`hermes`	`$HERMES_SESSION_ID`
WorkBuddy	`workbuddy`	`$CODEBUDDY_SESSION_ID`
OpenCode	`opencode`	this conversation’s ID in `opencode session list`
Cursor, OpenClaw	`cursor`, `openclaw`	no variable; see below

Without a variable, run agit status --check-missing --json and look for this runtime in result.value.unadopted.sessions. Open the candidate transcripts and pick the one that contains the user’s latest message in this conversation; for Cursor that is ~/.cursor/projects/*/agent-transcripts/SESSION_ID/SESSION_ID.jsonl. Never choose an entry just because it is the only entry or the newest. If you still cannot tell, ask the user, showing each candidate’s first message and time rather than its ID.

Then check whether this conversation is already saved:

agit status --json --limit 1000

If result.value.sessions.next_offset is not null, rerun with --offset NEXT_OFFSET until it is. If an entry in result.value.sessions.items has this session_id and a target, it is already saved. Use that target as OWNER/REPO@BRANCH and run agit repo info OWNER/REPO. If it warns remote info unavailable without saying the repo may not exist, stop and retry the lookup before committing or pushing. If its remote line ends in [public], step 6 would make this conversation public: ask the user to approve public publication before you go on. Then run agit commit OWNER/REPO@BRANCH and go to step 6.

5. Save it to an Agent repo

If result.value.bound_repo from step 4 is set, it is OWNER/REPO. Otherwise choose REPO: a short lowercase name based on the project folder; letters, digits, - or _, at most 64 characters. OWNER is the account from step 3. Check the repo:

agit repo info OWNER/REPO

If it warns remote info unavailable without saying the repo may not exist, the Hub could not be checked: retry, and never treat that as a free name. Then act on the first rule that matches:

The remote line ends in [public]: everything saved there is public. Ask the user whether to use it. If not, choose a new REPO and check again; if bound_repo is set, add --no-bind when you run agit init or agit clone below.
OWNER/REPO is bound_repo: use it.
There is a remote line: the user already has a Hub repo with this name. Choose a new REPO and check again, unless the user confirms that repo is for this project. Then use it, and if the local line says (missing), run agit clone OWNER/REPO first.
The local line shows a path: a repo with this name exists on this computer but is not bound to this folder. Ask the user whether it is for this project; if not, choose a new REPO and check again.

If no rule matches, the name is free. Create the repo; this also binds the project folder to it:

agit init REPO --private --auto-push=false

This keeps publication in step 6, after you have checked the destination.

Then import this conversation into it:

agit import SESSION_ID --from RUNTIME --into OWNER/REPO@BRANCH --independent

BRANCH: a short kebab-case name for what this conversation is about, such as fix-login-redirect. It must not start with agit-. If it is taken, choose another.
--independent is required when an agent runs the import.
If import says the session is already claimed on OWNER/REPO@BRANCH, it is already saved there: use that target, run agit commit OWNER/REPO@BRANCH, and go to step 6. Never pass -y or set AGIT_YES to claim it again.
If import exits with code 7 (the Hub does not let you push to the repo) or 3, or bound_repo’s owner is local, the bound repo is not the user’s. Choose the user’s own REPO, check it with the rules above, create it with agit init REPO --private --auto-push=false --no-bind, and import again.

6. Publish privately

The user’s request to save this conversation privately authorizes this publication. Supply --yes on the push command below; no additional user confirmation is needed for the private destination selected above. --private chooses a new repository’s visibility; it does not confirm publication or change an existing repository’s visibility.

First inspect the publication:

agit push OWNER/REPO@BRANCH --private --dry-run

Check the account, Hub, destination, visibility and snapshot summary. Continue if the preview succeeds. A first publication can instead report one of these initialization diagnostics:

a new destination needs an immutable repository identity before a session publication preview; publish without --dry-run to confirm its creation
session SESSION must be registered before a dry-run publication

SESSION in the second diagnostic is the saved session’s AgentGit ID. These diagnostics mean the ordinary push must create the destination or register the session before it can prepare the preview. For either exact diagnostic, continue the authorized publication with the command below. For any other error, follow the recovery instructions below or report the error; a nonzero exit code alone is not a reason to continue.

Keep the same account, Hub, target, saved history and visibility:

agit push OWNER/REPO@BRANCH --private --yes

The CLI creates or registers what is needed, prepares the preview and publishes with the supplied confirmation. If those inputs change, rerun the dry-run. Only continue to step 7 after publication succeeds. If it fails, see Push fails with a Hub error under If a step fails.

Secret detection and redaction run locally. Secret findings and unavailable privacy processing do not gate ordinary publication. Authentication, permissions, session authority and content integrity must still pass.
Use ordinary push for this workflow. --audit requires a human at an interactive terminal; --yes cannot complete that review.
If push says the branch has no settled turns yet, your prompt was the first message of this conversation, and a turn is saved only after it ends. Do not retry it now. Tell the user AgentGit is set up and ask them to send any short reply, such as “continue”. On that next turn, run agit commit OWNER/REPO@BRANCH, run this step again, and go on to step 7.

7. Get the links

agit repo invite OWNER/REPO@BRANCH --json

result.value.session_url is the session link. It opens this session.
result.value.url is the invite link. Whoever opens it signs in, accepts read-only access to the repository, and lands on this session. The link does not expire; the user can revoke it in the repository’s Settings → Invite by link.
If it says only repository owners can create invite links, the repo belongs to someone else: tell the user to ask an owner for an invite link. The session link is then the web: line at the end of agit show OWNER/REPO@BRANCH --max-chars 80.
If repo invite is not a recognized command even after step 1, do not keep reinstalling. Take the session link from that same web: line and tell the user they can create the invite link with the Invite button on the session page.

8. Report back

Send the user one short message in their language, for example:

Saved this conversation to AgentGit as a private session in OWNER/REPO.

Session link: SESSION_LINK
Opens this session. Only people with access to OWNER/REPO can see it.

Invite link: INVITE_LINK
Send it to a person or an agent. After they sign in, they get read-only access
to every session in OWNER/REPO and land on this one first, so they can continue
from it. The link doesn't expire. Revoking it in the repository's
Settings → Invite by link stops new joins; people who already joined keep
access until you remove them.

If the repo is public, say “as a public session” and “Anyone with the link can read it” instead. If step 7 made no invite link, leave that part out.

9. Offer automatic upload

Steps 1–8 saved one conversation. AgentGit can also save the folder’s next conversations by itself. Ask the user once, in their language, for example:

Do you want this folder's new conversations saved too? With automatic upload,
each new conversation in PROJECT_FOLDER and its subfolders[, and also
WORKTREES (git worktrees),] uploads to OWNER/REPO (private: only its members
can read it) automatically after each turn, in the same published form as this
one. Earlier conversations here stay as they are. You can turn it off any time
with `agit off` in this folder.

Wait for their next message.

PROJECT_FOLDER is the folder’s path, with your home folder written as ~.
Keep the bracketed part only if PROJECT_FOLDER is a Git repository’s main checkout and git worktree list shows other worktrees: WORKTREES are their paths, written with ~. Otherwise leave it out.
If the repo is public, say “public: anyone can read it” instead.
Run this only if the user says yes in this conversation:
```
agit on --repo OWNER/REPO
```
Add --public for a public repo. It replies FOLDER is on and names how to stop.
Anything else in their reply counts as no: an unclear answer or a change of subject. Then run agit off in the project folder so it stays off, and do not ask again for this folder.
If the output of a push in step 6 already asked you to put this question to the user, it is the same question: ask it once.

If a step fails

npx is not found: the installer needs Node.js 20 or later. Ask the user to install it from nodejs.org, then repeat step 1.
agit is not found: use ~/.local/bin/agit, or run export PATH="$HOME/.local/bin:$PATH".
agit repo invite is not recognized: the CLI is older than 0.2.5. Rerun npx -y create-agit@latest once; if that does not help, follow the fallback in step 7.
Sign-in is still pending: after the user approves, rerun the same complete_command. Start a new agit login --json only if the link expired.
Push says you are not signed in or credentials expired: run the agit login --json part of step 3, then push again.
Push reports an unsupported encryption format: keep the saved objects and report the error. Session-owner publications use account access and exact-version grants; repository viewing passwords cannot unlock or convert obsolete ciphertext.
Session-owner publication says account keys are unavailable: complete sign-in and retry. If provisioning still fails, report the service error before publishing.
Push asks for repository-creation or preview confirmation: follow step 6 and supply --yes on that push command. Do not set AGIT_YES globally; import uses confirmation for a different operation.
Push fails with a Hub error (for example remote error: HTTP 422, or it ends with publication did not complete; unconfirmed attempts may have taken effect): a line marked unconfirmed means the CLI sent that update but the Hub did not confirm it, so it may or may not have been applied. The conversation is still saved locally on OWNER/REPO@BRANCH. Rerunning the same agit push OWNER/REPO@BRANCH --private --yes is safe: it sends the same saved history to the same private destination. Retry it once. If it fails again with the same error, stop retrying, and do not change the repo, branch or visibility to get around it. Tell the user that AgentGit is installed and the conversation is saved on this computer, but its publication could not be confirmed, so you have no session or invite link to give them. Do not claim that nothing reached the Hub, and do not invent links. Give them, to report to whoever runs their Hub: the push command, its exit code, the complete error output, the output of agit --version, and the Hub URL. Once the cause is fixed, rerun step 6 and continue from step 7.
You do not know the session ID: ask the user which conversation to save. Do not guess.

After the links are sent

Read on only after step 9 is done. What you can do covers Multiplayer Mode for driving a live session with other people from a browser, handing sessions off, share links, secret protection, switching runtimes, and setting AgentGit up by hand.

This guide saves one conversation, and step 9 is how later ones in the same folder upload by themselves. Without agit on, the folder binding from agit init does not save sessions started with plain claude or codex; see Save every session in a project folder.