Coding agents

Claude Code plugin

Install g1t's plugin for Claude Code, which records your sessions on g1t, gives Claude the issue's work context, and adds g1t's MCP server, skills and commands. What each hook records and never records, and how to opt out.

g1t’s plugin for Claude Code connects the sessions you run on your own machine to the work on g1t. With it installed, working in a g1t repository:

each Claude Code session is recorded on g1t as a session, titled with what you asked for and attached to its issue and pull request, so the people and agents also working there can see it, issue or not;
Claude starts each session knowing the issue it is on: its definition of done, who has claimed it, its pull requests and what blocks it;
Claude has g1t’s MCP tools, three skills for working on issues, and the commands /g1t:claim, /g1t:status and /g1t:handoff.

Your session runs where it always does. g1t keeps the record and the coordination; nothing about how Claude Code runs changes.

Install

You need Claude Code, the g1t CLI 0.3.2 or later, which the plugin’s hooks use, and Node 18 or later on your PATH, which runs them. Claude Code’s native installer does not bring Node with it: run node --version to check, and install it from nodejs.org if it is missing or older.

Install the g1t CLI and sign in, if you have not:
```
curl -fsSL https://g1t.sh/install | sh
g1t auth login
```
On Windows, irm https://g1t.sh/install.ps1 | iex installs it.
Add g1t’s plugin marketplace and install the plugin:
```
claude plugin marketplace add https://g1t.sh/flagon-io/g1t.git
claude plugin install g1t@g1t
```
Or run /plugin inside Claude Code and choose the marketplace there.
Start Claude Code again, run /mcp and choose plugin:g1t:g1t to sign g1t’s MCP server in through your browser.

The plugin adds g1t’s MCP server itself. If you added it before with claude mcp add … g1t https://mcp.g1t.sh, remove that one (claude mcp remove g1t), or Claude sees every g1t tool twice.

curl -fsSL https://g1t.sh/install/claude.sh | sh prints the same commands; add -s -- --cli to have it install the CLI too.

The plugin works in any working copy whose git remote is on g1t.sh, or on the host in G1T_HOST for a self-hosted g1t. Everywhere else its hooks do nothing.

What it records

The plugin’s hooks call the g1t CLI, signed in as you, so a session is recorded as yours and is as visible as the repository it is in.

When	The hook runs	What g1t receives
A session starts or resumes	`g1t session start --harness claude_code --harness-session-id ID`	A session for this Claude Code session. Starting the same session again, as a resume does, finds it rather than making another.
You send a prompt	`g1t session log --kind prompt TEXT`	Your prompt’s first 2,000 characters.
You send the session’s first prompt that is not a slash command	`g1t session heartbeat --json`, then, if the session has no title, `g1t session attach --title INTENT`	Its title: what the prompt is for, as its first line or sentence without code blocks or markdown, up to 80 characters, cut on a word with `…`. A title the session already has (one Claude, you or an earlier prompt set) is never replaced. Not sent with prompts kept back.
Claude uses a tool	`g1t session log --kind tool_call TEXT`	The tool’s name and one line on what it was called with: the command, file, pattern or address, up to 200 characters, with anything that looks like a token or password replaced by `…`.
Claude uses a skill, or you run one (`/g1t:work-on-issue 42`)	`g1t session log --kind skill NAME`	The skill’s name, nothing more, once in a turn. A plugin’s skill or command you type as `/plugin:name` is recorded even with prompts kept back.
Claude writes a file, makes a branch or a commit, or claims an issue	`g1t session touch --file PATH` (or `--branch`, `--commit`, `--issue`)	What it touched: the path from the repository’s root, the branch, the commit, the issue. g1t ties the session to the pull requests and issues these lead to, and tells two sessions that touch the same file.
A `git push` reaches the remote	`g1t api update_session -f id=ID -f head_commit=SHA` and `g1t session touch --commit SHA --branch BRANCH`	The commit you pushed and its branch, so the session’s entries line up with the code and it is tied to the branch’s pull request.
Claude starts a subagent	`g1t session start --parent SESSION --agent-type TYPE --task TASK --prompt PROMPT`	A session of its own for the subagent, under this one, with its kind and the task it was given (its prompt’s first 4,000 characters). See Subagents.
A subagent finishes	`g1t session end --result MESSAGE`	Its final message, up to 8,000 characters: what it reported to Claude.
Claude finishes a turn	`g1t session heartbeat`	That the session is still active, which also renews its claims.
The session ends	`g1t session end --reason REASON`	That it ended, and why: you exited, cleared it or logged out.

It never records:

what a tool returned: command output, file contents, search results and web pages are never sent (an Agent call’s answer is the one thing read, for its subagent’s final message and id), nor the turns Claude Code starts itself to hand Claude a background task’s output;
Claude’s replies or reasoning;
your files, environment or transcript.

A session that stops sending heartbeats reads as idle after 15 minutes and ended after two hours, so a closed laptop does not leave work looking claimed.

