@poteto/noodle
Orchestrate agents using skills
| name | noodle |
| description | >- |
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
Loading...
Select a file to preview
Analyzing security...
Checking scan reports and verification data.
Bill of Materials
Everything this skill can do — files, network, commands, and more.