# Noodle

Operate the Noodle CLI, explain commands, find flags, create/edit .noodle.toml config.

- Repository: https://github.com/poteto/noodle (577 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-03-19
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add poteto/noodle --skill noodle -g -a claude-code -y`
Codex: `npx skills add poteto/noodle --skill noodle -g -a codex -y`
Cursor: `npx skills add poteto/noodle --skill noodle -g -a cursor -y`
Gemini CLI: `npx skills add poteto/noodle --skill noodle -g -a gemini-cli -y`

## Description

Operate the Noodle CLI, explain commands, find flags, create/edit .noodle.toml config. Also covers writing skills for Noodle: the orders pipeline, task-type schedule fields, stage composition, and the orders-next.json schema. Use when running noodle commands, editing .noodle.toml, writing or updating a skill's schedule field, authoring new task-type skills, or asking "how to run noodle", "noodle help", "configure noodle".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

1. **Brief**, Noodle gathers project state into `.noodle/mise.json` (backlog, active agents, history, capacity, registered skills)
2. **Schedule**, the scheduler agent reads mise, writes `.noodle/orders-next.json`
3. **Dispatch**, Noodle promotes orders and spawns agent sessions
4. **Execute**, each agent runs in its own worktree with the assigned skill
5. **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.

```yaml
---
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](references/skill-authoring.md).

## Configuration

Noodle reads `.noodle.toml` at project root. Scaffolded on first `noodle start`. Most projects only need:

```toml
mode = "supervised"  # auto | supervised | manual

[routing.defaults]
provider = "claude"
model = "claude-opus-4-6"

[skills]
paths = [".agents/skills"]
```

Full config reference: [references/configuration.md](references/configuration.md)

## CLI

All commands accept `--project-dir` (default: current directory, env: `NOODLE_PROJECT_DIR`).

### Core

The rest: https://github.com/poteto/noodle/blob/HEAD/.agents/skills/noodle/SKILL.md