Getting started

Your first hour

1. Pick one tool and install it. Any of the five. If your site provides model access, start with a tool that supports it.
2. Say what you want, and how you will check it. This is where careful thought pays off most. Before you prompt, decide the goal, the limits (what must not change, which dependencies are allowed) and the check that proves it worked: a test, a known value, a reference result, a plot you know how to read. Put all of that in the prompt. If you find yourself repeating the same instructions, move them into AGENTS.md; it helps you be specific, but you do not need one to start.
3. Start small and checkable. A test, a docstring with units, a plot, on a real repository, with a commit before you prompt.
4. Review the diff, commit, repeat. One step per prompt.

Install, step by step

These steps assume a fresh computer with nothing installed. Follow the tab for your operating system. Each step ends with a check; if the check works, move on.

Easiest and safest: the tutorial container

One image has Claude Code, Codex CLI, OpenCode, uv, gh, vim, emacs and VS Code in the browser. It mounts your project and saved agent settings, and uses the credentials you supply. You only need Git (step 2) and Podman (or Docker). See Run in a container.

What you need

• A computer: Windows 10 (version 1809 or later) or Windows 11, 64-bit; macOS 13 or later; or a recent Linux.
• Model access: a subscription or API key for the tool you pick (Claude for Claude Code, ChatGPT or OpenAI for Codex, any provider for OpenCode), or access through MAG for Genesis Mission teams.
• About 30 minutes and permission to install software. Most steps below do not need administrator rights; Git and Podman may ask for them.

1. Open a terminal

A terminal is a window where you type commands. Every command on this page is typed (or pasted) there, followed by Enter.

WindowsmacOSLinux

Press Win+X and choose Terminal (Windows 11) or Windows PowerShell (Windows 10). Check that you are in PowerShell: the prompt starts with PS C:\.

Use PowerShell, not "Command Prompt" (cmd): the commands below are PowerShell commands.

Press Cmd+Space, type Terminal, and press Enter.

Open your distribution's terminal (often Ctrl+Alt+T).

After installing something, open a new terminal

A terminal reads the list of installed programs (the PATH) when it starts. If a check below says "not recognized" or "command not found" right after an install, close the terminal, open a new one and try again. This fixes most problems.

2. Install Git

Git keeps the history of your project, and it is your undo button when an agent makes a change you do not want.

WindowsmacOSLinux

winget install --id Git.Git -e

If winget is not available, download the installer from git-scm.com/downloads/win and click Next on every screen to keep the defaults. Git for Windows also installs Git Bash, which Claude Code uses to run commands.

xcode-select --install

Click Install in the window that opens. This installs Apple's command-line tools, including Git.

sudo apt update && sudo apt install -y git curl     # Ubuntu / Debian
# sudo dnf install -y git curl                       # Fedora / RHEL

Open a new terminal, check, and tell Git who you are (once per computer):

git --version
git config --global user.name "Your Name"
git config --global user.email "you@lab.gov"

3. Install uv (Python)

uv installs Python itself, creates project environments and installs packages. You do not need a separate Python installation.

WindowsmacOS / Linux

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal, then:

uv --version
uv python install 3.12

4. Install Node.js (only if you need it)

The recommended installers below do not need Node.js. You need it only for OpenCode on Windows (npm route) or if you prefer installing any tool with npm.

WindowsmacOSLinux

winget install --id OpenJS.NodeJS.LTS -e

Download the LTS installer from nodejs.org, or with Homebrew: brew install node.

Use the LTS release from nodejs.org (the page gives the command for your distribution).

Check in a new terminal: node --version and npm --version.

5. Install a coding agent

Pick one to start. You can add others later; they read the same files in your repository. The commands below come from each tool's official page, which is the place to check if anything changes.

Claude Code

Official: github.com/anthropics/claude-code · setup documentation

WindowsmacOS / Linux

irm https://claude.ai/install.ps1 | iex

Alternative: winget install Anthropic.ClaudeCode. Install Git (step 2) first, so Claude Code can use Git Bash.

curl -fsSL https://claude.ai/install.sh | bash

Alternative on macOS: brew install --cask claude-code.

Check: claude --version. The npm package is deprecated; use the installers above.

Codex CLI

Official: github.com/openai/codex · documentation

WindowsmacOS / Linux

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Alternatives: npm install -g @openai/codex (needs Node.js, step 4) or brew install --cask codex. Check: codex --version.

OpenCode

Official: github.com/anomalyco/opencode · documentation

WindowsmacOS / Linux

npm install -g opencode-ai@latest

This needs Node.js (step 4). If you use Scoop or Chocolatey: scoop install opencode or choco install opencode.

curl -fsSL https://opencode.ai/install | bash

Alternative: brew install anomalyco/tap/opencode.

Check: opencode --version.

IDE agents (no terminal needed)

