agentleFS
noodle-restnoodle-rest/noodle/AGENTS.md

noodle

AGENTS.md403 starsChanged 2 days agoApache-2.0View on GitHub

Terminal REST client. Inspect, send, and iterate on HTTP requests from YAML files on disk. Built with OpenTUI (React binding) on Bun.

  • Pipes a download into a shell
  • Reads credentials
  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. wilfredinni/noodle★ 403100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

14 rules. About 0 are common, 3 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep Save/Open actions centralized in commandActions.ts.

    line 268
  2. Very specific:

    Oxfmt check covers: only ./src ./tests; .agents/ is not included.

    line 297
  3. Very specific:

    Error re-throws: must preserve { cause: e }, except at redaction boundaries where the original error exposes secrets or local paths.

    line 314
  4. Very specific:

    Notifications and completion: Keep transient Toast non-focusable.

    line 324
  5. Very specific:

    All except fixed keys can be overridden in YAML:

    line 335
  6. Distinctive:

    When a folder is selected, the folder targets replace the request and response targets:

    line 410
  7. Very specific:

    Use Ctrl+Alt+X on an external script to open its validated file in the configured editor.

    line 469
  8. Very specific:

    Never use fixed delays (setTimeout, Bun.sleep, or equivalent) to wait for asynchronous test state.

    line 563
  9. Very specific:

    Before handing off any changed asynchronous test, run its file with bun test <file> --rerun-each=10 and report the result.

    line 565
  10. Distinctive:

    Use project-scoped custom agents only for an independent final review of materially relevant changes.

    line 569
  11. Distinctive:

    If a change materially spans both areas, the two reviews may run in parallel.

    line 573
  12. Very specific:

    When the user types /graphify, use the installed graphify skill or instructions before doing anything else.

    line 579
  13. Very specific:

    If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.

    line 584
  14. Very specific:

    Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.

    line 585

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — noodle

Terminal REST client. Inspect, send, and iterate on HTTP requests from YAML files on disk. Built with OpenTUI (React binding) on Bun.

Quick commands

bun install
bun run dev                           # local services + TUI with dev/collection
bun run dev:check                     # validate the local development collection
bun test                              # all tests
bun test tests/lang.test.ts           # single file
bun run audit                         # fail on vulnerable dependencies
bun run lint                          # oxlint
bun run typecheck                     # tsc --noEmit
bunx oxfmt --check ./src ./tests      # format check (oxfmt, only src+tests)
bun run build:bin                    # compile standalone binary via bun build --compile
bun run build:homebrew --opentui-source <dir> --zig <path> # source-build host native assets
bun run release:context              # summarize public surfaces changed since the latest tag
bun run release:check -- --tag vX.Y.Z # validate code, docs site, and release readiness

CLI usage

noodle [<path>] [--collection <dir>] [--env <name>] [--noproxy] [--insecure]
noodle import <source> [--format <format>] [--output <dir>]
noodle export <collection> --format <openapi|postman> --output <file|dir>
noodle update
noodle agent install [--json] [--force]
noodle workspace list [--json]
noodle collection run <path> [<target>...] [--env <name>] [--tag <tag>]... [--exclude-tag <tag>]... [--fail-fast] [--delay <milliseconds>] [--data <file>] [--dry-run] [--noproxy] [--insecure] [--json | --reporter junit] [--output <file>]
noodle collection <create|init|list|inspect|format|audit> ... [--json]
noodle request <create|run> ... [--noproxy] [--insecure] [--json]
noodle request run <id> --collection <dir> [--body] [--headers] [--cookies] ...
noodle request run <id> --collection <dir> [--output/-o <file>] ...
noodle cookie <list|clear> --collection <dir> [--json]
noodle environment set <key> <value> --env <name> [--collection <dir>] [--json]
noodle secret <set|list|delete> ... --env <name> [--collection <dir>] [--json]
  • Default command (TUI mode): optional positional <path> (use . for current directory), --collection/-c, --env/-e, --noproxy, and --insecure. Positional path overrides --collection; supplying both is invalid. Without either, the first existing registered collection in ~/.config/noodle/config.yml is used, then the current directory. --noproxy forces direct connections and --insecure disables TLS verification for that invocation.
  • Import subcommand: source (positional, required), --format/-i (openapi, swagger, postman, or insomnia; auto-detected if omitted), --output/-o (default: ./collections). Postman and Insomnia importers asynchronously preserve source that passes conservative static compatibility checks and compile-only QuickJS syntax validation, without executing it or translating foreign APIs. Postman pre events map to collection/folder/request pre; only request test events map to tests. Insomnia preserves request pre/post hooks only. Unconverted scripts produce ordered warnings with safe item/phase, unsupported names, and reason metadata. Any import retaining scripts or tests requires a new collection; current or existing targets are rejected before writes. TUI warnings appear in a scrollable notification before the new-collection open confirmation.
  • Export subcommand: collection (positional, required), --format (openapi or postman), and --output/-o (a file for OpenAPI, or a new/empty directory for Postman). Postman creates collection.postman_collection.json plus one redacted environment file per environment; it preserves literal request values except that @/ file paths expand to absolute home paths, so review exports for secrets and local path disclosure before sharing.
  • Update subcommand: Self-update. Windows x64 stages a verified executable and reports a required restart plus a diagnostic log; its helper replaces the executable after Noodle exits. Reads https://noodlerest.dev/update.json, caches verified release metadata for one hour (with a seven-day stale fallback), and SHA-256 verifies standalone binaries before replacement. Detects Homebrew installs and prints Run: brew upgrade noodle without running it; JSON returns data.status: "homebrew_managed" and data.command: "brew upgrade noodle", including with --force; unavailable in Bun development runtime.
  • Agent subcommand: agent install writes the embedded noodle-use skill to ~/.agents/skills/noodle-use and links detected Claude, Cursor, Codex, and OpenCode installations to that managed copy. It preserves unmanaged targets by default and reports every conflict; --force deliberately replaces all reported paths with backup-backed rollback if any target fails. Existing managed installations refresh after successful standalone, TUI standalone, and curl-installer updates. After a Homebrew upgrade, run noodle agent install to refresh the managed skill; refresh failures do not roll back Noodle and include a retry command.
  • Automation commands: workspace list, workspace audit [--fix]; collection create, init, list, inspect, format, audit [--fix], run [<target>...] [--env] [--tag]... [--exclude-tag]... [--fail-fast] [--delay <milliseconds>] [--data <file>] [--dry-run] [--noproxy] [--insecure]; request create --url --method --collection, run [--env] [--noproxy] [--insecure]; environment set; secret set|list|delete; and cookie list|clear --collection. They are non-interactive and support --json, which writes one { status, data, errors } envelope and uses a nonzero exit status for invalid input, failed pre/post scripts, failed HTTP responses, failed captures, failed assertions, or failed scripted tests. Collection-run targets are request IDs or folder paths ending in /; folders include nested requests, overlapping targets run once in collection order, and omitting targets runs the whole collection. Request and non-root folder tags form case-sensitive dynamic suites; repeated include tags all must match, any repeated exclude tag removes a request, exclusion wins, and fail-fast records later selected requests as skipped. Collection CLI SIGINT/SIGTERM cancellation returns a partial result and exits 130; existing exit codes 0/1/2 remain success/completed failure/configuration failure. Interrupted executions carry cancelled: true; unstarted executions use skip reason cancelled. Summary completed, cancelled, and unstarted satisfy selected = completed + cancelled + unstarted and executed = completed + cancelled; cancelled executions do not count as request failures. Finished response phases are retained, unfinished script writes roll back, and timeout remains an ordinary transport/script failure. --delay accepts a non-negative safe integer number of milliseconds and waits only between selected requests. cookie list prints jar contents grouped by domain (values included); cookie clear empties the jar. secret set prompts without echo in a TTY or accepts --stdin. collection format canonicalizes request YAML and pretty-prints valid JSON bodies without lossy numeric conversion; imports run it automatically. collection init bootstraps missing collection markers in an existing directory and registers it. workspace audit --fix removes invalid registered paths.
  • Collection hooks: Optional hooks: { setup?: requestId, teardown?: requestId } in collection settings.yml runs saved requests around each nonempty main selection, once per dataset row. IDs must exist and differ. Resolve references and preflight all stage sources before HTTP; reuse the shared lifecycle and inherited scripts. Targets/tags exclude hooks from main selection. Setup failure skips mains (setup-failed), then attempts teardown; ordinary failures and fail-fast also attempt teardown for the started row. Cancellation never starts cleanup HTTP. Each row shares its RunScope and cookie jar across stages; later rows are isolated and fail-fast prevents starting them. Hook-enabled results/events/details expose stage and summaries include stage counts; hooks count toward execution limits. Settings > General edits both IDs; manual sends and request run remain unchanged.
  • Collection preview: collection run --dry-run shares selection and dataset validation with execution, without reading environment values or external scripts, opening cookie jars, running scripts, or sending HTTP. Human output shows the plan; JSON returns dryRun, environment (name or null), one iteration's ordered sequence: { id, stage }[], iterations, and totalExecutions, including hooks per row. Runtime failures may shorten execution and scripts can send additional requests. Reject --output and --reporter with exit 2; save previews by redirecting stdout.
  • OpenAPI imports: Accept OpenAPI 3.0 and 3.1 JSON/YAML. A 3.1 document without servers creates a default environment with empty base_url. Resolve local JSON Pointers, preserve supported examples or derive editable JSON body templates, and report unsupported references, schema constructs, security requirements, callbacks, and webhooks through import warnings. Require a supported outgoing path operation. OpenAPI export remains 3.0.3.
  • Iteration data: collection run --data <file> and the Runner Data file field repeat selected requests for each CSV/JSON row. CLI relative paths use the current directory; Runner paths use the collection root and support completion plus @/ home paths. Validate the whole file before sending: 5 MiB, 1,000 rows, and 10,000 selected executions maximum. CSV cells remain strings; JSON preserves types. Row values override environment substitution and noodle.run.get, while noodle.env.get stays a snapshot. Read-only noodle.iteration exposes zero-based index, count, and original data, or null without data. Each row gets a fresh RunScope and a transient copy of the initial cookie jar; row changes never persist. Delay and fail-fast span row boundaries. Results/skips/details carry iteration; collection results add iterations. No-data behavior and result shapes remain unchanged.
  • Automation environment selection: request run and collection run use --env when supplied; otherwise they use the collection root's settings.yml environment.
  • Run-scoped variables: Every manual TUI send and request run gets an isolated RunScope; every collection run and TUI Runner call shares one scope across its ordered requests, with a fresh scope for each dataset row. Resolved environment and secret values load first, then successful captures and script writes override the same names, with the latest successful write winning. Failed captures and failed script invocations leave earlier committed values unchanged. Captures are visible to the same request's post script and later requests. Transient values disappear when the call returns. Manual sends and request run may persist captures declared with persist; collection runs and the TUI Runner ignore persistence. Script writes are transient by default. Manual sends and request run honor explicit noodle.run.set/unset options { persist: "environment" | "secret" }; collection runs and the TUI Runner suppress persistence.
  • Body templates: src/bodyTemplate.ts expands $random.method and $time.method with optional JSON-literal arguments in JSON, text/XML bodies, and enabled text form values. Standalone JSON placeholders preserve types; quoted JSON values escape text. Other fields retain ordinary variable substitution. Resolve once before inherited pre scripts, reuse prepared values across redirects, and keep direct noodle.sendRequest inputs literal. Current-time calls share one instant per request execution. Inspection, validation, formatting, and completion must not generate values; preserve $VAR, $$, numeric source tokens, and immediate generated-password redaction. Reuse scriptRandom.ts, scriptTime.ts, and scriptJson.ts validation.
  • Scripts: Optional top-level scripts in collection settings.yml, non-root folder.yml, and request YAML accepts one string per pre and/or post. Each string is inline JavaScript or a collection-relative ./path/to/file.js reference. Empty strings are no-ops and omitted during canonical serialization; empty mappings, unknown keys, non-string sources, and malformed external paths are rejected. Canonical YAML preserves inline source whitespace in pre/post order. Each invocation gets a fresh QuickJS runtime and context with the frozen, null-prototype noodle namespace exposing noodle.request, noodle.env, noodle.run, noodle.crypto, noodle.random, and noodle.time, plus captured console. JavaScript built-ins remain global; top-level await and Promises use controlled VM jobs. Pre/post network calls use only noodle.runRequest and noodle.sendRequest; bare reader aliases, imports, require, module loading, host APIs, raw fetch, timers, and background work are unavailable. The shared lifecycle is folder merge → environment/RunScope → one substitution pass → inherited pre → HTTP → captures → inherited post → assertions → inherited tests. Script source is not substituted. Modules and foreign scripting API translation remain unsupported; imports can preserve compatible source already using supported APIs.
  • TUI script authoring: Request and folder + menus reveal empty Pre Script, Post Script, and Tests tabs; populated tabs remain visible. Collection Settings > Scripts edits all three phases and saves drafts when leaving the editor. ScriptEditor reuses CodeEditorRenderable for JavaScript highlighting, folding, line numbers, and undo/redo. Phase-aware completion and semantic diagnostics use a worker with bundled QuickJS-compatible type libraries; SCRIPT_API_CONTRACT generates the API declarations. Semantic diagnostics are advisory. The request Send button commits active script/test editor drafts before sending. TUI Send and Runner use compile-only syntax preflight through the shared source resolver before HTTP; CLI execution semantics remain unchanged. External mode completes collection-relative .js paths; opening a script validates it through resolveFile() and never creates or rewrites it. Console renders bounded, redacted logs with phase, level, and request-relative timing from existing results; Results owns outcomes and origins.
  • Code formatting: Ctrl+Alt+F formats an active inline script or JSON request body. Global format_on_save defaults to false and formats inline scripts/tests and JSON bodies through existing request, folder, and collection save paths. Preserve JSON source numbers and body-template tokens without evaluating them; leave external files, XML, and invalid source unchanged. Apply visible formatting only after persistence succeeds, preserve newer drafts, and warn while saving unformatted source if the formatting service fails.
  • External script sources: src/scriptSourceResolver.ts is the shared host resolver for pre/post scripts and tests. References must begin with ./, end with .js, and use forward slashes without absolute paths, dot/traversal segments, empty segments, or NUL bytes. Resolve the collection root and target with realpath; reject symlink escapes, non-regular files, unreadable files, invalid UTF-8, and sources over 256 KiB. Only source text enters QuickJS, never filesystem access or resolved absolute paths. Errors and result origins use safe messages and collection-relative paths. Manual sends and request run resolve all applicable sources before the first pre script; collection run and the TUI Runner preflight every selected request before any HTTP. Reads are deduplicated by canonical real path for one top-level run, including saved children; later manual sends read files again. Missing or invalid sources are configuration failures.
  • Async request chaining: Pre/post scripts can await noodle.runRequest(id) for an exact saved request in the current collection snapshot or noodle.sendRequest(options) for literal HTTP inputs. Saved children use the shared lifecycle and their own authentication; direct calls do not inherit parent credentials. Successful child variables reach the parent, but combined writes commit only when the enclosing script succeeds. Child persistence is transient; HTTP effects and received cookies survive variable rollback. Allow one outstanding call per script, ten calls per top-level request, and four child levels, with inherited cancellation/deadlines and cached-only nested OAuth. Results and history retain redacted child summaries without bodies.
  • Inherited scripts and tests: src/scriptInheritance.ts collects collection settings, ancestor folders derived from the request collection path, and request blocks for the shared lifecycle. Root folder.yml is ignored. Pre runs collection → outermost folder → nearest folder → request. After HTTP and captures, post runs collection → outermost folder → nearest folder → request. The most specific successful post write wins, including persisted writes. Declarative assertions follow, then tests run collection → outermost folder → nearest folder → request. Collection and folder blocks run once per request, including each Runner selection, not once per run. Empty blocks are no-ops and do not disable inheritance. Every block uses a fresh QuickJS invocation; JavaScript locals are isolated, and successful RunScope writes reach later blocks. A pre failure rolls back only that block, stops remaining pre blocks and HTTP, and leaves captures, assertions, and tests unevaluated. A post failure rolls back only that block and continues later posts, assertions, and tests. Successful persistence intents retain execution order; runners continue to suppress persistence. Saved noodle.runRequest() calls use the same inheritance. Diagnostics identify phase, scope, scope ID, source kind, and collection-relative external source path; test errors retains every block error and legacy error remains the first error. CLI, Results, and manual history retain bounded, redacted origins, logs, and diagnostics without source code or RunScope values.
  • Scripted tests: Optional tests in collection settings.yml, non-root folder.yml, and request YAML accepts one inline JavaScript string or collection-relative ./path/to/file.js reference evaluated after declarative assertions in manual sends, request run, and collection runners. It uses the existing QuickJS sandbox and limits, with synchronous or async test(name, callback) and expect(value) matchers, including .not, toMatchSchema, toHaveProperty, toHaveLength, toBeTypeOf, and toMatchObject. Returned Promises and thenables are awaited; tests cannot call network APIs. JSON Schema draft-07 compilation and validation run inside QuickJS with local references and standard formats, without coercion, defaults, or remote references. Tests read the final prepared request, response, environment, RunScope, and applicable cookies through noodle.*; request, RunScope, and cookie mutations are rejected, response JSON is frozen, and tests cannot persist values. Tests run after completed HTTP, capture, post, or assertion failures; pre and transport failures leave them unevaluated. Empty source is a successful no-op. Failed callbacks preserve declaration order and allow later tests to continue; top-level errors stop only their block while retaining completed results and allowing later blocks to run. Results expose bounded, redacted tests: { evaluated, results, logs, error?, errors? } diagnostics in CLI output, TUI Results, and manual timeline history, excluding test source and runtime values from history. Failed tests or a test script error add the test failure category and make automation exit nonzero.
  • Script time helpers: src/scriptTime.ts owns frozen noodle.time methods shared by pre and post: Unix milliseconds/seconds, strict ISO parsing/output, named-timezone pattern formatting, and elapsed-duration arithmetic. UTC is the default; days are always 24 hours. Helpers return numbers or strings, use the existing bridge validation and rollback, and leave JavaScript Date and random timestamp generators available.
  • Pre-request scripts: scripts.pre stages request and RunScope mutations and commits only on complete success. Pre failure skips HTTP and all response phases and returns the script failure category with redacted logs and errors. Successful writes survive later failures. Pre-request API behavior remains unchanged, but all Noodle API accesses require the noodle. prefix. Treat scripted collections as trusted code because noodle.env.get can read a selected-environment secret and place it in a following request.
  • Post-response scripts: scripts.post runs once per completed HTTP response, including HTTP and capture failures, not intermediate redirects/auth challenges or transport failures. It sees committed captures and adds read-only noodle.response metadata (status, statusText, timeMs), case-insensitive headers.get/has, text(), and json(); missing headers return null. Text transfers lazily without JSON-envelope expansion or truncation, with a 5 MiB UTF-8 cap checked before copying. JSON parses inside the VM with the captured native parser and caches success or failure per invocation, preserving null; invalid JSON is a structured API error. Request readers reflect the final prepared HTTP leg after signing and cookie/header preparation; every request mutator throws a read-only error. No host objects, streams, upload buffers, or Bun types are exposed. Post failure discards only its staged RunScope/cookie changes, preserving the response, captures, earlier successful mutations, and logs; assertions still run. Successful post writes reach later collection requests even after assertion failure.
  • Script persistence: Successful invocations stage bounded immutable noodle.run.set/unset intents. Manual sends and request run flush pre intents before HTTP, then original capture snapshots before post intents; runners report transient suppression. Persistent unset suppresses baseline substitution until a later set/capture, while ordinary unset keeps its transient behavior and noodle.env.get remains a snapshot. Storage failures preserve successful runtime/request/cookie commits while failing script diagnostics. Environment metadata and vault changes are coordinated under one cross-process environment-directory lock through load, transaction, save, and rollback; stale editor drafts fail before storage changes. Lock ownership is never reclaimed by age. After an interrupted writer, check vault/file consistency and ensure that no writer is active before manually removing .environments/.mutation.lock; timeout errors identify the exact lock path. Never expose raw intents or secret values in results.
  • Post cookie capability: When the jar is enabled/available and sendCookies is not false, post exposes final-URL-scoped noodle.cookies.get(name), noodle.cookies.set(input), and noodle.cookies.delete(name). Set requires string name/value, with optional applicable path, ISO 8601 date-time expires, boolean secure/httpOnly, and sameSite: strict|lax|none. Unknown attributes, including domain, and paths outside the URL's applicable scope are rejected. Cookies are host-only; omitted path uses tough-cookie defaults, omitted expiry means session lifetime, and past expiry is supported. Reuse tough-cookie prefix validation and secure-origin behavior, including localhost, without browser-navigation SameSite context. Get returns the first applicable matching value in tough-cookie order or null; delete removes all applicable same-name matches, preserving inaccessible cookies. Revalidate the complete staged batch against the current jar before synchronous publication together with RunScope writes. Successful operations enter the existing journal with deferred persistence, locking, encryption, and storage warnings. Response Set-Cookie processing precedes post, even with per-request suppression, and survives post failure.
  • TUI path modes: Existing collection roots open in collection mode. Directories containing request YAML but no collection markers open in read-only browse mode; empty directories open in read-only empty mode. Invalid or non-directory paths exit with an error. Initialize browse/empty directories from the command palette before editing or sending.
  • --help, --version auto-generated by citty

Collection reports

Collection report files use --json --output/-o or --reporter junit --output/-o. JSON stdout and file bytes match; JUnit keeps human stdout. Reject conflicting formats and existing destinations before HTTP. Reports consume sanitized shared results, retain failed/cancelled runs and exit codes, and include complete per-execution durationMs. Prepare the pinned destination before HTTP and use the native atomic report writer, never pathname-based staging publication. Report-write failure preserves execution data and an existing nonzero exit code; otherwise it exits 1. The field contract and CI artifact example live in .agents/skills/noodle-use/workflows/automation.md.

Stack

  • Runtime: Bun (not Node). bun run, bun test.
  • UI: OpenTUI React binding (@opentui/react, @opentui/core). jsxImportSource: "@opentui/react" — this is NOT standard React DOM. JSX renders to a terminal TUI. Use useKeyboard, createCliRenderer, createRoot from OpenTUI.
  • Language: TypeScript 7, strict mode, "type": "module".
  • Lint: Oxlint 1 with ESLint and TypeScript plugins. no-unused-vars ignores _-prefixed args.
  • Format: Oxfmt 0.74; semi: false, singleQuote: false, printWidth: 80.
  • Tests: bun:test (not vitest/jest). describe, it, expect.
  • Package manager: Bun. bun.lock (not yarn.lock/package-lock.json).

