Claude Code workflow

Claude Code is the agent that does the typing. Everything else on this site (the local box, the VPS, herdr) exists to give it somewhere to run. This page covers the install, the small amount of shell glue that turns it into a reflex rather than a tool you remember to open, and the conventions that keep agents producing code you actually want to merge.

Install

The official installer handles the download, the binary, and the PATH entry:

curl -fsSL https://claude.ai/install.sh | bash
claude --version   # 2.x.x

Pipe to bash, not sh

The installer is written in bash syntax. On Debian and Ubuntu, /bin/sh is dash, and piping to sh fails with a syntax error partway through. Always | bash. If you are installing on behalf of another user, spell it out: sudo -u <you> bash -c 'curl -fsSL https://claude.ai/install.sh | bash', then run the version check with the full path (/home/<you>/.local/bin/claude --version) because that user’s PATH is not yours.

Then authenticate:

claude auth login

This prints an auth URL and asks you to paste a code back. On a headless box, open the URL on whatever machine has a browser and paste the result into your SSH session.

claude login is not the command

Current builds have no top level login command; auth lives under the auth subcommand (claude auth login, logout, status). Typing claude login does not error. It gets swallowed as a chat prompt and opens an interactive session with “login” as your first message.

The headless onboarding loop

claude auth login writes the OAuth token (~/.claude/.credentials.json) and your account info (oauthAccount in ~/.claude.json), but it does not set hasCompletedOnboarding. That flag is only written by finishing the full first-run interactive picker. On a box with no browser you can end up genuinely authenticated and still stuck in a loop: every launch re-shows “Select login method” and then dies with an “invalid uri” error when it tries to open a browser that is not there. Set the flag by hand:

python3 -c "
import json
p = '$HOME/.claude.json'
d = json.load(open(p))
d['hasCompletedOnboarding'] = True
json.dump(d, open(p, 'w'))
"

Aliases that make it a habit

Two shell functions do most of the work. Put them in your ~/.zshrc:

cc()  { printf "\e]0;CC: ${PWD/#$HOME/~}\a"; claude --dangerously-skip-permissions "$@"; }
ccc() { printf "\e]0;CC: ${PWD/#$HOME/~}\a"; claude --dangerously-skip-permissions -c "$@"; }

cc starts a fresh session. ccc continues the last conversation in that directory, which is what you want after you have stepped away, read the diff, and come back with a correction.

The printf "\e]0;...\a" is an escape sequence that sets the terminal title, here to CC: plus the current directory with your home folder collapsed to ~. That looks like a nicety until you are running six agents at once. In a grid of tmux panes, the title is the only thing telling you which pane is grinding on which repo, and “which one was the migration again” is a question you want the window bar to answer rather than your memory. See herdr for the layer that manages those panes.

About --dangerously-skip-permissions

Both aliases above carry that flag, so be clear about what it does. Normally Claude Code asks before each consequential action: writing a file, running a shell command, hitting the network. The flag turns those prompts off. The agent just goes.

People use it because the prompts break flow. An agent doing real work makes hundreds of tool calls, and approving them one at a time turns a ten minute task into thirty minutes of clicking “yes”. You stop reviewing properly around call forty anyway, so the prompts buy less safety than they appear to.

What you give up is the last checkpoint before something irreversible. A wrong rm, a git reset --hard over uncommitted work, a curl to somewhere you did not intend: with the flag on, nobody asks first.

Sane guardrails:

• Run it in a git repo with a clean tree, so git reset --hard and git clean -fd undo anything.
• Keep hooks that block destructive commands, or run inside a container or sandbox.
• Never on a box holding production credentials, and never pointed at infrastructure you cannot rebuild.

Not the beginner default

Start in normal permission mode. Approve things for a week, notice which prompts you always say yes to, and move those into an allowlist in .claude/settings.json. That gets you most of the flow benefit while the prompts still catch the calls that matter. Reach for the flag once you have a feel for what the agent actually tries to do.

CLAUDE.md conventions worth stealing

CLAUDE.md is instructions the agent reads before it starts. A global one at ~/.claude/CLAUDE.md applies everywhere; a per-repo one adds project specifics. The global file is where your non-negotiables live, the rules you are tired of repeating. Some that earn their place:

Pin the toolchain. Python via uv only: uv run, uv add, uv sync, never pip or venv. JavaScript via pnpm or bun, never npm, and commit the matching lockfile (pnpm-lock.yaml or bun.lock), never package-lock.json. Without this an agent will happily reach for whatever it saw most in training and leave you with two lockfiles.

Read before you write. Before adding code to a file, read its exports, the nearest caller, and the obvious shared utilities. Duplicate helpers and conflicting implementations almost always come from skipping this step.

Surgical changes only. Touch what the task requires and nothing else. No opportunistic reformatting, no refactoring things that are not broken, no improving adjacent comments. Small diffs are reviewable; sprawling ones are not, and you are the reviewer.

Fail loud. “Migration complete” is a lie if rows were silently skipped, and “tests pass” is a lie if some were skipped. Tell the agent to surface uncertainty rather than smooth over it. Silent partial success is the most expensive bug class you can invite into an autonomous workflow.

Memory, skills, and plan mode

Claude Code keeps persistent memory directories, so facts worth remembering across sessions survive a restart rather than living in a conversation you eventually close. It also supports skills and slash commands: packaged instructions you invoke by name, so a workflow you refined once is repeatable instead of re-explained. Skills covers the ones worth installing.

Last habit, and the one with the best return: for anything multi-step, plan first. Have the agent produce a plan, read it properly, correct the parts that are wrong, and only then let it execute. Fixing a bad assumption in a plan costs a sentence. Fixing it after four files have been written costs an afternoon.

Full reference lives in the official Claude Code docs.