• Cursor: download from cursor.com, install, and sign in. It is a VS Code-based editor with an agent built in.
• Kilo Code: install VS Code (Windows: winget install --id Microsoft.VisualStudioCode -e), then search for Kilo Code in the Extensions panel. See kilocode.ai/docs.
• Claude Code and Codex also have VS Code extensions; search for them in the Extensions panel.

6. Sign in and run it the first time

Make a folder for a first project, put it under Git, and start the agent inside it:

mkdir my-first-agent-project
cd my-first-agent-project
git init
claude        # or: codex, opencode

The first run asks you to sign in: a browser window opens for a subscription login, or you can use an API key. For Genesis Mission model access, see Model access below. Type /help inside the agent to see its commands, and /exit (or Ctrl+C twice) to leave.

Then try the hands-on lab: it starts from a specification and a set of test molecules.

Windows troubleshooting

Problem	Fix
'claude' is not recognized (or codex, uv, git)	Close the terminal and open a new one. If it persists, rerun the installer and read its last lines: it prints the folder to add to your PATH.
running scripts is disabled on this system	Allow scripts for your user once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then open a new terminal.
winget is not recognized	Install or update App Installer from the Microsoft Store, or use the download links above.
Commands from a guide use export VAR=...	That is bash syntax. In PowerShell write $env:VAR = "..." (current window only).
You want a Linux environment instead	Run wsl --install in an administrator PowerShell, restart, open Ubuntu from the Start menu and follow the Linux tabs on this page.
You want the container	Install Podman (winget install -e --id RedHat.Podman, it uses WSL 2) or Docker Desktop, then follow Run in a container.

Model access

The steps above work with any model provider. Genesis Mission teams can get model access through the AmSC Model Access Gateway (MAG), which explains how to request access, create a personal access token, and connect Claude Code and Codex CLI.

For alternative backends hosted at Argonne, see Custom endpoints: argo-proxy (ANL network), argo-shim (ALCF machines), or ALCF Inference Endpoints (public, Globus auth).

The ALCF Inference Endpoints documentation describes how to point coding agents at open-weight models hosted on ALCF hardware.

Shortcut commands for MAG and ALCF

This repository has six small commands that start an agent on MAG or on the ALCF Inference Endpoints with the right settings. They are built into the tutorial container, and they also work on your own machine. They do not change your agents' configuration files, so plain claude, codex and opencode keep working as before.

	MAG	ALCF Inference Endpoints
Claude Code	claude-amsc	claude-alcf
Codex	codex-amsc	codex-alcf
OpenCode	opencode-amsc	opencode-alcf

When a token is missing they explain what to do. The MAG commands ask for your personal access token (PAT) and use it for that run. The ALCF commands start the ALCF login, which prints a Globus link: open it, log in, and paste the code back.

What you need: bash and curl (macOS and Linux have both), the agent you want to run, and for ALCF the alcf-tokens CLI:

uv tool install alcf-tokens

Install the commands. Download them into ~/.local/bin, which the uv installer already put on your PATH:

mkdir -p ~/.local/bin && cd ~/.local/bin
for f in agent-tokens.sh agent-status claude-amsc claude-alcf codex-amsc codex-alcf opencode-amsc opencode-alcf; do
  curl -fsSLO "https://raw.githubusercontent.com/Autonomous-Scientific-Agents/AgenticCodingTutorial/main/bin/$f"
done
chmod +x agent-status claude-amsc claude-alcf codex-amsc codex-alcf opencode-amsc opencode-alcf

Keep agent-tokens.sh in the same folder: the commands read it to handle tokens. Run the loop again to update. If you cloned this repository, you can instead add its bin folder to your PATH (export PATH="/path/to/AgenticCodingTutorial/bin:$PATH" in ~/.zshrc or ~/.bashrc) and update with git pull.

Save your MAG PAT so you are not asked every time. Add this line to ~/.zshrc (macOS) or ~/.bashrc (Linux) and open a new terminal. PATs are short-lived. agent-status --check tells you whether your MAG and ALCF tokens still work, and agent-status --models lists the models each offers (--hot: only the ALCF models loaded now). When MAG rejects the PAT, create a new one on myAmSC and replace it in your startup file. For the terminal you have open, run read -rs AMSC_TOKEN && export AMSC_TOKEN and paste it.

export AMSC_TOKEN='<your PAT>'

Use them in your project folder like the plain agents. Options pass through:

cd my-project
claude-amsc                       # Claude Code on MAG
codex-alcf -m nemotron-3-ultra    # Codex on ALCF with another model
opencode-amsc                     # OpenCode on MAG; /models lists the MAG models

The container page lists the default models and the variables that change them. With OpenCode 2 the opencode-* commands start their own private OpenCode server, because the shared background server would not see their settings. On your machine Codex keeps its own sandbox; only inside the container do codex-amsc and codex-alcf turn it off. On Windows, run the commands in WSL or Git Bash.

To switch Claude Code between MAG and ALCF with shell functions instead, or to set it up on a supercomputer, see Shell setup.