Start with one real project.

Updated September 15, 2026Read as Markdown ↗

Connect a small project you know well. Start by observing it, then decide how much work to hand over.

What it takes: steps 1–4 below get you to a first capability map and an opening checkpoint. On a repository you already know, that is an afternoon rather than a sprint — most of it is choosing which capability matters and which signal is readable, not configuration. Steps 5–6, the permissions and the scheduled watcher, are a separate decision you can make later.

1. Check the basics

You need Node.js 22.16.0 or newer, an installed and signed-in coding CLI, and the GitHub CLI authenticated for your project. Your project also needs at least one signal a machine can read: a test, a log check or a product metric.

node --version
gh auth status

2. Open the Factory checkout

After access is granted, clone Factory and install its dependencies. The current internal package and CLI use the name northstar.

git clone https://github.com/khaoss85/agentic-factory.git
cd agentic-factory
npm ci
npm run northstar -- preflight --agent codex

Use --agent claude or --agent grok if that is your configured CLI. Preflight checks that the executable exists; it cannot independently confirm every provider’s login. Sign in through your CLI before starting work.

3. Let your agent guide the connection

Open your coding agent in the Factory directory and ask:

Connect Factory to my project at /absolute/path/to/my-app.
Read .agents/skills/onboard-project/SKILL.md and follow it.
Start in observation mode. Explain what you found before running work.

The onboarding workflow inspects the project, proposes what to watch, sets up a project pack and guides the first audit. Keep credentials in the project’s existing secret storage.

4. Inspect the project and open the board

Use the actual pack path produced during onboarding in place of packs/my-app.

npm run northstar -- checkpoint --pack packs/my-app
npm run northstar -- serve --packs packs

Open the local URL printed by the server. Look at the mapped capabilities, open problems and missing evidence before enabling automated work.

5. Choose your operating boundaries

Observation, implementation, merge and release are different permissions. Configure the project’s autonomy contract before running an agent. The onboarding guide walks you through that choice.

For an already configured project where you have authorized execution:

npm run northstar -- run --pack packs/my-app

6. Keep checking on a schedule

After the pack’s schedule, run command and permissions are configured, start the periodic watcher:

npm run northstar -- watch --pack packs/my-app

Keep that process running on an awake host. The watcher measures at the configured times and launches the run command when the checkpoint finds work. It also records observations when there is nothing to repair. This is how operation can continue across days.

Each worker run still has time and invocation limits. Authentication, subscription quotas, human decisions and missing evidence can stop work. The project’s recorded history survives an individual agent session; multi-day operation does not mean one unlimited model call.

To inspect the full command reference in your installed checkout:

npm run northstar -- --help