Archon Variable Substitution Reference

Archon substitutes variables in command files, inline prompts, bash: scripts, and script: node bodies before passing content to the AI or executing it. This page covers every variable, where it is available, what it resolves to, and how to use it. There are three categories of variables: workflow variables (substituted by the workflow engine), positional arguments (substituted by the command handler), and node output references (DAG workflows only).

Workflow variables

These variables are substituted by the workflow executor in all node types: command:, prompt:, bash:, script:, and loop:.

$ARGUMENTS / $USER_MESSAGE

Resolves to: The user’s input message that triggered the workflow.$USER_MESSAGE is an alias — both variables resolve to the same value.Available in: All workflow node types (command, prompt, bash, script, loop)Example:

nodes:
  - id: analyze
    prompt: |
      Analyze this part of the codebase: $ARGUMENTS

This is the primary way to pass user input through to AI nodes.

$WORKFLOW_ID

Resolves to: Unique UUID for the current workflow run.Available in: All workflow node typesExample:

nodes:
  - id: log
    bash: echo "Run ID: $WORKFLOW_ID" >> /tmp/archon-runs.log

Useful for artifact naming, log correlation, and building run-specific file paths.

$ARTIFACTS_DIR

Resolves to: Pre-created external artifacts directory at ~/.archon/workspaces/<owner>/<repo>/artifacts/runs/<id>/.Available in: All workflow node typesThe directory always exists before any node executes. It is stored outside the repository to avoid polluting the working tree.Example:

nodes:
  - id: generate-report
    prompt: |
      Write your analysis to $ARTIFACTS_DIR/report.md

$BASE_BRANCH

Resolves to: Base branch for git operations (e.g., main or dev).Available in: All workflow node typesResolution order:

worktree.baseBranch from .archon/config.yaml (if set)
Auto-detected from git remote show origin (if not set)
Fails immediately if referenced but cannot be resolved

Unlike other variables, $BASE_BRANCH causes the workflow to fail immediately if the variable is referenced in a prompt but cannot be resolved. If the variable is not referenced, no error occurs.

Example:

nodes:
  - id: branch-info
    prompt: |
      Review the diff against $BASE_BRANCH and summarize changes.

$DOCS_DIR

Resolves to: Documentation directory path.Available in: All workflow node typesConfigured via docs.path in .archon/config.yaml. Defaults to docs/ when not set. Unlike $BASE_BRANCH, this variable always has a safe default and never throws.Example:

nodes:
  - id: update-docs
    prompt: |
      Update the relevant pages in $DOCS_DIR to reflect the new API.

$CONTEXT / $EXTERNAL_CONTEXT / $ISSUE_CONTEXT

Resolves to: GitHub issue or PR context, when the workflow is triggered from GitHub.All three names are aliases for the same value. When no issue context is available, they are replaced with an empty string (never the literal $CONTEXT text).Available in: All workflow node typesAuto-appending behavior: If issue context is present but no context variable appears in the prompt, the context is appended to the end of the prompt automatically. This prevents duplicate context when you explicitly use $CONTEXT.Example:

nodes:
  - id: triage
    prompt: |
      Triage this issue:
      $CONTEXT

$LOOP_USER_INPUT

Resolves to: User feedback provided via archon workflow approve <id> <text> at an interactive loop gate.Available in: Loop nodes with interactive: trueOnly populated on the first iteration after a resume — empty string on all other iterations (initial run and subsequent iterations).Example:

nodes:
  - id: refine
    loop:
      prompt: |
        Previous user feedback: $LOOP_USER_INPUT
        Refine the implementation based on this feedback.
      until: COMPLETE
      max_iterations: 5
      interactive: true
      gate_message: "Review the draft and provide feedback, or approve to complete."

$REJECTION_REASON

Resolves to: Reviewer feedback provided via archon workflow reject <id> --reason <text> at an approval gate.Available in: on_reject prompts on approval nodes only. Empty string everywhere else.Example:

nodes:
  - id: review-gate
    approval:
      message: "Review the PR diff and approve or reject."
      on_reject:
        prompt: |
          The reviewer rejected with reason: $REJECTION_REASON
          Address the feedback and update the implementation.
        max_attempts: 3

$LOOP_PREV_OUTPUT

Resolves to: Cleaned output of the previous loop iteration (loop nodes only).Available in: Loop nodesEmpty string on the first iteration (no prior output exists). Particularly useful for fresh_context: true loops that need to reference what the previous pass produced without carrying the full session history.Example:

nodes:
  - id: improve
    loop:
      prompt: |
        Previous attempt output:
        $LOOP_PREV_OUTPUT

        Review and improve on the above, then output COMPLETE when done.
      until: COMPLETE
      max_iterations: 3
      fresh_context: true

