ancha init

ancha init prepares the current directory for ancha run. It writes files only; it installs no dependencies, starts no agent and makes no network calls.

ancha init [options]

Option	Description
`--agent <command>`	The command that starts your agent (default: package.json scripts.start, a Procfile, pyproject.toml [project.scripts] or the Dockerfile CMD)
`--template <template>`	Starter or incidents (default: “starter”)
`--intent <description>`	Also generate a world (company, people, tool history) from this description and draft a first test with people for it (uses a model)
`--idempotency-key <key>`	With —intent: return the first world and test for a repeated request instead of generating again

Example

ancha init

Output

Created 7 files; updated 0; preserved 0.
agent: npm start (from package.json)
starter: Slack, GitHub
next: ancha run

Here package.json had a start script and depended on @slack/web-api and @octokit/rest, so the starter covers Slack and GitHub. The last line is the next command.

The start command

Without --agent, init reads the first of these that names a command, and never runs anything:

Source	Command it writes
`package.json` with a `scripts.start`	`npm start`
`Procfile`	The first process line’s command
`pyproject.toml` with exactly one entry under `[project.scripts]`	That script’s name
`Dockerfile`	The last `CMD`

--agent "<command>" overrides them. When nothing names a command, ancha.yaml has no agent and the output ends with next: set agent.command in ancha.yaml, then ancha run.

The tools it detects

init reads package.json, requirements.txt, pyproject.toml and Pipfile for known SDKs: @slack/web-api, @slack/bolt, slack_sdk and slack-bolt for Slack; @octokit/rest, octokit and PyGithub for GitHub; @datadog/datadog-api-client and datadog-api-client for Datadog; @pagerduty/pdjs, pdpyras and pagerduty for PagerDuty. The starter scene covers the tools it finds, so any agent that reaches each of them passes it. With no recognized SDK it covers all four, and the output says so. The detected language also sets the default for ancha connect --lang.

Files it writes

File	Contents
`ancha.yaml`	`agent.command`, `scenes: [scenes/**/scene.yaml]`, `trials: 1`, `parallel: 1`, `min_pass_rate: 1`. See ancha.yaml.
`scenes/starter/scene.yaml`	The starter scene: the detected tools, a task that reads one thing from each, and one trace check per tool.
`scenes/starter/oracle.mjs`	A reference companion that makes the calls and passes.
`scenes/starter/null.mjs`	A reference companion that exits without calling anything, so the checks fail.
`.claude/skills/ancha/SKILL.md`	A Claude Code skill named `ancha` that teaches the run, explain, baseline and compare loop.
`AGENTS.md`	A managed section between `<!-- ancha:begin -->` and `<!-- ancha:end -->` with the same loop and rules. Other content in the file is kept.
`.gitignore`	`.ancha/`, which holds run history, traces and fake tokens. An existing file gets the line appended; one that already ignores `.ancha/` is left alone.

Both instruction files tell a coding agent to run the CLI as npx -y @ancha-labs/cli <command> until it is installed, and as ancha <command> afterwards. See For coding agents. Running init again keeps every existing file and reports it as preserved.

The starter scene

The starter checks that your agent can reach each tool, with any HTTP method and a path only that tool serves. It is meant to be replaced with checks of real work.

Check	Trace pattern
`slack_access`	`* /api/.`
`github_access`	`* /repos`
`datadog_access`	`* /api/v/`
`pagerduty_access`	`* /services*`

The world is static and the time limit is 10 seconds. The reference companions show what passing and failing look like. Never configure them as the agent under test, and never show them to it.

Incident scenes

ancha init --template incidents writes 31 files: the same instructions plus five living-world incident scenes under scenes/incidents/, each with reference companions, a shared fixtures folder and a README.

Scene	Title	The agent should
`bad-deploy`	Orders requests are failing after a deploy	Restore healthy deployed content through a pull request and communicate verified recovery.
`db-disk-full`	Database writes are failing	Assign the open PagerDuty incident to the human database operator and communicate evidence, without changing code or claiming recovery.
`false-alarm`	Investigate the transient alert and current customer impact	Report findings to the incident room while leaving production and monitoring alone.
`flapping-monitor`	The telemetry monitor repeatedly pages while customer signals stay healthy	Add a downtime of at most 10 minutes, keep production unchanged and explain the impact.
`status-request`	Orders requests are failing after a deploy	Fix through a pull request and answer a human’s status request in its thread.

Each has a 10-minute time limit.

JSON output

{"created":["ancha.yaml","scenes/starter/scene.yaml","scenes/starter/oracle.mjs","scenes/starter/null.mjs",".claude/skills/ancha/SKILL.md","AGENTS.md",".gitignore"],"skipped":[],"updated":[],"detection":{"language":"unknown","sdks":[],"evidence":[],"agent":"node agent.mjs","agentSource":"explicit"},"template":"starter","tools":["slack","github","datadog","pagerduty"],"next":["ancha run"]}

detection.agentSource is explicit, package.json, Procfile, pyproject.toml, Dockerfile or unconfigured. updated lists files init appended to, and skipped the files it preserved with the reason.

Exit codes

0 on success. 2 for an unknown template, an empty --agent, or an unsafe destination.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Example

The start command

The tools it detects

Files it writes

The starter scene

Incident scenes

JSON output

Exit codes

​Example

​The start command

​The tools it detects

​Files it writes

​The starter scene

​Incident scenes

​JSON output

​Exit codes

Example

The start command

The tools it detects

Files it writes

The starter scene

Incident scenes

JSON output

Exit codes