← PART 2 · SHELBY · MCR TEST AGENT

Get shelby running in ten minutes

Shelby is a small coding agent you can read end to end. Install it, point it at the demo app, then open it up and see how an agent really works.

Setup

  1. Check you have Node 18 or newer
    node -v

    Prints v18 or higher? Carry on. Otherwise install Node from nodejs.org first.

  2. Install shelby
    npm install -g shelby-agent

    Permissions error on Mac or Linux? Skip the install and use npx shelby-agent everywhere you see shelby below.

  3. Clone the demo app and go inside it
    git clone <DEMO-APP-URL> cd <DEMO-APP-FOLDER> && npm install

    Shelby works on the folder you run it in, so always start it from inside the app.

  4. Add your API key
    shelby

    The first run creates a .env file and stops. Open it, paste your key after OPENROUTER_API_KEY=, save, and run shelby again. Never commit .env.

  5. Check it works
    shelby --doctor

    Every line should show a tick, including tool-calling: emitted tool_calls.

  6. Start it and say hello
    shelby

    Answer y to trust the folder. Shelby asks before every edit or command. Type /trace first to watch each step as it happens.

No key, or the wifi is bad? Run shelby --demo. It swaps the model for a scripted one so the real loop, /trace and /tools all work offline.

See inside the agent

/trace
Live view of every request, tool call and result
/prompt
The exact system prompt the model gets
/messages
The raw message list, resent every step
/tools
Everything the model can call
/context
How big the conversation has grown
/log
Where this session is recorded
/doctor <model>
Does this model emit tool calls?
--src
Prints the folder with shelby's readable source

Pick a task

Full list of 22: open the task board.

  • Use it: ask for a new page, then run /review on the result.
  • Break it: run /doctor tencent/hy3:free, switch to it with /model, and watch it describe actions instead of doing them.
  • Build a tool: copy word_count.mjs into .shelby/tools/, restart, then make it refuse files outside the repo.
  • Read the code: run shelby --src and start at agent.ts.

If something goes wrong

You seeTry
command not found: shelbyUse npx shelby-agent, or reopen the terminal after installing.
Missing OPENROUTER_API_KEYKey is empty or .env is in the wrong folder. It must sit in the app folder you run shelby from.
401 or "User not found"Stray space or quote in the key, or an expired key. Re-paste it and run --doctor.
It talks about editing files but nothing changesThe model can't call tools. Run /doctor and switch to openai/gpt-4o-mini.
Anything elseRun shelby --doctor, then put your hand up.