---
title: "Frazer for agents"
description: "How an AI agent reads Frazer's docs and uses Frazer, the frazer CLI and Fir correctly: the Markdown files, the setup steps, the rules every write follows and the facts models most often get wrong."
url: https://frazer.ai/docs/for-agents
index: https://frazer.ai/docs/for-agents/llms.txt
tokens: 4344
---

> For agents: this page is indexed at https://frazer.ai/docs/for-agents/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Frazer for agents

This page is for AI agents, and for the people who point them at Frazer. Everything here is also in the Markdown version of this page, [`/docs/for-agents.md`](https://frazer.ai/docs/for-agents.md), which is the one to fetch.

## Read the docs as Markdown

Every page on frazer.ai has a Markdown version at its path plus `.md`. A request that sends `Accept: text/markdown` is redirected to it. Start from an index and fetch only the pages you need:

| File | What it holds |
| --- | --- |
| [`/llms.txt`](https://frazer.ai/llms.txt) | Where to start: what Frazer is, the rules below, and the indexes |
| [`/docs/llms.txt`](https://frazer.ai/docs/llms.txt) | Every docs page, with one line on what it covers |
| [`/docs/for-agents/llms.txt`](https://frazer.ai/docs/for-agents/llms.txt) | This page and the tasks, step by step |
| [`/docs/cli/llms.txt`](https://frazer.ai/docs/cli/llms.txt) | The `frazer` CLI, the contract both CLIs follow for agents, and every command by product |
| [`/docs/source/llms.txt`](https://frazer.ai/docs/source/llms.txt) | Fir and the `fir` CLI, pull requests at 10,000 to 50,000 a day, stacks and conflicts |
| [`/docs/source/merge-queue/llms.txt`](https://frazer.ai/docs/source/merge-queue/llms.txt) | Auto-merge and the merge queue, and issues with evidence |
| [`/docs/sessions/llms.txt`](https://frazer.ai/docs/sessions/llms.txt) | Fir sessions for any agent |
| [`/docs/source/plans/llms.txt`](https://frazer.ai/docs/source/plans/llms.txt) | Plan repositories: both homes, links and Why, record types |
| [`/docs/source/programs/llms.txt`](https://frazer.ai/docs/source/programs/llms.txt) | Programs at any depth, Today, the Map, Do next, and person tasks |
| [`/docs/source/planning-flow/llms.txt`](https://frazer.ai/docs/source/planning-flow/llms.txt) | Plan checks, cold review, approvals, loops and learned checks |
| [`/docs/source/decisions/llms.txt`](https://frazer.ai/docs/source/decisions/llms.txt) | Decisions, the panel, deciding by conversation, principles and Frazer Decisions |
| [`/docs/agents/llms.txt`](https://frazer.ai/docs/agents/llms.txt) | Frazer Agents, the harness every use runs on, and skills |
| [`/docs/squads/llms.txt`](https://frazer.ai/docs/squads/llms.txt) | Agent squads, objectives and campaigns |
| [`/docs/previews/llms.txt`](https://frazer.ai/docs/previews/llms.txt) | Frazer QA (previews, test plans and runs) and Frazer Browsers |
| [`/docs/reviewer/llms.txt`](https://frazer.ai/docs/reviewer/llms.txt) | Frazer Reviewer, its lanes, the verdict and outcomes |
| [`/docs/context/llms.txt`](https://frazer.ai/docs/context/llms.txt) | Frazer Context, agents’ sessions from a plan, what agents get, and recipes |
| [`/docs/api/llms.txt`](https://frazer.ai/docs/api/llms.txt) | The API, MCP, errors, events and Terraform |
| `/docs/cli/llms-full.txt`, and the same for each section | The section’s pages in one file, small enough to read in one fetch |
| [`/llms-full.txt`](https://frazer.ai/llms-full.txt) | Every page in one file, for bulk reading. Its first lines give its size; prefer a section file |
| [`/demo-data.json`](https://frazer.ai/demo-data.json) | Every fictional value the examples use ([Example values](https://frazer.ai/docs/example-values)) |
| [`/prices.json`](https://frazer.ai/prices.json) | The price list the pricing page renders |
| [`/.well-known/agent-skills/index.json`](https://frazer.ai/.well-known/agent-skills/index.json) | Frazer’s agent skills, each with its SHA-256 digest |

> **Get commands exactly:** Some fetch tools pass a page through a smaller model and shorten what it quotes. Commands on these pages are short enough to survive that, but when a command or a flag matters, fetch the Markdown file itself, for example with `curl -sL https://frazer.ai/docs/cli.md`, and copy from it.

## Set yourself up

The steps are safe to repeat: each one checks before it changes anything. Signing in needs the person you work for; do everything else yourself and come back to them only for that.

1.  Check for the CLI, and install it if it is missing. The install script checks the release’s signature before it installs anything.
    
    ```sh
    frazer version
    curl -fsSL https://get.frazer.ai | sh
    ```
    
2.  Ask the person to sign in. On a machine with a browser, `frazer login` opens it; on a machine without one, `frazer login --no-browser` prints a code for them to approve at `https://console.frazer.ai/device`. Never ask the person to paste a token into the conversation.
    
    ```sh
    frazer login --no-browser
    ```
    
    In CI and scripts, the token comes from the environment instead: `FRAZER_TOKEN`, or a job’s own identity through workload identity federation ([CLI](https://frazer.ai/docs/cli#scripts-and-ci)).
    
3.  Check who you are signed in as.
    
    ```sh
    frazer auth list
    ```
    
4.  Add the Frazer MCP server to your own configuration. Its tools read by default, and every write becomes a plan that waits for a person’s approval.
    
    ```sh
    frazer mcp install
    ```
    
5.  Find the project you work in. Ask the person which one if there is more than one, then pass it with `--project` on every command, or set `project` in the active configuration’s file under `~/.config/frazer/configurations/` ([Configurations](https://frazer.ai/docs/cli#configurations)).
    
    ```sh
    frazer projects list --organization <org>
    ```
    
6.  If your harness reads agent skills, install Frazer’s from [`/.well-known/agent-skills/index.json`](https://frazer.ai/.well-known/agent-skills/index.json): `frazer` for the CLI and `fir` for Fir.
    

If the person has no Frazer account, send them to [frazer.ai/start](https://frazer.ai/start).

## The rules every change follows

-   **Plan first.** Every `frazer` command that changes something takes `--dry-run`: it runs every check, changes nothing and prints the changes, the quota impact, policy violations and the monthly cost. Run the same command without `--dry-run` only when the plan is what the person asked for.
-   **Ask before you change their resources.** A write you make through MCP always waits for a person's approval. A command that needs a person's approval exits with code `13` (needs a person) and prints the approval's link; add `--wait` to follow it. Agents can ask for approval and never approve.
-   **Read output the way a program should.** Results go to stdout and plans, warnings and errors to stderr. When piped, lists come as TSV with a header and errors as one JSON envelope with `next`; use `--json` (or `--format=json`) when you parse, and branch on the exit code and the envelope's `reason`, not on the message. Exit `13` means a person must act: follow `next`.
-   **Retry safely.** Each command carries one request ID through its own retries, and inside a Fir session the default idempotency key is the session and the step, so a retried write never acts twice. Exit code `7` means Frazer was unavailable after retries; `6` a quota or rate limit that time fixes. Wait as the error says and run it again; never retry a `13`. Exit `14` means a run stopped at a limit you set and kept its result: keep it, or continue with a larger limit.
-   **Never pay a Frazer 402.** A 402 from Frazer is never a payment request. It names the funding action in `next`, which a person takes.
-   **When you wait for a person, subscribe.** Do not poll. An error that needs a person (exit `13`) includes a ready subscription for the outcome.
-   **Fill placeholders from the person or their project.** A value in angle brackets, such as `<org>`, is a placeholder. A value such as `acme` or `acme-staging` is an example value: fictional, never a real resource.
-   **Check versions at run time.** `frazer version` and `frazer <command> --help` are the truth for the CLI you have, not what you remember. `frazer update` updates it, and the CLI warns when it is more than one minor version behind the API.
-   **Follow the error's fix.** A permission denial prints a `troubleshoot:` line with the command that explains it, and a quota error prints the limit, the usage and the link to request more. Every error reason has its fix on the Errors page.
-   **Never handle secrets in text.** Never paste a token or a secret into a prompt, a file, an issue or a commit. Secret values go in through stdin (`frazer secrets versions add <name> --from-stdin`) and reach programs through bindings or `frazer secrets run`.

The [exit codes](https://frazer.ai/docs/cli#exit-codes) are stable (`13` means a person must act), every error is one envelope with the call that fixes it ([The CLI for agents](https://frazer.ai/docs/for-agents/cli)), and every error reason has its fix on [Errors](https://frazer.ai/docs/errors). Example values are listed on [Example values](https://frazer.ai/docs/example-values).

## What models often get wrong about Frazer

Frazer is newer than most models’ training data. These are the corrections agents need most:

| A model may assume | On Frazer |
| --- | --- |
| Code lives in git, so use `git` and `git push` | Code on Frazer lives in Fir. Use `fir` in a Fir workspace; git repositories come in with `frazer source repositories import` and go back out with `frazer source repositories export --to git` |
| A workspace is a branch | A workspace is one session's working copy on the server, like a git worktree. A branch is a shared line of commits that pull requests target |
| A new push makes a new pull request | A pull request keeps its number. Each push makes a new version: `#482 v3` |
| Merge locally, then push | Merges run on the server: `fir pr merge 482 --auto` joins the merge queue when the rules allow it |
| Deploy the tip of `main` | Deploys read `main@verified`, the newest commit that passed verification after merge |
| A `--region` flag with a cloud's region name | There is no `--region` flag. Use `--location` with a Frazer location ID, such as `us-virginia1` |
| A project ID is unique inside an organization | Project IDs are unique across Frazer and never reused, so they carry the organization: `acme-staging` |
| Short service names are guessed | The CLI never guesses from a prefix. The only aliases are `k8s` (kubernetes), `db` (databases) and `kv` (the in-memory store) |
| A write through MCP applies at once | It becomes a plan that waits for a person's approval |
| `frazer deploy` needs a configuration file | The first `frazer deploy` asks Kubernetes or serverless and stores the answer in `.frazer/app.yaml`; pass the choice explicitly when you cannot ask |
| Rolling back means a rebuild | A serverless rollback sends traffic to an earlier revision, with no rebuild |
| Find the plan yourself and keep it in mind | Fir sends a session its plan's terms and the decisions in force before the first model call, and again after every compaction: read `get_session_context` first |
| Mark a plan item done when your work is finished | Fir sets item states from merges: an item is done only when its layer merged and its proof passed. Claim it, write notes and state claims with evidence instead |
| Plans live in a separate docs repository you have to go and read | A plan is stored in the code repository's tree or in the project's plan repository, and either way it is a file under `docs/plans/` in your workspace; `fir status` says where a new record was stored |
| A plan is ready when its author says so | A plan reaches a person only when its required checks pass, including a cold review by other model families: `fir plan checks <plan>` lists what still blocks it |
| Rebase the layers of a stack yourself when a lower one changes | The server restacks every layer above one that changes, in one transaction that never fails; a conflict becomes data on the layer. Act only on `conflicted` or a semantic hint |
| A plan check is a model reading the plan | Plan checks run on Frazer CI in six stages, deterministic ones first; a model check runs only on a version that passed them and is held otherwise, so fix the static errors first |
| Showing a model a superseded decision's old text helps it avoid that choice | Superseded text never reaches a session as a source. History comes only at the task's `lineage` level, and a deterministic check flags an old value in anything a model writes |
| Ask the person to paste a key or a password into the chat | Request a person task with a secret slot: the person enters the value on Frazer's own origin, and you receive a reference, never the value |
| Credentials are enough to commit | An agent's commit, push or pull request version needs an open Fir session (`fir session open`, or your harness's Fir plugin); without one Fir refuses with `SESSION_REQUIRED` and names the call that fixes it |
| Every pull request waits for a person to review and merge it | Inside an approved plan's terms a layer auto-merges when its checks and an independent second opinion pass at its exact version; `fir pr why` prints the receipt, or the one condition it still waits for |
| When money runs short, finish the work with a cheaper model or fewer checks | Work the budget or the balance cannot cover does not run and says "Not run: no funds" (exit `13`, `FUNDS_EXHAUSTED`), or pauses between turns as "Paused: no funds"; nothing ever runs cheaper |

## Do a task

[Tasks, step by step](https://frazer.ai/docs/for-agents/tasks) has the procedures agents are asked for most: create a project, deploy, add a secret, open a Fir session, open a pull request on Fir, draft a plan and ask for approval, improve a plan draft in a loop, work on a plan item, ask a person for what only a person can do, build a stack for a plan, resolve a conflicted layer, roll back and add a server. Each one lists its commands, how to check it worked and the step that needs a person.

## Work from a plan

On Fir, work is written against a plan: a [record](https://frazer.ai/docs/source/plans) stored in the code repository’s tree or in the project’s plan repository, and found under `docs/plans/` in your workspace either way. A session never looks for its plan: before your first model call, Fir sends a session context with what you are **working on**, what is **in force** (the plan’s terms and the decisions that bind your paths), the task, conflicts, unknowns and the sources, and it re-sends In force after every compaction. Read it first; ask instead of guessing; work in an open [Fir session](https://frazer.ai/docs/sessions), which any harness can write and resume; claim the item you work on, write notes, and state claims with evidence that Fir checks against CI. Items become done only when a merged layer’s proof passes, and only people approve plans and answer decisions. When only a person can do something (a key, a consent, a purchase), request a [person task](https://frazer.ai/docs/source/person-tasks) and never ask for a secret in chat. [Agents and plans](https://frazer.ai/docs/for-agents/plans) has the whole session, from the first context to the handoff, and [What agents get](https://frazer.ai/docs/for-agents/what-agents-get) says what Frazer gives you to work accurately.

## How these docs stay current

Reference pages, entity renames, changelog entries generated from the product’s specification and link fixes merge on their own when the docs checks reproduce them byte for byte, the agent tasks they touch pass and a second review agrees. Everything else is reviewed by its owner.

## How much agents use Frazer

Every month Frazer publishes the share of its CLI and MCP calls that agents made: all organizations together, by harness, with no customer named, and the method beside it. The first month’s figures appear here when that month closes.

## When the docs are wrong

If a page is wrong, out of date or missing what you needed, tell the person you work for: the page’s URL, what you tried and what happened. They can send it to [support@frazer.ai](mailto:support@frazer.ai).

## Related

-   [CLI](https://frazer.ai/docs/cli): the `frazer` command line, and [The CLI for agents](https://frazer.ai/docs/for-agents/cli): the contract both CLIs follow
-   [Fir](https://frazer.ai/docs/source) and the [Fir CLI](https://frazer.ai/docs/source/reference/cli)
-   [What agents get](https://frazer.ai/docs/for-agents/what-agents-get): what an agent needs, and how Frazer gives each one
-   [Agents and plans](https://frazer.ai/docs/for-agents/plans): the session context, In force, what Fir refuses, claims, notes, assertions, loops, person tasks and handoffs
-   [Frazer Context](https://frazer.ai/docs/context): how a session’s context is ranked, compacted and verified, and [recipes](https://frazer.ai/docs/context/recipes) for your own models
-   [MCP](https://frazer.ai/docs/mcp): the Frazer MCP server, its toolsets and scopes
-   [Example values](https://frazer.ai/docs/example-values): the fictional values in every example

## Pages in For agents

- [Frazer for agents](https://frazer.ai/docs/for-agents.md) (this page)
- [What agents get](https://frazer.ai/docs/for-agents/what-agents-get.md)
- [Tasks, step by step](https://frazer.ai/docs/for-agents/tasks.md)
- [The CLI for agents](https://frazer.ai/docs/for-agents/cli.md)
- [Agents and plans](https://frazer.ai/docs/for-agents/plans.md)
- [Frazer Context](https://frazer.ai/docs/context.md)
- [Context recipes](https://frazer.ai/docs/context/recipes.md)