Agents that change code#

You want a custom agent to do small chores in code. For example, it fixes the lint errors of a pull request and pushes the fix, or it opens a pull request for a typo that an issue reports.

Give the agent permissions: { contents: 'write' }. Then it gets the forge's tools that change a branch. The forge decides which branch each tool may change, not the agent.

You need admin access to the repository. Start with a working agent: see Custom agents.

1. Give the agent write permission#

import { defineFactory } from '@tanstack-source/ci'
import { forgeTools } from '@tanstack-source/ci/agent'
import { chat, defineAgent } from '@tanstack/ai'

export default defineFactory('house', {
  agents: {
    'fix-lint': {
      agent: defineAgent({
        name: 'fix-lint',
        description: 'Fixes the lint errors of a pull request, and pushes the fix.',
        run: (ctx) =>
          chat({
            adapter: ctx.forge!.model(),
            systemPrompts: [
              'Run the linter with run_command. Fix each error with write_file.',
              'Then push the fix with push_fix, and record the verdict "fixed" or "nothing-to-fix".',
            ],
            tools: forgeTools(ctx, ['run_command', 'write_file', 'push_fix', 'record_verdict']),
            messages: ctx.messages,
            ...ctx.forward,
          }),
      }),
      on: ['pull.opened', 'pull.pushed'],
      trigger: { on: 'label', label: 'fix-lint' },
      budget: { maxTokens: 200_000 },
      permissions: { contents: 'write' },
    },
  },
})

The label trigger makes it run only when a person adds the fix-lint label.

2. Save the file and see it run#

Save the file as in Save the file in the vault. Then add the fix-lint label to a pull request: its Factory panel shows the run, and the pull request gets a commit from the TanStack Source bot.

What the forge allows#

With permissions: { contents: 'write' }, the agent gets these tools:

Tool	What it changes
push_fix	The head branch of the pull request of the run, as the TanStack Source bot.
merge_base	The head branch of the pull request: it merges the base branch into it.
open_pr	A new branch factory/issue-<number>, with a pull request from it, for the issue of the run.

The forge checks each change, not the agent:

• push_fix and merge_base change a fork's branch only when the author of the pull request allows edits from maintainers.
• The commit lands only on the head commit that the agent read. If someone pushed in the meantime, the tool refuses, and the agent can try again.
• open_pr pushes only to factory/issue-<number>. The forge refuses a push to any other branch, and to the default branch.
• An agent without permissions: { contents: 'write' } does not get these tools.

Done#

Your agent fixes code on the pull request it runs on, or on its own branch for an issue, and nowhere else.