upseamdocs Upseam home GitHub
Contents

// Tools

Set up with a coding agent

You can paste one line into Claude Code, Codex or another coding agent running in your repository:

Set up Upseam (a GitHub App) in this repository using its setup guide at <site>/src/agent-setup.md. Ask me before changing any file.

<site> is the address of the Upseam site, which is not published yet. The agent reads the setup guide at that address. The site itself will show the upseam init commands for each agent once the @upseam/cli package is published.

What the agent does

The guide makes the agent download and run nothing and never ask for a key in the chat. It:

  1. Lists the languages, the supported vendor SDKs (see Providers) and any OpenAPI or GraphQL contract files in the repository.
  2. Writes .github/upseam.yml only if you want internal contracts with their consumer repositories or ignore rules, the only two things the file holds, and shows you the file before committing it.
  3. Asks how fixes should be written: by the model you connect on the settings page, with nothing added to the repository, or by your own GitHub Actions with the upseam-generate workflow, with upseam/action pinned to a release commit and the model key in secrets you set yourself. See Connect a model.
  4. Lists what only you can do: install the GitHub App, open its settings, connect a model or choose Actions generation, and optionally connect Slack.

New repositories start in the ask mode. Generation in your GitHub Actions needs the first published release of upseam/action; until then the agent says so and offers the stored key.

The same flow as one command

upseam init runs the same steps locally, without a model. An agent without a terminal to answer questions previews first, shows you the result and writes only after you agree:

upseam init --dry-run --json
upseam init --yes

In a repository with no supported SDK and no contract, it says there is nothing to watch and writes nothing. --yes never overwrites an existing file (that needs --force), never commits or pushes, and never guesses consumer repositories: name them with --internal <spec>=<owner/repo>,.... npx downloads the package from npm, so the first run needs network access; upseam init itself makes no network calls. The @upseam/cli package is published with the first release.