Let the agent work on your code

Use this when an agent reads or changes code other than its own recipe.

You need: an organization owner or admin for step 1; any signed-in member for the rest.

1. Install the GitHub App

On the organization’s Integrations page, select Connect on GitHub, install the Introspection GitHub App, and choose which repositories it may see. An organization has one installation.

2. Register the repository

introspection repositories add acme/api-service

The recipe’s own repository is registered when you create its runtime. One repository can be registered in several projects.

3. Grant the runtime access

name: coding-agent
path: apps/coding-agent
runtime:
  github:
    repositories:
      - acme/api-service
    permissions:
      contents: write
      pull-requests: write

Run introspection check, then merge to ship a new version.

• Without permissions, the grant is read-only.
• permissions accepts contents, pull-requests, issues, checks, statuses, deployments, and discussions. Anything else, such as workflows, administration, or actions, is refused.
• An unregistered repository grants nothing.

4. Clone it into a task

introspection tasks create --runtime coding-agent -e staging \
  --repository acme/api-service@main \
  --prompt "Fix the flaky checkout test and open a pull request"

--repository OWNER/NAME[@REF][:DEPTH] is repeatable. REF is a branch, tag, or full 40-character SHA; :0 clones full history. The checkout lands in /workspace/repos/<name>. Without --repository, the agent can still git clone a granted repository itself.

5. Push and open a pull request

Inside the task, git and gh authenticate automatically with a short-lived token for one repository:

cd /workspace/repos/api-service
git checkout -b fix/flaky-checkout-test
git commit -am "Fix flaky checkout test"
git push -u origin fix/flaky-checkout-test
gh pr create --fill

For other tools, wrap them: with-github-token --repo acme/api-service -- ./scripts/triage.mjs.

Let an agent improve its own recipe

Granting the recipe’s own repository with contents: write lets the agent change its own prompts and tools. First turn on required-review branch protection and pin production: with neither, a prompt injection that rewrites the instructions can reach production and persist. Granting a monorepo also grants the recipe inside it.

Verify

introspection repositories list shows what is registered. Read a task’s conversation to confirm the clone and push succeeded.

Limits

Or ask your agent: “Give coding-agent write access to acme/api-service and test it in staging.”