Skip to content

Using Claude Code on These Repos

Claude Code is an AI coding assistant you run from your terminal, inside a repo, to help write and review code. Several repos in this project already use it and ship a CLAUDE.md file — this page covers installing it and best practices for using it across the five component repos that make up this project.

Install

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

Confirm it worked:

claude --version

Then sign in once, from any directory:

claude
# follow the login prompt (opens a browser to authenticate)

⚠️ Common failure: claude: command not found right after installing — same cause as the uv install below it: the installer added claude to a directory not yet on your shell's PATH. Close and reopen your terminal, or run source ~/.bashrc (or ~/.zshrc if you use zsh).

What CLAUDE.md is

Each repo can have a CLAUDE.md file at its root. Claude Code reads it automatically at the start of every session in that repo — it's project memory that doesn't need to be repeated in every prompt: build commands, conventions, gotchas, architecture notes. Think of it as a briefing you'd give a new contractor before they touch the code.

All five component repos in this project have a CLAUDE.md today: optofly, basler-charuco-calibrator, liquid-lens-calibration, optotune-lens, and ximea-py.

Best practices

  • Run claude from the repo root you're working in, not from a parent directory covering multiple repos. This project's repos are siblings under ~/src/ (see Environment Setup) with separate CLAUDE.md files, dependencies, and conventions — mixing them in one session makes Claude guess which repo's rules apply.
  • Keep CLAUDE.md current as you go, not as a cleanup pass. If you change a build command, a config format, or a "this is surprising" behavior, update CLAUDE.md in the same commit — the same principle this wiki follows for its own docs (see When editing). A stale CLAUDE.md is worse than none: it actively misleads the next session instead of just being silent.
  • Let Claude read before it writes. For hardware-adjacent code in this project (serial protocols, camera SDK calls, calibration math), ask it to explain its understanding of the relevant code first, or point it at the specific file/function, before asking it to change behavior — wrong assumptions here can send bad commands to real hardware. optofly's CLAUDE.md documents several non-obvious invariants (e.g. config sections that must be valid even when their subsystem is disabled) that are easy to violate without reading first.
  • Don't let it touch docs/repos/** in this wiki repo. That directory is generated by scripts/sync_repo_docs.py and is gitignored — any fix belongs in the source repo's own docs, not here. See this repo's CLAUDE.md for the full rule.
  • Review hardware-triggering commands before approving them. Claude Code asks for confirmation before running commands or edits in most permission modes — don't reflexively approve when the change could fire a laser, LED stimulus, or move a lens; read what it's about to do first.

Checking whether a repo's CLAUDE.md is stale

There's no automatic check for this — periodically confirm by hand:

cd ~/src/<repo>
git log -1 --format="%ai %s" -- CLAUDE.md   # when it last changed, and why
git log -1 --format="%ai %s"                # most recent commit overall, for comparison

If the repo has moved on significantly since CLAUDE.md's last commit (new commands, renamed modules, changed config format), skim it for anything that no longer matches the code before trusting it in a new session.