Positional arguments

These variables are substituted by the command handler when commands are invoked directly (outside workflows). They are processed before workflow variables.

Variable	Resolves to	Notes
`$1`	First positional argument	Split by whitespace from the user’s input
`$2`	Second positional argument
`$3` … `$9`	Third through ninth positional arguments
`$ARGUMENTS`	All arguments as a single string	Same variable available in both command and workflow contexts
`\$`	Literal `$` character	Escape a dollar sign to prevent substitution

Example command file (.archon/commands/analyze.md):

Analyze the following aspect of the codebase: $1

Focus on: $ARGUMENTS

Provide actionable recommendations for improvement.

When a user sends analyze security authentication authorization, this becomes:

Analyze the following aspect of the codebase: security

Focus on: security authentication authorization

Provide actionable recommendations for improvement.

Node output references

In DAG workflows, nodes can reference the output of any completed upstream node. These are substituted after workflow variables.

Pattern	Resolves to	Notes
`$nodeId.output`	Full output string of the referenced node	The node must be declared in `depends_on`
`$nodeId.output.field`	A specific JSON field from the node’s output	Requires the upstream node to use `output_format` for structured JSON

Shell quoting behavior

In bash: scripts: $nodeId.output values are auto shell-quoted (single-quoted, with embedded ' escaped), so the value is always safe to embed in a shell command.
In script: nodes: Values are embedded as-is (not shell-quoted). Treat substituted values as untrusted input and parse them with language features (e.g., JSON.parse), not by interpolating into shell syntax.

Example

nodes:
  - id: classify
    command: classify-issue
    output_format:
      type: object
      properties:
        type:
          type: string
          enum: [BUG, FEATURE]
      required: [type]

  - id: fix
    prompt: |
      The issue was classified as: $classify.output.type
      Full classification result: $classify.output
      User's original request: $USER_MESSAGE
    depends_on: [classify]

Substitution order

Variables are substituted in a defined sequence within the workflow engine:

Workflow variables — $WORKFLOW_ID, $USER_MESSAGE, $ARGUMENTS, $ARTIFACTS_DIR, $BASE_BRANCH, $DOCS_DIR, $LOOP_USER_INPUT, $REJECTION_REASON, $LOOP_PREV_OUTPUT
Context variables — $CONTEXT, $EXTERNAL_CONTEXT, $ISSUE_CONTEXT
Node output references — $nodeId.output, $nodeId.output.field

Positional arguments ($1 through $9) are substituted separately by the command handler and are only available when commands are invoked directly, not through workflow nodes.

Availability by context

Variable	Workflow nodes	Direct command invocation	`when:` conditions
`$ARGUMENTS` / `$USER_MESSAGE`	Yes	Yes	No
`$1` … `$9`	No	Yes	No
`$WORKFLOW_ID`	Yes	No	No
`$ARTIFACTS_DIR`	Yes	No	No
`$BASE_BRANCH`	Yes	No	No
`$DOCS_DIR`	Yes	No	No
`$CONTEXT` / aliases	Yes	No	No
`$LOOP_USER_INPUT`	Yes (loop nodes)	No	No
`$REJECTION_REASON`	Yes (`on_reject` only)	No	No
`$LOOP_PREV_OUTPUT`	Yes (loop nodes)	No	No
`$nodeId.output`	Yes (DAG nodes)	No	Yes

$nodeId.output is the only variable available in when: conditions. This lets you use upstream node output to conditionally skip or run downstream nodes.

Authentication environment variables

These are standard environment variables read from process.env at startup. They are not workflow-substituted variables — they must be set in your shell environment or .env file before Archon starts.

Variable	Description
`GH_TOKEN`	GitHub personal access token for authenticated clone operations
`GITLAB_TOKEN`	GitLab personal or project access token (`glpat-*`) for authenticated GitLab clones
`GITEA_TOKEN`	Gitea API token for authenticated Gitea/Forgejo clones

Workflow Schema

Complete YAML schema for nodes, loop config, and approval gates.

Authoring Workflows

Practical guide to building and testing your own workflows.

Loop Nodes

How to use $LOOP_PREV_OUTPUT and interactive loop gates.

Approval Nodes

How to use $REJECTION_REASON in on_reject prompts.

Reference

Documentation Index

​Workflow variables

​Positional arguments

​Node output references

​Shell quoting behavior

​Example

​Substitution order

​Availability by context

​Authentication environment variables

Workflow Schema

Authoring Workflows

Loop Nodes

Approval Nodes

Build docs developers (and LLMs) love

Workflow variables

Positional arguments

Node output references

Shell quoting behavior

Example

Substitution order

Availability by context

Authentication environment variables