Gear check.

Before you run the cycle, lay the gear. This chapter covers everything you install or sign in to once per machine — the accounts, the runtime, the editor, the CLI. Past this checklist, the next chapter (Workflow) is the deep dive on actually driving the cycle.

Prerequisites

Have these in place before anything else:

• A naholo account and a project. Sign up, create or join a project. Operations belong to projects.
• A local project directory. A cloned repo, or any working folder you want the agent to ship code into.
• Node.js v22 or newer, plus npm or pnpm. Needed to install and run the naholo CLI.
• A coding agent. Claude Code is the supported one today. Codex support is on the way.

Install VS Code + the Claude Code extension

Install Claude Code, then VS Code, then add the Claude Code extension to VS Code from the marketplace. That pairing is the canonical setup.

OPERATION.md is durable — a real file on disk that survives every checkpoint, /clear, and restart between /infil and /exfil. The cycle's reviews happen against that file, with you hand-editing WARNING ORDER and OPERATION ORDER between the agent's passes. That wants a proper text editor sitting next to the agent. Most chat-app agent interfaces can edit the file too, but the writing experience is usually rough enough that you'll want a separate editor anyway — VS Code + the extension just folds both windows into one.

Install the CLI

Install naholo globally from npm.

# with npm
npm install -g @naholo/cli

# or with pnpm
pnpm add -g @naholo/cli

The binary registers as naholo on your PATH. Confirm with naholo --version.

Log in

naholo login

Opens a browser for device-flow auth. Confirm the word pair shown in the CLI matches the one in the browser. On success, a user API token is saved to ~/.naholo/profiles/{name}.yml. Run this once per machine.

Pick an init mode

There are two ways to attach a repo to a project. Pick based on whether anyone else on the project will use naholo from this codebase.

naholo init — team setup.

# in the root of your repo
naholo init

Writes .naholo/config.yml (project id, slug, default operator id — commit this) and .mcp.json (usually gitignored). Anyone else who clones the repo can run naholo login and inherit the project wiring from the committed config.

naholo covert init — solo setup.

naholo covert init

Same effect as naholo init but the project wiring lives at ~/.naholo/covert-ops/ instead of in the repo. Nothing lands in the working tree, nothing gets committed. Pick this when you’re the only person on the project who uses naholo and you do not want the config visible to teammates.

The caveat: covert config is per-working-directory. Each git worktree you create is a new working directory, so each worktree needs its own naholo covert init. Regular naholo init does not have this problem because the config is committed and travels with the worktree.

Either flow prompts to install the agent skills into .claude/skills/ (default yes). If you decline now, run naholo install-skills later — same outcome. Re-run naholo install-skills after every CLI upgrade too, so the bundled skills match the binary you just upgraded.