Set up with your agent

Set up Upstream from your coding agent. Copy for Codex copies the setup prompt immediately. Use the adjacent menu for Claude Code, OpenCode, or another agent. Choosing an option copies its prompt. These choices tailor the instructions; they do not change your agent's model.

The agent explains the choices, checks your project, connects your account, and verifies the result. You choose where your code lives and whether GitHub stays involved.

Choose your GitHub relationship

Choice	Primary repository	What happens
Keep GitHub primary	GitHub	GitHub Sync connects the repository and selected collaboration history.
Move to Upstream	Upstream	A verified migration changes the source of truth. GitHub remains a one-way mirror.
Copy once	Upstream for the new copy	Git history is imported. Later changes do not automatically synchronize.
Start fresh	Upstream	Create a native repository and push an existing local project or start a new one.

A Git import does not mean every GitHub setting, secret, issue or pull request is migrated. Review the selected backfill options and returned operation details. A migration cutover needs explicit approval.

Install and sign in

Use CLI 0.6.4 or newer. If already installed, run upstream update and confirm with upstream --version; your session is preserved. For a new installation, use the official CLI installation instructions, then run:

upstream auth login
upstream auth status
upstream agent tools

Approve the printed sign-in URL in your browser. Your agent never needs your password or a token pasted into the conversation. Check the download manifest: capabilities.agentProtocolVersion must be at least 1 for structured tools and MCP. The hosted catalog describes the server; upstream agent tools describes the installed binary. If the channel does not include these capabilities, reinstalling the same version will not add them. Use the installed CLI's documented commands or report the missing release.

If upstream --version is killed with signal 9/exit 137 or produces no version, stop before signing in or configuring Git. Report the version and platform at Support. Do not use a debugger, change quarantine attributes, re-sign the download or disable OS security. A failed executable also breaks Git's credential helper.

Upload an existing local project

An upload request already identifies the workflow. A project with no GitHub remote does not need a discussion about GitHub sync or mirroring. Discover the user's personal namespace after login with list_destinations; ask only about unresolved visibility or organization choices. Preserve uncommitted changes and existing remotes. Optional MCP configuration can wait until the repository task is complete.

On CLI versions whose help lists --wait:

upstream repo create college --workspace YOUR_NAMESPACE --visibility private --wait --json

Use the returned canonical slug and clone URL. College may become college; do not build a URL from the original argument. A timeout is pending work, not permission to create another repository. Resume with upstream operation wait OPERATION_ID --workspace YOUR_NAMESPACE --json. Read repository state through lifecycleStatus (also normalized to status by current CLI versions), and operation state through operation.status.

New repositories are empty and accept direct pushes to main. From an existing project, add the returned clone URL as a remote and push your branch to main. Change Requests are optional unless an administrator has enabled branch protection. Creating a repository does not upload your files: confirm the push succeeded and the remote main commit matches your local commit. Existing repositories may already have history; fetch and reconcile it without overwriting commits.

The CLI stores its session in the operating system credential store, with a restricted file fallback on headless machines. External agents use your signed-in identity and permissions. They do not acquire a separate agent identity through this connection. Revoke access in CLI sessions.

Structured tools from the terminal

printf '{}' | upstream agent call list_destinations --input -

Every tool accepts a JSON object from a file or stdin and returns a JSON data envelope. Run upstream agent tools for the exact installed schemas. The tools cover repositories, GitHub discovery and sync, imports, migration requests and approval, operation status, and Change Requests, including diffs, comments, reviews and version updates.

Create, import, sync and migration requests require an idempotency key. Keep the same key and body when retrying. Read operation status before reporting success. Use ordinary Git with the CLI credential helper for clone, fetch and push.

Connect an MCP client

For VS Code, Zed, Cursor and Windsurf, use the editor setup commands when the installed CLI lists setup in its help. These configure Git, editor actions and MCP together while preserving existing settings. Preview changes with upstream setup TARGET --dry-run --json. Use upstream doctor --json to diagnose the local connection.

After signing in, configure a local stdio MCP server:

{
  "mcpServers": {
    "upstream": { "command": "upstream", "args": ["mcp"] }
  }
}

This is the configuration shape used by clients that accept mcpServers. Use your client's documented equivalent and the absolute path to the binary when it is not on the client's PATH. Merge this entry into existing configuration. Do not replace other servers.

For an inspection-only connection, use ["mcp", "--read-only"]. The adapter omits write tools and rejects writes locally; your account's server-side permissions still apply. This is a local stdio integration, not a hosted MCP URL. Clients without local process support can use a terminal agent with the CLI.

Install the Upstream skill

The official skill teaches setup, GitHub choices, authentication, operation verification and the daily Change Request workflow. Save it in your agent's supported project skill directory as upstream/SKILL.md. Follow the links in the skill for detailed instructions. Existing project guidance stays in place.

For discovery, use the tool catalog, agent index, and Markdown versions of these docs under /.well-known/upstream/docs/{slug}.md.

Completion means verified

The agent should report the repository link, namespace, visibility, default branch, GitHub direction, and Git connection result. An accepted asynchronous request is not a completed import or migration. Missing GitHub authorization, provider availability or permissions should be reported with the exact next step.

CLI and MCP tools do not bypass repository permissions, migration approval, review policies or required checks. Workspace API tokens are not interchangeable with CLI sessions. Keep secrets out of prompts and use the normal browser approval flow.