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.tomlagainstnoodle schema. - Missing adapter scripts — Create scripts or update paths in config.
- Stale worktrees —
noodle worktree list, thennoodle 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