Skip to content

docs: clarify --max-turns counts agent steps, not user messages #373

@anandgupta42

Description

@anandgupta42

Problem

--max-turns sounds like it limits user conversation turns, but it actually counts step-start events (agent steps including tool calls). A single user prompt can trigger 10+ steps.

Location

packages/opencode/src/cli/cmd/run.ts--max-turns option

Current Description

"maximum number of assistant turns before aborting the session"

Suggested Fix

Either:

  1. Rename to --max-steps for clarity
  2. Or update the description: "maximum number of agent steps (including tool calls) before aborting"
  3. Add documentation in CI guide explaining the relationship between turns and steps

Impact

Low — the feature works correctly, the naming is just slightly misleading for users who expect "turns" to mean "back-and-forth exchanges".

Found During

PR #350 deep analysis.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions