Noodle is a skill-based agent orchestration framework. You write skills (markdown files describing what an agent should do) and Noodle's loop schedules and runs them. Think kitchen brigade: a head chef (the scheduler) reads the backlog, writes orders, and dispatches line cooks (agents) to do the work in isolated worktrees.
The scheduler reads .noodle/mise.json (project state: backlog, active agents, history, registered skills) and writes .noodle/orders-next.json. The loop promotes orders and spawns agent sessions. Each agent gets a skill loaded as its instructions. When the agent finishes, its worktree merges back.
The minimum loop is schedule then execute. Noodle handles merging completed work back to main. You can add more stages (quality review, reflection, etc.) by writing skills for them.
Noodle adds one thing to skills: a schedule field in the YAML frontmatter. Skills without it work normally (agents invoke them directly). Skills with it become autonomous. The scheduler reads the schedule value as prose and decides when conditions are met.
schedule: "After execute completes and all tests pass."A working loop needs at least two scheduled skills: a schedule skill (reads backlog, writes orders) and one task-type skill like execute (does the work).
Work through these steps in order. Each has a skip condition. If the check passes, move on.
Skip if: noodle --version succeeds.
Detect the platform and install:
- macOS:
brew install poteto/tap/noodle - Linux/Windows: Download the binary for your platform from
https://github.com/poteto/noodle/releases/latestand place it on PATH.
Verify: noodle --version prints a version string.
Skip if: .agents/skills/noodle/SKILL.md AND all files in .agents/skills/noodle/references/ exist.
If only some files exist (interrupted install), fetch the missing ones.
The noodle skill teaches agents how to use the CLI and write skills. Copy this one verbatim. Everything else you write yourself.
Fetch these files from GitHub:
https://raw.githubusercontent.com/poteto/noodle/main/.agents/skills/noodle/SKILL.md
https://raw.githubusercontent.com/poteto/noodle/main/.agents/skills/noodle/references/skill-authoring.md
https://raw.githubusercontent.com/poteto/noodle/main/.agents/skills/noodle/references/configuration.md
Write them to the same paths under the project root (.agents/skills/noodle/...). Create directories as needed.
Skip if: .noodle.toml exists at the project root.
Ask the user which provider they use: Claude or Codex. Then generate .noodle.toml:
For Claude:
mode = "supervised"
[routing.defaults]
provider = "claude"
model = "claude-opus-4-6"
[skills]
paths = [".agents/skills"]
[adapters.backlog.scripts]
sync = "adapters/backlog-sync"
add = "adapters/backlog-add"
done = "adapters/backlog-done"
edit = "adapters/backlog-edit"For Codex:
mode = "supervised"
[routing.defaults]
provider = "codex"
model = "gpt-5.4"
[skills]
paths = [".agents/skills"]
[adapters.backlog.scripts]
sync = "adapters/backlog-sync"
add = "adapters/backlog-add"
done = "adapters/backlog-done"
edit = "adapters/backlog-edit"Then fetch the default adapter scripts from GitHub and write them to adapters/:
https://raw.githubusercontent.com/poteto/noodle/main/defaults/adapters/backlog-sync
https://raw.githubusercontent.com/poteto/noodle/main/defaults/adapters/backlog-add
https://raw.githubusercontent.com/poteto/noodle/main/defaults/adapters/backlog-done
https://raw.githubusercontent.com/poteto/noodle/main/defaults/adapters/backlog-edit
Create adapters/ and write each file there. Make them executable (chmod +x).
Minimal config. The user can expand it later. See the configuration reference for all options.
Skip if: .gitignore already contains .noodle/.
Grep .gitignore for .noodle/. If absent (or .gitignore doesn't exist), append:
# Noodle runtime state
.noodle/
Skip if: .agents/skills/schedule/SKILL.md AND .agents/skills/execute/SKILL.md both exist.
Start by understanding how your human works. Read the conversation history in ~/.claude/ and ~/.codex/ for this project. Look at what commands they run, how they test, how they review code, what they ask agents to do repeatedly. This is the ground truth for what the skills should encode. Existing code, CI config, and test commands fill in the rest.
Then browse https://github.com/poteto/noodle/tree/main/.agents/skills/ for patterns. Use Noodle's own schedule and execute skills as starting points, but adapt them to this project. Don't copy. The noodle skill's reference docs (from step 2) cover the orders schema and CLI details.
Skills describe process, not individual tasks. The order tells the agent what to do. The skill tells it how. Everything in the skill should be reusable across every backlog item. Don't bake current task details into the skill, and don't use the current backlog item in examples. Use generic placeholders instead.
Schedule skill (schedule/SKILL.md): Reads project state and writes orders. Reads the backlog from .noodle/mise.json (synced from todos.md or the configured backlog adapter). Writes orders-next.json, not orders.json directly. Use noodle schema orders to get the schema. Routes to providers/models based on routing.defaults in .noodle.toml. Include a schedule frontmatter field, something like "when orders are empty, after backlog changes, or when session history suggests re-evaluation."
Execute skill (execute/SKILL.md): Describes how work gets done, not what work to do. The order's prompt provides task context at runtime. The skill covers: worktree workflow (noodle worktree create/merge, never on main), verification commands for this project's stack, commit conventions, and scope discipline. Don't include sections about specific features or domains (like "for auth work, do X"). Include a schedule frontmatter field, something like "when backlog items are ready for implementation."
Skip if: todos.md exists at the project root.
Create todos.md in the default backlog-adapter format:
# Todos
<!-- next-id: 1 -->
## Inbox
1. [ ] <first task>Ask the user what they want to work on and set that as the first task line (1. [ ] ...).
Also ask if they want to sync backlog items from another source (GitHub Issues, Linear, Jira, a custom script, etc.). If yes, configure a backlog adapter in .noodle.toml. See the noodle skill's configuration reference for adapter options.
Ask the user: "Do you want brainmaxxing? It adds a brain/ vault for persistent memory across sessions, plus reflect, meditate, and ruminate skills."
If yes, follow the install instructions at https://github.com/poteto/brainmaxxing.
If no, move on.
Tell the user to start the loop:
noodle start
Noodle scaffolds .noodle/ runtime state, the scheduler reads the backlog, and the loop begins.