# AI coding assistants: Claude Code & Codex

An **AI coding assistant** is a program that lives in your terminal (or editor), reads the files in your
project, and helps you by *conversation*: you describe what you want in plain language, and it explains
code, writes and edits files, and can even run commands — all under your review. For a newcomer to qc-rs
this is a gentle on-ramp: you can ask *"what does this script do?"*, *"write a script that optimizes this
molecule and prints its Mulliken charges"*, or *"why did this calculation fail?"* and get a concrete,
project-aware answer.

This chapter introduces two popular assistants — **Claude Code** (Anthropic) and **Codex CLI** (OpenAI).
They are optional tools; qc-rs does not require them. (This very manual was drafted with Claude Code — you
will see `Co-Authored-By: Claude` in the git history.)

:::{note} Accounts and cost
Both tools need an account and are **paid** services (a subscription or metered API usage). Check the
current pricing and the official setup docs — links are below — before you rely on them.
:::

## What they can do for a qc-rs beginner

- **Explain code and errors** — paste a traceback or point at a file and ask what it means.
- **Write small scripts** — "build a water molecule, run B3LYP, and print the dipole moment."
- **Navigate the codebase** — "where is the SCF convergence tolerance set?" across a large repository.
- **Draft tests and docs** — a first version you then review and refine.

They are assistants, not oracles: **always read what they produce**, and keep your work under `git` so you
can undo anything.

## How they work

Both tools run an **agentic loop** in your terminal: they read your request, look at the relevant files,
propose an action (answer, an edit, or a shell command), and — with your permission — carry it out, then
repeat. Two things are worth knowing:

- **They read the project's own instructions.** This repository ships an `AGENTS.md` (and a `CLAUDE.md`)
  with coding conventions and a `docs/user/CLAUDE.md` for the manual; the assistants load these
  automatically, so their suggestions already follow the project's rules.
- **They ask before acting.** By default an assistant asks for confirmation before it edits a file or runs a
  command; you approve, edit, or decline. You can loosen or tighten this (permission modes) — but as a
  beginner, keep confirmations on and read each proposed action.

## A typical session

Working in the repo, a short exchange might look like:

```text
$ claude
> Write a script that computes the HOMO–LUMO gap of benzene with B3LYP/def2-SVP and prints it in eV.

  (the assistant proposes a new file gap.py, and asks to create it)   [y] approve

> Run it.

  (it runs `python gap.py`, shows the output, and explains the number)

> The value looks too large — is that expected for Hartree–Fock vs B3LYP?

  (it explains why HF over-estimates gaps, and offers to switch functionals)
```

You stay in control the whole time: you approve the file, approve the run, and judge the science.

## Claude Code

**Install** — the **native installer** is simplest; it needs no Node.js and auto-updates itself:

```bash
curl -fsSL https://claude.ai/install.sh | bash      # macOS / Linux / WSL
```

(You can also install it from npm — `npm install -g @anthropic-ai/claude-code`, which needs
[Node.js](https://nodejs.org/) 18+ — but the native installer avoids that. Don't run `npm install` with
`sudo`; use a per-user Node manager like [`nvm`](https://github.com/nvm-sh/nvm) if you hit permission
errors.) The official [Claude Code setup docs](https://code.claude.com/docs/en/setup) cover Windows and
other options.

**Run it** from inside your qc-rs checkout:

```bash
cd ~/path/to/qc_rs
claude
```

The first run walks you through **authentication** (a Claude subscription or an Anthropic API key). After
that, just type what you want. A few qc-rs-flavoured prompts:

```text
> Explain what the quickstart in docs/user does, step by step.
> Write a script that optimizes benzene with B3LYP/def2-SVP and reports the C–C bond length.
> This SCF didn't converge — what convergence options can I try?
```

Claude Code can run shell commands and edit files; it asks for confirmation on actions, and you review each
change.

## Codex CLI

OpenAI's **Codex CLI** is similar. **Install** — the native installer (macOS/Linux) again needs no Node.js:

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

(Or from npm: `npm install -g @openai/codex`, Node.js 18+.)

**Run and authenticate** from your checkout:

```bash
cd ~/path/to/qc_rs
codex           # sign in with a ChatGPT account, or set an OpenAI API key
```

See the official [Codex CLI docs](https://developers.openai.com/codex/cli) for current setup details.

## Using them well

- **Work in a git branch.** So you can inspect the diff and discard anything you do not want (see the
  contributor workflow in the project docs).
- **Review before you run.** These tools can execute shell commands and modify files — read the proposed
  action first, especially anything that deletes, installs, or pushes.
- **Be specific.** "Compute the HOMO–LUMO gap of pyridine with ωB97X-D/def2-TZVP and print it in eV" beats
  "do some chemistry." Point at files and functions by name.
- **Verify the science.** An assistant can write a qc-rs script for you, but *you* are responsible for the
  chemistry — check that the method, basis, and result make sense (the rest of this manual is how you learn
  to).

## Let the assistant set up qc-rs

Because these tools can run commands, an excellent *first* use is the build itself. Building qc-rs on a new
machine means running `make setup` and `make install` and getting the environment-specific details right —
exactly the fiddly chore an assistant handles well. Once the **prerequisites** are installed — git,
`uv` + a Python, Rust, a BLAS/LAPACK, and MPI if you need it (the [next chapter](installation-and-make-setup.md)
covers these) — clone the repo, open it in the assistant, and ask:

> Build qc-rs with `make setup` and `make install`, and save the build configuration to a profile for this
> machine.

It will detect your machine, run `make setup` (generating the profile plus the `.vscode` and build config),
run `make install` (the `maturin` build), and check `import qc`. This is often the *easiest* way to get
qc-rs built — but note the assumption in bold: **the prerequisites (uv, Python, Rust, BLAS, MPI) must
already be installed** — the assistant builds *qc-rs*, not the system toolchain.

Next, get qc-rs installed — by hand or with the assistant — in
[Installation & the build](installation-and-make-setup.md).

---

*Sources for the install commands: [Claude Code setup](https://code.claude.com/docs/en/setup) ·
[Codex CLI](https://developers.openai.com/codex/cli). Tooling changes fast — prefer the official docs for
the current method.*