The hooks return at once: the CLI calls run in a background process, so a slow network never holds Claude up.

Shell commands are read the same way from the Bash tool and, on Windows, the PowerShell tool: a git commit, a git push, a branch made or a g1t work claim in either is recorded.

Once the session has started, the plugin sets G1T_SESSION for the commands Claude runs (through Claude Code’s session environment), so Claude’s own g1t commands act in this session even when another session works in the same working copy. A command run before the session’s id arrives, in its first second, uses the working copy’s session.

The context Claude starts with

When a session starts, the plugin looks for the issue it is working on: the one the session claimed earlier, or a number in the branch’s name (42-fix-login, issue-42, fix/42). If it finds one, it runs g1t work context N and gives Claude the answer: the issue and its definition of done, its claims and sessions, its pull requests with their checks and overlaps, what blocks it and what it blocks, the decisions recorded on it and the last integration failure. If the answer takes longer than a second, Claude is told to load it itself.

With no issue in sight, Claude is told that the session is already recorded on g1t and shows to the team with what it is for, so it can just work; see Work with no issue yet.

Claude is also told to put the trailer G1t-Session: $G1T_SESSION on the commits it makes, so g1t ties them, and the pull request they land in, to the session.

A session started from a hand-off (Start a session without an Anthropic connection, or g1t work dispatch N --handoff) runs as G1T_ISSUE=N claude '…': the plugin attaches it to issue N as it starts.

Work with no issue yet

Most sessions start from a question or a request, not an issue, and most never need one. The session is the record of that work:

It is titled with what it is for. At the session’s first prompt that is not a slash command (/clear and /g1t:status are not), the plugin gives the session a title from it, unless it has one. To name it yourself, or have Claude name it, run g1t session attach --title "Fix the preview builds"; that replaces the title the prompt gave.
It shows to the team. The project’s overview and its Work page list it in Live now under its pull request, else its branch, else under No branch yet, with who it is for, Claude Code, its state, when it was last heard from and its branch.
It gets an issue when it becomes a change others should know about: a branch to push, a pull request. Claude is told to look for an issue first (g1t work list, g1t issue list) and claim it with g1t work claim N, and if there is none, to open one and claim it in one step:
```
g1t work claim --title "Preview builds time out on large repositories"
```
The issue is opened, claimed for this session, and the session is attached to it, so Live now lists it under the issue from then on. Claude is told never to open issues for questions, exploration or trivial fixes. /g1t:claim with a title instead of a number does the same.

Subagents

Each subagent Claude Code starts is recorded as a session of its own, under the session that started it, so if Claude hands parts of an issue to twelve subagents, g1t shows twelve sessions and they see each other.

When it starts (SubagentStart), the plugin starts its session with the parent’s session as --parent, its kind (Explore, your own subagents’ names) and the task Claude gave it: the description and prompt of the Agent call, kept from the moment Claude made it (PreToolUse). The subagent is told it has a session of its own, to look at its siblings with g1t session list --issue N --subagents before changing anything, and to claim only what it takes.
While it works, what it does is recorded in its own session, not its parent’s: its tool calls, the skills it uses and the files it touches. Its g1t commands and g1t MCP claims act as its own session: the plugin sets G1T_SESSION for its shell commands and session_id for its claims. Each subagent’s claim is its own, so siblings see each other’s, and when two touch the same file both are told (overlap.detected).

A subagent shares its parent’s shell environment, so the plugin sets its session on each of its commands that runs g1t or names G1T_SESSION, as Claude Code lets a PreToolUse hook do: the command runs with export G1T_SESSION=ses_…; before it in Bash, or $env:G1T_SESSION='ses_…'; in PowerShell. The plugin makes no permission decision: Claude Code checks your permission rules against the command as it runs, with that prefix, so a rule such as Bash(g1t work claim:*) may no longer match it and Claude Code asks instead. Other commands are left as Claude wrote them, and the session records each command as Claude wrote it.
When it finishes (SubagentStop), its session ends with its final message as its result. A background subagent’s, or a late hook’s, order does not matter: starting a subagent again finds the same session, and an ended one stays ended.

Subagents use g1t’s MCP tools as Claude does: Claude Code gives a subagent the MCP servers of the session that started it, including the plugin’s g1t server, unless the subagent’s own definition leaves them out.

Skills

Claude uses a skill when the task matches it, or you can run one by name.

Skill	What it does
`/g1t:work-on-issue N`	Loads the issue’s context, claims it, makes a branch named for it, opens a draft pull request early with `g1t pr create --issue N --draft`, does the work, watches the checks and merges, or adds the pull request to the merge queue.
`/g1t:fix-integration N`	For a pull request the merge queue failed together with others: reads the `integration.failed` event and the failing check, compares the other pull requests in the combination, fixes, pushes and queues it again.
`/g1t:coordinate N`	Follows the issue’s events in the background with `g1t work events --follow --issue N`, and acts on another claim, an overlapping pull request, a change to what blocks it or an integration result as it happens.

