Build your own coding agent (TypeScript) · Chapter 5 of 20

Running commands

By the end of this chapter Kaarigar runs shell commands the way a careful engineer does: in the repository, with a time limit that stops the command and everything it started, with long output cut to its start and its end, and with none of the agent's secrets in reach. You will see what each of those does to a real run first. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The tools
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Build your own coding agent (TypeScript) are free. This one comes with the all labs plan.

Why you need this

So far Kaarigar reads, edits and runs the tests through tools you wrote for exactly those jobs. A real coding agent also needs a shell: to reproduce a bug, run a script, look at a log, try the app. Claude Code, Codex and Cursor all give their models one. Two of MeterDown's issues ask for it in their text:

  • MD-103: "You can see it in the trip log: run npm run log."
  • MD-104: "To see it, start the fare server with npm run serve."

The model reads those lines, and when it has a way to run a command, it runs them first, the way a person reproduces a bug before fixing it. Kedar's first run_command was four lines: spawnSync('bash', ['-lc', command], { timeout: 30_000 }), and it returned whatever the command printed. Here is what happened.

MD-103: npm run log prints October's trip log, 30,001 lines, 1.56 MB. All of it went back to the model as the tool's result, and the next request was refused:

400 This model's maximum context length is 8192 tokens. However, your
messages resulted in 976232 tokens. Please reduce the length of the messages.

The run crashed at its second request. The model never saw the bug.

MD-104: npm run serve starts a server that never exits, and that server starts a meter-sync helper of its own. The tool waited its full 30 seconds, then gave up, and the model went on and fixed the issue. The run took 30.3 s, and after it had finished, this was still running:

60 node scripts/fare-server.ts
68 /usr/local/bin/node -e setInterval(() => {}, 60_000)

The fare server and its helper, on a port, with nobody to stop them. Run Kaarigar on ten issues and there are ten of each. Jaya: "An agent that leaves things running on my laptop is an agent I do not run twice."

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    run-command.ts: run a command, and stop it for good

    Export the type Ran ({ exitCode, timedOut, output, ms }) and runCommand(root, command, { timeoutMs = 10_000, env = process.env }): spawn bash -c command in root with that env, detached: true, collect stdout and stderr; after timeoutMs set timedOut and kill the whole process group (process.kill(-child.pid, 'SIGKILL')); on close, clear the timer, kill the group again, and resolve with the exit code (null when it timed out) and the milliseconds it took.

    npm run serve with a 2 s timeout must return in time and leave no fare server or meter-sync running.

  2. Task 2

    cap.ts: cap long output, keep both ends

    Write and export cap(text, max = 4000): text of max characters or fewer as it is; longer, the first max / 2 characters, a newline, [... N characters cut from the middle ...], a newline, and the last max / 2 characters (N: how many were left out).

  3. Task 3

    run-tool.ts: run_command, Kaarigar's tool

    Write and export cleanEnv(): only PATH, HOME, LANG and TERM from process.env (those that are set), plus CI: '1' and NO_COLOR: '1'.

    Export commandTool(timeoutMs = 10_000): a Tool named run_command with a required command parameter that runs it in ctx.root with runCommand, that timeout and cleanEnv(), and returns exit code N (or timed out after S s: the command was stopped (a server or a watch mode never ends by itself)), a newline, and cap(output), trimmed at the end.

  4. Task 4 · interview question

    Interview: long-commands.ts, commands that do not behave

    For MD-103, then MD-104, run runAgent on a fresh checkout with a new Stamps and the tools searchTool, stampedRead(stamps), editTool(stamps), createTool, testsTool and a run tool: first version 0 (naiveRunTool(3000)), then yours (commandTool(3000)).

    After each run print ID LABEL: STOP, fixed, N steps, L left running (STOP: run.stop; not fixed from grade; L: leftRunning()), then call stopLeftovers().

What you will learn

  • Why killing a command is not enough, and what a process group is.
  • A timeout that stops the command and everything it started.
  • Capping output: keep the head and the tail, say what was cut.
  • A clean environment: what a command may see of the agent's process.
  • Results that say how a command ended: an exit code, or that it was stopped.

More in The tools

Build "Running commands" yourself

MeterDown, a Pune app for auto-rickshaw fares, has eleven open issues. You build Kaarigar, an agent that fixes them without breaking tests, running risky commands or touching files outside the repository. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Build your own coding agent (TypeScript) are free. This one comes with the all labs plan.