Setup

Everything in this clinic runs on the NMFS Openscapes JupyterHub. You do not need anything installed on your own computer. You need a GitHub account.

Get on the JupyterHub

  1. Log in to GitHub. The hub uses your GitHub account to let you in.

  2. Open https://nmfs-openscapes.2i2c.cloud/ . You should see the start a server page.

  3. You can accept the default image. Choose the 4 GB size and click Start. It can take a minute or two to start.

Once on the hub, run the setup script.

  1. In JupyterLab: File → New → Terminal.

  2. Run the workshop setup script in the terminal.

Choose the tool you are using for the clinic:

In a terminal, run:

~/shared/workshop/claude-agent-coders

The first time you run this, it will ask for your key that starts with sk-. You can find your key in ~/shared/workshop/agentcoders-keys.md (i.e. in the shared directory in your home directory).

First start Start in your home directory. cd ~. The first start will ask a few setup questions. Pick a theme. When it asks whether to trust this folder, say no (since you are not in a directory). This first setup is only to get Claude Code installed and your key saved. If Claude Code starts anyway, type /exit to close it.

Second and later start If you have already done a first start (at any point), then navigate to the directory you want to work in (cd directory-name) and then type claude-agent-coders or ~/shared/workshop/claude-agent-coders.

In the terminal, run the team launcher:

~/shared/agent-coders/agy-agent-coders

The launcher checks for the Antigravity CLI (agy), installs it automatically if missing, sets up your terminal PATH, adds auto-approved everyday commands to your settings, and configures safety guards.

On your first run, it will walk you through sign-in:

  1. When prompted with “Select login method”, choose/accept “Continue with Google Cloud”.
  2. Look for the link in the terminal: click “click to authenticate” (or copy and paste the URL into your browser).
  3. Sign in with your Google account, click through the authorization prompts, and copy the authorization code.
  4. Return to the terminal and paste the code.
  5. Note, it is going to say you have no license. That is ok and correct. You are using pay-as-you-go (except NMFS is paying not you).
  6. When prompted for your Google Cloud project code, paste the project code provided to you (from Jira or your organizer).
  7. When prompted with “Accept License”, accept the ‘Agent Platform’.

Once authentication completes and you see the agent prompt, type /exit to close it so you can complete the repository setup steps below.

GitHub Access

Choose how much of your GitHub the agent can reach:

  • No access If you are not having the agent push to GitHub, then you don’t have to login to GitHub at all.
  • Token for one repository: the agent can only push to your practice repository.
  • Full access: you log in with your browser, and the agent can do anything on GitHub that you can, in every repository your account can reach—except NMFS GitHub Enterprise (which is SSO protected).

Make a token for that one repository

Go to https://github.com/settings/personal-access-tokens/new and fill in:

  • Token name: JupyterHub Claude Code training
  • Expiration: a few days after the clinic
  • Resource owner: your personal GitHub username
  • Repository access: Only select repositories, then pick whatever repo you want to give it access to.
  • Permissions → Repository permissions:
    • Contents: Read and write
    • Pull requests: Read and write
    • Issues: Read and write

Leave every other permission at No access. (Metadata: Read-only is added automatically; that is expected.) Pull requests and Issues are there for the GitHub workflow in Skills 100.

Click Generate token and copy it. GitHub shows it only once.

Log in to GitHub with the token

Open a terminal (File → New → Terminal) and run:

gh auth login

Answer the prompts:

  • Where do you use GitHub? GitHub.com
  • Preferred protocol for Git operations? HTTPS
  • Authenticate Git with your GitHub credentials? Yes
  • How would you like to authenticate? Paste an authentication token

Paste the token and press Enter. It may mention required scopes; you can ignore that for a fine-grained token. gh saves the token on the hub, so every terminal, and your agent, uses it until it expires. If you logged in with your browser on this hub before, this replaces that login.

Note, logging in for full access (the Full access tab) replaces the token with full access.

Warning

With this option the agent can read, change and delete anything you can on GitHub, including private repositories. But it cannot reach NMFS GitHub Enterprise (SSO protected).

Log in

In a terminal, run:

gh auth login

Answer the prompts:

  • Where do you use GitHub? GitHub.com
  • Preferred protocol for Git operations? HTTPS
  • Authenticate Git with your GitHub credentials? Yes
  • How would you like to authenticate? Login with a web browser

It prints a one-time code. Copy it, open the link it shows, paste the code, and approve. When the terminal says you are logged in, you are done.