Architecture

src/
├── assertions.ts  # Declarative response assertion evaluation
├── executionResults.ts # Async shared captures → post callback → assertions execution
├── executionBounds.ts # Shared bounds for retained Runner and timeline diagnostics
├── runnerSession.ts # Per-collection app-session Runner snapshots and bounded previews
├── preRequestScript.ts # Phase-aware pre/post/tests sandbox; thin pre entry point
├── scriptAsync.ts # Controlled Promise jobs, CPU/wall deadlines, cancellation
├── scriptInheritance.ts # Collection/folder/request blocks and diagnostic origins
├── scriptSchemaValidator.ts # JSON Schema validator bundled for QuickJS
├── iterationData.ts # CSV/JSON validation, execution limits, result keys
├── requestLifecycle.ts # Shared merge → scope → substitute → pre → HTTP → capture → post → assert → tests
├── response.ts    # Shared response expression parser and resolver
├── runScope.ts    # Transient capture values and capture result evaluation
├── tags.ts        # Tag validation and effective inheritance
├── timelineEntry.ts # Shared redacted timeline entry construction
├── schema/        # Types: Method, Auth, Request, Collection, Response, Environment, ParamEntry, FormEntry, KvEntry
├── lang/          # YAML request language: parse + serialize
│   ├── auth.ts     # Shared strict auth parsing and serialization
│   └── parsers/   # Tree-sitter WASM + highlights.scm for JSON and YAML
│       ├── json/  # tree-sitter-json.wasm, highlights.scm
│       └── yaml/  # tree-sitter-yaml.wasm, highlights.scm
├── filestore/     # loadCollection(dir) / saveRequest(dir, req) — disk I/O
├── env/           # loadEnvironment, listEnvironments — env file I/O + secret resolution
├── auth/          # Shared auth defaults for request, folder, UI, and converters
├── secrets/       # OS credential-vault storage + redaction helpers
├── cookies/       # Per-collection cookie jar, URL-scoped post transactions, encrypted persistence
├── agentSkill.ts  # Embedded noodle-use installer + supported-agent links
├── tls.ts         # TLS/mTLS validation and per-request policy resolution
├── requests/      # executor.send, OAuth 1 signing, OAuth 2 tokens, substitution
├── hooks/         # React hooks
│   ├── useCollection.ts, useTreeNavigation.ts, useSidebarSelection.ts
│   ├── useRequestDraft.ts, useFolderDraft.ts
│   ├── useEditBrowse.ts, useFolderEditBrowse.ts
│   ├── useResponse.ts, useCollectionRunner.ts, useEnvironments.ts, useEnvironmentEditor.ts
│   ├── useConfig.ts
│   └── useKeymap.ts
├── converters/
│   ├── index.ts   # Importer registry, detectFormat, getImporter
│   ├── openapi/   # OpenAPI 3.0/3.1 importer + 3.0.3 exporter
│   ├── postman/   # Postman 2.1 importer + exporter (uses postman-collection npm pkg)
│   ├── swagger/   # Swagger 2.0 → Collection importer
│   └── insomnia/  # Insomnia v4/v5 JSON → Collection importer
├── app/           # CLI args parsing, entry point (src/app/cli.ts)
└── ui/            # React components + hooks + pure helpers
    ├── App.tsx              # Root component: state wiring, theme, config, env list
    ├── AppInner.tsx         # Core logic: hooks, overlays, keymap, timeline, file actions
    ├── AppOverlays.tsx      # Central overlay rendering
    ├── MainView.tsx         # Main vs folder view dispatch (sidebar + content pane)
    ├── RequestResponseView.tsx # UrlBar + RequestPane + ResponsePane layout
    ├── [env-editor]
    │   ├── EnvironmentEditorView.tsx # Env editor top-level view
    │   ├── EnvSidebar.tsx
    │   ├── EnvHeaderPane.tsx
    │   └── EnvEditorPane.tsx
    ├── [cookie-jar]
    │   ├── CookieJarView.tsx  # Cookie jar top-level view (domains + cookie rows)
    │   ├── CookieJarSidebar.tsx # Domain list with cookie counts
    │   └── CookieJarPane.tsx  # Cookie table for the selected domain
    ├── Sidebar.tsx          # Tree sidebar: requests, folders, dirty indicators, method badges
    ├── RequestPane.tsx      # Full request detail + inline editing (8 tabs)
    ├── ResponsePane.tsx     # Response body, headers, trace, timeline, cookies, Results
    ├── ResponseResults.tsx  # Shared expandable script/capture/assertion results
    ├── CollectionRunnerView.tsx # Transient collection-run configuration and results
    ├── FolderPane.tsx       # Folder editor: meta, headers, auth overrides, activity
    ├── FolderMetaTab.tsx    # Folder name/seq editing
    ├── FolderActivityTab.tsx # Per-request activity stats in folder
    ├── UrlBar.tsx           # URL editing bar with env substitution
    ├── Autocomplete.tsx     # Shared searchable variable, expression, path, and body-template menus
    ├── VarInput.tsx         # Variable-aware input/textarea with completion popup
    ├── VarText.tsx          # Variable-highlighted read-only text rendering
    ├── KeyValueSection.tsx  # Key/Value pair editor (headers/params/captures)
    ├── AuthEditor.tsx       # Auth type selector + rows for all supported auth schemes
    ├── authRows.ts          # Auth field metadata shared by request and folder editors
    ├── FormEditor.tsx       # Multipart/urlencoded form editor with text/file toggle
    ├── Checkbox.tsx, Select.tsx, Tabs.tsx, Frame.tsx, Badge.tsx, GradientBadge.tsx
    ├── CenterText.tsx, Toast.tsx, Tips.tsx
    ├── [overlays]
    │   ├── PickerOverlay.tsx           # Generic searchable picker overlay (base)
    │   ├── CommandPaletteOverlay.tsx   # Command palette: fuzzy-searchable, sectioned
    │   ├── CollectionSwitcherOverlay.tsx # Collection directory picker
    │   ├── EnvironmentPickerOverlay.tsx # Searchable active-environment picker
    │   ├── NewEnvironmentOverlay.tsx   # Environment name/color creation form
    │   ├── HelpOverlay.tsx             # F1 keybinding cheatsheet overlay
    │   ├── ConfirmOverlay.tsx          # Yes/No confirmation dialog
    │   ├── NewRequestOverlay.tsx, CloneRequestOverlay.tsx, NewFolderOverlay.tsx
    │   ├── TagEditorOverlay.tsx       # Request and Runner tag editing
    │   └── Overlay.tsx                 # Generic overlay (modal) container
    ├── [editor]
    │   ├── CodeEditor.ts              # CodeEditorRenderable class (tree-sitter highlight, folding, validation)
    │   ├── CodeEditorCompletion.tsx    # Variable completion list tied to CodeEditor
    │   ├── codeEditorParsers.ts       # Registers tree-sitter JSON + YAML + XML parsers
    │   ├── useJsonHighlight.ts        # JSON syntax + env var highlighting for textareas
    │   ├── syntax.ts                  # JSON tokenizer
    │   ├── yamlSyntax.ts              # YAML tokenizer
    │   ├── JsonBodyViewer.tsx         # JSON body viewer with line numbers + syntax highlighting
    │   ├── YamlEditorOverlay.tsx      # YAML code editor with syntax highlighting + folding
    │   └── ValidationNotice.tsx       # Validation error bar
    ├── [variable completion]
    │   ├── variableCompletion.ts       # getVariableToken, getVariableSuggestions, replaceVariableToken
    │   ├── useVariableCompletion.ts    # Cursor-aware $var completion hook
    │   ├── variableCompletionInterceptor.tsx # High-priority key interceptor for completion
    │   ├── variableHighlight.ts        # $var highlighting (resolved/missing) for Input/Textarea
    │   ├── highlightOffsets.ts         # Char-to-display offset mapping for emoji/wide chars
    │   └── envHighlight.ts             # splitEnvVars — segments text into plain/resolved $var
    ├── [themes]
    │   ├── theme.tsx                   # ThemeProvider, useTheme, ThemePickerOverlay
    │   └── theme-data.ts              # 35 themes, Theme interface, THEMES array
    ├── [infrastructure]
    │   ├── keybind.ts                  # Keybinding definitions, CommandMap, parseOverrides
    │   ├── helpTexts.ts                # Help overlay section/keys builder
    │   ├── useJumpMode.ts              # Jump mode hook (leader-key focus jumps)
    │   ├── useAppKeymap.ts             # All keymap layers (17 layers)
    │   ├── focus.ts                    # Focus type, cycleFocus, toggleExpand
    │   ├── commands.ts                 # buildCommandPaletteCommands
    │   ├── commandActions.ts           # All command action implementations
    │   ├── useCollectionFileActions.ts # Create/save/delete request/folder file operations
    │   ├── clipboard.ts                # copyToClipboard (pbcopy/xclip/wl-copy/clip.exe + OSC 52)
    │   ├── format.ts, formatRequest.ts # Display formatting helpers
    │   ├── urlParams.ts                # buildDisplayUrl, parseUrlAndParams
    │   ├── tree.ts                     # Tree helpers (findRequestById, visibleNodes, etc.)
    │   ├── selection.ts                # Clamped index navigation
    │   ├── borders.ts                  # Border presets (FullBorder, LeftBar, PaneBorder)
    │   ├── useOverlayIntercepts.ts     # All overlay keyboard intercepts
    │   └── useSaveFile.ts              # Save file logic with timeout, confirming state
    ├── tabs/                           # UI state persistence
    │   ├── uiState.ts                  # ResponseTabKind, save/load last-request, expanded-folders
    │   └── useUIState.ts               # Per-request tab index state
    └── timeline/                       # Timeline viewer; large bodies load from compressed sidecars
        ├── TimelineEntry.tsx           # Single timeline entry renderer
        ├── TimelineTab.tsx             # Full timeline tab
        ├── formatTimeline.ts           # Timeline display formatting
        └── useTimeline.ts              # Per-request response history hook
