Agent ergonomics and programmatic access for dev

[jokull]

I built a small experimental runner (procpane) after hitting friction running turbo dev from inside coding agents (Claude Code, Codex, Cursor agent mode). Posting this to map the agent UX gap against work already in flight — partly to share what I learned, partly because the experiment is more interesting if it informs where Turborepo itself is heading.

The problem, concretely

Coding agents need to do three things with a running dev session:

1. Address one task — "what did @acme/api#dev log in the last 50 lines?"
2. Search across tasks — "where did this EADDRINUSE originate?"
3. Poll incrementally — "give me anything new since cursor N" (so the agent isn't re-reading 2k lines every loop)

Today, none of these have a first-class answer with turbo run dev:

• TUI mode (ui: "tui") is in-process — the ratatui buffer is unreachable from outside. Copy/paste is broken in many terminals (Turbo 2 UI: Can't copy terminal outputs #8372). --output-logs=errors-only is replay-only and ignored for non-cached tasks ([turborepo] The --output-logs errors-only flag is ignored for non-cached tasks. #6677).
• Stream mode (ui: "stream") interleaves all tasks to stdout. There's no per-task addressing once the stream is in a file, and persistent tasks emit forever, so the file grows unbounded.
• Cached task logs at node_modules/.cache/turbo/<hash>-<task>.log are great, but they don't exist for persistent dev tasks (cache: false). That's where agents actually need them most.

The agent ends up screen-scraping or attaching to a multiplexer — both lossy and brittle.

What's already in flight

To avoid asking for things that already exist:

• Structured logging? #12217 — --json (NDJSON to stdout) and --log-file[=path] (structured JSON to .turbo/logs/) in v2.8.21-canary.2. This covers most of what an agent wants for build/one-shot tasks. ✓
• Parallel File Output for Task Logs #11368 — a future turbo logs subcommand was mentioned. Big +1 from this corner.

The gap that remains, from an agent perspective, is live querying of persistent (dev) tasks while they're running — not just consuming a log file after they finish.

Concrete proposals

In rough order of "smallest thing that helps most":

1. turbo logs <pkg#task> [--tail N] [--since CURSOR] [--json] — read from the --log-file artifacts, or an in-memory tail buffer for persistent tasks. The --since cursor is the key for agent polling loops without re-reading the whole buffer.
2. turbo logs grep PATTERN [--task FILTER] — server-side grep across tasks with task-name prefixed output. Avoids agents loading entire log files.
3. Per-task log file for persistent tasks too — extend --log-file to write a rotating ring file (capped at, say, 2k lines) for cache: false tasks. Today they're invisible.
4. turbo run --headless — explicit third mode alongside tui/stream. No interactive output to stdout; everything to .turbo/logs/. Useful as the agent default since it removes the "is this a TTY?" question.
5. turbo status --json — list current dev task states + pids + log-file paths. Today an agent has to parse stream output to know what's running.

What procpane does

procpane is a turbo.json-compatible runner that does (1–5) in-memory today for dev sessions. It deliberately doesn't reimplement turbo's value: non-persistent dependsOn (e.g. ^build) chains are delegated to a single pnpm exec turbo run … call, so users keep the cache. The wedge is purely agent-facing query for dev.

The interesting outcome of the experiment isn't the runner itself — it's the shape of the API surface that emerged once you take agent ergonomics seriously. Happy to open separate issues for any of the above and turn the procpane work into prototype PRs if that's useful.

Links:

• procpane: https://github.com/jokull/procpane
• README "Why" section has more detail on the design choices

[anthonyshew]

These are all interesting ideas. I've had turbo logs on my mind (with the same name 😄 ) for a while now. I need to have a think and experiment about what a concrete architecture can look like going forward. There's definitely footguns to be had with the way Turborepo is built today with some of these proposals, but I want to work backwards from the pristine, A+, agentic experience that can exist, and figure out how to mold and mesh that onto today's world.

I can say that --headless fascinates me immediately. We could automatically detect an agent (we already have logic for this in the repo) and print something to the effect of:

Running turbo run <tasks> in headless mode...When you are finished, run "turbo kill <pid?>".
Run "turbo logs pkg#task" to retrieve logs.
Other useful instruction...
Other useful instruction...

I think my one, concrete, early opposition to all of this is: Should an agent be running a dev server anyway? I can see this line of thought if your usage looks more like "pair programming with an agent", where you run the dev server yourself, and then the agent is an actor that may want to interact off to the side. We should be careful about how we design this so we create a great experience for all modus operandi.

[jokull]

The big thing for me is not to cloak dev but to be able to have the agent read and navigate logs effectively.