Agentic mode
This page explains agentic mode: the roadmap that makes Golf fast enough, and easy enough to reach, for many coding agents to work in one repository at once. Read it to understand what will change and how people stay in control.
Agentic mode is being built on the Cloudflare-native deployment. The self-hosted (Forgejo) deployment does not have these features.
- Live on Cloudflare-native and measured on the hosted demo: concurrent Git with a branch-level push fence (AM-1), the Source API (AM-2), and scoped API tokens with the remote MCP endpoint
/mcp(AM-3). See Connect a coding agent. - Built, hosted verification pending: merges of diverged branches and squash, and the per-repository agentic mode setting with its landing policy (AM-4). Golf evaluates pull requests against the policy but does not land, queue or revert anything on its own yet.
- Being built: the lock-free landing queue (AM-4) and the agentic inbox (AM-5).
Status and the product ledger record what has shipped, with runnable evidence.
Why agentic mode
GitHub and GitLab were built for people pushing a few times an hour. Coding agents push, read and land changes continuously. On a forge designed for people, they wait on repository-wide write locks, need a full clone to read or change a file, and queue behind reviews built for human pace.
Golf does not need a new storage engine for this: on Cloudflare, Artifacts already keeps Git on Cloudflare’s storage. The limits are in Golf’s own control path, so that is where agentic mode works. The plan targets the Cloudflare-native deployment.
The target is at least 100 agents working in one repository without the forge or the reviewers becoming the bottleneck. Every speed change is measured before and after, and the numbers are recorded.
What changes
| Area | Before agentic mode | With agentic mode |
|---|---|---|
| Git traffic | Pushes to one repository wait for each other. | Clones, fetches and pushes overlap. Pushes to different branches proceed; only pushes to the same branch conflict. |
| Reading and changing code | Reads cover files, trees, commits, diffs and history, but changing code requires a clone and a push. | A Source API reads many files in one call and commits changes on the server, without a clone. |
| Agent access | People sign in through Cloudflare Access. Native Golf cannot issue API tokens, and MCP is a local, read-only server in the CLI. | Scoped API tokens and a remote MCP endpoint let coding agents work with the caller’s own authority. |
| Landing | Merging requires the target branch not to have diverged. There is no merge queue. | Changes land onto the current branch head with a three-way merge, without a global lock. Conflicts are listed by path. |
| Review | Each pull request is reviewed on its own. | An agentic inbox groups work in progress, ready to land and needing a person, with AI-written intent and risk summaries and batch approval. |
Golf stays Git throughout. There is no custom protocol or storage engine, and clients that speak Git keep working unchanged.
How people stay in control
Agentic mode is designed so that speed never removes a person from a decision that needs one.
- Per repository, off by default. Each repository turns agentic mode on separately, in Settings → Agentic mode (built; hosted verification pending).
- Landing without a person is a separate switch. It is also off by default, and applies only to changes whose paths all match the repository’s low-risk paths (for example, documentation or tests).
- Sensitive paths always need a person. A change that touches a path marked sensitive needs approval from a writer who is neither the author nor an agent. By default the sensitive paths are CI configuration (
.github/**,.forgejo/**,.gitlab-ci.yml),deploy/**and**/CODEOWNERS. - Required checks must pass. A change lands without a person only when every required check has passed.
- Automatic revert. If a required check fails on the base branch after an agent change lands, Golf will revert it, comment on the pull request and open an issue for the person who requested the work. The setting is on by default; the revert itself is still being built.
- Authority is rechecked on every write. Tokens are scoped to repositories, a read or write permission and optionally a branch pattern, and are always capped by the user’s current access.
Milestones
| Milestone | What it delivers | Status |
|---|---|---|
| AM-0 Measure | A speed bench that runs the same push, clone, fetch and read scenarios against a hosted or local deployment and records throughput, latency and status codes | Built. Hosted baseline and later runs recorded on the hosted demo. |
| AM-1 Concurrent Git traffic | Clones, fetches and pushes overlap; a branch-level push fence replaces the repository-wide one; unknown push outcomes settle automatically | Built and measured on the hosted demo. The next step is splitting writes per repository. |
| AM-2 Source API | Read many files and commit changes on the server without a clone, with an automatic merge when the branch moved | Built and measured on the hosted demo: commit, branch, files and tree routes on the AM-1 branch fence. |
| AM-3 API tokens and remote MCP | Scoped API tokens and a remote MCP endpoint for coding agents | Built and verified on the hosted demo with Claude Code. |
| AM-4 Landing at agent speed | Diverged and squash merges, the per-repository agentic mode setting and landing without a global lock | In progress. Built, hosted verification pending: diverged merges and squash with conflicts listed by path; the agentic mode setting and landing policy. Being built: the lock-free landing queue. |
| AM-5 Agentic inbox | A repository inbox for agent work, with intent and risk summaries and batch approval | In progress; not shipped. |
| AM-6 Budgets and later work | Per-token rate budgets, line-level merges, blame and exact text search | Later |
Measured on the hosted demo
Recorded on October 14, 2026 on the hosted demo with the speed bench (scripts/agent_speed_bench.mjs), against eight repositories at 20 seconds per step. Results are successes over attempts. The evidence is in docs/compatibility/evidence/agent-speed-20261014-hosted-*.json in the product repository.
Pushes to separate branches of one repository
| Workers | Baseline | After the first fix (#77) | After #82 to #88 |
|---|---|---|---|
| 16 | 0/32 | 0/80 | 48/48 |
| 64 | 0/64 | 0/128 | 93/93 |
In the baseline, two pushes racing on one branch left the repository's write fence set with nothing to clear it, so every later push was refused (412).
Pushes spread across repositories
| Workers | Baseline | After |
|---|---|---|
| 16 | 21/24 at 0.38 writes/s, p50 24 s | 48/48 at 2.19 writes/s, p50 7.6 s |
| 64 | 51/64, p50 76 s | 93/93 at 1.6 writes/s, p50 37 s |
Shallow clones under push load
| Cloners | Baseline | After |
|---|---|---|
| 16 | p50 19.6 s | p50 10.3 s, background pushes 39/39 |
| 64 | 62/166 (104 refused with 429) | 70/70, background pushes 75/75 |
Source API commits with an API token, no clone
| Mode | Workers | Result |
|---|---|---|
| A branch per writer | 16 | 48/48 at 1.85 commits/s, p50 8.3 s |
| A branch per writer | 64 | 61/93; 32 client timeouts at 60 s |
One shared branch (onStale: merge) | 16 | 13/63; 49 refused after 3 merge attempts |
Remote MCP. Claude Code was connected to the hosted /mcp with a golf_pat_ token limited to one repository and agent/*, with no Cloudflare Access headers. Using only MCP tools it read the repository, created a branch, committed a function with tests, opened a pull request and commented on it. A commit to main was refused by the branch scope. /mcp without a token, and the token on a browser route, both answer 401.
What the numbers show:
- Total throughput levels off near 2 writes/s for the deployment: the single Workspace object plus the provider. The next step is splitting writes per repository.
- On one shared branch, merges cannot keep up with 16 writers. AM-4's landing queue addresses that case.
- Not verified on hosted yet: diverged merges and squash, the agentic mode landing panel, and RPC reads (S5).
Connect a coding agent
On a Cloudflare-native installation, a coding agent reaches Golf with a personal API token:
- the remote MCP endpoint
POST <origin>/mcp; - the Source API,
POST <origin>/native/source/{commit,branch,files,tree}; - HTTPS Git,
<origin>/git/<owner>/<name>.git.
A token is refused everywhere else, including the browser UI.
Create a token
Open Settings → Developer → API tokens and choose New token. Choose:
- the repositories: a list, or all you can access;
readorwrite;- for write tokens, an optional branch pattern: an exact branch, or a prefix ending in
*such asagent/*; - an expiry from 1 hour to 90 days.
The secret (golf_pat_…) is shown once, with ready-to-paste setups. A token never has more access than you currently do, and changing your account's login, email or active state ends it. You can have at most 50 active tokens. Administrators can turn token use off with the API tokens and MCP feature policy.
For a writing agent, prefer a short expiry, selected repositories and an agent/* branch pattern, so its changes land through pull requests.
Add Golf to your client
Replace <origin> with the installation origin and <token> with the secret.
Claude Code:
claude mcp add --transport http golf <origin>/mcp --header "Authorization: Bearer <token>"
Codex (~/.codex/config.toml, with GOLF_API_TOKEN set to the token in the environment):
[mcp_servers.golf]
url = "<origin>/mcp"
bearer_token_env_var = "GOLF_API_TOKEN"
OpenCode (opencode.json):
{ "$schema": "https://opencode.ai/config.json",
"mcp": { "golf": { "type": "remote", "url": "<origin>/mcp", "enabled": true,
"headers": { "Authorization": "Bearer <token>" } } } }
Git:
git clone https://x:<token>@<host>/git/<owner>/<name>.git
A token in a clone URL is saved in .git/config. On shared machines, prefer a credential helper.
The Claude Code setup was verified on the hosted demo. The Codex and OpenCode snippets follow those tools' documented remote MCP settings but have not been run against Golf.
What the MCP endpoint offers
/mcp is a stateless Streamable HTTP MCP server that answers with JSON. It offers 11 read tools (repo_overview, list_tree, read_files, search_code, list_commits, compare, get_issue, list_issues, get_pull_request, pull_request_diff, pipeline_status) and 4 write tools (commit_changes, create_branch, open_pull_request, comment). Write tools are listed only for write tokens. Each tool runs through the same handlers as the web UI, so permissions, token scope, feature policy, branch rules and audit are the same.
If Cloudflare Access protects the whole hostname, the operator adds bypass (or service-auth) policies for /mcp, /native/source/ and /git/. Golf still requires Access on those paths for any request without a token.
Related pages
- Coding-agent accounts and agent usage describe agent features available today.
- Local MCP tools describes the CLI's local, read-only MCP server.
- Status records what has shipped.