pome init

Synopsis

pome init [options]

Description

pome init writes the manifest Pome reads on every run, pome.json. Run it once per agent project, before your first pome run. What else it writes depends on where you run it. In an empty directory it also scaffolds a starter library — tasks/, examples/agents/, and runs/ — so there is something to run in the next minute. In a directory that already has a package.json, it writes the manifest and nothing else: that is the bring-your-own-agent case. --bare and --starter override that decision in either direction. --example <id> skips scaffolding altogether and fetches a complete runnable example — agent, tasks, manifest and lockfile — into ./<id>. See Start from an example. pome init never overwrites an existing manifest. The one exception is --sdk, which updates agent.framework and command in the manifest already there. Hosted runs also need pome login and pome register agent <name>, which links the project to a cloud agent so its runs land on the dashboard together.

Options

Flag	Default	Description
`--sdk <name>`	—	Scaffold for one agent SDK: `claude` or `claude-managed`. Writes the SDK’s example agent file, points `command` at it, and pre-fills `agent.framework` so the dashboard badges the run correctly. `claude-managed` is not available yet and exits `2` with the reason.
`--bare`	on in a directory that has a `package.json`	Write only the manifest. Skips the starter task library and the sample agents, and leaves `command` unset for you to fill in.
`--starter`	off	Write the full starter library even in an existing project. Cannot be combined with `--bare`.
`--example <id>`	—	Fetch the bundled example named `<id>` into `./<id>` instead of scaffolding a starter project. Cannot be combined with `--sdk`, `--bare` or `--starter`.

What it writes

In a new project:

Path	Purpose
`pome.json`	The manifest: the agent’s slug, its start command, the task directory, and the pass threshold.
`tasks/`	Your task markdown files. Add more from the bundled library with `pome tasks <twin> --copy`.
`examples/agents/`	Sample agent implementations, including the one `command` points at.
`runs/`	Default artifacts directory for `pome run`.

The manifest it writes looks like this:

{
  "$schema": "https://pome.sh/schemas/v1/pome.json",
  "agent": { "slug": "my-triage-bot" },
  "command": "node examples/agents/scripted-triage-agent.ts",
  "tasks": "tasks",
  "artifacts_dir": "runs",
  "pass_threshold": 100
}

agent.slug starts as a slug derived from the directory name, so the manifest validates before you have an account. pome register agent replaces it with the slug the cloud assigns. The agt_ agent id is deliberately not written to the manifest — a committed opaque id lets a fork keep pushing runs at an agent its new owner cannot see. Pome caches it in .pome/link.json, local and uncommitted, and re-resolves it from the slug when it is missing.

Set up a project

pome init
pome login
pome register agent my-triage-bot
pome tasks github --copy
pome run tasks/01-bug-happy-path.md

Start from an example

Every bundled example is named by an id, never by a path inside pome-sh/digital-twins. --example fetches the one you name into ./<id>:

npx @pome-sh/cli@latest init --example support-triage
cd support-triage && npm install

An id is a stable name, so upstream moves and renames do not break it — and an id that does not exist fails immediately:

$ pome init --example nope
Unknown example "nope". Available examples:

  gmail-retry-notify        A Gmail notification agent that must retry throttled (429) sends without duplicating already-delivered ones.
  merge-agent               A model-driven GitHub PR merge agent (Vercel AI SDK) run against the local GitHub twin's REST surface.
  minimal-viktor            Minimal-viktor, an MVP viktor.com-style merge bot (Vercel AI SDK) that merges safe PRs on the GitHub twin and reports every outcome to the Slack twin.
  minimal-viktor-langgraph  Minimal-viktor built on LangGraph, observed via OpenInference OTel instrumentation.
  pr-summary-agent          A Claude Agent SDK agent that summarizes pull requests on the local GitHub twin.
  pr-summary-review         A Claude Agent SDK agent that summarizes and reviews pull requests on the local GitHub twin.
  support-triage            Pome hero example: the support-triage examinee as a local Claude Agent SDK subprocess, wired to the GitHub + Slack twins over MCP.
  triage-agent              A Claude Agent SDK agent that triages issues on the local GitHub twin.
  braintrust                Braintrust Eval() gives every dataset row its own hosted Pome sandbox, and each Pome criterion comes back as its own Braintrust score column.
  langsmith                 LangSmith's evaluate() gives every dataset row its own hosted Pome sandbox, and each Pome criterion comes back as its own LangSmith feedback key.

Run `pome init --example gmail-retry-notify` to scaffold one.

The list ships inside the CLI — pome init --help prints the same set, offline — so it cannot name an example that no longer exists. The files come over the network, from the commit that built the CLI you are running, so an older CLI scaffolds the example as it stood then. The ids the rest of these docs walk through:

Id	Walked through in
`support-triage`	The graded capstone
`minimal-viktor-langgraph`	Cross-twin consistency
`braintrust`	Use your existing eval stack
`langsmith`	Use your existing eval stack

`pome register agent`

Create a cloud agent under your team and write its slug to the manifest.

pome register agent <name>

Flag	Default	Description
`--force`	off	Re-resolve the agent even when `.pome/link.json` already links one.
`--twins <list>`	the manifest’s `twins`, else the cloud’s default	Comma-separated twins this agent may exercise, for example `github,slack`. Unioned with the manifest’s `twins`.

Plus the global flags — --api-url, --artifacts-dir, and -V, --version.

Examples

Scaffold a project. In an empty directory this writes the starter library too; in a repo that already has a package.json it writes only the manifest:

pome init

Force the starter library into an existing repo anyway, to read the samples:

pome init --starter

Write only the manifest in an empty directory, when you already have an agent elsewhere:

pome init --bare

Scaffold against the Claude Agent SDK, which writes the example agent and pre-fills agent.framework:

pome init --sdk claude

Fetch a complete bundled example instead of a starter project, into ./support-triage:

pome init --example support-triage

Exit status

Code	Meaning
0	The manifest, and any scaffold, are written.
2	`--sdk` names an SDK that does not exist or is not available yet; `--example` names an id that does not exist, and the message lists every id that does; `./<id>` already exists and is not empty; or two flags that exclude each other were passed together.

CLI

MCP

REST API

Terminology

Troubleshooting

Synopsis

Description

Options

What it writes

Set up a project

Start from an example

`pome register agent`

Examples

Exit status

See also

​Synopsis

​Description

​Options

​What it writes

​Set up a project

​Start from an example

​pome register agent

​Examples

​Exit status

​See also

Synopsis

Description

Options

What it writes

Set up a project

Start from an example

`pome register agent`

Examples

Exit status

See also