collections/       # Sample request .yml files + .environments/
tests/             # bun:test suites
tests/unit/        # Unit tests for pure helpers + components
tests/integration/ # Integration tests

Response bodies and downloads

Live responses retain optional original, non-enumerable bodyBytes and bodyKind: text|binary; missing classification remains text-compatible. responseBody.ts owns MIME, UTF-8, image-signature, byte-size, and safe filename handling. Decode text once, keep binary body empty, and never rebuild downloads from text. Binary JSON diagnostics omit body and bytes, reporting bodyKind, size, contentType, and optional filename. Captures/assertions on JSON body paths fail clearly for binary responses; status/header/time still work. Explicit post-script text/json readers retain the existing UTF-8 behavior and 5 MiB limits. Preserve the non-enumerable payload when copying a live response; ordinary object spreads omit it. History and result envelopes must construct metadata explicitly.

request run --output/-o validates a new destination before sending (invalid or existing paths exit 2), writes unredacted received bytes after all available diagnostics even on completed response failures, and reports outputFile. Pre-script/transport failures produce no file; later write failures preserve diagnostics and exit 1. responseFile.ts owns exclusive creation, parent creation, partial-file cleanup, and direct platform-opener argument handling. CLI downloads pin an existing output directory before HTTP; TUI Save As pins it during confirmation. The private Node-API addon creates new components relative to that directory without following symlinks; existing directory aliases are resolved during preparation. Maintain the five release-target native prebuilds and their manifest together (bun scripts/build-response-file-native.ts --all, then --check); maintainer regeneration uses Zig 0.15.2, while normal installs and binary builds require no extra tools. Native response-file CI tests shipped prebuilds in source and standalone modes and independently rebuilds the native source on the five release targets: macOS x64/arm64, Linux glibc x64/arm64, and Windows x64 (beta). Linux musl and Windows ARM64 are unsupported; reject them explicitly rather than loading an addon for a different platform.

Save As state pins the selected Response; saved paths use response identity. TUI Save As suggests and saves to an available filename, adding compact (1), (2), etc. suffixes before the extension. Retry exclusive-creation collisions without overwriting existing files; CLI --output remains strict. Keep Save/Open actions centralized in commandActions.ts. Body-only native image previews support PNG/JPEG/static WebP/GIF first frame, automatic protocol and pane fit, explicit activation above 5 MiB, decoder-error fallback, and unmount cleanup. Binary history and Runner details retain redacted metadata only, with no response body/sidecar or download/preview/open; history says “Binary body was not retained.” Text history remains compatible. Add no request YAML fields for response handling.

Entry point

src/app/cli.ts — citty main command, delegates to TUI, import, export, update, or automation subcommands. Automation command definitions live in src/app/commands/automation.ts; src/app/services.ts owns collection, request, environment, audit, and run behavior. TUI bootstrap is extracted to main.tsx (bootstrap() function).

Distribution

