Skip to content

Add agent output mode (NXF_AGENT)#6782

Open
edmundmiller wants to merge 11 commits intomasterfrom
agent-output-mode
Open

Add agent output mode (NXF_AGENT)#6782
edmundmiller wants to merge 11 commits intomasterfrom
agent-output-mode

Conversation

@edmundmiller
Copy link
Member

@edmundmiller edmundmiller commented Jan 29, 2026 •
edited
Loading

Summary

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

  • NXF_AGENT=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

[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
  • Deduplicates warning messages
  • Includes full error context (exit code, command, stderr, workdir)
  • One-line summary at completion

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)

Changes

  • SysEnv.isAgentMode() - Detects agent mode via env vars
  • AgentLogObserver - New TraceObserverV2 for minimal output
  • Session - Adds agentLog flag and observer integration
  • CmdRun - Suppresses banner/launch info in agent mode
  • LoggerHelper - Routes logs to AgentLogObserver

Tests

  • AgentLogObserverTest - 8 tests for output formatting
  • SysEnvTest - Tests for isAgentMode() detection

@netlify
Copy link

netlify bot commented Jan 29, 2026 •
edited
Loading

✅ Deploy Preview for nextflow-docs-staging canceled.

Name Link
🔨 Latest commit 28df1de
🔍 Latest deploy log https://app.netlify.com/projects/nextflow-docs-staging/deploys/698a5e3c8a41f50008069ec6

@edmundmiller edmundmiller self-assigned this Jan 29, 2026
@edmundmiller edmundmiller marked this pull request as ready for review January 29, 2026 19:22
@pditommaso
Copy link
Member

pditommaso commented Jan 29, 2026

Interesting, but does it still need ansi escape capabilities?

@edmundmiller
Copy link
Member Author

edmundmiller commented Jan 29, 2026 •
edited
Loading

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
Copy link
Member

pditommaso commented Jan 29, 2026

Nice!

ewels
ewels approved these changes Jan 30, 2026
View reviewed changes
Copy link
Member

@ewels ewels left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice!

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

@pditommaso
Copy link
Member

pditommaso commented Feb 6, 2026

is the output format complete for this?

bentsherman
bentsherman reviewed Feb 6, 2026
View reviewed changes
modules/nextflow/src/main/groovy/nextflow/Session.groovy Outdated
Comment on lines 317 to 322
Copy link
Member

@bentsherman bentsherman Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I assume you would only ever enable one observer or another, maybe we should combine these into a single logObserver field

Copy link
Member

@pditommaso pditommaso Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make sense

@pditommaso
Copy link
Member

pditommaso commented Feb 7, 2026

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

edmundmiller and others added 9 commits February 9, 2026 08:38
@edmundmiller
Add tests for agent output mode (NXF_AGENT)
f8ff606 
Tests for AI agent-friendly output mode via env vars.
All tests marked @PendingFeature until implementation.

Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Implement agent output mode (NXF_AGENT)
7483087 
Add AI agent-friendly output mode triggered by env vars:
- NXF_AGENT=true
- AGENT=true
- CLAUDECODE=true

When enabled, outputs minimal structured format:
- [PIPELINE] name version | profile=X
- [WORKDIR] path
- [WARN] deduplicated warnings
- [ERROR] with exit/cmd/stderr/workdir context
- [SUCCESS|FAILED] summary

Achieves 98-100% token savings for AI context windows.

Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Add integration tests for agent output mode
4ec897e 
- agent-output.nf: Tests successful workflow in agent mode
- agent-output-error.nf: Tests error output format in agent mode
- Validates [PIPELINE], [WORKDIR], [SUCCESS/FAILED] format
- Verifies banner suppression and error context (exit code, workdir)

Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Add failing tests for '1' as truthy value in agent mode
1693f68 
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Support '1' as truthy value in SysEnv.getBool()
5ce41a4 
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller @bentsherman
Add LogObserver interface for common log observer contract
3addba3 
Co-authored-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller @bentsherman
Implement LogObserver on AnsiLogObserver and AgentLogObserver
730c6df 
Co-authored-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller @bentsherman
Unify ansiLogObserver/agentLogObserver into single logObserver field
820c8c8 
Only one observer is ever active. Use instanceof for ANSI-specific
features (appendSticky, started/stopped checks).

Co-authored-by: Ben Sherman <bentshermann@gmail.com>
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller @pditommaso
Auto-disable ANSI log in agent mode for plain, parseable output
627659b 
Task hashes and submission lines flow through ConsoleAppender instead
of being captured and suppressed.

Co-authored-by: Paolo Di Tommaso <paolo.ditommaso@gmail.com>
Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Fix agent output: write to stderr and install CaptureAppender in agen…
3eed513 
…t mode

AgentLogObserver.println wrote to System.out but integration tests
capture stderr. Also enable CaptureAppender in agent mode so log-level
warnings/errors are forwarded to the observer.

Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
@edmundmiller
Fix printConsole: route process stdout directly in agent mode
28df1de 
printConsole was routing view operator output through
logObserver.appendInfo() which suppresses most messages in agent mode.
Only AnsiLogObserver needs to capture console output for rendering.

Signed-off-by: Edmund Miller <edmund.miller@seqera.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ewels ewels ewels approved these changes

@bentsherman bentsherman Awaiting requested review from bentsherman

@pditommaso pditommaso Awaiting requested review from pditommaso

Assignees

@edmundmiller edmundmiller

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@edmundmiller @pditommaso @ewels @bentsherman

Comments