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
1---
2name: noodle
3description: >-
4 Operate the Noodle CLI — explain commands, find flags, create/edit .noodle.toml config.
5 Also covers writing skills for Noodle: the orders pipeline, task-type schedule fields,
6 stage composition, and the orders-next.json schema. Use when running noodle commands,
7 editing .noodle.toml, writing or updating a skill's schedule field, authoring new
8 task-type skills, or asking "how to run noodle", "noodle help", "configure noodle".
9---
10
11# Noodle
12
13Skills 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.
14
15## How the Loop Works
16
171. **Brief** — Noodle gathers project state into `.noodle/mise.json` (backlog, active agents, history, capacity, registered skills)
182. **Schedule** — the scheduler agent reads mise, writes `.noodle/orders-next.json`
193. **Dispatch** — Noodle promotes orders and spawns agent sessions
204. **Execute** — each agent runs in its own worktree with the assigned skill
215. **Merge** — completed work merges back to main
22
23## Skills
24
25A skill is a directory with a `SKILL.md`. The body is the agent's instructions. The frontmatter is metadata.
26
27**General skills** (no `schedule:`) are invoked directly by agents. Examples: `commit`, `debugging`.
28
29**Scheduled skills** (with `schedule:`) run autonomously. The scheduler reads the `schedule:` value as prose and uses judgment to decide when conditions are met.
30
31```yaml
32---
33name: quality
34description: Post-cook quality gate.
35schedule: "Follow-up stage after execute. Cross-provider review preferred."
36---
37```
38
39Skills live in `.agents/skills/` by default. Paths in `skills.paths` are searched in order; first match wins.
40
41For the full guide on writing skills, orders, and schedule fields, see [references/skill-authoring.md](references/skill-authoring.md).
42
43## Configuration
44
45Noodle reads `.noodle.toml` at project root. Scaffolded on first `noodle start`. Most projects only need:
46
47```toml
48mode = "supervised" # auto | supervised | manual
49
50[routing.defaults]
51provider = "claude"
52model = "claude-opus-4-6"
53
54[skills]
55paths = [".agents/skills"]
56```
57
58Full config reference: [references/configuration.md](references/configuration.md)
59
60## CLI
61
62All commands accept `--project-dir` (default: current directory, env: `NOODLE_PROJECT_DIR`).
63
64### Core
65
66| Command | Description |
67|---------|-------------|
68| `noodle start` | Start the noodle loop |
69| `noodle start --once` | Run one scheduling cycle and exit |
70| `noodle status` | Show runtime status (active agents, queue depth, loop state) |
71| `noodle reset` | Clear all runtime state (refuses if loop is running) |
72
73### Skills & Schemas
74
75| Command | Description |
76|---------|-------------|
77| `noodle skills` | List resolved skills |
78| `noodle skills list` | List all resolved skills |
79| `noodle schema <target>` | Print schema docs for a target |
80| `noodle schema list` | List available schema targets (`mise`, `orders`, `status`) |
81
82### Worktrees
83
84| Command | Description |
85|---------|-------------|
86| `noodle worktree create <name>` | Create a new linked worktree |
87| `noodle worktree create <name> --from <ref>` | Create from a specific branch or commit |
88| `noodle worktree exec <name> <command...>` | Run a command inside a worktree (CWD-safe) |
89| `noodle worktree merge <name>` | Merge a worktree branch into integration branch |
90| `noodle worktree merge <name> --into <branch>` | Merge into a specific target branch |
91| `noodle worktree list` | List all worktrees with merge status |
92| `noodle worktree prune` | Remove merged and patch-equivalent worktrees |
93| `noodle worktree cleanup <name>` | Remove a worktree without merging |
94| `noodle worktree cleanup <name> --force` | Remove even with unmerged commits |
95| `noodle worktree hook` | Run worktree session hook (used internally) |
96
97### Events
98
99| Command | Description |
100|---------|-------------|
101| `noodle event emit <type>` | Emit an external event into the loop |
102| `noodle event emit <type> --payload <json>` | Emit with a JSON payload |
103| `noodle event emit <type> --session <id>` | Emit to a specific session's event log |
104
105Full CLI reference: https://poteto.github.io/noodle/reference/cli
106
107## Troubleshooting
108
1091. **"fatal config diagnostics prevent start"** — Check `.noodle.toml` against `noodle schema`.
1102. **Missing adapter scripts** — Create scripts or update paths in config.
1113. **Stale worktrees** — `noodle worktree list`, then `noodle worktree prune`.
112
113## References
114
115- [references/skill-authoring.md](references/skill-authoring.md) — writing skills: pipeline, orders schema, schedule fields, stage composition, full examples
116- [references/configuration.md](references/configuration.md) — full .noodle.toml config reference
117- https://poteto.github.io/noodle/concepts/adapters — adapter setup, script contracts, provider examples
118- https://poteto.github.io/noodle/concepts/scheduling — how the loop schedules and dispatches work
119- https://poteto.github.io/noodle/concepts/skills — skill discovery, composition, scheduled vs general
120- https://poteto.github.io/noodle/concepts/runtimes — process, sprites, and runtime routing
poteto