Skip to content

Get started

Start with your first cycle

Install the CLI, check your environment and turn a request into verifiable work.

Install and check

Use Node.js 20 or later, Git and a repository with at least one commit: a thread starts from the base commit. The package is @orkastery/cli; its executable is ork. The core contains no AI model. Your configured agent runtime executes the phases: claude-bg (the claude binary), the default, or the Codex CLI. This documentation describes version 0.6.10; check the published version with npm view @orkastery/cli version. The package ships nine pinned runtime dependencies, including the code graph analyzers; the code graph needs Node 20.19, 22.12 or later.

To use Codex only, move each block of the allowed modes to it with ork setup <mode> --bloco N --runtime codex --model <model>. After that, a missing claude is only an ork doctor warning.

npm install -g @orkastery/cli
ork doctor
ork demo

Prepare the project

Run ork init at the root of your repository. It generates the manifest, which defines checks, conduction mode and runtime integration, plus an Orkastery block in AGENTS.md. The ork state (.orkastery/) and the thread worktrees belong to the machine, not to the repository: they stay out of git without changing your .gitignore. Commit the manifest before your first thread. Outside a git repository, ork init refuses without creating anything (init.fora-do-repositorio), and ork doctor warns when the orkastery.yaml it read lies outside the repository, such as one left by an old ork init in a parent folder.

Then complete onboarding. Record credential variable names only; values stay in the process environment or the host vault. The maestro stage also offers conversation preferences: language, timezone and depth, or opt-out. In version 0.6.10, that language (owner.language) also applies to ork doctor, ork init, ork onboarding, ork experiencia show, ork thread new, ork thread status, ork phase list, ork phase run, ork verify, ork ship, ork pulse, ork master, ork retry plan, ork retry run, ork roadmap status and the help, which print English when the choice is English; without a choice, the locale (LC_ALL, LC_MESSAGES, LANG) decides. The other commands still print Brazilian Portuguese, and --json does not change with the language. Check the effective values with ork experiencia show --json; the orchestration experience guide explains installation in each host. Once answered, the maestro step writes the owner block into orkastery.yaml: commit the manifest again before the first ork ship, because a dirty main tree blocks the merge with tree.blocked.

ork init --name "my-product" --abbrev prd
git add orkastery.yaml AGENTS.md
git commit -m "ork init"
ork onboarding
git commit -m "ork onboarding" orkastery.yaml
ork experiencia show --json
ork doctor

Create a thread

A thread brings together the goal, plan, implementation, verification and delivery. Start with a small request and an observable criterion. With worktree.por_thread: true, which ork init writes, the thread is created with its own worktree and an ork/<slug> branch, no flag needed; --dry-run shows the worktree before creating it, and --sem-worktree creates the thread without one, but then ork ship on the base branch is blocked. Use the returned ID in subsequent commands; the example ID is not a real receipt.

Prefer claims backed by a focused test: a claim that runs the whole suite gets a warning when recorded and is refused by ork ci prepare.

ork thread new "fix the date filter" --modo classic --dry-run
ork thread new "fix the date filter" --modo classic
ork thread status <thread>
ork phase list <thread>

Close your first thread in #Fast

The smallest full cycle uses #Fast mode: a single GO phase whose only HITL point is approving the push. ork phase run dispatches the request to the runtime, which works in the thread’s worktree. Record the claim, what the agent states plus the command that judges it, and ork verify re-runs it on the real HEAD together with the manifest checks. ork ship merges and pushes with your authorization; without --autorizar-push it stops with human.pending and prints the command that authorizes it. ork master by default closes the thread with the index derived from the ledger, and ork thread status then shows status fechada (closed).

If ork phase run stops with runtime.workspace-untrusted, run claude once in the worktree, accept the directory trust prompt and exit; then ork retry run <thread> dispatches GO again with the same recorded prompt. ork pulse shows the same instruction. Other CLI commands, such as ork claims add, still print Brazilian Portuguese: the README glossary, Reading the CLI in English, translates what they show. The repository quickstart details each step in #Classic, which also has HITL points at the goal, the plan and the evidence.

ork thread new "fix the date filter" --modo fast
ork phase run <thread> GO --prompt "<the request>"
ork claims add <thread> <file> --claim "<statement>" --verificar "<test command>"
ork verify <thread>
ork ship <thread> --para main --autorizar-push <you>
ork master <thread> --aceitar-omissao
ork thread status <thread>

Confirm before proceeding

A blocked ork doctor prevents a new dispatch; a warning never blocks. Each failure carries its fix: before ork init, for example, the missing manifest points to ork init. Resolve the reported cause and rerun it. The demo is a local exercise in a claim that fails and then passes; it does not establish that your project is ready for publication. The graph analyzers line shows the typescript and micromark versions that ork grafo uses and, when they are missing, warns with the fix.

Activate it in your host

Copying the adapter files does not activate the Claude Code plugin: run the activation the installer prints, then install the project MCP server. In a session opened in the project, say orkastery maestro or use /orkastery:ork; the phases are /orkastery:goal, /orkastery:plan, /orkastery:go, /orkastery:check, /orkastery:ship and /orkastery:master. In Codex, ork adapter install codex adds the $ork entry to the project skills.

The same plugin, without the project hooks, is also available from the repository marketplace. Choose one of the two paths, because both are named orkastery.

ork adapter install claude-code
claude plugin validate "$PWD/.claude/plugins/orkastery"
claude plugin marketplace add "$PWD/.claude/plugins/orkastery" --scope project
claude plugin install orkastery@orkastery --scope project
ork mcp install --project "$PWD" --host claude-code

Try it without an account

ork demo runs offline without an account: it shows a false claim failing and its correction passing. The hermetic core CI suite requires no agent runtime. Running phases uses the project’s configured runtime and profile.

ork demo
ork --version