MethodCommand
curlcurl -LsSf https://raw.githubusercontent.com/noodle-rest/noodle/main/scripts/install.sh | sh
Homebrewbrew install noodle
PowerShell (Windows x64 beta)irm https://raw.githubusercontent.com/noodle-rest/noodle/main/scripts/install.ps1 | iex
Sourcebun install && bun run build:bin
  • Install script at scripts/install.sh — detects OS/arch, downloads and verifies the binary from GitHub Releases
  • Homebrew core formula is the source of truth (https://formulae.brew.sh/formula/noodle); old wilfredinni/noodle tap is retired with tap_migrations.json → homebrew/core. See packaging/homebrew/README.md for migration (brew reinstall + brew untap wilfredinni/noodle).
  • Release workflow at .github/workflows/release.yml: triggered by git tag v* or manual recovery, reuses validated CI binaries at the exact release commit for macos-arm64, macos-x86_64, linux-x86_64, linux-arm64, and windows-x86_64 (unsigned beta .exe). Only absent or expired eligible artifacts trigger a rebuild; failed CI or invalid metadata blocks publication. It publishes SHA256SUMS, validates downloaded macOS and Windows artifacts before publication, and updates noodle-site's update.json after release publication. Homebrew core updates independently; no tap dispatch (manual bump via brew bump-formula-pr, see packaging/homebrew/README.md).
  • Windows PowerShell 5.1+ installation uses %LOCALAPPDATA%\Programs\Noodle\noodle.exe and user PATH by default; NOODLE_VERSION, NOODLE_INSTALL_DIR, and NOODLE_SKIP_PATH_UPDATE=1 override those choices. Windows updates return restart_required and log_path; the detached helper applies the verified binary after Noodle exits, verifies its version, and refreshes an installed skill. Windows ARM64 release binaries are unsupported; ordinary-account interactive terminal testing remains pending.
  • macOS standalone builds run scripts/sign-macos-binary.ts immediately after compilation, before smoke tests and checksums. Release publication requires verifying the downloaded draft macOS artifact's checksum, signature, version, and scripting sandbox without re-signing it; published release assets cannot be replaced by rerunning the workflow.

Key conventions

  • GitHub issues and reviews: Never close GitHub issues, mark pull request review threads or comments as resolved, or dismiss reviews unless the user explicitly instructs you to perform that action. Reviewing code, addressing feedback, fixing CI, committing, or pushing does not grant this permission. Leave issue and review states unchanged without that explicit instruction.
  • Oxfmt check covers only ./src ./tests; .agents/ is not included.
  • Do NOT commit docs/, CONTINUE.md, .superpowers/, .timeline/ (all gitignored).
  • Commit style: feat(scope):, fix(scope):, test(scope):, refactor(scope):, style:, docs:.
  • Requests are .yml files, one per request. Extension is .yml not .yaml. Optional sendCookies: false suppresses outgoing jar cookies and the post cookie capability, but still processes response Set-Cookie headers (serialized only when set; parsed strictly like followRedirects/maxRedirects).
  • Response assertions: Optional request assert blocks are evaluated by manual TUI sends, request run, and collection run. Each row accepts optional enabled: false; disabled rows remain validated and editable but produce no outcomes. Expressions address status, response.time, case-insensitive headers.<name>, and JSON body paths. Failed assertions make automation runs fail; assertion expected values support recursive environment substitution, and known secrets are redacted from expected and actual result values.
  • Script results: Requests with either phase return optional scripts: { evaluated, results } before capture/assertion result groups. Retain executed results in pre/post order; never invent outcomes for phases that did not run. The existing Results surface uses Pre-request/Post-response labels and shows status, duration, log count, and normalized errors with source locations; Console displays the redacted log text. Human automation output distinguishes Pre-script/Post-script without printing log text; JSON retains redacted phase-tagged logs/errors. Script failure affects request success and the fixed category order: configuration, execution, script, transport, http, capture, assertion, test. Collection continuation/fail-fast is decided after all available response diagnostics finish. Each invocation retains a 500 ms VM execution budget across resumptions and a 30-second wall deadline bounded by ancestors, 32 MiB runtime memory, 512 KiB stack, 256 KiB source and ordinary bridged/RunScope values, depth 32 bridged JSON, 100 console entries, 64 KiB console text, 4 KiB random bytes, depth 4 console serialization, and fixed 64 MiB WASM memory. Only lazy response text gets the separate 5 MiB UTF-8 limit.
  • Response captures: Optional request capture mappings bind response expressions to RunScope variable names. Every entry is an object with required value, optional enabled: false, and optional persist: secret|environment; scalar shorthand is invalid. Captures and assertions share one createResponseResolver(). Successful captures commit before post and assertions, including on HTTP error responses; missing or invalid traversal results fail without creating or replacing a variable. Outward result redaction waits for post-discovered secrets. Manual sends and request run honor persistence using the captured value, not a later post overwrite, even after post/assertion failure; collection runs and the TUI Runner keep captures transient. Secret-persisted capture values are fully redacted.
  • Request IDs are collection-relative paths without .yml; reject traversal, absolute paths, backslashes, empty segments, hidden segments, and request basenames settings or folder (case-insensitive). Collection loads preserve original request bytes; only explicit saves/formatting rewrite them. Creating, initializing, or importing a new collection adds /.noodle/ and /.timeline/ to .gitignore while preserving existing rules.
  • Windows filenames: userPath.ts validates request/folder/collection/environment names against forbidden characters, trailing dots/spaces, and reserved device names. Keep logical IDs in forward-slash form, use native path operations for disk access, and derive the config directory from getNoodleConfigDir().
  • CLI response details: request run --body/--headers/--cookies adds opt-in human output from the existing redacted result; --json keeps one envelope and includes received-cookie metadata with masked values. Escape terminal controls in displayed details and keep binary bodies metadata-only; --output saves unredacted original bytes.
  • Request bodies support none, json, xml, multipart, urlencoded, and binary. XML bodies use the code editor, default to application/xml when no enabled Content-Type exists, and are sent unchanged after variable substitution.
  • Environments are .env files under <collection>/.environments/. Format is KEY=value (dotenv-style, not YAML). Lines starting with # disable a var. _color=<name> sets sidebar badge color. # @secret NAME followed by a blank NAME= placeholder declares a credential-vault value; process environment wins over the stored value.
  • $VARNAME template syntax for variable substitution in url/headers/params/body/auth and assertion expected string values. Automation overlays current RunScope values through the same substitution path. Strings substitute verbatim; numbers, booleans, null, arrays, and objects use JSON.stringify().
  • Optional request tabs: Empty Assert and Capture tabs are hidden behind the request pane + menu. g then o focuses it; existing g then v/c targets reveal either tab directly. useEditBrowse owns per-request session reveal state and menu focus; populated tabs remain visible.
  • System theme: Select system to follow the terminal palette. ThemeProvider listens for palette/theme notifications, refreshes colors, and retains the saved choice while using Noodle colors if detection fails.
  • Authentication: Requests and folder overrides support bearer, basic, API key, connection-bound server NTLMv2, AWS SigV4, OAuth 1.0a, and OAuth 2.0. OAuth 1.0a supports HMAC, RSA, and PLAINTEXT signatures with header, query, or URL-encoded body placement. OAuth 2.0 accepts discovery_url to fill missing endpoints from an OIDC issuer or standard discovery URL; discovery_url_kind: document requests an exact document URL. Explicit endpoints take precedence. OAuth 2.0 supports authorization code, client credentials, implicit, and password grants; browser grants run interactively in the TUI, while automation only reuses, refreshes, or directly acquires non-browser credentials. Cached tokens live in the OS vault with a session-only memory fallback and are never written to request YAML. Keep all credentials in secret environment variables. Generated client code is unavailable for NTLM, AWS SigV4, OAuth 1.0a, and OAuth 2.0 requests.
  • @/path home syntax for multipart file values and binary file_path; the TUI completes the shorthand from the user home directory, while expansion happens only at output boundaries, including file reads during request sending, HAR generation through buildHar, and Postman export.
  • Error re-throws must preserve { cause: e }, except at redaction boundaries where the original error exposes secrets or local paths. For example, scriptSourceResolver.ts intentionally replaces filesystem errors with safe public reasons and omits the raw cause; tests must cover inspected errors as well as public messages.
  • Settings, proxy, and TLS policy: F4 opens Settings. Global Behavior selects a detected external editor for command-palette actions that open the active collection or ~/.config/noodle. Global proxy mode is system, off, or custom; a collection may inherit, use off, or define custom. Custom URLs reject credentials and variables; authenticated proxies persist only auth: true, while credentials live in the OS vault. --noproxy takes precedence for one run. Collection settings.yml also stores generated collection_id, optional name, description, timeline_max_entries, active environment, cookie jar toggle (cookies.enabled, default on), and TLS verification, CA, and exact-host client-certificate metadata. Encrypted key passphrases live in the OS vault; --insecure disables verification for one run. Settings parsing is strict.
  • Cross-origin redirects: Strip sensitive headers and headers containing known secret values when the origin changes. Refuse a redirect leg that would preserve a known secret in a request body; redirects that discard the body remain allowed. Apply this policy to environment, RunScope, script-created, auth, cookie, proxy, and transport-discovered secrets.
  • Invalid collection repair: Invalid request or folder YAML opens CollectionErrorView, which reuses YamlFileEditor for per-file drafts, strict save-time validation, deletion, and reload after repair. Invalid mode must keep send and edit commands unavailable except for repair actions.
  • Read-only TUI modes: Browse and empty modes allow inspection plus global UI actions, but block request/folder/environment edits, saves, sends, and collection-only keybindings until initialized.
  • Resizable main layout: AppInner.tsx owns the current sidebar width plus separate stacked and side-by-side request/response ratios. MainView.tsx handles drag state, responsive minimums, and double-click reset; RequestResponseView.tsx renders the layout-specific resize handles. Keep sizing session-only unless persistence is explicitly requested.
  • Sidebar visibility: AppInner.tsx owns session-only visibility and toggleSidebarVisible() centralizes both shortcut and command-palette behavior. Toggling preserves non-sidebar focus; hiding the focused sidebar falls back to the URL bar or folder pane, while the sidebar jump reopens and focuses it.
  • UI features require loading the opentui skill. The skill lives at .agents/skills/opentui/SKILL.md.
  • Command actions are centralized in commandActions.ts. Both useAppKeymap.ts and commands.ts import from it. Never duplicate command logic.
  • Overlay state travels as one object. useOverlayState owns every overlay's visibility, pending value, and handle, and AppInner passes the whole OverlayState to AppOverlays and useOverlayIntercepts rather than re-declaring fields at each consumer. Adding an overlay means declaring it in useOverlayState (state, activeOverlay branch, return), handling its keys in the intercepts, and rendering it in AppOverlays — never widening a mirrored prop list. State owned elsewhere (useReloadGuard, useCollectionSwitcher) and behavior callbacks stay explicit props. tests/unit/_overlayState.ts builds a default OverlayState for tests.
  • Notifications and completion: Keep transient Toast non-focusable. Show Last Notification opens NotificationOverlay for keyboard scrolling and resets its scroll on each opening. Autocomplete.tsx owns bounded, cursor-anchored completion rendering and keyboard/mouse selection; reuse it for inputs and CodeEditorCompletion rather than duplicating menu state.
  • Command palette commands return boolean: run() returns true (close palette) or false (stay open).
  • PickerOverlay isNavigable: Pass to skip non-selectable items (section headers) during up/down/return navigation.
  • Environment controls: e opens the searchable picker from the main view; F3 opens the full editor. New environments are created through NewEnvironmentOverlay, then persisted by useEnvironmentEditor.createEnv(). In environment browse mode, configurable env_secret (s) toggles secure storage and env_reveal (r) reveals the selected secret for the session.
  • Timeline security: Request snapshots resolve ordinary variables, redact declared environment secrets and settings secrets, and mask sensitive headers, auth credentials, OAuth signatures, assertions, and tokens before persistence. Response headers and bodies receive the same known-secret redaction, sensitive response headers such as Set-Cookie are field-masked, and body redaction happens before compression into sidecars. Marking or updating a secret does not rewrite existing history. Capture declarations and script source persist in request YAML but are excluded from timeline snapshots; capture results and RunScope values are not persisted. Manual timeline entries retain bounded, redacted pre/post and scripted-test diagnostics and logs, including test invocation logs and script persistence outcomes. Cancelled manual sends carry cancelled: true, retain any completed response and partial diagnostics, and are excluded from folder success-rate and timing calculations. History loads merge entries saved while loading; late completions retain their original request and collection, and one failed save must not stop the save queue. src/timelineEntry.ts redacts before src/filestore/timeline.ts applies the existing 10,000-byte diagnostic text and per-log-array budget with [TRUNCATED] markers; preserve safe logs rather than replacing them with empty arrays. Successful prepared request mutations are included in manual timeline request snapshots, while automation runs do not create timeline entries. Timeline YAML and gzip sidecars may still contain sensitive public variables or server data that Noodle does not know is secret.
  • Cookie jar security: Jar contents are encrypted at rest (~/.config/noodle/cookies/), and jar-sent Cookie headers and response Set-Cookie headers are masked in timeline snapshots. Ordinary non-script cookie policy does not use short values as unrestricted substring-redaction tokens. Post-enabled execution registers applicable, received, read, staged, overwritten, and deleted values, including failed invocations and short values, for existing redaction before outward results and timeline persistence; short values may over-redact public output. Deliberately encoded/exfiltrated secrets and unknown server data remain risks, and successful cookie transactions retain deferred disk durability.
  • Visual response view: m or the footer action switches the focused Body tab between Source and Visual. ResponseVisualBody renders JSON/XML parsed by responseVisual.ts as expandable rows and compact tables. / searches labels and values literally, case-insensitively; Source retains JSONPath. Visual copying returns the original body. Preserve the 5 MiB opt-in rendering guard, response-scoped search/expansion state, and viewport-width content sizing with intrinsic row width used only as the horizontal-scroll minimum.
  • Response body editor: ResponsePane renders bodies through a read-only CodeEditorRenderable; JSON folds retain source line numbers, XML responses use XML highlighting, the gutter owns fold signs, and copy operations must return original source text even when rows are folded.

Keybindings (defaults; customizable via ~/.config/noodle/keybinds.yml)

All except fixed keys can be overridden in YAML:

env_cycle: ctrl+u
command_palette: ctrl+p

Global (always active, gated on !helpVisible)

KeyAction
Tab / Shift+TabCycle focus (sidebar → URL bar → request → response)
Ctrl+ReturnSend request
Ctrl+SSave request to disk
Ctrl+NNew request
Ctrl+KClone request
Ctrl+WDelete request
Ctrl+UCycle environment
F3Open environment editor
F4Open Settings
Ctrl+POpen command palette
Ctrl+FFind request
Ctrl+LToggle layout (stacked / side-by-side)
Ctrl+BToggle sidebar (open / closed)
F2Expand/collapse focused pane
F5Open collection Runner
F1Toggle help overlay
Ctrl+TOpen theme picker
Ctrl+EEdit request in overlay
Ctrl+Alt+EEdit request YAML in overlay
Ctrl+Alt+BCopy response body
Ctrl+Alt+SSave live binary response file (focused response Body tab)
Ctrl+Alt+OOpen saved binary response in default app (focused response Body tab)
mToggle Source / Visual (response Body tab focused)
/Filter the focused Body tab with JSONPath in Source or text search in Visual
Ctrl+Alt+NNew folder
Ctrl+OOpen collection switcher
Ctrl+ZUndo all unsaved changes
gEnter jump mode (press a hint letter to focus that element; Esc exits)
eOpen environment picker
Ctrl+CQuit (copies selection first if text is selected)

In browse or empty mode, collection-only actions above are unavailable. Command palette still exposes inspection, reload, layout, theme, help, and collection initialization actions.

The command palette also provides Run Collection or Run Folder, Import Collection (as a new collection or into the current collection), Export Collection (OpenAPI or Postman), Import cURL Request, Generate Code, Install Noodle skill, direct application and collection Settings categories, and actions to open the active collection or Noodle settings directory in a detected external editor. For an effective OAuth 2.0 request it also provides actions to fetch or authorize, copy, and clear the current token. Code generation supports choosing a language and library, and can optionally interpolate the active environment, but is unavailable for NTLM, AWS SigV4, OAuth 1.0a, and OAuth 2.0 requests. Save pending changes before importing into the current collection.

Jump mode (leader-key focus jumps)

Activated by jump_mode (default g). Shows [letter] hints on each focusable element; press a letter to focus that element, or Esc to cancel. Non-matching keys are swallowed (mode stays active).

LetterTarget
sSidebar pane
mURL bar method select / Folder General tab
uURL bar URL field
hRequest Headers tab / Folder Headers tab
pRequest Params tab
xRequest Path tab
bRequest Body tab
aRequest Auth tab / Folder Auth tab
vRequest Assert tab
cRequest Capture tab
dRequest / Folder Pre Script tab (when visible)
fRequest / Folder Post Script tab (when visible)
jRequest / Folder Tests tab (when visible)
tRequest Settings tab
oRequest / Folder optional-tab menu (+, when visible)
rResponse Body tab
eResponse Headers tab
nResponse Network tab
lResponse Timeline tab
kResponse Cookies tab
iResponse Results tab
zResponse Console tab (when logs make it visible)
yFolder Activity tab

the sidebar jump still works even when it is collapsed

When a folder is selected, the folder targets replace the request and response targets:

LetterFolder target
sSidebar pane
mGeneral tab
hHeaders tab
aAuth tab
dPre Script tab (when visible)
fPost Script tab (when visible)
jTests tab (when visible)
oOptional-tab menu (+, when visible)
yActivity tab

In the environment editor, only these environment targets are available:

LetterEnvironment target
sEnvironment sidebar
mEnvironment name
cEnvironment color
vEnvironment variables

In the cookie jar, only these cookie jar targets are available:

LetterCookie jar target
sDomain sidebar
cCookie list

Browse mode (request pane focused, not editing)

KeyAction
↑/↓/←/→Navigate fields
Home / EndJump to first / last field
ReturnEnter edit mode
EscapeExit browse mode
SpaceToggle header/param/assertion/capture enabled/disabled
Ctrl+TToggle form entry text/file (browse context)
Ctrl+DRevert current field
Ctrl+RRevert all fields

Edit mode (editing a field value)

KeyAction
ReturnCommit edit
EscapeCancel edit
TabMove to next field

Code editor (YAML overlay, JSON/XML bodies, and inline JavaScript)

KeyAction
Ctrl+GToggle fold at current line
Ctrl+SpaceScript completion / parameter help
Ctrl+Alt+FFormat inline JavaScript or JSON request body
Ctrl+Z / Ctrl+Shift+ZUndo / redo editor changes
Shift+ReturnInsert newline

Use Ctrl+Alt+X on an external script to open its validated file in the configured editor. On a request script tab, Ctrl+Alt+R shows the active phase's inherited execution order.

Bulk fold and unfold actions are configurable in Shortcuts and unbound by default.

Help overlay

KeyAction
↑/↓ or j/kScroll
PageUp / PageDownPage scroll
Home / EndJump to top / bottom

Env editor mode

KeyAction
Ctrl+SSave environment
Ctrl+NCreate new environment
Ctrl+KClone selected environment
Ctrl+WDelete selected environment
sToggle secure storage for the selected variable (browse mode)
rReveal or mask the selected secret (browse mode)

Collection Runner mode

KeyAction
Tab / Shift+TabMove between options and requests
↑/↓Select an option, request, folder, or result row
SpaceToggle the selected request or folder
EnterActivate an option or expand a result row
rStart the configured run from options
sStop the active run, including from its detail overlay
o in settled result detailsOpen the request or selected result's source; choose an origin when needed
←Return from results to configuration
EscLeave the Runner while the active run continues

Results update per execution, with pending, running, passed, failed, skipped, and cancelled states keyed by request and dataset iteration. Completed details remain inspectable during execution. Tab and scrolling stay available; the Run action becomes Stop, activated by click or focused Enter/Space. Stop remains in the stopping state until shared cancellation and cookie cleanup settle. F5 resumes live results or the collection's latest settled run. App.tsx owns a session map keyed by collection directory, retaining run configuration, display metadata, iteration/result selection, redacted diagnostics, and bounded body previews across view changes, reloads, and collection switches. Configuration edits do not relabel retained results, and preflight failures preserve the prior snapshot. A later settled run replaces it; app exit clears it. No disk history is added. runnerSession.ts reserves failure summaries and origins before optional details within a 5 MiB budget; required metadata can exceed that budget. Text body previews are limited to 10,000 UTF-8 bytes and binary bodies remain metadata-only. Omission notices distinguish missing retained details from unevaluated checks. runnerSource.ts resolves current request/folder/collection owners; unavailable sources warn without discarding the snapshot. Source navigation is available after cleanup, and F5 returns to the retained selection. Active runs block edits, sends, collection switch/reload, and environment/cookie/transport configuration changes across keyboard, palette, and mouse paths; read-only browsing and appearance remain available.

Cookie jar mode

KeyAction
↑/↓Select domain (sidebar) or cookie (list)
Ctrl+NAdd a cookie (modal form: name, value, domain, path, expires, secure, httpOnly, sameSite)
Ctrl+EEdit the selected cookie
EnterExpand or collapse the selected cookie
Ctrl+Alt+BCopy the selected cookie as name=value
/Filter the cookie list (Esc clears, Enter keeps)
Ctrl+WDelete all cookies for the selected domain (confirms)
Ctrl+DDelete the selected cookie (confirms)
Ctrl+Alt+WClear the entire cookie jar (confirms and backs up unreadable storage)
rRetry unavailable cookie storage
EscClose the cookie jar view

The cookie jar is opened from the command palette (Cookies). It captures Set-Cookie response headers and re-sends matching cookies on later requests (per redirect hop; user-authored Cookie headers win on name conflicts). The response pane's Cookies tab lists cookies sent on the final request leg and the final response's Set-Cookie entries. One jar per collection, stored encrypted at ~/.config/noodle/cookies/<collection_id>.json with the key in the OS vault; falls back to plaintext 0600 on macOS/Linux when the vault is unavailable. Windows requires vault-backed encryption and rejects plaintext jars; unavailable storage is preserved until an explicit backup-backed reset. Controlled per collection via cookies.enabled in settings.yml (default on), per request via sendCookies: false in request YAML, and honored by collection run / request run. Per-request suppression prevents sending jar cookies but still captures response cookies.

Focus model

Pane cycles are controlled by the active view:

  • Main view: sidebar → urlbar → request → response (4 panes). Tab/Shift+Tab wraps. URL bar has method and URL sub-focuses; Tab moves between them while focused.
  • Folder view: sidebar → folder (2 panes, when a folder is the selected item).
  • Env editor: env-sidebar → env-header → env-vars (3 panes).
  • Cookie jar: cookie-sidebar → cookie-list (2 panes).
  • Settings: settings-sidebar → settings-content (2 panes).
  • Collection Runner: runner-options → runner-requests (2 panes).

Active pane gets cyan border + ▸ prefix. Global keys work regardless of focus. Context-dependent bindings (Ctrl+S, Ctrl+N, Ctrl+K, Ctrl+W, Ctrl+T) dispatch to the appropriate action based on which pane is focused. Skips hidden panes when expanded mode (F2) collapses request or response.

Drag the divider after the sidebar or between the request and response panes to resize the workspace. Stacked and side-by-side layouts keep separate request/response proportions for the current session; double-click a divider to restore its default.

Testing

  • bun test runs all tests. No external services needed.
  • Pure helpers in tests/unit/, integration tests in tests/integration/.
  • Tests use real filesystem I/O for filestore, lang, and env modules (write to temp dirs with mkdtemp).
  • Never use fixed delays (setTimeout, Bun.sleep, or equivalent) to wait for asynchronous test state. Await the real operation or use a state-based wait such as waitFor.
  • Tests must finish without unexpected console or runtime warnings. Treat React/OpenTUI act(...) diagnostics as failures; expected warnings must be captured and asserted explicitly.
  • Before handing off any changed asynchronous test, run its file with bun test <file> --rerun-each=10 and report the result.

Subagents

Use project-scoped custom agents only for an independent final review of materially relevant changes; do not spawn them for documentation-only work, trivial mechanical edits, or unrelated areas.

  • Delegate to tui_reviewer after material changes to src/ui/, UI hooks, keymaps, focus, overlays, editors, or OpenTUI rendering. Ask it for a read-only regression review after implementation and focused tests are complete.
  • Delegate to request_security_reviewer after material changes to request execution, authentication, OAuth, variables, secrets, cookies, TLS, proxy behavior, file/path handling, imports/exports, timeline persistence, HAR/code generation, or redaction. Ask it for a read-only security review after implementation and focused tests are complete.
  • If a change materially spans both areas, the two reviews may run in parallel. Wait for both and assess their evidence before changing code; do not accept findings without verifying them against implementation and tests.

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types /graphify, use the installed graphify skill or instructions before doing anything else.

Rules:

  • For codebase questions, first run graphify query "<question>" when graphify-out/graph.json exists. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
  • Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
  • If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
  • Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.