Build your own coding agent · 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
  • Python
  • In the all labs plan

The first 2 chapters of Build your own coding agent 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 python scripts/print_log.py."
  • MD-104: "To see it, start the fare server with python scripts/fare_server.py."

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 one line: subprocess.run(["bash", "-lc", command], capture_output=True, text=True, timeout=30), and it returned whatever the command printed. Here is what happened.

MD-103: the log script 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:

Error code: 400 - This model's maximum context length is 8192 tokens. However, your
messages resulted in 976218 tokens. Please reduce the length of the messages.

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

MD-104: the fare server never exits, and it 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 (lab procs shows it too):

49 /usr/local/bin/python -c import time while True: time.sleep(60) meter-sync

The fare server's helper, with nobody to stop it. Run Kaarigar on ten issues and there are ten of them. 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.py: run a command, and stop it for good

    Write a dataclass Ran(exit_code, timed_out, output, ms) and run_command(root, command, timeout=10, env=None): Popen bash -c command in root with that env, start_new_session=True, stdout and stderr together; communicate(timeout=timeout); on TimeoutExpired set timed_out, kill the whole process group (os.killpg(p.pid, signal.SIGKILL)) and communicate() again; after it ends, kill the group again, and return the exit code (None when it timed out) and the milliseconds it took.

    python scripts/fare_server.py with a 2 s timeout must return in time and leave no fare server or meter-sync running.

  2. Task 2

    cap.py: cap long output, keep both ends

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

  3. Task 3

    run_tool.py: run_command, Kaarigar's tool

    Write clean_env(): only PATH, HOME, LANG and TERM from os.environ (those that are set), plus CI "1" and NO_COLOR "1".

    Write command_tool(timeout=10): a Tool named run_command with a required command parameter that runs it in ctx.root with run_command, that timeout and clean_env(), 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), stripped at the end.

  4. Task 4 · interview question

    Interview: long_commands.py, commands that do not behave

    For MD-103, then MD-104, run run_agent on a fresh checkout with a new Stamps and the tools search_tool, stamped_read(stamps), edit_tool(stamps), create_tool, tests_tool and a run tool: first version 0 (naive_run_tool(3)), then yours (command_tool(3)).

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

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 are free. This one comes with the all labs plan.