Edit configuration with a coding agent

Give a coding agent the right project context, distinguish templates from active configuration, and review changes before deployment.

4 min read

Use a coding agent to help edit a CLI-managed Tale configuration project. The project includes instructions, example configuration and a selected source reference. You still need to review the proposed change and verify which organizations it will affect.

This is different from contributing to Tale’s application source. For a source checkout, start with Contributor setup and the repository’s own AGENTS.md.

A worked setup

Install the Tale CLI, then create a new directory for the configuration project:

bash

tale init agent-config-example --no-env
cd agent-config-example
ls -a

The following is an excerpt of the generated paths:

text

AGENTS.md
CLAUDE.md
default/
.gitignore
.tale/
tale.json

--no-env skips environment setup; it does not create a runnable deployment or generate .env. This is useful when you want to inspect configuration before starting containers. tale dev performs environment setup when you later launch locally. Review the quickstart prerequisites first.

Open this directory in your coding editor. Ask the agent to read AGENTS.md, the relevant existing configuration and the source under .tale/reference/ before proposing a change.

The two instruction files

AGENTS.md contains Tale’s configuration guidance. CLAUDE.md points to that file so there is one maintained set of project instructions. The CLI also recognizes an existing AGENT.md, or a CLAUDE.md already stored under .claude/.

The CLI owns the section between its tale:begin and tale:end comment markers. Put your project-specific conventions outside that section; initialization and updates preserve that surrounding content. Do not put credentials into either instruction file.

The CLI does not generate separate Cursor, Windsurf or Copilot rule files. If an editor does not automatically load the project instructions, explicitly include them in the agent’s context. Check the actual configuration schemas rather than relying on the agent’s memory of an earlier release.

What lives where

Path	How to use it
`default/agents/`	Agent configuration catalog, including the supplied coding-agent example.
`default/automations/`	Automation definitions available to install or deploy. Presence on disk does not mean an automation is active.
`default/skills/`	Skill bundles, including document and visual-analysis skills. Each bundle is a directory.
`default/branding/`	Branding configuration and image assets for the template.
`default/governance/`	Policy and retention examples. Follow the formats of the files generated by your CLI.
`default/README.md`	Explains the template and automatic-install behavior of its catalog.
`.tale/reference/`	Selected implementation source embedded in the CLI. Read it; changes here are replaced by regeneration. It is not a complete repository checkout.
`.tale/orgs/<slug>/<domain>/`	Runtime configuration of actual organizations created in the app.
`.tale/checksums.json`	Records scaffolded-file hashes so updates can distinguish your edits from generated content.

default/ is the template for new organizations, not a deployable organization itself. Editing it does not by itself update an existing organization. The .tale/ directory and secret sidecars are ignored by Git; public template files are intended for version control.

Keep the mirror fresh

tale update updates the CLI within its current release line and refreshes generated project content. It regenerates the reference, updates managed instruction sections, adds new catalog files and updates files whose checksums show no local changes. Locally changed catalog files are preserved unless you use --force.

Use tale update --dry-run to inspect the proposed changes. Keep a version-controlled copy of your public configuration and protected backups of runtime configuration and secrets. Do not treat .tale/reference/ as a place to maintain a fork. Updating the CLI does not roll running containers; follow Upgrades when changing the deployed version.

Cursor: config plane vs runtime plane

An editor agent working in this directory changes local configuration files. A Tale project agent using the Cursor harness runs work in a Tale-managed sandbox. These are separate execution contexts with separate credentials and consequences.

The sandbox harness uses its configured provider account and model. Giving your editor the project instructions does not configure that account. Follow Harnesses for runtime setup.

Review and apply a proposal

Ask for one bounded change and name whether it belongs to the new-organization template or an existing organization.
Check every changed path, schema field, slug and referenced credential. Keep secrets out of the prompt and public diff.
Validate or test through the corresponding product surface. For an automation, inspect validation results and run its mock tests before deployment.
Review the deployment plan and the destination organization. tale deploy --override can replace runtime configuration with the local copy; use it only for a deliberate, reviewed overwrite.
Read back the configuration and exercise the behavior after deployment.

If the agent proposes a field absent from the installed schema, stop at validation and correct the proposal. If an edit to default/ leaves an existing organization unchanged, check the destination instead of repeatedly deploying the template.

Edit on GitHub