Getting started with ashr

ashr is an AI agent for model training work. It runs in your terminal, inside your repo, on your machine. It works through your ChatGPT plan or an Anthropic API key, runs commands in your own shell, and splits work across parallel subagents.

What you need

• A Mac with Apple Silicon (M1 or newer). The installer stops on any other machine.
• A ChatGPT plan, or an Anthropic API key.
• A git repository to work in. ashr can clone one for you. Subagents need git to work.

Install

We email you a private install link. Paste the command from that email into Terminal. It looks like this:

curl -fsSL https://ashr.io/i/<your-link> | sh

The installer downloads ashr, checks it against its checksum, and puts it in ~/.local/bin/ashr. It needs no admin password. If ~/.local/bin isn't on your PATH, it adds it to ~/.zshrc (or ~/.bash_profile if your shell is bash).

Open a new Terminal window, then check it worked:

ashr --version

You should see something like 0.2.0 (4967d0e6, 2026-10-21). The part in brackets is the build you have. Mention it if you ever report a problem.

Sign in to your ashr account

The first time you run ashr, it opens your browser to sign in to your ashr account. If the browser is on another machine, it shows a link and a code to paste back. Every run needs this sign-in, including ashr -p and scripts, so do it once in a terminal first.

Sign in to your model

ChatGPT. ashr login codex signs in the same way the Codex app does, so it works even when your company's ChatGPT workspace blocks other apps. It opens your browser. When it asks, choose 1:

Select OpenAI Codex login method:
  1. Browser login (default)
  2. Device code login (headless)
Choose a number: 1
Signed in with your ChatGPT (through the Codex sign-in) subscription. ashr now runs on it, and the sign-in stays on this machine.

Anthropic. Claude subscriptions only work in Anthropic's own apps, so ashr uses an API key. ashr login --provider anthropic asks for the key in the terminal (it isn't shown as you type) and saves it in ~/.ashr/credentials.json, readable only by you. An ANTHROPIC_API_KEY set in your shell takes priority over the saved one.

Your sign-in stays on your machine in ~/.ashr and is only ever sent to OpenAI or Anthropic. If you set up both, ashr starts on Claude. Switch any time with /model.

Set up a repo

/init teaches ashr how your project works. It reads the repo (README, dependencies, how tests and training run) and checks what's on your machine (GPUs, profilers, job launchers, SSH hosts). Then it asks you a few questions in one message and writes the answers to ASHR.md. Every later session reads that file, so you only do this once per repo.

Start ashr in the repo, then type /init:

cd ~/code/my-project
ashr

/init

A repo on GitHub. Clone it first with your own git credentials, then do the same:

git clone https://github.com/karpathy/nanoGPT && cd nanoGPT
ashr

It will ask things like where real GPU jobs run and which profiler you use. Answer in plain words, for example:

Small tests on this Mac. Real training runs on an 8xH100 box I ssh into
as gpu-box, launched with torchrun. I profile with nsys there.

It then writes something like this into ASHR.md. Edit it any time:

## Commands
python train.py config/train_shakespeare_char.py --device=cpu --max_iters=200

## Setup
- This Mac: CPU smoke tests only.
- Real training: ssh gpu-box, torchrun --standalone --nproc_per_node=8 train.py <config>
- Profiler: nsys on gpu-box.

Work with ashr

Start it inside your repo and type what you want, the way you'd ask a colleague:

cd ~/code/my-project
ashr

Run the training smoke test and tell me why loss stops going down after step 150.
Add a cosine learning-rate schedule with 100 warmup steps, then run the tests.
Profile one training step and show me where the time goes.

ashr runs the commands, edits files, and shows you each step as it goes. The bar at the bottom shows the permission mode, how full the context is, tokens used and cost so far.

Type / to see every command. All commands and keys are in the reference at the end.

One-off tasks from the shell. Run a single task without opening the app. Good for scripts:

ashr -p "Which config gives the lowest val loss in runs/? Answer in one line."

Parallel subagents

For work that splits into independent pieces, ask ashr to use subagents. Each one gets its own copy of your repo (a git worktree) on its own branch, so they never step on each other or on your files. A subagent's copy starts from your working tree as it is, including changes you haven't committed. Files git ignores (like .venv or data folders) aren't copied.

Try three learning rates (1e-4, 3e-4, 1e-3) on the smoke-test config in parallel,
one subagent each, then compare final val loss and merge the best config.

