What the agent does
The agent clones the repository into its own cloud sandbox and reads the configuration before it generates anything. In a module like hashicorp-education/learn-terraform-provision-eks-cluster, terraform.tf requires Terraform ~> 1.3 and four providers: hashicorp/aws ~> 5.47.0, hashicorp/random ~> 3.6.1, hashicorp/tls ~> 4.0.5 and hashicorp/cloudinit ~> 2.3.4, with a commented-out cloud block. variables.tf declares one variable, region, a string defaulting to us-east-2 with a description. outputs.tf has four outputs with descriptions: cluster_endpoint, cluster_security_group_id, region and cluster_name. main.tf has the aws provider, a data "aws_availability_zones" filtered on opt-in-status, a random_string.suffix of length 8, and three registry modules: terraform-aws-modules/vpc/aws 5.8.1, terraform-aws-modules/eks/aws 20.8.5 with cluster_version = "1.36" and two t3.small managed node groups, and terraform-aws-modules/iam/aws//modules/iam-assumable-role-with-oidc 5.39.0 for the EBS CSI driver. README.md is four lines pointing at the tutorial, there is no .github directory, and .terraform.lock.hcl also pins null and time, which the modules pull in.
The agent installs the terraform-docs release binary in the sandbox and runs terraform-docs markdown table . once to see what it produces for this module: a Requirements table (terraform and the four providers with their constraints), a Providers table (aws and random, the ones used directly), a Modules table (eks, irsa-ebs-csi, vpc with source and version), a Resources table listing random_string.suffix, data.aws_availability_zones.available and data.aws_iam_policy.ebs_csi_policy with links to the provider docs, an Inputs table with region, and an Outputs table with the four outputs and their descriptions. It compares that against the files to confirm nothing is missing, which is also how it notices a variable or output with no description, and there are none here.
Then it writes .terraform-docs.yml at the root: formatter: "markdown table", output: {file: README.md, mode: inject, template: ...} with the <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> markers, sort: {enabled: true, by: required}, and settings: {anchor: false} so headings stay plain. It adds the two markers to README.md below the existing paragraph, runs terraform-docs . so the tables appear between them, and runs terraform fmt -check and terraform init -backend=false followed by terraform validate to be sure the configuration it documented parses with the pinned providers.
Finally it adds .github/workflows/terraform-docs.yml. On pull_request the job runs terraform-docs/gh-actions with working-dir: ., config-file: .terraform-docs.yml, output-file: README.md, output-method: inject and fail-on-diff: true, so a pull request that adds a variable without regenerating the README fails with the diff in the log. On push to main the same action runs with git-push: true and a fixed commit message, so the default branch never drifts even when a contributor forgets. The workflow gets permissions: contents: write for that job only and contents: read elsewhere. The agent changes no .tf file.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add terraform-docs to this Terraform configuration. Read every .tf file first and list the variables, outputs, providers, modules and resources you find. Add a .terraform-docs.yml using the markdown table formatter with inject mode into README.md, keep the README's existing text, and generate the documentation between the markers. Run terraform fmt -check and terraform validate without a backend. Add a GitHub Actions workflow that fails a pull request when the generated docs differ from the committed README, and that regenerates and commits the README on pushes to the default branch. Do not change any .tf file. If any variable or output lacks a description, list it in the pull request rather than inventing one.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that adds .terraform-docs.yml and .github/workflows/terraform-docs.yml and changes README.md, which now carries the six generated tables between the markers under the original text. The description shows the Inputs and Outputs tables inline, quotes the terraform validate result from the sandbox, and lists any variable or output without a description, so the reviewer can write those rather than have a generator guess.
The run's record keeps every command with its output, including the terraform-docs version installed, the first dry run, the terraform init -backend=false provider download and the validation, so a reviewer can confirm the tables were produced from this configuration and not typed.
Before merging, a reviewer checks the generated Resources links point at the right provider versions, decides whether the push job should commit to main directly or open its own pull request (a protected branch needs the latter), and confirms the workflow's write permission is acceptable for the repository.
Run it on every new Terraform module
Each new module or root configuration in your organisation gets the same treatment with one POST /o/{org}/sessions carrying this body and that repository in resources. Started from a terminal, the run continues in its sandbox after you close the window; the sandbox parks when the turn ends and a follow-up (POST /o/{org}/sessions/{id}/messages) can switch the formatter or add a section without starting over.
A webhook on the API key reports run.completed with the session_url to read the pull request link, so a script that loops over repositories needs no polling.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The hard part of module documentation is not the generator but the drift after it: a variable added in a hurry, a README that still shows last quarter's outputs. The agent sets up the check that catches the drift and the job that repairs it, and it runs the generator and terraform validate in its own sandbox first, so the README in the pull request is produced from the configuration, with the output kept as proof.
No cloud credentials are involved: terraform init -backend=false downloads providers and terraform validate checks the configuration without touching an account. Several modules can be documented at once, each in its own sandbox, each with its own pull request.
Frequently asked questions
Will it overwrite my README?
No. Inject mode writes only between the BEGIN_TF_DOCS and END_TF_DOCS markers. The text above and below them is yours, and the agent adds the markers below your existing content rather than at the top.
Does it need AWS credentials?
No. terraform-docs reads the .tf files directly. The validation step uses terraform init -backend=false, which downloads providers but configures no backend, and terraform validate, which never contacts a cloud API.
What if a variable has no description?
terraform-docs leaves the description cell empty and the agent lists the variable in the pull request. It does not write descriptions for you, because a wrong description in generated docs is worse than a blank one. A follow-up can add them once you supply the wording.
Can it document a repository with several modules?
Yes. Say where they are, or let the agent find every directory with a .tf file. It adds a recursive setting or one workflow matrix entry per module, and each module's README gets its own markers.