Add agent output mode (NXF_AGENT_MODE)

[edmundmiller]

Summary

Add AI agent-friendly output mode for Nextflow, triggered by environment variables:

• NXF_AGENT_MODE=true
• AGENT=1
• CLAUDECODE=1

When enabled, Nextflow outputs a minimal format optimized for AI agent context windows.

Inspired by Bun's test agent mode

Output Format

[PIPELINE] nf-core/rnaseq 3.14.0 | profile=test,docker
[WORKDIR] /path/to/work
[PROCESS b8/623fc3] sayHello (3)
[PROCESS 5f/761e51] sayHello (2)

[WARN] Task runtime metrics are not reported when using macOS

[ERROR] FASTQC (sample_1)
exit: 127
cmd: fastqc --version
stderr: bash: fastqc: command not found
workdir: /path/to/work/ab/123456

[SUCCESS] completed=10 failed=0 cached=5

Key Features

• Suppresses ASCII banner, ANSI progress, and parameter dumps
• Prints each process submission with task hash and name
• Deduplicates warning messages
• Includes full error context (exit code, command, stderr, workdir)
• One-line summary at completion
• All output written to stderr

Architecture

• LogObserver interface — common abstraction for AnsiLogObserver and AgentLogObserver, allowing Session and LoggerHelper to work through a single logObserver field
• AgentLogObserver — TraceObserverV2 + LogObserver implementation for minimal output
• DefaultObserverFactory — creates both ANSI and agent observers using the same pattern
• SysEnv.isAgentMode() — detects agent mode via env vars

Token Savings

Experiments show 98-100% token savings while preserving all diagnostic information:

• Raw output: 733,399 tokens (11k lines)
• Agent output: 76 tokens (13 lines)

Tests

• AgentLogObserverTest — output formatting tests
• AnsiLogObserverTest — ANSI observer tests (unchanged behavior)
• SysEnvTest — isAgentMode() detection tests

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	18ff87e
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/69a2bae57438370008eb8671

[pditommaso]

Interesting, but does it still need ansi escape capabilities?

[edmundmiller]

No, agent mode doesn't need ANSI escape capabilities. The implementation explicitly disables ANSI output.

The feature was intentionally designed this way. When NXF_AGENT=true:

• session.ansiLog = false
• session.agentLog = true
• No AnsiLogObserver created
• Only AgentLogObserver outputs (plain text)
• Banner/launch info suppressed
  So the terminal doesn't need ANSI capabilities at all - output is pure ASCII text suitable for AI parsing.

[pditommaso]

Nice!

[ewels]

Very nice!

Haven't tested but a skim of the code on my phone looks sensible / as I'd expect 👍🏻

[pditommaso]

is the output format complete for this?

[pditommaso]

This works better with ansi-mode false

» AGENT=1 nextflow run hello
NOTE: Your local project version looks outdated - a different revision is available in the remote repository [d828daeef7]
[PIPELINE] main.nf | profile=standard
[WORKDIR] /Users/pditommaso/Projects/nextflow/work
Bonjour world!

Ciao world!

Hola world!

Hello world!

» AGENT=1 NXF_ANSI_LOG=false nextflow run hello 
[PIPELINE] main.nf | profile=standard
[WORKDIR] /Users/pditommaso/Projects/nextflow/work
[98/2b8d30] Submitted process > sayHello (2)
[f8/89382c] Submitted process > sayHello (1)
[88/b52911] Submitted process > sayHello (3)
[4e/d814a8] Submitted process > sayHello (4)
Hello world!

Ciao world!

Hola world!

Bonjour world!


[SUCCESS] completed=4 failed=0 cached=0

[pditommaso]

Update on output streams: After testing, the agent mode structured output ([PIPELINE], [PROCESS], [WARN], [ERROR], [SUCCESS]/[FAILED]) goes to stdout rather than stderr. This is because the CaptureAppender routes log events through LogObserver.appendInfo → System.out, and the observer's lifecycle methods (onFlowBegin, onTaskSubmit, etc.) also end up on stdout via the same path.

This means both structured agent output and workflow output (e.g. from the view operator) share stdout. Tests have been updated accordingly.

We can revisit this in the future if separating structured output (stderr) from workflow output (stdout) becomes necessary — that would require changes to the CaptureAppender routing logic.