> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# How Ancha works

> The objects Ancha uses (agent, tool, world, test, run, attempt and check) and how the CLI's scene and trial vocabulary maps onto them.

Ancha runs your agent against replicas of the tools it uses, many times, from the same starting point.

## Objects

| Object | What it is |
| - | - |
| Agent | Your code, how it starts (a command or an HTTP endpoint) and the model provider it uses. |
| Tool | A stateful replica of a service such as Slack or GitHub. It answers the real API's endpoints with realistic IDs, and its state changes as the agent acts. CLI output calls a tool a *twin*. |
| World | A set of tools with starter data: channels and messages, repositories and issues, monitors, incidents, contacts and deals. See [Worlds](https://docs.ancha.io/concepts/worlds.md). |
| Test | A world plus tasks and how many times to try each one, saved so it runs again against new agent code. See [Tests](https://docs.ancha.io/concepts/tests.md). |
| Run | One execution of a test. |
| Attempt | One independent try at one task, on its own fresh copy of the world. See [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md). |
| Check | A condition on the final world state or on the agent's API calls that decides whether an attempt passed. See [Checks](https://docs.ancha.io/concepts/checks.md). |

## What happens in a run

```mermaid theme={null}
flowchart LR
  W["Fresh world"] --> A["Agent works"] --> C["State and calls captured"] --> V["Checks decide"]
```

1. Ancha creates a fresh copy of the world for each attempt, from the same seed.
2. It starts your agent with the task and the tool addresses and fake credentials in environment variables.
3. The agent calls the tools. Every call is recorded, and tool state changes as it would in the real service.
4. When the agent exits or times out, Ancha captures the final state and the call trace.
5. Checks run against what was captured. The attempt passes when every required check passes.

## Two vocabularies

The hosted console and the CLI's playground commands use agents, worlds, tests, runs and attempts. `ancha run` is file-based and uses scenes and trials. They describe the same ideas:

| Idea | Hosted console and `ancha playground` | `ancha run` |
| - | - | - |
| World | A saved, versioned world | `twins`, `seed` and `world_rules` in a scene file |
| Task | A task on a test | `task` in a scene file |
| Checks | A JSON list on each task | `checks` in a scene file |
| Test | A saved test | `ancha.yaml` plus the scene files it lists |
| Attempt | Attempt | Trial |
| Live copy of a world | Playground | Environment (`envId`) |

## Determinism

The same world and seed always produce the same starting data, including record IDs. Tools run on a simulated clock that starts at a fixed time, so timestamps and time-based behavior repeat across attempts. A difference between two attempts comes from your agent.

## Where results live

| You run | Results are stored in |
| - | - |
| `ancha run` | `.ancha/runs/` in your project. See [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md). |
| `ancha playground` | `.ancha/playgrounds/` in your project. |
| Runs in the hosted console | Your hosted workspace's disk. |


## Related topics

- [Introduction](https://docs.ancha.io/index.md)
- [ancha run](https://docs.ancha.io/cli/run.md)
- [Results in your workspace](https://docs.ancha.io/cloud/results.md)
- [Hosted workspace](https://docs.ancha.io/cloud/overview.md)
- [ancha status](https://docs.ancha.io/cli/status.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.