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"  # 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