noodle

Original：🇺🇸 English

Translated

Operate the Noodle CLI — explain commands, find flags, create/edit .noodle.toml config. Also covers writing skills for Noodle: the orders pipeline, task-type schedule fields, stage composition, and the orders-next.json schema. Use when running noodle commands, editing .noodle.toml, writing or updating a skill's schedule field, authoring new task-type skills, or asking "how to run noodle", "noodle help", "configure noodle".

20installs

Sourcepoteto/noodle

Added on2026-09-07

NPX Install

npx skill4agent add poteto/noodle noodle

SKILL.md Content

View Translation Comparison →

Noodle

Skills that run themselves. Write skills with a

schedule:

field describing when they should run. Noodle's scheduler agent reads those descriptions, writes orders, and the loop spawns agents in isolated worktrees to do the work.

How the Loop Works

Brief — Noodle gathers project state into
```
.noodle/mise.json
```
(backlog, active agents, history, capacity, registered skills)
Schedule — the scheduler agent reads mise, writes
```
.noodle/orders-next.json
```
Dispatch — Noodle promotes orders and spawns agent sessions
Execute — each agent runs in its own worktree with the assigned skill
Merge — completed work merges back to main

Skills

A skill is a directory with a

SKILL.md

. The body is the agent's instructions. The frontmatter is metadata.

General skills (no

schedule:

) are invoked directly by agents. Examples:

commit

,

debugging

.

Scheduled skills (with

schedule:

) run autonomously. The scheduler reads the

schedule:

value as prose and uses judgment to decide when conditions are met.

yaml

---
name: quality
description: Post-cook quality gate.
schedule: "Follow-up stage after execute. Cross-provider review preferred."
---

Skills live in

.agents/skills/

by default. Paths in

skills.paths

are searched in order; first match wins.

For the full guide on writing skills, orders, and schedule fields, see references/skill-authoring.md.

Configuration

Noodle reads

.noodle.toml

at project root. Scaffolded on first

noodle start

. Most projects only need:

toml

mode = "supervised"  # auto | supervised | manual

[routing.defaults]
provider = "claude"
model = "claude-opus-4-6"

[skills]
paths = [".agents/skills"]

Full config reference: references/configuration.md

CLI

All commands accept

--project-dir

(default: current directory, env:

NOODLE_PROJECT_DIR

).

Core

Command	Description
`noodle start`	Start the noodle loop
`noodle start --once`	Run one scheduling cycle and exit
`noodle status`	Show runtime status (active agents, queue depth, loop state)
`noodle reset`	Clear all runtime state (refuses if loop is running)

Skills & Schemas

Command	Description
`noodle skills`	List resolved skills
`noodle skills list`	List all resolved skills
`noodle schema <target>`	Print schema docs for a target
`noodle schema list`	List available schema targets ( `mise` , `orders` , `status` )

Worktrees

Command	Description
`noodle worktree create <name>`	Create a new linked worktree
`noodle worktree create <name> --from <ref>`	Create from a specific branch or commit
`noodle worktree exec <name> <command...>`	Run a command inside a worktree (CWD-safe)
`noodle worktree merge <name>`	Merge a worktree branch into integration branch
`noodle worktree merge <name> --into <branch>`	Merge into a specific target branch
`noodle worktree list`	List all worktrees with merge status
`noodle worktree prune`	Remove merged and patch-equivalent worktrees
`noodle worktree cleanup <name>`	Remove a worktree without merging
`noodle worktree cleanup <name> --force`	Remove even with unmerged commits
`noodle worktree hook`	Run worktree session hook (used internally)

Events

Command	Description
`noodle event emit <type>`	Emit an external event into the loop
`noodle event emit <type> --payload <json>`	Emit with a JSON payload
`noodle event emit <type> --session <id>`	Emit to a specific session's event log

Full CLI reference: https://poteto.github.io/noodle/reference/cli

Troubleshooting

"fatal config diagnostics prevent start" — Check
```
.noodle.toml
```
against
```
noodle schema
```
.
Missing adapter scripts — Create scripts or update paths in config.

Stale worktrees —

noodle worktree list

, then

noodle worktree prune

.

References

references/skill-authoring.md — writing skills: pipeline, orders schema, schedule fields, stage composition, full examples
references/configuration.md — full .noodle.toml config reference
https://poteto.github.io/noodle/concepts/adapters — adapter setup, script contracts, provider examples
https://poteto.github.io/noodle/concepts/scheduling — how the loop schedules and dispatches work
https://poteto.github.io/noodle/concepts/skills — skill discovery, composition, scheduled vs general
https://poteto.github.io/noodle/concepts/runtimes — process, sprites, and runtime routing