Commands

Command	What it does
`/g1t:claim N [note]`	Loads issue N’s context and claims it for this session, telling you who else holds a claim. With a title instead of a number (or nothing), looks for an issue that covers the work in hand, and opens and claims one with `g1t work claim --title` if there is none.
`/g1t:status`	This session (its title, issue, branch or pull request), and the repository’s active claims and sessions.
`/g1t:handoff N [@login]`	Pushes what is unpushed, writes a hand-off note and hands the issue off, to anyone or to one person.

A claim says you are working on an issue. It is never a lock: a second claim is allowed, and whoever makes it is told about the first.

When the CLI is missing, signed out or out of date

If g1t is not installed, not signed in, or older than 0.3.2 (the oldest that takes every command the hooks run), the hooks record nothing and Claude Code says so once. The plugin never installs anything itself. Install the CLI or run g1t auth login, and the next session is recorded.

To update the CLI, run its installer again:

curl -fsSL https://g1t.sh/install | sh

On Windows, irm https://g1t.sh/install.ps1 | iex. g1t --version says which you have. A CLI that refuses a command the hooks send is taken as out of date, and said the same way.

The hooks run on Node. Without Node 18 or later they record nothing: with an older Node, Claude Code says so once; with no node on your PATH at all, Claude Code shows each hook’s failure (node: command not found) as a hook error. Install Node, or turn the plugin off until you do.

Opt out

To	Do
Not send prompts	Set `G1T_RECORD_PROMPTS=0` in the environment Claude Code runs in.
Not record anything	Set `G1T_RECORD=0`.
Turn the plugin off for now	`claude plugin disable g1t@g1t`
Remove it	`claude plugin uninstall g1t@g1t`

To set one of these for every session, put it under env in Claude Code’s settings, for example in ~/.claude/settings.json:

{ "env": { "G1T_RECORD_PROMPTS": "0" } }

A recorded session can be read on its own page, linked from the issue, the pull request’s Session tab and the repository’s Work page: who ran it, its subagents as a tree, the skills used, what it touched, and the issues and pull requests it worked on.

The earlier hook installer

An earlier curl -fsSL https://g1t.sh/install/claude.sh | sh added a hook of its own, node ~/.g1t/hook.mjs, to ~/.claude/settings.json. The plugin replaces it. Once the plugin is installed, remove those entries from ~/.claude/settings.json so a session is not recorded twice. Running the installer again brings the old hook up to date and prints the plugin’s commands.

Other coding agents

Agents without plugins use the same CLI commands from their instructions file. Put this in the repository’s AGENTS.md:

## Working on g1t

This repository is on g1t. Other agents and people may be working in it at
the same time; the `g1t` CLI is how you see them and how they see you.

- When you start, record a session titled with what you were asked to do:
  `g1t session start --harness codex --title "Fix the preview builds"`
  (or `cursor`, `copilot`, `other`: the harness you are). The CLI remembers
  it for this working copy. Run `g1t session heartbeat` every few minutes
  while you work, and `g1t session end` when you stop.
- With no issue, just work: the session shows to the team. When the work
  becomes a change others should know about (a branch to push, a pull
  request), look for its issue (`g1t work list`, `g1t issue list`) and
  claim it; if there is none, open and claim one with
  `g1t work claim --title "TITLE"`. Never open issues for questions,
  exploration or trivial fixes.
- Before working on an issue, load it with `g1t work context N`: its
  definition of done, who has claimed it, its pull requests, checks and
  overlaps, and what blocks it. Then claim it with
  `g1t work claim N --note "what you are about to do"`. If someone else
  holds a claim, say so before going on.
- Work on a branch whose name starts with the issue number
  (`42-short-description`), and open a draft pull request early:
  `g1t pr create --issue N --draft --fill`.
- Log decisions worth keeping with `g1t session log --kind note "TEXT"`.
  Never log secrets or command output.
- Run the repository's tests before each push, and watch the checks with
  `g1t pr checks --watch --fail-fast` (and `g1t run logs --failed` for why
  one failed). When the merge queue reports an integration failure, read
  it with `g1t work events --type integration.failed --issue N`, diff the
  other pull requests in the combination (`g1t pr diff OTHER`), fix, push
  and merge again.
- If you stop before the issue is done, hand it off:
  `g1t work handoff N --note "what is done, what is left"`.

The same text is in the g1t repository at plugins/other-harnesses/AGENTS.snippet.md.

To give Codex g1t’s MCP tools as well:

codex mcp add g1t --url https://mcp.g1t.sh
codex mcp login g1t

or, in ~/.codex/config.toml, with a token in G1T_TOKEN instead of signing in through the browser:

[mcp_servers.g1t]
url = "https://mcp.g1t.sh"
bearer_token_env_var = "G1T_TOKEN"

Connect a coding agent covers Cursor, OpenCode and other MCP clients.