| 1 | --- |
| 2 | title: Claude Code plugin |
| 3 | description: 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. |
| 4 | --- |
| 5 | |
| 6 | g1t's plugin for Claude Code connects the sessions you run on your own |
| 7 | machine to the work on g1t. With it installed, working in a g1t repository: |
| 8 | |
| 9 | - each Claude Code session is recorded on g1t as a |
| 10 | [session](/guides/why-blame/#sessions), attached to its issue and pull |
| 11 | request, so the people and agents also working there can see it; |
| 12 | - Claude starts each session knowing the issue it is on: its definition of |
| 13 | done, who has claimed it, its pull requests and what blocks it; |
| 14 | - Claude has g1t's [MCP tools](/reference/mcp/), three skills for working |
| 15 | on issues, and the commands `/g1t:claim`, `/g1t:status` and |
| 16 | `/g1t:handoff`. |
| 17 | |
| 18 | Your session runs where it always does. g1t keeps the record and the |
| 19 | coordination; nothing about how Claude Code runs changes. |
| 20 | |
| 21 | ## Install |
| 22 | |
| 23 | You need Claude Code, Node 18 or later (Claude Code runs on it) and the |
| 24 | [g1t CLI](/guides/cli/), which the plugin's hooks use. |
| 25 | |
| 26 | 1. Install the g1t CLI and sign in, if you have not: |
| 27 | |
| 28 | ```sh |
| 29 | curl -fsSL https://g1t.sh/install | sh |
| 30 | g1t auth login |
| 31 | ``` |
| 32 | |
| 33 | On Windows, `irm https://g1t.sh/install.ps1 | iex` installs it. |
| 34 | |
| 35 | 2. Add g1t's plugin marketplace and install the plugin: |
| 36 | |
| 37 | ```sh |
| 38 | claude plugin marketplace add https://g1t.sh/flagon-io/g1t.git |
| 39 | claude plugin install g1t@g1t |
| 40 | ``` |
| 41 | |
| 42 | Or run `/plugin` inside Claude Code and choose the marketplace there. |
| 43 | |
| 44 | 3. Start Claude Code again, run `/mcp` and choose **g1t** to sign g1t's |
| 45 | MCP server in through your browser. |
| 46 | |
| 47 | `curl -fsSL https://g1t.sh/install/claude.sh | sh` prints the same |
| 48 | commands; add `-s -- --cli` to have it install the CLI too. |
| 49 | |
| 50 | The plugin works in any working copy whose git remote is on g1t.sh, or on |
| 51 | the host in `G1T_HOST` for a self-hosted g1t. Everywhere else its hooks do |
| 52 | nothing. |
| 53 | |
| 54 | ## What it records |
| 55 | |
| 56 | The plugin's hooks call the `g1t` CLI, signed in as you, so a session is |
| 57 | recorded as yours and is as visible as the repository it is in. |
| 58 | |
| 59 | | When | The hook runs | What g1t receives | |
| 60 | | --- | --- | --- | |
| 61 | | 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. | |
| 62 | | You send a prompt | `g1t session log --kind prompt TEXT` | Your prompt's first 2,000 characters. | |
| 63 | | 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 `…`. | |
| 64 | | A `git push` reaches the remote | `g1t api update_session -f id=ID -f head_commit=SHA` | The commit you pushed, so the session's entries line up with the code. | |
| 65 | | Claude finishes a turn | `g1t session heartbeat` | That the session is still active, which also renews its claims. | |
| 66 | | The session ends | `g1t session end --reason REASON` | That it ended, and why: you exited, cleared it or logged out. | |
| 67 | |
| 68 | It never records: |
| 69 | |
| 70 | - what a tool returned: command output, file contents, search results and |
| 71 | web pages are never read or sent; |
| 72 | - Claude's replies or reasoning; |
| 73 | - your files, environment or transcript. |
| 74 | |
| 75 | A session that stops sending heartbeats reads as idle after 15 minutes and |
| 76 | ended after two hours, so a closed laptop does not leave work looking |
| 77 | claimed. |
| 78 | |
| 79 | The hooks return at once: the CLI calls run in a background process, so a |
| 80 | slow network never holds Claude up. |
| 81 | |
| 82 | ## The context Claude starts with |
| 83 | |
| 84 | When a session starts, the plugin looks for the issue it is working on: |
| 85 | the one the session claimed earlier, or a number in the branch's name |
| 86 | (`42-fix-login`, `issue-42`, `fix/42`). If it finds one, it runs |
| 87 | `g1t work context N` and gives Claude the answer: the issue and its |
| 88 | definition of done, its claims and sessions, its pull requests with their |
| 89 | checks and overlaps, what blocks it and what it blocks, the decisions |
| 90 | recorded on it and the last integration failure. If the answer takes longer |
| 91 | than a second, Claude is told to load it itself. |
| 92 | |
| 93 | With no issue in sight, Claude is told how to load and claim one. |
| 94 | |
| 95 | ## Skills |
| 96 | |
| 97 | Claude uses a skill when the task matches it, or you can run one by name. |
| 98 | |
| 99 | | Skill | What it does | |
| 100 | | --- | --- | |
| 101 | | `/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](/guides/merge-queue/). | |
| 102 | | `/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. | |
| 103 | | `/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. | |
| 104 | |
| 105 | ## Commands |
| 106 | |
| 107 | | Command | What it does | |
| 108 | | --- | --- | |
| 109 | | `/g1t:claim N [note]` | Loads issue N's context and claims it for this session, telling you who else holds a claim. | |
| 110 | | `/g1t:status` | This session, and the repository's active claims and sessions. | |
| 111 | | `/g1t:handoff N [@login]` | Pushes what is unpushed, writes a hand-off note and hands the issue off, to anyone or to one person. | |
| 112 | |
| 113 | A claim says you are working on an issue. It is never a lock: a second |
| 114 | claim is allowed, and whoever makes it is told about the first. |
| 115 | |
| 116 | ## When the CLI is missing or signed out |
| 117 | |
| 118 | If `g1t` is not installed, or not signed in, the hooks record nothing and |
| 119 | Claude Code says so once. The plugin never installs anything itself. |
| 120 | Install the CLI or run `g1t auth login`, and the next session is recorded. |
| 121 | |
| 122 | ## Opt out |
| 123 | |
| 124 | | To | Do | |
| 125 | | --- | --- | |
| 126 | | Not send prompts | Set `G1T_RECORD_PROMPTS=0` in the environment Claude Code runs in. | |
| 127 | | Not record anything | Set `G1T_RECORD=0`. | |
| 128 | | Turn the plugin off for now | `claude plugin disable g1t@g1t` | |
| 129 | | Remove it | `claude plugin uninstall g1t@g1t` | |
| 130 | |
| 131 | To set one of these for every session, put it under `env` in Claude Code's |
| 132 | settings, for example in `~/.claude/settings.json`: |
| 133 | |
| 134 | ```json |
| 135 | { "env": { "G1T_RECORD_PROMPTS": "0" } } |
| 136 | ``` |
| 137 | |
| 138 | A recorded session can be read on the pull request's **Session** tab. |
| 139 | |
| 140 | ## The earlier hook installer |
| 141 | |
| 142 | An earlier `curl -fsSL https://g1t.sh/install/claude.sh | sh` added a hook |
| 143 | of its own, `node ~/.g1t/hook.mjs`, to `~/.claude/settings.json`. The |
| 144 | plugin replaces it. Once the plugin is installed, remove those entries from |
| 145 | `~/.claude/settings.json` so a session is not recorded twice. Running the |
| 146 | installer again brings the old hook up to date and prints the plugin's |
| 147 | commands. |
| 148 | |
| 149 | ## Other coding agents |
| 150 | |
| 151 | Agents without plugins use the same CLI commands from their instructions |
| 152 | file. Put this in the repository's `AGENTS.md`: |
| 153 | |
| 154 | ```md title="AGENTS.md" |
| 155 | ## Working on g1t |
| 156 | |
| 157 | This repository is on g1t. Other agents and people may be working in it at |
| 158 | the same time; the `g1t` CLI is how you see them and how they see you. |
| 159 | |
| 160 | - When you start, record a session: `g1t session start --harness codex` |
| 161 | (or `cursor`, `copilot`, `other`: the harness you are). The CLI remembers |
| 162 | it for this working copy. Run `g1t session heartbeat` every few minutes |
| 163 | while you work, and `g1t session end` when you stop. |
| 164 | - Before working on an issue, load it with `g1t work context N`: its |
| 165 | definition of done, who has claimed it, its pull requests, checks and |
| 166 | overlaps, and what blocks it. Then claim it with |
| 167 | `g1t work claim N --note "what you are about to do"`. If someone else |
| 168 | holds a claim, say so before going on. |
| 169 | - Work on a branch whose name starts with the issue number |
| 170 | (`42-short-description`), and open a draft pull request early: |
| 171 | `g1t pr create --issue N --draft --fill`. |
| 172 | - Log decisions worth keeping with `g1t session log --kind note "TEXT"`. |
| 173 | Never log secrets or command output. |
| 174 | - Run the repository's tests before each push, and watch the checks with |
| 175 | `g1t pr checks --watch --fail-fast` (and `g1t run logs --failed` for why |
| 176 | one failed). When the merge queue reports an integration failure, read |
| 177 | it with `g1t work events --type integration.failed --issue N`, diff the |
| 178 | other pull requests in the combination (`g1t pr diff OTHER`), fix, push |
| 179 | and merge again. |
| 180 | - If you stop before the issue is done, hand it off: |
| 181 | `g1t work handoff N --note "what is done, what is left"`. |
| 182 | ``` |
| 183 | |
| 184 | The same text is in the g1t repository at |
| 185 | `plugins/other-harnesses/AGENTS.snippet.md`. |
| 186 | |
| 187 | To give Codex g1t's MCP tools as well: |
| 188 | |
| 189 | ```sh |
| 190 | codex mcp add g1t --url https://mcp.g1t.sh |
| 191 | codex mcp login g1t |
| 192 | ``` |
| 193 | |
| 194 | or, in `~/.codex/config.toml`, with a token in `G1T_TOKEN` instead of |
| 195 | signing in through the browser: |
| 196 | |
| 197 | ```toml |
| 198 | [mcp_servers.g1t] |
| 199 | url = "https://mcp.g1t.sh" |
| 200 | bearer_token_env_var = "G1T_TOKEN" |
| 201 | ``` |
| 202 | |
| 203 | [Connect a coding agent](/guides/bring-your-own-agent/) covers Cursor, |
| 204 | OpenCode and other MCP clients. |