Get started
Set up your coding agent
Your coding agent knows gh and GitHub, but not src or the features that only the forge has. One prompt installs src, logs you in, and teaches your agents to use it.
7 min read
The features that only the forge has are CI secrets for each CI environment, the vault, assets, agent sessions and the factory. After the login, your agent gives itself:
- the TanStack Source skill,
- the instructions to use
srcin place ofgh, - the hooks that upload your transcripts.
You need:
- Node.js 22 or later on your computer.
- Claude Code, Codex, Cursor, OpenCode, Gemini CLI or GitHub Copilot CLI.
Tip
Do you install from a terminal? See Set up your agents from a terminal.
1. Copy the setup prompt
Open the home page signed out, and copy the prompt on the Agent tab. Or copy it here:
Set up TanStack Source (https://gitflare.t-zlak97.workers.dev) for me:
1. Install its CLI, src: `curl -fsSL https://gitflare.t-zlak97.workers.dev/install | sh`, or in Windows PowerShell `irm https://gitflare.t-zlak97.workers.dev/install.ps1 | iex`. It needs Node.js 22 or later.
2. Run `src auth login --web --hostname gitflare.t-zlak97.workers.dev`, with the path that the installer printed if src is not on the PATH yet. Show me the code and the URL, and wait while I approve in the browser. Then run `src auth setup-git`.
3. Run `src agent setup`. It gives my coding agents the TanStack Source skill, the instructions to use src instead of gh, and the hooks that upload our transcripts to my pull requests. Show me each note it prints, such as a step to trust the hook in Codex or to restart an agent.

2. Paste it into your agent
Paste the prompt into your agent. The agent runs the three steps of the prompt.
3. Approve the login
The agent shows you a one-time code and a URL, and your browser opens the URL.
- If the forge asks, sign in.
- Type the code that the agent showed you, and click Continue.
- Click Approve.
Note
The page never takes the code from the URL. So a link from someone else cannot log in their program as you.
The agent then runs src auth setup-git, so that git push uses the same login. Then it runs src agent setup, which also installs the transcript upload hooks for this forge. Each pull request of your agent then shows why you made it. See Share the why of a change.
The login prints To upload your agent transcripts to pull requests, run: src agent setup when an agent on your computer has no upload hook yet. The next step of the prompt runs that command.
Done
Start a new session of your agent. Before it acts on a forge, it checks the repository with src repo view:
- When the repository exists on TanStack Source, the agent uses
srcand notgh:src pr create,src issue list,src secret set,src vault pull. - When it does not, for example a repository that is only on GitHub, the agent keeps using
ghand git.
The agent reads the skill when it needs a command or a feature that it does not know yet.
Next, connect your coding agent: it gets its own short-lived token for one repository. Or switch from GitHub to move your repositories, CI and team.
Later: update or remove
- To update the skill and the instructions, run
src update, or run the install command again. When your agents were set up before, both update what setup added before, with no question. - When the new version has something new to add, such as a hook or an instruction block that is not there yet, it lists the new changes and asks
Make these changes?. The default answer is No. If you say no, it printsSkipped. Run src agent setup to add them later. src agent setupalso lists the new changes and asks first, with Yes as the default answer. To make them with no question, add--yes.- To remove them, run
src agent setup --remove. It removes the skill, the links, the blocks, the workspace hooks, the link handler and the transcript upload hooks. It also deletes a file that held only the block. Add--no-transcriptsto keep the transcript upload hooks.
What the setup changes
The skill goes to ~/.agents/skills/source. It is one short SKILL.md, with a reference file for each part of the forge, which the agent reads only when it needs it.
| Agent | The skill | The instructions |
|---|---|---|
| Claude Code | A link in ~/.claude/skills | ~/.claude/CLAUDE.md |
| Codex | Reads ~/.agents/skills | ~/.codex/AGENTS.md, or AGENTS.override.md when that file has text |
| GitHub Copilot CLI | Reads ~/.agents/skills | ~/.copilot/copilot-instructions.md |
| Gemini CLI | Reads ~/.agents/skills | ~/.gemini/GEMINI.md |
| OpenCode | Reads ~/.agents/skills | ~/.config/opencode/AGENTS.md, or ~/.claude/CLAUDE.md when OpenCode has no AGENTS.md |
| Cursor | Reads ~/.agents/skills | None: Cursor has no instruction file outside a project |
- Only the agents that are on your computer get the instructions: setup looks for their config folders.
CLAUDE_CONFIG_DIR,CODEX_HOME,COPILOT_HOMEandXDG_CONFIG_HOMEmove the folders, as they do for the agents. - The instructions are one block between two marker lines. Setup keeps the rest of each file, and writes through a file that is a link.
- Setup never replaces a folder that holds another skill. It stops and names the folder.
The transcript upload hooks
When you are logged in, setup also installs the transcript upload hooks of Claude Code, Codex, Cursor and OpenCode. It installs them for each forge that you are logged in to. Your agent then uploads its conversation to the pull request.
- Without a login, setup installs no hook. It tells you to run
src auth login, thensrc agent setupagain. --dry-runlists the hooks that a setup run installs.--no-transcriptssets up the skill and the instructions only, and leaves the hooks as they are.
The workspace hooks of Claude Code
Claude Code makes a git worktree for claude --worktree, for a subagent with isolation: "worktree" and for a background session. Each worktree needs its own install of your dependencies, and stays on your disk.
When Claude Code is on your computer, setup adds two hooks to ~/.claude/settings.json. They need no login.
| Hook | What it runs | What it does |
|---|---|---|
WorktreeCreate | src ws hook claude-create | Makes a workspace from HEAD, with the name of the worktree, and gives Claude Code its folder |
WorktreeRemove | src ws hook claude-remove | Runs src ws close on that workspace: it saves a checkpoint and runs the trusted teardown hook. Then it gives the folder to the pool of ready workspaces, or deletes it when the pool is off |
How the hooks behave:
- The folder is a slot, for example
ws-1. Its name is not the name of the worktree. Claude Code gets the path from the hook. - Setup adds the hooks to the lists that your settings have, and keeps your other settings and hooks.
- If your settings have a
WorktreeCreatehook of your own, setup adds no workspace hooks. Your hook makes the worktrees. - The hook also works in a repository where you never ran
src ws init. It tests copy-on-write, and makes no disk image. If copy-on-write is not available, it copies the files. --no-workspace-hooksadds no workspace hooks, and removes the ones that setup added.
OpenCode gets tools for workspaces in the plugin of its transcript upload hook: src_ws_create, src_ws_exec, src_ws_list, src_ws_diff, src_ws_checkpoint and src_ws_close. Setup installs that plugin when you are logged in. Codex, Cursor and the other agents use src ws commands. See Use workspaces with a coding agent.
The link handler of Send to my agent
The Send to my agent button opens a tanstack-source:// link, and your computer must know that src opens it. Setup registers src for these links. It needs no login and no admin rights.
| OS | What setup writes |
|---|---|
| Windows | The key HKCU\Software\Classes\tanstack-source |
| macOS | A small app, ~/Applications/TanStack Source Link.app, which runs src in Terminal |
| Linux and other desktops | ~/.local/share/applications/tanstack-source-link.desktop (under XDG_DATA_HOME when it is set), made the default with xdg-mime |
- When the handler is there already, setup changes nothing.
- If setup cannot register the handler, it prints the error, and the rest of the setup goes on.
--no-linksleaves the handler as it is.
See Send to your agent.