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
- noodle-rest/noodleword for word, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 1
- noodle-rest/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.
- noodle-devSkill
- noodle-releaseSkill
- noodle-useSkill
- opentuiSkill
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
- Very specific: line 268
Keep Save/Open actions centralized in commandActions.ts.
- Very specific: line 297
Oxfmt check covers: only ./src ./tests; .agents/ is not included.
- Very specific: line 314
Error re-throws: must preserve { cause: e }, except at redaction boundaries where the original error exposes secrets or local paths.
- Very specific: line 324
Notifications and completion: Keep transient Toast non-focusable.
- Very specific: line 335
All except fixed keys can be overridden in YAML:
- Distinctive: line 410
When a folder is selected, the folder targets replace the request and response targets:
- Very specific: line 469
Use Ctrl+Alt+X on an external script to open its validated file in the configured editor.
- Very specific: line 563
Never use fixed delays (setTimeout, Bun.sleep, or equivalent) to wait for asynchronous test state.
- Very specific: line 565
Before handing off any changed asynchronous test, run its file with bun test <file> --rerun-each=10 and report the result.
- Distinctive: line 569
Use project-scoped custom agents only for an independent final review of materially relevant changes.
- Distinctive: line 573
If a change materially spans both areas, the two reviews may run in parallel.
- Very specific: line 579
When the user types /graphify, use the installed graphify skill or instructions before doing anything else.
- Very specific: line 584
If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Very specific: line 585
Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
≈ “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.
Files
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 readinessCLI 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.ymlis used, then the current directory.--noproxyforces direct connections and--insecuredisables TLS verification for that invocation. - Import subcommand:
source(positional, required),--format/-i(openapi,swagger,postman, orinsomnia; 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(openapiorpostman), and--output/-o(a file for OpenAPI, or a new/empty directory for Postman). Postman createscollection.postman_collection.jsonplus 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 printsRun: brew upgrade noodlewithout running it; JSON returnsdata.status: "homebrew_managed"anddata.command: "brew upgrade noodle", including with--force; unavailable in Bun development runtime. - Agent subcommand:
agent installwrites the embeddednoodle-useskill to~/.agents/skills/noodle-useand links detected Claude, Cursor, Codex, and OpenCode installations to that managed copy. It preserves unmanaged targets by default and reports every conflict;--forcedeliberately 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, runnoodle agent installto 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; andcookie 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 carrycancelled: true; unstarted executions use skip reasoncancelled. Summarycompleted,cancelled, andunstartedsatisfy 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.--delayaccepts a non-negative safe integer number of milliseconds and waits only between selected requests.cookie listprints jar contents grouped by domain (values included);cookie clearempties the jar.secret setprompts without echo in a TTY or accepts--stdin.collection formatcanonicalizes request YAML and pretty-prints valid JSON bodies without lossy numeric conversion; imports run it automatically.collection initbootstraps missing collection markers in an existing directory and registers it.workspace audit --fixremoves invalid registered paths. - Collection hooks: Optional
hooks: { setup?: requestId, teardown?: requestId }in collectionsettings.ymlruns 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 andrequest runremain unchanged. - Collection preview:
collection run --dry-runshares 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 returnsdryRun,environment(name or null), one iteration's orderedsequence: { id, stage }[],iterations, andtotalExecutions, including hooks per row. Runtime failures may shorten execution and scripts can send additional requests. Reject--outputand--reporterwith 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 andnoodle.run.get, whilenoodle.env.getstays a snapshot. Read-onlynoodle.iterationexposes zero-basedindex,count, and originaldata, 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 carryiteration; collection results additerations. No-data behavior and result shapes remain unchanged. - Automation environment selection:
request runandcollection runuse--envwhen supplied; otherwise they use the collection root'ssettings.ymlenvironment. - Run-scoped variables: Every manual TUI send and
request rungets an isolatedRunScope; everycollection runand 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 andrequest runmay persist captures declared withpersist; collection runs and the TUI Runner ignore persistence. Script writes are transient by default. Manual sends andrequest runhonor explicitnoodle.run.set/unsetoptions{ persist: "environment" | "secret" }; collection runs and the TUI Runner suppress persistence. - Body templates:
src/bodyTemplate.tsexpands$random.methodand$time.methodwith 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 directnoodle.sendRequestinputs 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. ReusescriptRandom.ts,scriptTime.ts, andscriptJson.tsvalidation. - Scripts: Optional top-level
scriptsin collectionsettings.yml, non-rootfolder.yml, and request YAML accepts one string perpreand/orpost. Each string is inline JavaScript or a collection-relative./path/to/file.jsreference. 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-prototypenoodlenamespace exposingnoodle.request,noodle.env,noodle.run,noodle.crypto,noodle.random, andnoodle.time, plus capturedconsole. JavaScript built-ins remain global; top-level await and Promises use controlled VM jobs. Pre/post network calls use onlynoodle.runRequestandnoodle.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.ScriptEditorreusesCodeEditorRenderablefor 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_CONTRACTgenerates 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.jspaths; opening a script validates it throughresolveFile()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+Fformats an active inline script or JSON request body. Globalformat_on_savedefaults 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.tsis 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 andrequest runresolve 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 ornoodle.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.tscollects collection settings, ancestor folders derived from the request collection path, and request blocks for the shared lifecycle. Rootfolder.ymlis 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. Savednoodle.runRequest()calls use the same inheritance. Diagnostics identify phase, scope, scope ID, source kind, and collection-relative external source path; testerrorsretains every block error and legacyerrorremains the first error. CLI, Results, and manual history retain bounded, redacted origins, logs, and diagnostics without source code or RunScope values. - Scripted tests: Optional
testsin collectionsettings.yml, non-rootfolder.yml, and request YAML accepts one inline JavaScript string or collection-relative./path/to/file.jsreference evaluated after declarative assertions in manual sends,request run, and collection runners. It uses the existing QuickJS sandbox and limits, with synchronous or asynctest(name, callback)andexpect(value)matchers, including.not,toMatchSchema,toHaveProperty,toHaveLength,toBeTypeOf, andtoMatchObject. 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 throughnoodle.*; 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, redactedtests: { 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 thetestfailure category and make automation exit nonzero. - Script time helpers:
src/scriptTime.tsowns frozennoodle.timemethods 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 JavaScriptDateand random timestamp generators available. - Pre-request scripts:
scripts.prestages request and RunScope mutations and commits only on complete success. Pre failure skips HTTP and all response phases and returns thescriptfailure category with redacted logs and errors. Successful writes survive later failures. Pre-request API behavior remains unchanged, but all Noodle API accesses require thenoodle.prefix. Treat scripted collections as trusted code becausenoodle.env.getcan read a selected-environment secret and place it in a following request. - Post-response scripts:
scripts.postruns 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-onlynoodle.responsemetadata (status,statusText,timeMs), case-insensitiveheaders.get/has,text(), andjson(); 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/unsetintents. Manual sends andrequest runflush 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 andnoodle.env.getremains 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
sendCookiesis not false, post exposes final-URL-scopednoodle.cookies.get(name),noodle.cookies.set(input), andnoodle.cookies.delete(name). Set requires stringname/value, with optional applicablepath, ISO 8601 date-timeexpires, booleansecure/httpOnly, andsameSite: strict|lax|none. Unknown attributes, includingdomain, 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,--versionauto-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. UseuseKeyboard,createCliRenderer,createRootfrom OpenTUI. - Language: TypeScript 7, strict mode,
"type": "module". - Lint: Oxlint 1 with ESLint and TypeScript plugins.
no-unused-varsignores_-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(notyarn.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 testsResponse 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
| Method | Command |
| curl | curl -LsSf https://raw.githubusercontent.com/noodle-rest/noodle/main/scripts/install.sh | sh |
| Homebrew | brew install noodle |
| PowerShell (Windows x64 beta) | irm https://raw.githubusercontent.com/noodle-rest/noodle/main/scripts/install.ps1 | iex |
| Source | bun 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); oldwilfredinni/noodletap is retired withtap_migrations.json→homebrew/core. Seepackaging/homebrew/README.mdfor migration (brew reinstall+brew untap wilfredinni/noodle). - Release workflow at
.github/workflows/release.yml: triggered bygit 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 publishesSHA256SUMS, validates downloaded macOS and Windows artifacts before publication, and updates noodle-site'supdate.jsonafter release publication. Homebrew core updates independently; no tap dispatch (manual bump viabrew bump-formula-pr, seepackaging/homebrew/README.md). - Windows PowerShell 5.1+ installation uses
%LOCALAPPDATA%\Programs\Noodle\noodle.exeand user PATH by default;NOODLE_VERSION,NOODLE_INSTALL_DIR, andNOODLE_SKIP_PATH_UPDATE=1override those choices. Windows updates returnrestart_requiredandlog_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.tsimmediately 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
.ymlfiles, one per request. Extension is.ymlnot.yaml. OptionalsendCookies: falsesuppresses outgoing jar cookies and the post cookie capability, but still processes response Set-Cookie headers (serialized only when set; parsed strictly likefollowRedirects/maxRedirects). - Response assertions: Optional request
assertblocks are evaluated by manual TUI sends,request run, andcollection run. Each row accepts optionalenabled: false; disabled rows remain validated and editable but produce no outcomes. Expressions addressstatus,response.time, case-insensitiveheaders.<name>, and JSONbodypaths. 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
capturemappings bind response expressions to RunScope variable names. Every entry is an object with requiredvalue, optionalenabled: false, and optionalpersist: secret|environment; scalar shorthand is invalid. Captures and assertions share onecreateResponseResolver(). 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 andrequest runhonor 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 basenamessettingsorfolder(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.gitignorewhile preserving existing rules. - Windows filenames:
userPath.tsvalidates 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 fromgetNoodleConfigDir(). - CLI response details:
request run --body/--headers/--cookiesadds opt-in human output from the existing redacted result;--jsonkeeps one envelope and includes received-cookie metadata with masked values. Escape terminal controls in displayed details and keep binary bodies metadata-only;--outputsaves unredacted original bytes. - Request bodies support
none,json,xml,multipart,urlencoded, andbinary. XML bodies use the code editor, default toapplication/xmlwhen no enabled Content-Type exists, and are sent unchanged after variable substitution. - Environments are
.envfiles under<collection>/.environments/. Format isKEY=value(dotenv-style, not YAML). Lines starting with#disable a var._color=<name>sets sidebar badge color.# @secret NAMEfollowed by a blankNAME=placeholder declares a credential-vault value; process environment wins over the stored value. $VARNAMEtemplate 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 useJSON.stringify().- Optional request tabs: Empty Assert and Capture tabs are hidden behind the request pane
+menu.gthenofocuses it; existinggthenv/ctargets reveal either tab directly.useEditBrowseowns per-request session reveal state and menu focus; populated tabs remain visible. - System theme: Select
systemto follow the terminal palette.ThemeProviderlistens 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_urlto fill missing endpoints from an OIDC issuer or standard discovery URL;discovery_url_kind: documentrequests 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. @/pathhome syntax for multipart file values and binaryfile_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 throughbuildHar, 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.tsintentionally 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:
F4opens Settings. Global Behavior selects a detected external editor for command-palette actions that open the active collection or~/.config/noodle. Global proxy mode issystem,off, orcustom; a collection mayinherit, useoff, or definecustom. Custom URLs reject credentials and variables; authenticated proxies persist onlyauth: true, while credentials live in the OS vault.--noproxytakes precedence for one run. Collectionsettings.ymlalso stores generatedcollection_id, optionalname,description,timeline_max_entries, activeenvironment, 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;--insecuredisables 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 reusesYamlFileEditorfor 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.tsxowns the current sidebar width plus separate stacked and side-by-side request/response ratios.MainView.tsxhandles drag state, responsive minimums, and double-click reset;RequestResponseView.tsxrenders the layout-specific resize handles. Keep sizing session-only unless persistence is explicitly requested. - Sidebar visibility:
AppInner.tsxowns session-only visibility andtoggleSidebarVisible()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
opentuiskill. The skill lives at.agents/skills/opentui/SKILL.md. - Command actions are centralized in
commandActions.ts. BothuseAppKeymap.tsandcommands.tsimport from it. Never duplicate command logic. - Overlay state travels as one object.
useOverlayStateowns every overlay's visibility, pending value, and handle, andAppInnerpasses the wholeOverlayStatetoAppOverlaysanduseOverlayInterceptsrather than re-declaring fields at each consumer. Adding an overlay means declaring it inuseOverlayState(state,activeOverlaybranch, return), handling its keys in the intercepts, and rendering it inAppOverlays— never widening a mirrored prop list. State owned elsewhere (useReloadGuard,useCollectionSwitcher) and behavior callbacks stay explicit props.tests/unit/_overlayState.tsbuilds a defaultOverlayStatefor tests. - Notifications and completion: Keep transient
Toastnon-focusable. Show Last Notification opensNotificationOverlayfor keyboard scrolling and resets its scroll on each opening.Autocomplete.tsxowns bounded, cursor-anchored completion rendering and keyboard/mouse selection; reuse it for inputs andCodeEditorCompletionrather than duplicating menu state. - Command palette commands return boolean:
run()returnstrue(close palette) orfalse(stay open). - PickerOverlay isNavigable: Pass to skip non-selectable items (section headers) during up/down/return navigation.
- Environment controls:
eopens the searchable picker from the main view;F3opens the full editor. New environments are created throughNewEnvironmentOverlay, then persisted byuseEnvironmentEditor.createEnv(). In environment browse mode, configurableenv_secret(s) toggles secure storage andenv_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-Cookieare 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 carrycancelled: 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.tsredacts beforesrc/filestore/timeline.tsapplies 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-sentCookieheaders and responseSet-Cookieheaders 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:
mor the footer action switches the focused Body tab between Source and Visual.ResponseVisualBodyrenders JSON/XML parsed byresponseVisual.tsas 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:
ResponsePanerenders bodies through a read-onlyCodeEditorRenderable; 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+pGlobal (always active, gated on !helpVisible)
| Key | Action |
Tab / Shift+Tab | Cycle focus (sidebar → URL bar → request → response) |
Ctrl+Return | Send request |
Ctrl+S | Save request to disk |
Ctrl+N | New request |
Ctrl+K | Clone request |
Ctrl+W | Delete request |
Ctrl+U | Cycle environment |
F3 | Open environment editor |
F4 | Open Settings |
Ctrl+P | Open command palette |
Ctrl+F | Find request |
Ctrl+L | Toggle layout (stacked / side-by-side) |
Ctrl+B | Toggle sidebar (open / closed) |
F2 | Expand/collapse focused pane |
F5 | Open collection Runner |
F1 | Toggle help overlay |
Ctrl+T | Open theme picker |
Ctrl+E | Edit request in overlay |
Ctrl+Alt+E | Edit request YAML in overlay |
Ctrl+Alt+B | Copy response body |
Ctrl+Alt+S | Save live binary response file (focused response Body tab) |
Ctrl+Alt+O | Open saved binary response in default app (focused response Body tab) |
m | Toggle Source / Visual (response Body tab focused) |
/ | Filter the focused Body tab with JSONPath in Source or text search in Visual |
Ctrl+Alt+N | New folder |
Ctrl+O | Open collection switcher |
Ctrl+Z | Undo all unsaved changes |
g | Enter jump mode (press a hint letter to focus that element; Esc exits) |
e | Open environment picker |
Ctrl+C | Quit (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).
| Letter | Target |
s | Sidebar pane |
m | URL bar method select / Folder General tab |
u | URL bar URL field |
h | Request Headers tab / Folder Headers tab |
p | Request Params tab |
x | Request Path tab |
b | Request Body tab |
a | Request Auth tab / Folder Auth tab |
v | Request Assert tab |
c | Request Capture tab |
d | Request / Folder Pre Script tab (when visible) |
f | Request / Folder Post Script tab (when visible) |
j | Request / Folder Tests tab (when visible) |
t | Request Settings tab |
o | Request / Folder optional-tab menu (+, when visible) |
r | Response Body tab |
e | Response Headers tab |
n | Response Network tab |
l | Response Timeline tab |
k | Response Cookies tab |
i | Response Results tab |
z | Response Console tab (when logs make it visible) |
y | Folder 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:
| Letter | Folder target |
s | Sidebar pane |
m | General tab |
h | Headers tab |
a | Auth tab |
d | Pre Script tab (when visible) |
f | Post Script tab (when visible) |
j | Tests tab (when visible) |
o | Optional-tab menu (+, when visible) |
y | Activity tab |
In the environment editor, only these environment targets are available:
| Letter | Environment target |
s | Environment sidebar |
m | Environment name |
c | Environment color |
v | Environment variables |
In the cookie jar, only these cookie jar targets are available:
| Letter | Cookie jar target |
s | Domain sidebar |
c | Cookie list |
Browse mode (request pane focused, not editing)
| Key | Action |
↑/↓/←/→ | Navigate fields |
Home / End | Jump to first / last field |
Return | Enter edit mode |
Escape | Exit browse mode |
Space | Toggle header/param/assertion/capture enabled/disabled |
Ctrl+T | Toggle form entry text/file (browse context) |
Ctrl+D | Revert current field |
Ctrl+R | Revert all fields |
Edit mode (editing a field value)
| Key | Action |
Return | Commit edit |
Escape | Cancel edit |
Tab | Move to next field |
Code editor (YAML overlay, JSON/XML bodies, and inline JavaScript)
| Key | Action |
Ctrl+G | Toggle fold at current line |
Ctrl+Space | Script completion / parameter help |
Ctrl+Alt+F | Format inline JavaScript or JSON request body |
Ctrl+Z / Ctrl+Shift+Z | Undo / redo editor changes |
Shift+Return | Insert 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
| Key | Action |
↑/↓ or j/k | Scroll |
PageUp / PageDown | Page scroll |
Home / End | Jump to top / bottom |
Env editor mode
| Key | Action |
Ctrl+S | Save environment |
Ctrl+N | Create new environment |
Ctrl+K | Clone selected environment |
Ctrl+W | Delete selected environment |
s | Toggle secure storage for the selected variable (browse mode) |
r | Reveal or mask the selected secret (browse mode) |
Collection Runner mode
| Key | Action |
Tab / Shift+Tab | Move between options and requests |
↑/↓ | Select an option, request, folder, or result row |
Space | Toggle the selected request or folder |
Enter | Activate an option or expand a result row |
r | Start the configured run from options |
s | Stop the active run, including from its detail overlay |
o in settled result details | Open the request or selected result's source; choose an origin when needed |
← | Return from results to configuration |
Esc | Leave 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
| Key | Action |
↑/↓ | Select domain (sidebar) or cookie (list) |
Ctrl+N | Add a cookie (modal form: name, value, domain, path, expires, secure, httpOnly, sameSite) |
Ctrl+E | Edit the selected cookie |
Enter | Expand or collapse the selected cookie |
Ctrl+Alt+B | Copy the selected cookie as name=value |
/ | Filter the cookie list (Esc clears, Enter keeps) |
Ctrl+W | Delete all cookies for the selected domain (confirms) |
Ctrl+D | Delete the selected cookie (confirms) |
Ctrl+Alt+W | Clear the entire cookie jar (confirms and backs up unreadable storage) |
r | Retry unavailable cookie storage |
Esc | Close 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 testruns all tests. No external services needed.- Pure helpers in
tests/unit/, integration tests intests/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 aswaitFor. - 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=10and 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_reviewerafter material changes tosrc/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_reviewerafter 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. Usegraphify path "<A>" "<B>"for relationships andgraphify 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.
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
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.

