| name | noodle |
| description | 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". |
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.
---
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:
mode = "supervised"
[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