Good to know

  • Claude Code budget: In a terminal, claude-agent-coders --budget shows what you have spent, your budget, and when your key expires. Spending shows up about a minute after you use Claude.
  • Switch models: In Claude, use /model, for example /model claude-opus-4-6 for a hard problem. The default is Claude Sonnet 4.6; see Models & Budget.
  • Full path: In a terminal, if claude-agent-coders is not found, use ~/shared/workshop/claude-agent-coders.
  • Your settings are preserved: claude-agent-coders preserves your personal configurations.
  • Always use the team launcher: Start Antigravity in a terminal with agy-agent-coders, not plain agy. Plain agy asks for permission before every single shell command out of the box; agy-agent-coders adds everyday commands to your settings and guards against destructive actions.
  • Full path: If agy-agent-coders is not found, use ~/shared/agent-coders/agy-agent-coders.
  • Do not use agy --sandbox on the hub: The hub’s container security does not support container sandboxing and JupyterHub is already a sandbox.
  • Your settings are preserved: agy-agent-coders preserves your personal settings and existing configurations.

Guardrails

Once you connect GitHub (see GitHub Access), the agent can do on GitHub whatever your login allows. The two launchers protect you in different ways.

claude-agent-coders adds no guard of its own. Claude Code’s permission mode protects you. The current mode is shown below the prompt box, and Shift+Tab switches between modes.

  • Auto mode: before each action runs, a second model checks it. Routine work runs without asking. Risky actions are blocked, such as force pushes, git reset --hard, deleting files that were already there, downloading and running scripts, and merging a pull request you have not approved. Auto mode does allow pushing to main, so start each task on a branch.
  • Manual mode: Claude Code asks before every command and every file edit. Read each one before you approve it. Answering “don’t ask again” for a command means it will not ask about that command again.

claude-agent-coders starts in auto mode, on the default model, Claude Sonnet 4.6. Auto mode needs a Sonnet or Opus model; it is not available with Claude Haiku 4.5. If the mode below the prompt box is not auto, switch back with /model claude-sonnet-4-6 and press Shift+Tab until it shows auto.

agy-agent-coders installs a guard that checks every shell command the agent runs. It watches only the agent. You can still run any of these commands yourself in a terminal.

Always blocked:

  • git reset --hard, git clean -f, and force pushes (--force-with-lease is allowed)
  • rm -r outside the folder you started the agent in
  • Pushing to main (or master). The agent works on a branch and opens a pull request instead.
  • Deleting a GitHub repository. You do that yourself.

Stops and asks you first:

  • Merging a pull request
  • Deleting a branch
  • Closing an issue
  • Opening a pull request in a repository you do not own

For these, the agent should tell you what it is about to do and ask. Once you say yes, it runs the command again. For merging and closing issues, Antigravity then shows its own approval prompt too.

These match the workflow in this clinic: one branch per task, a pull request, and you decide when it is merged.

If something goes wrong

  • claude-agent-coders: command not found: Open a new terminal (new terminals load the updated PATH with ~/.local/bin), or run the full path ~/shared/workshop/claude-agent-coders.
  • “That workshop code is not right”: Check the code and try again.
  • “That key was not accepted”: Paste the whole key, starting with sk-. If it still fails, ask your organizer.
  • “A key for … was already issued”: You, or someone using your name, already signed up. Ask your organizer.
  • “All workshop keys are handed out”, “sign-up is closed” or “has ended”: Ask your organizer.
  • “not set up yet” or “Could not reach the workshop gateway”: The gateway is not running. Ask your organizer.
  • A key from an earlier workshop: Run claude-agent-coders --reset, then claude-agent-coders and enter the new code.
  • agy-agent-coders: command not found: Open a new terminal (new terminals load the updated PATH with ~/.local/bin), or run the full path ~/shared/agent-coders/agy-agent-coders.
  • “agent-coders guard: …”: The safety guard stopped a command (see Guardrails). For a blocked one, such as git reset --hard or a push to main, tell the agent to use a safe alternative: git stash, a soft reset, or a branch and a pull request. If it says “needs the user to say yes first”, the agent should ask you before trying again.
  • Commands asking for confirmation: Prompts to approve actions like pip, cp, mv, or rm are expected behavior for commands not on the everyday whitelist. Review the proposed command and approve it if appropriate.
  • Google Cloud project prompt: Make sure you paste the exact Google Cloud project code provided in your clinic materials or Jira ticket.