gitstalk docs agents

Connecting agents live

Paste one line into your agent. Approve it once in your browser. From then on it pushes beans as you, and every change carries your name.

Install

Pick your agent. Each line adds Gitstalk to it and opens your browser to sign in (passkey or email code) and approve the session.

claude plugin marketplace add coop-collective/gitstalk-plugin && claude plugin install gitstalk@gitstalk && claude mcp login plugin:gitstalk:gitstalk

codex plugin marketplace add coop-collective/gitstalk-plugin && codex plugin add gitstalk@gitstalk && codex mcp login gitstalk

{ "mcpServers": { "gitstalk": { "url": "https://mcp.gitstalk.io/mcp" } } }
cursor-agent mcp login gitstalk

gemini mcp add --transport http gitstalk https://mcp.gitstalk.io/mcp
/mcp auth gitstalk

https://mcp.gitstalk.io/mcp

The same lines are on the sign-up page, Connect an agent. Signing up through your agent is the whole sign-up: a new address picks a handle in the browser.

What the plugin adds live

• /gitstalk:setup [owner/repo]: connects git on this machine. It lists the SSH keys it finds, you pick one, and you approve it once in a browser tab.
• A skill that teaches the flow: push a bean, take the next task, fix your own reds, never sleep-poll. Claude Code loads it on its own when origin is a Gitstalk host.
• /gitstalk:new [owner/]name: creates a repository for the directory you are in (private unless you say otherwise), connects it as origin and pushes your work as the first bean. The agent asks you first before a public repository or one in an organization.
• /gitstalk:host [url]: points the plugin and the setup script at another Gitstalk (self-hosted, local or staging).
• /gitstalk:bean-status [bean]: where a bean is, and what to do next.
• The MCP server, signed in with OAuth. See MCP tools and scopes.

Connecting git with /gitstalk:setup

› /gitstalk:setup acme/api
Which SSH key should Gitstalk use?
  1. 1Password agent   SHA256:Hq3…x9k   ssh-ed25519   ada@laptop
  2. ~/.ssh/id_ed25519 SHA256:Wm1…t4e   ssh-ed25519
  3. Make a new key for Gitstalk
› 1
approve: opened your browser (check the code and fingerprint match, then Add key)

Setup asks for the create scope too, so the key and its token may create repositories (with /gitstalk:new, or by pushing to a new address); untick it to keep the key to existing repositories. Because git over SSH is not public yet, setup also stores an HTTPS token (read and write, plus create when ticked; 90 days) in git's credential helper (your OS keychain where there is one) for the Gitstalk host only, and says so. It shows up under Tokens in Settings. On a machine without a browser it shows a code to enter on another signed-in device.

What an agent session looks like

Git does the work and MCP adds context. This is a typical run, shortened. Tool calls are in plain words.

› repo_status acme/api
  stalk and sprout heads, 2 beans in flight, nothing red
$ git push origin HEAD:refs/heads/bean/add-truncate
remote: gitstalk: new bean add-truncate received at 3f9a1c2: "Add truncate helper"
remote: gitstalk: pre-land check started: your change is merged onto the sprout…
› bean_wait acme/api add-truncate
remote: gitstalk: RED: add-truncate was not landed. Merged onto the sprout, these tests failed:
remote: gitstalk:   - test/format.test.js
remote: gitstalk: fix: git fetch origin sprout && git rebase origin/sprout
$ git fetch origin sprout && git rebase origin/sprout
# fix, commit
$ git push -f origin HEAD:refs/heads/bean/add-truncate
remote: gitstalk: LANDED: add-truncate passed its pre-land check and is on the sprout as 8d2e51b

The full flow, with every message, is in Git compatibility. If a push is refused or a verdict is confusing, look it up in Troubleshooting.

What can my agent do?

An agent never merges to the stalk, never answers a decision card and never changes repository settings. The full tool and scope tables are on MCP tools and scopes.

Credentials

Four kinds of credential exist. How to make, scope and revoke them is on Accounts, tokens and keys; this is just which one an agent uses.

No credential can push to the sprout or the stalk, and none can land a change: landing is the engine's job. Never paste a token into a chat or a remote URL.

Without the plugin: the setup script

Any agent, or you, can run the same setup from the web app. It needs only sh, curl, git and OpenSSH 8.0 or newer. Windows has setup.ps1 with the same subcommands (its options are written -Key, -AgentKey, -NoBrowser, -Public, -Start, -Description and -Reset).

curl -fsSL https://gitstalk.io/setup.sh | sh -s -- detect

For a compact version of the skill, paste AGENTS-snippet.md into a repository's AGENTS.md; Codex, Cursor, Copilot and Gemini CLI read it.

Containers and CI: environment variables

The start page's Env vars tab, and later Settings, Deploy tokens, make a deploy token and fill in this block, so git in a container needs no file and no prompt:

export GITSTALK_TOKEN=bsd_…            # a deploy token for one repository
export GIT_TERMINAL_PROMPT=0
export GIT_CONFIG_COUNT=1
export GIT_CONFIG_KEY_0='credential.https://<gitstalk host>.helper'
export GIT_CONFIG_VALUE_0='!f() { echo "username=x"; echo "password=$GITSTALK_TOKEN"; }; f'

Where each kind of variable goes (secrets, workflow variables, check variables) is on Environment variables.