Each subagent's steps show up under its name, then its report:

 spawn {"name":"lr-3e-4","brief":"Run the smoke-test config with --learning_rate=3e-4…  done
      Spawned subagent lr-3e-4 (conversation 19) on openai-codex/gpt-6.1-sol.
   lr-3e-4  started in its own worktree
   lr-3e-4  bash python train.py config/smoke.py --learning_rate=3e-4
 lr-3e-4  finished
       Final val loss 1.47, the best of the three.
       Branch: ashr/57ba0e14-lr-3e-4-19
       Commit: c3feda06bc59eb37aaa5160f11bc42fc3add4121

When they finish, ashr reviews each branch and brings the work it keeps into your checkout as new commits on your current branch.

The copies live in ~/.ashr/worktrees, outside your repo. They stay there after the session, along with their ashr/… branches, so you can look back at what each subagent did. To clean up:

git worktree list                  # see them
git worktree remove <path>         # remove one
git branch -D ashr/<branch-name>   # and its branch

Your GPUs and tools

ashr runs in your own shell, so anything you can run, it can run: your Python environments, nvidia-smi, nsys, sbatch, kubectl, and ssh to your GPU machines with your normal SSH config. There's nothing to connect.

To make ashr use your setup the right way every time, put it in ASHR.md (that's what /init does). Notes that apply to every repo go in ~/.ashr/memory.md. ashr reads both at the start of every session.

Teach it a workflow with a skill. A skill is a short playbook ashr reads when it's relevant. ashr comes with skills for common training work, including GPU profiling, SFT, RL post-training, evaluation design, distributed training, quantization, serving and robotics. Add your own as a folder with a SKILL.md file, in the repo (.ashr/skills/) or just for you (~/.ashr/skills/):

mkdir -p .ashr/skills/cluster-profiling
cat > .ashr/skills/cluster-profiling/SKILL.md <<'EOF'
---
name: cluster-profiling
description: Use when profiling a training step on our Slurm cluster.
---
1. Submit with: sbatch scripts/profile.sbatch <config>
2. Reports land in /scratch/$USER/nsys/. Open the .nsys-rep there.
3. Compare against the baseline in docs/perf-baseline.md.
EOF

When two skills share a name, the repo's wins, then yours, then the built-in one.

Sessions

Every conversation is saved. If you quit, or your laptop closes, pick up where you left off. Work that was still running picks up too.

ashr -c     # continue your latest session in this repo
ashr -r     # pick an older session from a list

Permissions

ashr has three permission modes. Press Shift+Tab to cycle through them (ask → edit → auto), or type /mode.

Dangerous commands are sudo, git push, force flags like --force and --hard, and piping a download into a shell (curl … | sh). In every mode, a deny rule blocks the action outright, and ashr asks before spending money on Manifold.

Approving. In edit and ask modes, an action that needs you shows up as a card:

Rules. Permission rules live in three files:

A deny rule in any file always wins. The first time you open a repo whose team file has allow rules or a default mode, ashr asks whether to trust it. Until you do, only that file's deny rules apply. A team file can never turn on auto mode.

{
  "defaultMode": "edit",
  "permissions": {
    "allow": ["shell:pytest *", "shell:git commit *"],
    "deny": ["shell:git push *", "edit:.env*"]
  }
}

defaultMode sets the mode ashr starts in.

Warning: in auto mode ashr can run any command your user account can. For a repo you don't trust, use ask mode, or run ashr in a separate user account or VM.

Your data

Your code and data stay on your machine. ashr sends your messages, and the files and command output it works with, to your model provider (OpenAI or Anthropic) to do the work. We keep heavily redacted logs of chats for debugging and maintenance. Secrets, emails, phone numbers and your home directory path are removed on your machine before anything leaves it.

Updating

ashr checks for a new build once a day and tells you when it starts. It never updates on its own. To update:

ashr update

Or type /update inside ashr, then restart it. ashr -c brings your session back.

Fixes

Starting over, or uninstalling:

rm ~/.local/bin/ashr     # remove the app
rm -rf ~/.ashr           # remove sign-ins, sessions, settings and subagent worktrees

Then delete these two lines from ~/.zshrc (or ~/.bash_profile), if the installer added them:

# added by the ashr installer
export PATH="$HOME/.local/bin:$PATH"

Removing ~/.ashr deletes the worktree folders but not their ashr/… branches in your repos. Run git worktree prune and delete those branches in each repo you used.

Command and key reference

Terminal commands

Slash commands (type / inside ashr)

Keys