itda

Just type an address after itda and your AI can use the site.

Give itda one address. It learns what the site can do and tries it. It gives your AI agent a short list of actions in plain words. Reads just work. Nothing changes on the site until you say yes. It runs on your own computer, and it works on the old intranet behind a login too.

It is for the sites your company runs and the services you have an account on, not the web at large. What it can and cannot do lists both, and what happens when a site changes.

$ itda news.ycombinator.com
1/5  Looking at news.ycombinator.com...
    The page opens without signing in.
    Found: a list of 30 records, a form, a feed.
2/5  What agents will be able to do:
    read   home         List what Hacker News shows  (inputs: p)
    read   feed         Read the RSS feed
3/5  Trying every read once...
    ✓ home         30 records
    ✓ feed         ok
4/5  Saved as 'news-ycombinator'.
    Connect Claude Desktop? [Y/n]
5/5  Adding itda to Claude Desktop...

Ask your agent: “use news-ycombinator to list what Hacker News shows”. A site behind a sign-in opens in your own browser. You sign in and use it as usual while itda watches. What you type never leaves your computer.

Why

Agents that drive a browser re-read every page and spend thousands of tokens on each screenshot. They follow whatever the page tells them and break silently when a layout changes. itda moves that work to a setup step. A site definition says which actions exist, what they send, what a correct answer looks like and whether they change anything. After that, every call is small, typed and checked.

• Checked. A signed-out page or a redesigned site comes back as an error with what to do next, never as data.
• Read-only by default. Changes wait for a person to approve the exact request, in a terminal or in the agent app. No agent tool can approve.
• Adaptive. Reads can recover through browser fetch and rendering. Unresolved reads fail without locking the site; changes are never replayed.
• Accountable. A local log records every call, approval and change. Each entry seals the one before it, so edits show.
• Local. No server, account or telemetry. Secrets stay in your OS keyring.

Where to go next

• Quick start: install, set up a site you use, and try the bundled sandbox.
• Use it from an agent: connect Claude, Cursor, VS Code or Codex.
• Writing a site definition: add your own site by hand.

Quick start

Install

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/brnyxx/itda-cli/releases/latest/download/itda-cli-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/brnyxx/itda-cli/releases/latest/download/itda-cli-installer.ps1 | iex"

Download an archive from Releases, or build from source with cargo install --git https://github.com/brnyxx/itda-cli itda-cli.

Claude Desktop, with no terminal: download the bundle for macOS (Apple silicon), macOS (Intel) or Windows and open the file. Claude Desktop installs itda with its tools, and “use the-site-you-use.example” sets a site up from inside the conversation. Approving a change still happens in a terminal with itda approve, so for changes install the command too.

Check the setup:

$ itda doctor
itda 0.7.0
ok    data directory   /home/you/.local/share/itda
ok    secrets          system keyring; long secrets sealed in ~/.local/share/itda/vault.sealed with a key from the keyring
ok    audit log        0 records, chain intact
ok    changes          none with an unknown outcome
ok    sites            0 installed, 0 invalid
ok    agents           none connected (itda setup <url>, or itda mcp install <client>)
ok    local addresses  refused (ITDA_ALLOW_LOCAL=1 allows them)

Set up a site you use

Type itda and paste the address of a site you use. Press Enter. itda looks at the page. When the page is drawn by scripts and shows itda only a title, it opens your browser on it for a few seconds. It watches what the page loads by itself and drafts from those calls. Nothing is clicked or typed, and the window closes on its own. If the page needs a sign-in, it asks for your user name and password and fills in the site’s own form for you (--user <name> from a script, the password on stdin). Or it asks to open your browser and watch you use the site. It shows what agents can do and tries every read. After one more Enter, it connects the agent apps it finds on your computer. From then on, ask your agent for things on that site. itda setup <address> does the same from a script. --no-record never opens the browser; --watch-only watches but never asks you to record. itda setup --help lists the flags. itda speaks the language of your LANG; ITDA_LANG=ja (or any tag in docs/i18n.md) overrides it.

itda recognises sites running known software (GitLab, Jira, Confluence, Redmine, Discourse, MediaWiki, WordPress, Gitea or Forgejo) from their pages and confirms each with one request to the software’s own API. itda then says “This looks like GitLab. Using its API at .” and the agent gets the software’s real reads and changes from a ready-made template, with the page’s own lists and forms joining them. --as <software> forces a template when the page does not say; --no-template skips them.

From inside your agent

Once itda is connected (itda mcp install <client>, or the question at the end of a setup), you can skip the terminal for the next sites. Tell your agent “use news.ycombinator.com”. It calls itda_setup with the address. itda looks at the site, drafts and tries it the same way. Its actions appear as tools in the same conversation. A page drawn by scripts opens briefly in a browser window on your screen. itda watches what it loads without clicking or typing. When a read says to sign in, the agent calls itda_login. Your own browser opens for you to sign in; the agent only sees the account id. itda_check, itda_sites and itda_manage cover checking, listing, removing and resuming sites and reading approvals and the audit log, with a form for you to confirm the ones that change something. Nothing an agent can call approves a change.

Try the sandbox

The repository includes a small fake intranet that only listens on 127.0.0.1: a notice board with an HTML table, a JSON API behind an API key, and a page that refuses automated access.

git clone https://github.com/brnyxx/itda-cli && cd itda-cli
cargo run -p itda-sandbox            # http://127.0.0.1:8787

In another terminal, use a scratch data directory and install its definition:

export ITDA_HOME=$(mktemp -d) ITDA_ALLOW_LOCAL=1
mkdir -p "$ITDA_HOME/specs/sandbox"
cp examples/sandbox/spec.yaml "$ITDA_HOME/specs/sandbox/"
itda ls

Read, sign in, and see what happens when a site says no:

itda call sandbox.list-notices --q 보안      # JSON API
itda call sandbox.notice-board --json       # HTML table extracted into records
itda call sandbox.me                        # exit 10: no API key yet
echo sandbox-key | itda login sandbox       # stores the key in the OS keyring
itda call sandbox.me                        # signed in
itda call sandbox.reports                   # exit 12: refused, in your browser too; nothing is paused

Make a change:

itda call sandbox.create-notice --title hi  # exit 20: waits for approval <id>
itda approve <id>                           # shows what it does and the exact request, asks y/N
itda call sandbox.create-notice --title hi --approval <id>
itda audit                                  # everything above, hash-chained
itda describe sandbox                       # every action with its inputs and a command to copy

Without a keyring (CI, containers), skip itda login and set ITDA_SECRET_STORE=env ITDA_SECRET__SANDBOX__DEFAULT__API_KEY=sandbox-key.

Requests to one site go one at a time, about 1.2 seconds apart, as on a real website. Consecutive or parallel calls take a moment. A site definition can ask for more room with defaults.interval.

Commands

Use it from an agent

The repository has two files for the agent itself: AGENTS.md, a guide to using itda well, and skills/itda/SKILL.md, the same guide in the short form skill loaders take. The MCP server hands the agent the same rules as its instructions.

MCP clients

itda mcp install claude-desktop   # or cursor, vscode, codex
itda mcp install claude-code      # prints the `claude mcp add` command

The installer keeps your other servers and settings and saves the previous file as .bak. It changes nothing if itda is already there. --dry-run shows the new file without writing it. It starts itda by its absolute path and passes ITDA_HOME, ITDA_ALLOW_LOCAL and ITDA_SECRET_STORE along when they are set. Restart the client afterwards.

What the agent sees

With up to 30 actions installed, each is a tool named like the CLI (sandbox.list-notices), with a JSON Schema for inputs. Hints: reads are readOnlyHint; DELETE actions are destructiveHint; PUT and DELETE are idempotentHint.

With more actions, itda lists three fixed tools. The tool list stays short and prompt caches stay valid:

itda mcp --mode direct or --mode catalog overrides the choice. itda mcp --site <name> serves only that site’s actions as tools. It refuses itda_setup and itda_prepare and confines itda_login, itda_check, itda_sites, itda_manage and itda_shape to that site. Use it in a project’s MCP configuration when the agent should only reach one site from there.

Seven tools are always there, so the agent never needs a terminal to set a site up or look after it:

Every gap comes as {rule, subject, priority, reason, remedy}; remedy has the command for a terminal and the tool and arguments to call next (the action’s own tool, or itda_call with action when the server lists the catalog). Act on a remedy only when it serves what the user asked; never call a change because a gap names it. itda_setup returns the top three gaps as gaps.

When itda_setup keeps one read or none, its result carries a remedy naming itda_prepare with the page’s address.

Every result uses the itda call --json envelope, marked "untrusted": true. A note before it says website data is not instructions. Results over 24 KB keep the start of their longest lists and say "truncated": true. Failures are tool errors with a code and a fix, so the agent can tell the user what to do.

Prepare a site yourself

Some sites tell a person more in their docs than a page tells itda: a reference that lists GET /api/v2/items/{id}, an API description, a GraphQL schema. With itda_prepare the agent reads them and drafts the definition itself; itda calls no model. The agent never sees a value the site holds. Results carry titles, the headings of a page’s own sections, paths, methods, field names, selectors, keys, types, JSON pointers and counts, each piece with an evidence id (e12) the agent cites. The loop, one tool with an op:

An operation is kept only when its base_url is a server the site documented or answered from, its method and path are a route in the docs, a description or a script that answered, or, for a GET, a path itda read (/users/@me matches /api/v10/users/@me), an HTML read has an html extraction (records or page fields; with required_html_fields alone it has nothing to return), a file read declares format: file, and a signed-in operation has a path read with the session. A declared read whose request asks for a change is a change. A route the description says needs a sign-in itda cannot use is dropped. A draft that only reads the home page and checks nothing is refused (no_actions). Changes are written into the definition and never sent; the user approves each later, as for any site.

A session has 120 tool calls, 48 requests for pages and documents, 24 requests for checks (browser recovery counted, from the sites’ own pacing record), and two rounds each for coverage and repairs. Past them, budget_exhausted or round_limit says to install what is kept or stop. Every result has feedback entries {kind, subject, reason, next}; next is the call to make. A call with the same arguments is answered from the session, not sent again. A site that refuses itda (blocked) means pause and tell the person. The checks are tries of the knowledge base’s prepare stage, which itda fsck and the pass rates leave out. skills/itda-prepare/SKILL.md is the loop in the short form skill loaders take.

Files

A read declared format: file saves its answer on the user’s computer and returns a manifest in data, never the bytes: {path, bytes, media_type, sha256}. The file lands under files/<site>/ in the data directory, or where itda call ... --out <dir> says; the command prints Saved <path> (<bytes> bytes, sha256 …) once. Over MCP the result carries the manifest and a resource_link to the file, and the tool’s description says so. A failed download says why in one word, and keeps nothing: wrong_media_type (the site answered with a page or another kind of content), partial_answer (a 206 or a short body), empty_answer, too_large. itda check skips file reads (“saves a file”). itda setup tries each one once by its headers and first bytes (the media type and size the definition allows) and keeps nothing, so a site whose only reads are files is set up like any other.

A change whose body carries a file takes the path of a file on the user’s computer in the input its definition names. The user approves that exact file: the review shows its name, size and SHA-256, and other bytes under the same path withdraw the approval (approval_expired, reason: file_changed). A file that changes while it is being sent ends the call with action_outcome_unknown and reason: file_changed; as with any lost answer, never call it again on your own.

Lists that go on

A read with pagination in its definition returns meta.next if the site reports another page. It is an opaque handle such as ic_4f0a4207d04f4a0fb4e059d26bd54b6d. The agent passes it back as next (--next on the command line) with the same inputs to get the following page. That page may have its own meta.next. The site’s own marker, a cursor, page number or offset, stays on the user’s computer. itda stores it in the local database for fifteen minutes, bound to that site, action, account, inputs and definition. itda removes it from the data it appears in. itda refuses handles for another action, account or inputs, or after a definition change or expiry, with pagination_invalid or pagination_expired (exit 23). The agent starts again without next. Only reads turn pages. itda sends a change once. The server instructions, AGENTS.md and the skill tell the agent to read only as many pages as the question needs.

Changes

A change never runs on the first call. The agent gets approval_required, an approval id and instructions to ask you. You run itda approve <id> in a terminal. You see what the action does, the exact request and every input, and answer y. The agent calls again with the same inputs and the approval id; itda sends the change once. Until you answer, that call returns approval_pending (exit 20) and the approval stays. A call with other inputs withdraws it (approval_expired with reason: inputs_changed). With --approve-in-client, clients that show forms ask you directly instead. See Approvals and the audit log.

itda sends a change once. If a request gets no reply after sending (a timeout, a dropped connection), or a GraphQL reply carries errors behind a 2xx, the call fails with action_outcome_unknown (exit 22). The audit log records this outcome: the site may or may not have applied the change. itda never resends a change on its own. An agent must not either. When the change names the read that shows it (confirm in its definition), itda runs that read once and puts the result next to the error as outcome_check: landed means the change is in, so tell the user and do not ask for it again; not_found means the site shows no trace of it, so the user may ask for a new approval; unknown means that read failed too. Without outcome_check, check the site first; only a person decides whether to ask for the change again. Which read a change names shows before you call it: itda describe prints it under the change (after a lost answer: checks list-notices for the new title), --json carries it as confirm: {read, match}, and the change’s tool description (or itda_describe in catalog mode) says the same. A new approval request for a change that landed carries previous_outcome: landed, and its review tells the user so. A change that never left the machine (no turn at the gate, a name that did not resolve, a connection that was refused) keeps its network code. itda reports it as not sent. Agents may retry reads, which keep their usual codes (timeout, request_failed).

A 403 that is not a sign-in problem is api_denied (exit 14): the site refused that one request as not allowed. The error carries upstream_status. It includes provider_reason only if the site’s JSON answer names access_denied, permission_denied, insufficient_scope, insufficient_permissions, service_disabled, forbidden or not_authorized. itda passes on nothing else from the answer. A 403 whose reason says the site rejected the session itself (unauthenticated, invalid_token, token_expired, session_expired, login_required) stays auth_required. Every refusal carries upstream_status.

When something that worked stops working

Run itda check <site> before retrying or re-drafting (itda check --all checks every site and prints one verdict line each). It runs every read needing no input and never sends a change. Each site ends with one verdict and what to do:

A site with several problems gets one verdict, in this order: signed_out, then site_changed, blocked, unreachable. The exit code follows the worst verdict across the sites checked: 10, 11, 12 or 30 as in the table below, or 0 for ok. A read the site refused (api_denied) does not affect the site’s overall verdict. The verdict uses the other reads; the hint names the refused read. --json adds verdict, one entry per site under sites, and every action under results with the HTTP status the site answered as upstream_status.

Shell agents

Agents that only have a shell can call itda call <site>.<action> --json and branch on the exit code:

With --json, itda prints errors on stdout as {"status": "<code>", "message": …, "remedy": …} plus details such as approval.

Approvals and the audit log

How a change is approved

1. An agent calls an action that changes something. itda records the exact request and answers approval_required with an id. Nothing is sent.

2. You list what is waiting with itda approvals, then run itda approve <id> in a terminal:

   $ itda approve 9e96f90486f74733926ffaeb738825e2
   create-notice wants to change Sandbox intranet (sandbox) as account default:
     does         Post a notice
     request      POST http://127.0.0.1:8787/api/notices
     title        점검 공지
   Approve this change? [y/N] y
   Approved. The agent can now run it once, with exactly these inputs.
   

   does is the action’s description from the site definition, followed by every input. itda cuts values longer than 500 characters and shows their length. itda reject <id>, or any answer but y, refuses it. itda reject also withdraws an approval you already granted and the agent has not used.

3. The agent calls again with approval set to the id. itda checks the request matches what you saw. It marks the approval used and sends it once.

Until you answer, a call with the id gets approval_pending (exit 20) and the command to run. The approval stays unchanged; the agent waits instead of asking for a new one. A call with inputs other than those you saw withdraws the approval (approval_expired with reason: inputs_changed). To use those inputs, the agent asks again for you to review them.

An approval covers one request: the site, action, account, every input, the definition (by hash) and the credential (by fingerprint). Changing any of them needs a new approval.

A change that sends a file shows the file instead of the path input, by name, size and SHA-256:

$ itda approve 4c0d0f2e6b3b4ad8a0c1d9e7f5a2b3c4
attach-file wants to change Sandbox intranet (sandbox) as account default:
  does         Attach a file to a notice
  request      POST http://127.0.0.1:8787/board/42/attach
  file         plan.csv (8 bytes, sha256 3a1f0c…)
  memo         Q4 plan
Approve this change? [y/N] y

The approval is for those bytes. If the file under that path changes before the agent calls again, the approval is withdrawn (approval_expired with reason: file_changed) and the agent asks for a new one. If it changes while itda is sending it, the send stops and the call ends with action_outcome_unknown and reason: file_changed. The audit log records the hash of the file a change sent, never its path or contents. It expires five minutes after the request or five minutes after you approve it. itda uses an approval once, before sending anything, so it never replays a failed change. itda logout, itda remove, a new itda login and replacing a definition (itda setup, itda refresh, itda add --force, itda draft ... --install --force) withdraw all pending or granted approvals for that site or account: what you reviewed differs from what itda would send.

itda never retries changes or follows their redirects. If the answer is lost after sending or a GraphQL answer carries errors behind a 2xx, the call fails with action_outcome_unknown (exit 22). When the change names the read that shows it (confirm in the definition, see SPEC.md), itda runs that read once, as a read, and says what it found next to the error: landed (the record is there: the change is in, and the agent is told not to ask for it again), not_found (it is not: the agent may ask again and you review a new approval) or unknown (the read failed too). Only the read’s name and the match result are reported, never its answer. Without confirm, check the site yourself before trying again. In no case does itda send the change again. A change that never left the machine (the gate gave no turn, the name did not resolve, the connection was refused) keeps its network code. itda reports it as not sent.

After a landed check, asking for the same change with the same inputs still needs a new approval, and its review carries a note line: when the earlier one was sent and which read showed it landed. Approving sends it again; decline if one is enough.

Approving in your MCP client

Clients with MCP elicitation forms can ask for approval there, without a switch to a terminal:

itda mcp install claude-code --approve-in-client   # or set ITDA_APPROVE_IN_CLIENT=1

When an agent asks for a change, the client shows you the same review itda approve prints, with an “Approve this change” box. Ticking the box and accepting approves that one request. The call continues and runs it. Declining or closing the form rejects it, and the agent gets approval_rejected. Both decisions go into the audit log. If the client cannot show forms, nothing changes. The agent gets the approval id; you can still use itda approve.

How the form reaches you depends on the protocol revision the client speaks. Up to 2025-11-25 itda sends the client a request and waits 290 seconds for an answer. If nobody answers, the form closes; the agent gets the approval id with seconds left of its five minutes. From 2026-07-28 the form is the call’s result. The client keeps it open as long as it likes and calls itda again with your answer. itda ignores answers that arrive after the approval expires and asks you again for a new approval.

What each client showed, measured on 2026-10-22:

• Claude Code 2.1.289 shows the form in the terminal, under “MCP server “itda” requests your input“: the review lines, the box (“Approve this change”), and Accept and Decline buttons. Space ticks the box, Enter on Accept sends it, Esc closes the form. The agent waits (“Calling itda”) and sees nothing until you answer. Accept runs the change; Decline and Esc both end in approval_rejected. A four-line review showed whole. A longer one showed only its first three lines with “(+2 more lines)” and no key to show the rest; a change with several inputs may not show them all. Claude Code speaks protocol 2026-07-28 with itda. Its Elicitation hook can answer a form from a script without showing it. A hook answering itda’s form would approve changes on its own: do not add one.
• Claude Desktop 3.1623.1 declares no elicitation capability, so itda never sends it a form. Desktop shows its own “Allow once” card for the tool call. The agent gets approval_required with the id; you approve in a terminal. --approve-in-client changes nothing there.

Turn this on only for clients that put elicitation forms in front of you. The form goes to the client application, never the model. A client that answers forms on its own would also approve on its own.

Why a terminal

Without the client option above, approvals come only from a terminal. itda approve refuses to run when its input is not a terminal, and there is no MCP tool that approves. An agent working through a pipe or an MCP connection therefore cannot answer the question for you. This keeps honest agents from approving their own changes. It is not a sandbox: software that runs with your account and full shell access could drive a terminal or edit the data directory. See the threat model.

The audit log

itda appends every call, approval, rejection and change to audit.jsonl in the data directory:

$ itda audit
    1  2026-10-19T08:43:01.846Z  call            sandbox.create-notice  approval_required  approval 9e96…
    2  2026-10-19T08:43:01.895Z  approved        sandbox.create-notice  ok  approval 9e96…
    3  2026-10-19T08:43:02.168Z  change_started  sandbox.create-notice  sending  approval 9e96…
    4  2026-10-19T08:43:02.187Z  call            sandbox.create-notice  ok  approval 9e96…
$ itda audit --verify
The audit log is intact: 4 records in /home/you/.local/share/itda/audit.jsonl.

• Changes are written down first. itda writes a change_started record before sending the request. If itda cannot write it, it sends no change.

• Tampering shows. Each record holds the hash of the one before it. Editing, deleting or reordering a line makes itda audit --verify name the first broken record, and itda doctor reports it.

• Safe to share. Records keep input names and a digest of their values, never the values or any credential.

• A stopped process shows. A change_started record with no later call record means the process stopped after sending the change. Nobody knows whether the site applied it. itda audit lists those changes at the end as “unknown outcome”. itda doctor counts them under changes. itda_manage audit returns them under unknown_outcome. Check the site before asking for the change again.

• A lost answer shows with its check. A call record ending in action_outcome_unknown carries outcome_check (landed, not_found or unknown) and confirm_read when the change named a confirming read. itda audit lists those changes among the records shown, each with what the read said; itda_manage audit lists them under unknown_outcome with check.

itda audit --json prints the records for scripts.

Writing a site definition

A site definition (spec.yaml) tells itda a website’s actions, what each sends, what a correct answer looks like and whether it changes anything. itda reads <data dir>/specs/<site>/spec.yaml. Beside it, check.json stores the last itda check time and verdict; sources.json stores a drafted definition’s sources (see Keep it working). itda add spec.yaml copies it there after a short review. itda doctor prints the data directory; ITDA_HOME moves it.

Start from an OpenAPI document

When the site publishes an OpenAPI 3 or Swagger 2.0 description, let itda draft the definition:

itda draft openapi openapi.json > spec.yaml            # print the draft
itda draft openapi openapi.json --include orders       # only matching paths, ids or tags
itda draft openapi openapi.json --base-url https://api.example.com --install

The draft keeps each operation’s source in evidence and maps GET to reads, all else to changes. It adds response checks from required fields in the success schema and maps header API keys and bearer tokens to auth. itda lists what it cannot translate (OAuth, cookie keys, header parameters, multipart bodies, deprecated operations) on stderr without guessing. Review the draft before agents use it: shorten descriptions, remove actions agents should not call, and tighten the response checks.

Start from the pages you use

For a site with no API description, and pages you can open without signing in, give itda the addresses of the pages an agent should read:

itda draft page https://example.com/board > spec.yaml      # print the draft
itda draft page https://example.com/board https://example.com/board/42
itda draft page https://example.com/board --name board --install

itda fetches each page under the same rules as every other read: once over HTTP and, when the page answers with a challenge, once more inside the browser installed on the computer (see HONEST_CLIENT.md). Private addresses need ITDA_ALLOW_LOCAL=1. If the page still refuses, the draft stops with what the gate saw, as itda call would report it: blocked_by_site (exit 12) naming Cloudflare, a bot manager or a captcha, or site_rate_limited (exit 13) with the wait the site asked for; nothing is paused. A page that sends itda on to a sign-in page stops with auth_required (exit 10) and points at itda record. itda does not solve a captcha; the site’s official API, or its owner, is the way in. Each page that answers becomes a read with a response check, so itda check notices when the page changes:

When a site also publishes an API description, itda reads it: the one the page points at, else /openapi.json on the same origin when it answers with an OpenAPI 3 or Swagger 2.0 document. It makes one GET as itda, at most 4 MB. Every request to a site waits its turn, so no other path is tried. Where the page points comes from the HTTP Link header the first page was answered with (RFC 8288) and from the <link> and <a> elements of the pages, which costs no request. The best wins: service-desc (RFC 8631) or a description file name, then api-catalog (RFC 9727), then describedby; on a tie the header comes first. A service-desc document is read even when it does not parse, so the draft can say so. An API catalog is a linkset (RFC 9264, application/linkset+json): itda follows its service-desc links, up to three, and takes the first OpenAPI document; a catalog that only points at further catalogs is not followed. A describedby document counts only when it is an OpenAPI document; otherwise /openapi.json is still tried. Its reads become actions as itda draft openapi makes them. Each path is drafted once, whether the page or description named it. The changes it lists are notes rather than actions (one each up to ten, then a count); itda draft openapi <url> drafts those for review. itda omits and lists reads with credential inputs, such as an apikey query parameter. Install-time checks would refuse them. itda only notes descriptions with another server address; it does not merge them. A description that does not parse leaves the page draft unchanged. The header comment and every merged action’s evidence name the description’s address.

Field and input names face the same checks as a hand-written definition: itda omits and lists names that look like credentials. A hidden form field other than a token keeps its value as a default: the form always sends it. itda copies nothing else from the page. A script-drawn page shows little to a plain fetch. itda draft page reports this and points to recording the site; itda setup first watches the page load in your browser (below).

A fetched page is a shell when its main content is one or more same-origin <iframe src> (or an older <frameset>’s <frame src>) and it has no records, data, form or feed of its own. itda then fetches each frame’s page as a read, on the same pacing and with the same session, and drafts from the frame pages as pages of the site. Each frame read keeps the frame’s own address as its operation path, since that is what a request to the server looks like. A form inside a frame posts to the frame’s action like any other. itda follows at most four frames, at most two deep. itda lists a frame on another origin in the notes and never fetches it. The same goes for a same-origin frame that answered with nothing. itda draft page and itda setup say what they followed (“Followed 1 frame: /frame/board.”).

When a same-origin frame answers with a redirect to a sign-in page (the same detection the top-level page uses), itda treats it as if the top-level page had: following the redirect to read the login form is a read, so with itda setup --user it signs in through that form and reads the frame again with the session, then drafts from it. itda draft page, which does not sign in, notes that the frame leads to a sign-in rather than only that it was not read.

Start from the software a site runs

Most intranets run software everyone knows, and that software has a stable API worth more than a reading of one page. itda setup recognises eight of them from page HTML (a generator meta, a well-known asset path, an Atlassian context-path meta, a body class). It confirms the guess with exactly one GET to the software’s own endpoint, as itda, through the same gate as other requests. No fingerprint, no request. A confirmed match says so in one line, “This looks like GitLab. Using its API at .”, and drafts from the software’s template under sites/software/:

Each template holds eight to fourteen reads an agent needs most (lists, search, one item), up to three marked changes, record models and the software’s sign-in method. Every operation has its documentation in evidence. itda names the site after the host (issues.apache.org becomes issues-apache; --name overrides). The template’s store:<software>/... secrets follow that name. itda tries every read once, as on any site, and removes reads the instance does not answer (a private project list, a disabled module). The page draft still runs. Its lists, forms and feeds join the template under the page’s address if it differs from the API’s. Each method and path is drafted once. A page that is not enough on its own, because it needs a sign-in or is drawn by scripts, still gets the template when the software is confirmed. If the page says WordPress but /wp-json/ does not answer like WordPress, itda says nothing. It drafts the page like any other.

itda setup --as <software> forces a template, using the fingerprint’s base if the page agrees, else the API under the page’s origin. The confirm request still runs; the line says if it got no answer. --no-template reads the page like any other. itda check and itda refresh work on the result as on any site. A refresh fills the same template at the same API base and merges the page’s reads again. Over MCP, itda_setup does the same. It takes template (a name or none) and names the template used in its result. itda add does not install the templates: setup fills their placeholder base_url.

Sites with a ready-made definition

A page on pypi.org, github.com, www.npmjs.com (or npmjs.com) or crates.io gets the site’s itda add definition (pypi, github, npm, crates-io). It reads the site’s own API instead of its pages. itda setup says so in one line, “This is PyPI. Using its JSON API.”, and does not fetch the page. It saves the definition under its own name and tries its reads once as on any site. --no-template reads the page like any other; --as <software> uses that template instead. Over MCP, itda_setup takes the same path, with template: none to skip it, and puts the line in its notes. A site set up this way has no sources to redraft from, so itda refresh does not apply. itda add <site> --force installs the current definition.

When setup tries the reads

itda setup tries every read once while you watch, over HTTP and then, when the site answers with a challenge, once more in the installed browser. A read the site still blocks or challenges (a 403 from a bot manager, a captcha, a 200 page titled as a challenge) is a finding of the setup, not a refusal to remember: that read is left out with one line, “: the site does not give itda this page”, and nothing more is sent to the site in that run. The reads after it are kept and shown as not tried, so the next itda check tries them. The site is not paused, since nothing was retried. itda installs reads that already answered. itda check, itda call and the MCP tools on an installed site try a challenged read in the browser as well; only in direct-HTTP mode (ITDA_TRANSPORT=http) does a block pause the site until you resume it.

Start from an agent’s reading of the docs

When the pages say little but the site documents its API in prose, an agent connected over MCP can draft the definition itself with itda_prepare (agents.md has the loop). itda reads the pages and documents and gives the agent their shapes and an id for each piece of evidence, never a value. The agent proposes a definition in this format; itda checks it with the same rules itda spec validate applies and keeps an operation only when the evidence carries it:

A route the description says needs a sign-in itda cannot use is dropped, and a draft that only reads the home page and checks nothing is refused. itda then tries the kept reads through the same path as any call, at most 24 requests in a session: a JSON read without required_pointers gets them from the field names at the top of its answer (none for a list, or for an object keyed by data such as languages or dates), and one that answers with nothing or only an error does not count. A change is never sent. Installing takes the same steps as itda setup: save, try every read once, keep what works. The header says the definition came from itda_prepare; review it like any draft.

Start from a browser recording

Most internal and older sites publish no API description, but their pages still call one. Record yourself using the site and let itda draft from the recording:

itda record https://intranet.example.com/board                  # print the draft
itda record https://intranet.example.com/board --name board --install
itda record https://intranet.example.com/board --save session.har   # keep the recording too

itda opens Chrome, Edge or Chromium (or ITDA_BROWSER) in a fresh, empty profile at that page and watches, through the browser’s own DevTools protocol, what every page asks the server for. Use the site the way an agent should: sign in, search, open an item, submit a form. Press Enter in the terminal or close the window when you are done. itda never clicks, types or navigates in that window; it opens only the page you named. The recording stays in memory unless --save writes it to a file. That file holds your cookies and tokens; delete it afterwards. With --install, itda offers to keep the recording’s sign-in token for a drafted header auth entry and session for a browser entry. Each needs a yes in the terminal. They go to the system keyring under <site>/default and never appear on screen. You need itda login only when a token expires.

itda setup runs a shorter version automatically when a page shows itda only a title and has scripts that could fetch data: a script file, preloaded module, or inline script that imports a module or mentions fetch, XMLHttpRequest, graphql or api. Without these, the page goes straight to the question below. It opens the same kind of window on the page, waits for two seconds of network silence (ten at most), scrolls to the bottom once and waits again. It closes the window and drafts from what the page loaded on its own, like itda draft har. It tries the page’s own address first, so what the page itself shows is never lost to a busier API elsewhere. It reports one line (Watched the page load: 12 calls, 3 reads drafted., counting reads beyond a title check). It asks you to record only if it drafted no such read. It never clicks or types in the window or keeps sign-in data, since nobody signed in. A page whose scripts lead to sign-in stops with auth_required, as a redirect does. --no-record skips the window as well, --watch-only watches but never asks you to record. itda uses the template for a site with recognised software (above) and does not watch it.

A browser developer-tools recording works the same way. Open the Network tab, use the site, save with “Save all as HAR” (Chrome, Edge) or “Save All As HAR” (Firefox), and draft from the file:

itda draft har session.har > spec.yaml                  # print the draft
itda draft har session.har --base-url https://intranet.example.com/api
itda draft har session.har --name board --install

A GraphQL page sends every call to one path; each recorded operation becomes an action named after it (exploreProjects is explore-projects), with queries as reads and mutations as changes. The document and operation name are fixed inputs; agents fill in variables, which a json_template renders into the same JSON the page sent. itda lists variables holding objects or lists for you to add by hand.

A GraphQL endpoint can also say what else it offers. When a draft finds an endpoint in a recorded call or a page naming a same-origin /graphql path, itda sends the standard introspection query once, as a read with a size cap. It drafts one read per root Query field with scalar, enum or id arguments: the field name is the action (countries), arguments are typed inputs (required if the schema says so), and the selection contains up to 24 scalar fields, two levels deep. itda omits and lists optional object or list arguments, so it can still read the field without them. It lists fields requiring an object, list or credential instead of drafting them. An argument named query becomes the input <field>_query, since query holds the document. itda lists Mutation fields in notes, never drafting them as changes: a schema says what a change takes, not what it does. itda drafts sites with introspection off from their pages and calls alone, with no error. This is the one request itda draft har makes on its own.

In both cases, itda also drafts the pages you saw, as itda draft page does. Sites rendering lists and forms on the server get actions even when their pages call no API. A recording holds real tokens, cookies and personal data, so the draft keeps only the shape of each call: method, path, input names and types, and the response fields every sample returned. Numbers and ids in paths become placeholders (/notices/42 becomes /notices/{notice_id}). itda marks inputs every sample sent as required. Token headers become auth entries whose values you add with itda login. Calls with a sign-in cookie (by name, such as JSESSIONID or SID) but no token get a kind: browser entry. itda login <site> --browser signs them in. A form token such as _csrf becomes a preflight step. It reads the token from the form page recorded before the post, so each change sends a fresh one. A recorded multipart/form-data post whose parts the browser kept (their names, and the file part’s file name, never the file) becomes a change with body.multipart; a recording without the part names lists the call instead. An answer the site sent as Content-Disposition: attachment becomes a file read of the media type it carried. A header such as X-CSRF-Token gets the same treatment using a <meta name="csrf-token"> tag on an earlier page, as Rails, Laravel and many single-page apps do. A session the site carries in the URL rather than a cookie also gets a kind: browser entry, with value_from: query:<key>. itda drafts a query key as the session when the sign-in’s answer hands it out (in the redirect Location, or on the links of the first page after the sign-in), its value looks like a session, and every signed-in call carries it. Every operation that sent the key gets auth: <name>, and itda drops the key from each operation’s inputs. itda keeps the value in the keyring, never in the definition. At run time, itda adds it to each request’s query, just as it sends a cookie: session as a cookie. itda leaves out the sign-in call: a person signs in, never an agent. itda omits and lists other token and session fields, since they come from sign-in, never the agent. itda skips calls to other addresses and failed calls. Delete the HAR file when you are done with it.

Write one by hand

This page covers everything version 0.1 runs. The fastest way in is to copy examples/sandbox/spec.yaml and change it.

A complete example

spec_version: 1
site:
  name: sandbox                 # lower case, digits and '-'; used in <site>.<action>
  title: Sandbox intranet       # shown to people and agents
  base_url: http://127.0.0.1:8787
auth:
  - name: key
    kind: header
    header: X-Api-Key
    value_from: store:sandbox/api-key   # filled by `itda login sandbox`
operations:
  - name: list-notices
    desc: Search notices by title
    method: GET
    path: /api/notices
    effect: read
    evidence: GET /api/notices returns {total, items}
    query:
      q: {type: string}
    response:
      format: json
      required_pointers: [/items, /total]
  - name: create-notice
    desc: Post a notice
    method: POST
    path: /api/notices
    auth: key
    effect: write
    evidence: POST /api/notices creates a notice
    body:
      json:
        title: {type: string, required: true}

itda ls lists what it found, and a broken definition shows up there and in itda doctor with the problem and how to fix it.

To check a file before installing it, run itda spec validate spec.yaml. It runs the checks itda add runs (the structure, the addresses, confirm and the rest) and installs nothing. A valid file exits 0; otherwise it prints one problem: <field>: <detail> line per problem and exits 2, the code of every definition problem. --json prints {status, file, site, actions, issues}, each issue {code, field, detail}; a file that does not parse prints the usual error envelope.

site

defaults.headers adds headers to every request (for example an Accept language). Browser-controlled headers (sec-*, client hints) belong to the transport and cannot be supplied by a definition; see HONEST_CLIENT.md.

defaults.interval sets the minimum time between requests to a site, written as 2s or 500ms. itda spaces action-request admissions to an origin about 1.2 seconds apart by default; a definition can increase this to 30 seconds but cannot reduce it. Use it when the site’s terms name a rate, or when itda check keeps running into site_rate_limited.

defaults:
  interval: 2s

operations

Each operation is one action, called as itda call <site>.<name>.

Inputs

query:
  q:     {type: string}
  page:  {type: int, default: 1}
  draft: {type: bool, required: true}

type is string, int, float or bool. itda checks inputs before sending anything; agents see them as a JSON Schema. itda refuses inputs with names resembling credentials (password, token, api_key…): those go in auth, never through the agent.

Sending a file

A form that takes a file is a multipart/form-data body. fields are its text inputs, declared like form fields; file names the form field the file goes in and the input (from) that carries the path of a file on this computer:

operations:
  - name: attach-file
    desc: Attach a file to a notice
    method: POST
    path: /board/{id}/attach
    auth: session
    effect: write
    evidence: the attach form on /board/42 posts multipart/form-data
    params:
      id: {type: int}
    body:
      multipart:
        fields:
          memo: {type: string}
        file: {name: attachment, from: file}

The agent gives file as a path. itda reads the file once, and the approval the user sees names it by name, size and SHA-256 (file plan.csv (8 bytes, sha256 3a1f…)). The approval is for those bytes: other bytes under the same path withdraw it (approval_expired, reason: file_changed), and the agent asks again. itda streams the file from disk in small chunks, checking its size and modification time before every chunk and its hash at the end. A file that changes during the send stops it; the call ends with action_outcome_unknown and reason: file_changed, like any change whose answer was lost. The audit log records the hash. An action with a file is always a change, whatever its method or name says, and its body goes only to the site’s own origin. A multipart body without a file sends its fields as parts. multipart is one of the three body encodings; declare one of json, form or multipart.

Read or write

An action is a read only if effect is read, its method is not PUT, PATCH or DELETE, and neither name nor path has a change word (delete, send, pay, submit, logout…). It must also have no input such as action or mode asking for a change, and no mutation in a GraphQL query input. A POST can be a read, for example a search endpoint or a GraphQL query. Anything else is a change. itda sends a change once, without retries, only after the user approves that exact request with itda approve.

When the checks disagree with your effect: read, itda treats the action as a write. Rename the action or path rather than fighting the classifier: a GET /logout really is a change. itda refuses headers and inputs that ask the site to use another method or address (X-HTTP-Method-Override, X-Method-Override, X-HTTP-Method, _method, X-Original-URL, X-Rewrite-URL). It sends the reviewed method to the reviewed address. itda refuses transport other than http and auth kinds other than none, header and browser. How a read travels (direct HTTP, or the installed browser after a challenge) is itda’s choice, not the definition’s; see HONEST_CLIENT.md. A change always goes over direct HTTP.

Those checks look at what the definition declares. Just before sending, itda reads the request it built once more: every query key and body field, the value of a field such as action or mode, and any GraphQL document in query (the body, or the address of a GET). A read whose rendered request asks for a change, for example a json_template whose literal body is a mutation or carries {"op": "delete"} deep inside, is reclassified as a change: the call returns approval_required with reclassified naming the reason (body names a mutation, body asks for a change, address names a mutation, …), the review shows the same line, and the user decides as for any change. A read whose effect itda cannot tell, such as a GraphQL endpoint sent no document, or a document it cannot read, stops with effect_unknown (exit 2) and a remedy; nothing is sent. A declared write never gets looser this way. A search whose text happens to contain a change word stays a read: only keys, intent fields and GraphQL documents are read.

response

A declared response is how itda knows the answer is real data and not a sign-in page, an error page or a redesigned site.

response:
  format: json                       # json | html | text | xml | empty | file
  required_pointers: [/items, /total]  # JSON Pointers that must exist

For records inside a wrapper, extract_pointer returns only that part. required_pointers and model then apply to it:

response:
  format: json
  extract_pointer: /items            # {"total_count": 3, "items": [...]} -> [...]

For server-rendered pages, extract records with CSS selectors:

response:
  format: html
  required_html_fields:
    - {selector: "h1#board"}         # must be on the page
  html:
    items: tr.notice                 # one record per match
    fields:
      id:    {selector: td.id, required: true}
      title: {selector: td.title a, required: true}
      link:  {selector: td.title a, attribute: href, absolute_url: true}
    limit: 100                       # at most this many records

When the answer does not match, the call fails with response_mismatch (exit 11) instead of returning the wrong page as data.

Reading a file

A read whose answer is a file to keep, an attachment on a board or a report to download, declares format: file and the media types it accepts:

operations:
  - name: get-attachment
    desc: Download an attachment from a notice
    method: GET
    path: /board/files/{file_id}
    effect: read
    evidence: /board/42 links to it as an attachment
    params:
      file_id: {type: int}
    response:
      format: file
      media_types: [application/pdf, application/vnd.ms-excel]
      max_bytes: 20000000            # optional; 64 MiB when left out, 1 GiB at most
      allow_empty: false             # optional; an empty answer is a failure

itda streams the answer to a file instead of reading it into memory. The answer’s content type (before any ;) must be one of media_types; an HTML answer counts only when the site marks it Content-Disposition: attachment, so a sign-in page in place of the file is a failure, not a file. A 206 or an answer with Content-Range, a body shorter than its Content-Length, an empty body (unless allow_empty) and anything over max_bytes fail too, by name: wrong_media_type, partial_answer, empty_answer, too_large (exit 11, or 30 for too_large). Nothing is kept from a failed answer. A good answer is sealed at its end and gets its name from the site’s Content-Disposition, else the address, reduced to plain characters; a name already taken gets -2, -3. The file lands under files/<site>/ in the data directory, or in the folder itda call ... --out <dir> names. The read returns a manifest, never the bytes:

{"path": "/home/you/.local/share/itda/files/board/minutes.pdf", "bytes": 48213,
 "media_type": "application/pdf", "sha256": "9c1e…"}

Over MCP the result carries the same manifest and a resource_link to the file. A file read has no model, pagination, pointers or extraction, and itda check skips it (“saves a file”) rather than fill the folder. itda setup tries it once, through the gate like every read: it reads the answer’s headers and first bytes, counts the read as working when they describe a file the definition allows (status, media type, size), and drops the rest; nothing is saved. A transfer longer than the pace allows keeps its turn at the gate by renewing it; a turn lost mid-transfer stops it (request_lease_lost, exit 30), never retried.

auth

API keys and tokens

A key or token sent in a header:

auth:
  - name: key
    kind: header
    header: Authorization
    prefix: "Bearer "
    value_from: store:<site>/api-key

Store the value with echo "$KEY" | itda login <site> (OS keyring), or set ITDA_SECRET__<SITE>__<ACCOUNT>__<NAME> for CI and containers. --account picks among several accounts; the default account is default. itda sends the header only to base_url’s origin, or to origin when you set it.

Sign in with a password

For a site with its own sign-in form, name the form on the browser entry and itda fills it in for you:

auth:
  - name: session
    kind: browser
    value_from: cookie:JSESSIONID   # the cookie that shows you are signed in
    login:
      path: /login                  # the page with the form; a query is fine
      user: username                # the user name field
      password: password            # the password field

$ itda login intranet --user me
    Password for me on intranet (sent once to the site's own sign-in form, never saved):
Signed in. itda sealed the session for intranet/default (2 cookies) under the data directory with a key in the system keyring; agents only see the account id.

itda reads the page at path, like any other read, and selects the same-site POST form with those two fields. It fills them in and sends the form once, as your browser would, with the page’s hidden fields (a token such as _csrf, a return address) and cookies. A redirect means sign-in succeeded. itda stores the site’s reply cookies as the session, as for a browser sign-in. If the form comes back, sign-in failed. itda does not retry or pause anything. itda sends the password only to the form’s own action and never keeps it. Without a terminal, the password is the first line of stdin, so a password manager can pipe it.

itda setup <page> --user me does the same if the page needs a sign-in (redirects to one, answers 401 or 403, or says “log in to see this”). It drafts from the page as you see it signed in. Every action gets auth: session; it writes the login block from the form it found so the command above works later. An agent never gets this path: itda_setup over MCP refuses pages behind a sign-in and says what you should run.

Some older sites keep the session in the address instead of a cookie, as a query parameter the sign-in hands out (?sid=...). Name that key with value_from: query:<key> in place of the cookie:

auth:
  - name: session
    kind: browser
    value_from: query:sid         # the query key the signed-in session rides in
    login:
      path: /login
      user: username
      password: password

itda signs in the same way; when the site answers with no session cookie but a redirect (or a first page) carrying sid, that value is the session. itda keeps it in the keyring like any other. At run time it adds it to the query of every request to the site, the way it sends a cookie session as a cookie. Because it travels in URLs, it can reach a server’s or a proxy’s logs; see THREAT_MODEL.md. A browser entry carries one or the other, a cookie or a query key, not both.

A session a single-page app keeps in storage

Some sites keep no session cookie at all. A single-page app signs you in, puts a token (often a JWT) in the browser’s localStorage, and its scripts send it on every call as Authorization: Bearer <token> or a custom header. That is a header credential whose value is a session, so its value_from names the storage key instead of the site’s own store:

auth:
  - name: session
    kind: header
    header: Authorization
    prefix: "Bearer "
    value_from: storage:access_token   # the localStorage/sessionStorage key

When you set the site up or record it, itda reads that one origin’s localStorage and sessionStorage once, over the DevTools protocol, from the window you signed in to. It keeps a value only when the recorded calls sent it as a header; a stored value no request sent is reported and left alone (“the site keeps a value in storage that no request sent; not used”). The token goes to the keyring as the session, never into the definition. itda login <site> --browser reads it again from the window at the next sign-in, the way a cookie session is refreshed. itda reads only the signed-in origin’s storage, never another site’s and never a file on disk, and never writes anything into a page.

If the token is a JWT with an exp claim, itda records when it expires: itda check reports signed_out (not site_changed) once it has passed, and itda_sites shows when the sign-in expires. itda never signs in again on its own; it asks you to. value_from on a header entry accepts store:<site>/<key> or storage:<key>.

When the site redirects after a change (post, then redirect, then get, as older sites do), the change has landed. Its result carries the redirect address. A redirect to a sign-in page means the site no longer accepts the session. The call stops with auth_required; itda login <site> signs in again.

Browser sign-in

For single sign-on, a one-time code, or a site whose form itda cannot fill in:

auth:
  - name: session
    kind: browser
    value_from: cookie:JSESSIONID   # optional: the cookie that shows you are signed in

Sign in once in your own browser:

$ itda login intranet --browser
Sign in to intranet in the browser window that just opened.
itda continues when the JSESSIONID cookie appears, or press Enter once you are signed in.
Saved the session for intranet/default (3 cookies). It is sealed under the data directory with a key in the system keyring. Agents only see the account id.

itda opens Chrome, Edge or Chromium (or ITDA_BROWSER) in a fresh, empty profile at the site’s address, or at --url. You sign in by hand; itda never clicks or types on the page. It keeps only the site’s unexpired cookies. It closes the window and deletes the profile. itda sends the session only to addresses on the same site and removes cookie values from results.

A session is a whole Cookie header, too long for some credential stores (Windows Credential Manager caps a credential at 2560 bytes). itda stores it in vault.sealed under the data directory, encrypted with a system keyring key. API keys stay in the keyring itself. The move is automatic in both directions, and itda doctor says where secrets are.

When the session expires, the site answers 401, or 403 with a reason such as session_expired. The account pauses with auth_required; itda login <site> --browser signs it in again and resumes it. A 403 with any other reason is api_denied: the site did not allow the request. Signing in again will not help. On a server without a keyring, set ITDA_SECRET__<SITE>__<ACCOUNT>__SESSION to a Cookie header value instead.

preflight

Older sites often hand out a one-time value with the form page, such as a CSRF token in a hidden input, and refuse a change without it. A preflight step reads that page just before the action and passes the value along:

operations:
  - name: post-notice
    method: POST
    path: /board/write.do
    auth: session
    effect: write
    evidence: the write form posts _csrf from /board/writeForm.do
    preflight:
      - name: form
        path: /board/writeForm.do
        extract:
          csrf: "css:input[name=_csrf]@value"
    headers:
      X-CSRF-Token: "{{step.form.csrf}}"           # if the site wants a header
    body:
      form:
        title:   {type: string, required: true}
        _csrf:   {type: string, default: "{{step.form.csrf}}"}   # or a form field

A step is a GET to the action’s own origin, with the same account, either to path or to a read action named in op (with args). Steps run in order after you approve a change, just before itda sends it. This keeps the value fresh. itda sends cookies from a step’s answer with the action, as a browser does, for that request only; it never keeps them. A Rails site keeps its issued token in a session cookie it rewrites on every answer. A value is used as {{step.<step>.<name>}}. Agents cannot see or set inputs filled this way. If a step finds nothing, itda stops the call with response_mismatch and sends nothing. After the steps, itda classifies a read again with the values filled in. If it now counts as a change, itda stops with effect_changed (exit 2) without sending it.

models

A model picks and renames fields from a JSON answer, so agents get small, stable records. For a list answer, itda picks each record the same way. itda draft page writes one for every list it finds in a page’s embedded data; path reaches into nested objects with dots (item.headline):

models:
  notice:
    id:    {path: id, type: int}
    title: {path: subject}
    by:    {path: author.name}
operations:
  - name: list-notices
    model: notice
    ...

pagination

A read that lists things can say how the site turns pages. The agent can then read on without seeing the site’s own marker:

operations:
  - name: search
    method: GET
    path: /api/v1/crates
    effect: read
    evidence: https://crates.io/data-access#api
    query:
      q: {type: string, required: true}
      page: {type: int, default: 1}
    pagination: {style: page, next: /meta/next_page, send: {query: page}}

When the answer says there is another page, the call returns meta.next, an opaque handle such as ic_4f0a4207d04f4a0fb4e059d26bd54b6d. itda keeps the marker on the user’s computer for fifteen minutes, bound to the site, action, account, inputs and definition. itda call ... --next <handle> (over MCP, next) sends it back in the declared input. Agents never see or set a cursor input; they can still give page and offset inputs directly. For a pointer holding an address or query string (?page=2&per_page=10), itda extracts only the input’s value, and only if the origin and path match. itda drops a marker that would change the read or point elsewhere. Only a read turns pages.

itda draft openapi declares it when the document is plain about it: a cursor, page_token or after query parameter together with a next_cursor, next_page_token or end_cursor string in the answer; a page parameter, with header:link when the answer documents a Link header; an offset parameter. itda draft har does the same from the query a recorded read sent and the fields its answers had, and from a GraphQL after variable with pageInfo.endCursor in the answer. itda drafts GraphQL schema connections (after: String in, pageInfo { endCursor hasNextPage } out) with send: {body: after}. Pages with pagination links (?page=2) get style: page on reads returning their records.

confirm

itda sends a change once and never resends it. When the answer is lost after sending (a timeout, a dropped connection), the call fails with action_outcome_unknown and nobody knows whether the site applied it. A change can name the read that would show it, so itda checks instead of guessing:

operations:
  - name: list-notices
    method: GET
    path: /api/notices
    effect: read
    evidence: GET /api/notices answers {items: [{id, title}]}
    response:
      format: json
      required_pointers: [/items]
  - name: create-notice
    method: POST
    path: /api/notices
    effect: write
    evidence: POST /api/notices creates a notice; GET /api/notices lists it under title
    body:
      json:
        title: {type: string, required: true}
    confirm:
      read: list-notices
      match: {pointer: /items/*/title, from: body.title}

After action_outcome_unknown, itda runs the read once, as a read: no approval, through the same gate and pacing, with the change’s account, first page only. It compares each value at the pointer with the input as text and reports one of three results next to the error, as outcome_check in --json and MCP results and as outcome_check on the audit record:

The result stays action_outcome_unknown (exit 22) in every case; the check is information next to it, never a reason to resend. The read’s answer is not passed on, only the read’s name and the match result. A confirm that names a missing operation, a change, or a read that needs inputs is a definition problem, reported by itda ls and itda doctor like any other.

itda setup and itda draft fill confirm when the draft itself shows it: a POST whose list read is on the same path or above it (POST /api/notices with GET /api/notices, POST /issues/new with GET /issues) and a string input of the change that the read’s records carry under the same name (an HTML read’s fields, a model’s fields, or /0/<field> in required_pointers). The evidence says so. Without that, the change keeps no confirm; add one by hand when you know the read.

Keep it working

Sites change. itda check runs every read needing no input; give inputs a default to include more. It reports whether each action’s answer still matches its response:

$ itda check board
board.list-notices  ok                 HTTP 200 142 ms
board.get-notice    skipped            needs notice_id
board.post-notice   skipped            changes the site
board.my-messages   auth_required      sign in: itda login board
verdict  signed_out: sign in again with itda login board

1 ok, 1 failed, 2 skipped.

itda sends no changes. Each site gets a verdict (ok, signed_out, site_changed, blocked or unreachable) and a matching exit code, per the contract. Code 11 means a site no longer matches its definition, letting a scheduled job warn you before an agent runs into it. itda check --all checks every installed site and prints one verdict line each. An address the site answers with 404, 405 or 410 and a query it answers with errors count as site_changed. itda lists a refused read (api_denied) on its own line; it does not affect the site’s verdict.

What itda knows about a site

itda keeps a small knowledge base per site in itda.db: the pages it drafted from and the actions in the definition, which list read can supply which detail read’s input, every try (from setup, check, refresh or a call) with its verdict, HTTP status and time, and the hashes of spec.yaml and the last verdict. It keeps shapes only: selectors with match counts, field names, the keys and types of an answer. Never an answer, an input, a cookie, a header value or a record. itda ls --json adds each action’s verified (its last try answered) and pass_rate, and per site the reads that fail now and then (unstable).

itda fsck runs fixed rules over it and prints what is worth a look, worst first, each with the command to run:

$ itda fsck board
board: 3 to look at
  2 read_needs_input: get-notice needs notice_id; list-notices gives it at /items/0/id
    fix: itda call board.list-notices --json
  2 endpoint_untried: list-archive has never been tried
    fix: itda check board
  3 endpoint_untried: post-notice has never been tried
    fix: itda describe board.post-notice

A call itda refused before sending (waiting for an approval, a bad input, an expired page handle) is kept as a record but is not a try; a 404 the site answered is one. itda fsck sends nothing. It exits 0 when no gap is at priority 1 and 1 when one is; --json prints status (ok or problems) and each site’s gaps with rule, subject, priority, reason and remedy (command, plus the MCP tool and arguments to call next). itda setup ends with the top three. itda describe <site> adds what can be read and changed, how one read feeds another, and a few ways to ask an agent.

Draft a changed site again

A definition that itda setup, itda draft ... --install or itda record --install made remembers where it came from, in sources.json next to it:

{
  "pages": ["https://board.example/board"],
  "description": "https://board.example/openapi.json",
  "graphql": ["https://board.example/graphql"],
  "recording": "recording.har",
  "lang": "en",
  "drafted": {"get-board": "<sha256 of the operation as drafted>"},
  "drafted_at": "2026-10-22T09:00:00.000Z"
}

pages lists addresses the draft read; description is the API description it found (an address or the file given to itda draft openapi); graphql lists endpoints it asked what they offer. recording is the HAR kept under the site when itda draft har or itda record --save ... --install had one. A refresh needs only names and shapes, so the copy keeps the recording’s shape: cookie, token and session values, private query and body fields and sign-in call answers become <redacted> before saving. itda remove deletes the copy with the site. template names the site’s ready-made template (gitlab, jira…), with its API base in base_url. A refresh fills that template again and rereads the page if it still opens. base_url, include and lang otherwise record the draft’s choices; itda omits any you did not give. Nothing in the file is a secret. drafted holds each operation’s original draft hash. A refresh uses it to distinguish hand-edited operations from those it may replace. A definition installed with itda add has no sources and cannot be refreshed.

When a check says site_changed, draft the site again from those sources:

$ itda refresh board
Drafting 'board' again from its pages...
    Looking at board.example...
    As installed: site_changed (the site changed; run itda refresh board to draft it again from the same sources).
What would change:
    ~ get-board    changed: evidence, response
    ~ feed         changed: path, evidence
    = list-notices kept as you edited it
    + search-board added: Search on Notices
    Write these changes to 'board'? [y/N] y
Updated 'board'. Checking it...
board.get-board     ok                 HTTP 200 131 ms
...
verdict  ok: every read still matches the site

The merge keeps the site’s name, title and base_url, defaults, auth and the header comments as they are, and goes through the operations by name. YAML differing from the last source draft means hand edits. itda keeps that operation as is. One the new draft changed (a renamed column, a moved endpoint, a response check) takes the new version. itda drops what the sources no longer draft only if its read also failed the check. itda tries a new operation once and adds it if it answers. itda withdraws pending approvals for the site, as for any replaced definition. -y writes without asking; without it, itda writes only after you say yes. itda checks the site right after and prints the verdict. The exit code says whether the new definition matches. Over MCP, itda_manage with refresh does the same after you confirm the diff in a form.

Checklist before sharing a definition

• itda spec validate finds no problem.
• Every read declares a response, and itda check passes.
• Every change whose records a read lists names that read in confirm.
• Every desc says what the action does, in one line.
• evidence points at something a reviewer can check.
• No credentials, personal data or internal hostnames in the file you share.
• The site’s terms allow automated access for your use.

Languages

itda speaks twelve languages where a person reads it: the lines itda setup and its friends print, the landing page and the README. English is the source. Korean was edited by hand and is kept as it is. The other ten are translated from English with the glossary below.

What is translated, and what is not

What a person reads. Everything an agent acts on stays English, on purpose, so that a definition, an error or a tool behaves the same in every conversation. Translated:

• the lines the CLI prints during itda setup, itda login, itda refresh, itda fsck and the first bare itda, all through apps/cli/src/text.rs;
• what itda describe <site> and itda ls --json say a person can do with a site (user_guide) and the example prompts (natural_prompts), from one table of phrases in crates/prep/src/guide.rs; itda_sites gives them to agents in English;
• the action descriptions itda setup and itda draft write, from one table of phrases in crates/prep/src/label.rs (List what {title} shows, Search on {title}). The language is the one the person set, else the page’s own <html lang>, else English. The site’s own words (titles, field and operation names) stay as the site wrote them, and so does the kind of record (news articles) outside Korean. Agents read every one of these languages, so a description in Japanese works as well as one in English; what an agent acts on (tool names, error codes, remedies) stays English;
• the landing page and its title and description;
• the README.

Not translated:

• MCP tool descriptions, error codes and their remedy lines, the keys of the JSON envelope. Agents read them.
• Site definitions apart from the drafted desc: the ready-made ones and the reviewed ones in examples/ are English originals, and nothing translates a definition once it is written.
• The handbook under docs/ (this file included). docs/SPEC.md alone is 41 KB and changes with every minor release; a translation would be wrong within weeks. The README carries what a newcomer needs in every language.
• og:title and og:description on the landing page. Crawlers do not run scripts, so they see English.

How the language is chosen

The CLI reads ITDA_LANG, then the system LANG, and takes the first language it supports. The tag may be BCP 47 (ja, zh-TW, pt-BR) or a POSIX locale (ja_JP.UTF-8, zh_TW.Big5, C). Encoding and modifier are dropped, _ reads as -, case does not matter. Then:

ITDA_LANG=ja itda speaks Japanese whatever the system says. A key that a language file lacks falls back to English.

The landing page picks ?lang= from the address, then the last choice on that device (localStorage), then the first entry of navigator.languages that maps to a language above, with the same rules. The picker in the header changes it and remembers it. <html lang>, the title and the description change with it.

Glossary

Each language uses these words for these things, in the CLI, on the landing page and in the README alike. A translation that needs another word for one of them changes this table in the same pull request.

Product and command names stay as they are: itda, Claude Desktop, Claude Code, Cursor, VS Code, Codex, GitHub, MCP, and every itda ... command, flag, exit code, verdict (ok, signed_out, site_changed, blocked, unreachable) and error code.

Rules for a translation

• A {field} in a CLI string is filled in by the code. Every translation keeps the same set of fields as English, in whatever order its grammar wants. A test checks that.
• A landing string keeps every HTML tag and attribute, every <code> and link exactly. Only the words change.
• Numbers, commands, code blocks, file names, addresses and the console transcript’s prompt line are not translated.
• The example hosts (the-site-you-use.example, intranet.example) stay exactly as they are in every language. They are reserved example domains inside commands people copy, not prose. The transcript’s output lines are what the binary prints in that language: they come from the CLI strings.
• The README keeps the English section order, the same headings count, the same links and the same images. Its first lines carry the same language line as every other README, with its own language in bold.
• Plain words, in the voice of the English text. No slogans.

Add a language

1. Copy apps/cli/text/en.json to apps/cli/text/<tag>.json and translate the values. Add the tag to LANGUAGES in crates/types/src/lang.rs, to SUPPORTED in apps/cli/src/text.rs and the file to the include_str! list next to it, and to LANGS in apps/cli/tests/i18n.rs. Add a column to TEMPLATES in crates/prep/src/label.rs and in crates/prep/src/guide.rs. cargo test -p itda-cli and cargo test -p itda-prep check the keys and fields.
2. Copy site/i18n/ko.js to site/i18n/<tag>.js, change the tag in window.ITDA_I18N["<tag>"] and translate the values. Add the tag and its name in its own language to the <select data-lang-switch> in site/index.html and to LANGS in site/main.js. Drop flow.src unless the diagram was redrawn in that language (python3 assets/src/flow.py).
3. Translate README.md to README.<tag>.md and add the language to the language line of every README.
4. Add the row to the tables above and a line to CHANGELOG.md.

Checks

• cargo test -p itda-cli text:: : every language has every key of en.json and no other; every key has the same {fields} in every language; locale tags resolve as the table says; the strings and the description phrases cover the same languages.
• cargo test -p itda-prep label:: and guide:: : every description, guide and prompt phrase exists in every language, with the same {fields} as English.
• cargo test -p itda-cli --test i18n : every site/i18n/<tag>.js has the keys of index.html and the same HTML tags and links per key, and links to a heading its README has; every README has the headings, code blocks and links of README.md and the same language line; the picker lists every language.
• A pull request that changes README.md, site/index.html or apps/cli/text/en.json changes the eleven other languages in the same pull request, or says in its description what it leaves for later.

Architecture

itda is a Rust workspace that builds one binary, itda. This page explains how a call flows through it, what it keeps on disk, and why the crates are split the way they are.

Layers

Each crate depends only on crates in a lower layer. Cargo rejects cycles. CI runs cargo xtask check-layers to check the direction.

itda-spec never does I/O. Response checks take a ResponseLike trait, so testing and reusing the format needs no network stack.

One call

itda call sandbox.list-notices --q 점검 and the MCP tool sandbox.list-notices take the same path:

1. Resolve. The CLI loads specs/sandbox/spec.yaml. itda-policy validates it and refuses unsafe definitions with named problems.
2. Check inputs. Every input must be declared; itda checks types and required inputs as it builds the request.
3. Classify. operation_effect decides read or change from the method, name, path, inputs and any GraphQL document.
4. Approve (changes only). The first call stores the exact request (site, action, account, inputs, definition hash, credential fingerprint) and returns approval_required. After itda approve, the next call with that id must match the digest; itda uses up the approval before sending.
5. Credential. The vault supplies the account’s secret. itda attaches a header credential only when the destination has the credential’s origin.
6. Send. itda-net resolves DNS and refuses private addresses unless allowed. It waits for the site’s pacing slot, then sends with size and time limits. In direct-HTTP mode every request carries the itda/<version> user agent; in adaptive mode every request, a change included, carries the installed browser’s, so the direct requests and the browser look the same to the site. When a read is answered with a challenge, or the answer lacks the fields the definition promises, itda tries it again inside the browser (a fetch, then for a GET a rendered page) and remembers which way worked. Changes never retry or follow redirects. When a change’s answer is lost and its definition names a confirming read (confirm), itda runs that read once and reports landed, not_found or unknown next to action_outcome_unknown; it never resends.
7. Classify the answer. A challenge the browser did not get past fails that read, not the site. In direct-HTTP mode a block or challenge pauses the site until itda resume. A 401 on a signed-in request pauses that account either way. A rate limit sets a cooldown every transport respects; it is not a reason to try the browser.
8. Verify and shape. The declared response (JSON pointers, HTML fields) must match and the data must extract, or the call fails with response_mismatch; in adaptive mode a mismatch is first a reason to try the next way, and only an answer that passed is kept and its way remembered. An error the site itself reports (a GraphQL errors list) ends the call and is not retried. itda then projects the data through a model and removes the secret.
9. Record. The audit log gets a record; a change got one before step 6. The knowledge base gets one line: the verdict, the status, the time it took and the keys and types of the answer, never an input or a value.
10. Return. The CLI prints the data or JSON envelope. MCP marks it untrusted, cuts it to 24 KB and returns it as structuredContent.

What is stored

Definitions and application state are in the data directory (ITDA_HOME or the platform’s data folder). itda doctor prints it. Windows browser workers use the user’s local application-data directory instead.

Browser worker

A read that needs the browser goes to a worker process; direct HTTP needs no worker, and the first read that needs one starts it. One worker belongs to one data directory, itda executable, browser and private-address setting. It keeps up to four browser sessions, one per site and account, closing the least recently used when a fifth is needed, and exits after five idle minutes. Reads for the same site and account queue behind each other inside the worker; the turn-taking between processes and the pacing per site stay in SQLite, as for direct HTTP. A changed credential gives the session a new generation, so the old cookies are not reused; a changed query does not.

The CLI and the worker talk over the loopback address in itda’s own message format, not HTTP. Before any credential is sent, both sides prove they hold a secret kept in a file only this user can read: each signs the other’s fresh nonce together with the generation, protocol version, direction and the hash of the itda executable. Messages carry a bounded JSON header and the raw bytes. A reset ends every queued generation; shutdown waits for the reads in flight and gives the ownership lock back. Lock files are never deleted to take over.

Everything the browser loads goes through itda’s own SOCKS proxy, which resolves each name and connects only to addresses the private-address rule allows. Frames and workers the page creates are paused and set up the same way before they run. Other sites get neither the account’s credential headers nor its referrer. A resource POST passes only when the policy crate reads it as a GraphQL query. A Retry-After from one resource cools that resource’s site down in the shared gate without failing the page that loaded it.

Each browser is started through a small supervisor process whose standard input the worker holds. When that pipe closes, the supervisor kills the browser, waits for it and removes its private profile, even before the browser has written its DevTools port. Profiles the worker registered are also cleaned up at the next start, once the browser shows (through its command line) that the profile is its own. While a read’s outcome is unknown the account’s turn is kept; once the worker is known to have died, the read gets one more try.

Decisions

• Definitions over browsing. Browser agents repeat the same work on every task (finding the button, reading the page). Here it happens once, when the definition is written and reviewed. Calls are cheap, typed and checkable.
• Changes need a person. No code path sends a change without the user’s approval for that exact request. No MCP tool grants approval.
• Adaptive transport. Bounded browser recovery is allowed for reads, with account isolation, shared pacing and no write replay. See HONEST_CLIENT.md.
• Website text is data. itda marks results untrusted for agents; an agent gets instructions only from itda itself.
• Local first. No server, account or telemetry. Secrets stay in the OS keyring; a browser session a read recovers in lives in a private profile on this computer and is removed when it closes.
• The knowledge base informs; it does not decide. It tells a person or an agent what was tried, what failed and what needs an input. No transport, header, retry or account choice reads it: the runtime gets a handle that can only write a try, and a test makes the same requests with it empty and full.

Roadmap

Provenance

Parts of the foundation were ported from Hycli (Apache-2.0). Each ported file says so in its header; NOTICE lists them. The main changes from the original:

Transport policy

itda acts for a person, on websites that did not build it an API, with that person’s own account. It reads a site over plain HTTP and, when the site answers a read with a challenge page, tries that read once more inside the browser installed on the computer. Moving to the browser is the only thing a challenge changes: it does not let itda send a change, carry a credential elsewhere or skip a wait the site asked for.

How a read recovers

Direct HTTP goes first. When the answer is a challenge page, or does not have the fields the definition promises, itda runs the same read inside a hidden window of the installed browser: a fetch from the page’s own origin, then, for a GET, the rendered page. An answer counts only when its response check passes and the data extracts. An error the site itself reports, such as a GraphQL errors list, ends the read instead of moving it on.

itda remembers which way worked for an hour, per site, account and action, so the next call starts there instead of paying for the failed HTTP try again; changing an input does not forget it. A way that failed is skipped for a few minutes (five for direct HTTP, three for the browser). This cache holds no secrets.

The browser is the one installed. itda downloads neither a browser nor a captcha solver, and does not solve captchas. Every request in this mode, a change and a sign-in form included, carries that browser’s user agent, over HTTP too, and the hidden window keeps the browser’s own client hints. The site sees one client whichever way a request goes, so a session or a challenge clearance the browser earned also holds for the direct requests. itda does not copy the browser’s TLS fingerprint, and nothing here guarantees that a challenge passes.

Each site and account gets its own browser session, isolated from every other. A worker process starts on first need, keeps up to four sessions warm across CLI calls and exits after five idle minutes; no daemon command is needed. Reads for different sites or accounts run at the same time, under the shared pacing; two reads for the same one take turns. Signing in again, signing out or removing the site closes its session; changing a query, body or Accept header does not.

Everything the page loads goes through itda’s own proxy, so the address checks of a direct request apply to every resource, frame and worker: private addresses are refused, other sites get neither the account’s credentials nor the page’s address as referrer, and only reads pass, plus a GraphQL query itda has read and found to be one (no mutation, subscription, batch, or document it cannot tell). A browser answer is capped at 16 MiB, and the read’s own byte and time limits still apply. After each read the page and its workers are stopped and the proxy drained; the session stays warm.

A 429 or Retry-After from one resource the page loads cools down that resource’s site, across CLI calls, without throwing away the page’s data when the resource was optional. A read that cannot be satisfied during that wait fails with retry_after, upstream_origin and paused: false.

If the worker dies mid-read, itda notices (its ownership lock, or a new worker answering) and tries that read once more within the original deadline. A small supervisor process closes a browser whose worker died, even before the browser has reported its DevTools port. While itda does not know whether a read ended, it keeps the account’s turn rather than start a second read next to it.

ITDA_TRANSPORT=http keeps every request on direct HTTP with the itda/<version> user agent; a block or challenge then pauses the site until itda resume, as before. ITDA_TRANSPORT=auto, or leaving it unset, is the behaviour above.

Boundaries

In itda setup, a read the site still refuses is dropped from the draft with a line saying so, and nothing more is sent to the site in that run. Recovery never changes an action’s inputs, whether it counts as a read or a change, or what it needs approving. An agent’s preparation loop (itda_prepare) checks only reads, through the same path a call takes, and counts each request, recovery included; its advice never names a way around a refusal: a block means pause and tell the person.

A definition may set a different User-Agent in defaults.headers when a site asks for one; that choice is visible in the spec and in review. It cannot set sec-* headers: the transport owns those.

After a pause

A site pauses only in direct-HTTP mode, or for a sign-in the site no longer accepts. Check the site in your browser, then run itda resume <site>: that clears the site’s pauses and the ways of fetching it remembered, and closes the browser session for that site and account. Sign in again only when the account’s session was rejected (auth_required), not when an API refused one request (api_denied). Adaptive mode clears an old challenge pause for the site and account on its own; it never clears a sign-in pause or a rate-limit cooldown.

Transport measurements

Measured on October 23, 2026 on Apple M4 Pro, macOS arm64, with Google Chrome 155.0.8059.86. Both CLIs used release builds and identical synthetic loopback responses. This measures the CLI, not just the browser driver.

Results

Each primary cohort has 20 warm samples. Times are process-spawn to process-exit, including internal pacing. Cold samples are separate.

For the concurrent batch, both tools completed 20 reads with four workers: Hycli took 32.251 seconds (0.620 reads/s); itda took 6.471 seconds (3.091 reads/s). Pacing remains enabled.

The primary run completed 195/195 reads, including cold samples, with no cleanup failures. With a warm worker, itda’s browser-fetch p95 was 23.0x lower than Hycli’s and its render p95 25.1x lower; concurrent throughput was 4.98x higher. Most of that gap is lifecycle: a default Hycli browser call starts and closes Chrome, itda keeps its worker. Against Hycli attached to an already-running Chrome, itda’s render p95 was 7.47x lower.

The warm numbers hold only while the worker is alive; it exits after five idle minutes. A caller that comes back later pays the cold cost: the first direct calls took 248 ms for Hycli and 918 ms for itda; the first browser fetch 2,966 ms and 2,792 ms; the first render 3,199 ms and 3,143 ms. These are fresh data-directory and profile samples, not machine-cache-flushed experiments.

The aim for direct HTTP was a p95 within 5% of Hycli’s. It was not met. One predefined follow-up alternated AB/BA order for 30 pairs, without changing binaries or resetting policy per call:

All 62/62 follow-up reads, including cold samples, and cleanup succeeded. itda’s median was slightly lower, but its p95 was 16.9% higher in the primary run and 38.4% higher in the paired run. With 20 and 30 samples, p95 and p99 are the largest one or two values, so those percentages are rough; the medians are the stable figure. These comparisons do not identify the cause or show a regression from itda’s pre-change version, which was not benchmarked here.

Method

• Hycli (the project itda’s net layer derives from; see the README’s credits) is the unmodified official checkout at 192d71329720f553b382a366573ef06f4e156bb7. itda is the feature/adaptive-transport branch as it was on the day; the data files carry the binary’s SHA-256.
• Each cohort has its own persistent data directory. Installed definitions, pacing, budgets and browser state are not reset between samples.
• Interactive primary samples have equal 1,500 ms think time outside the measured interval. Paired samples alternate tool order with 1,500 ms between pairs. Concurrent samples include all pacing waits.
• Direct mode is explicit HTTP for both. itda recovery is automatic; Hycli uses its explicit browser transports because its localhost policy suppresses automatic escalation. Default Hycli browser calls launch/close the engine; itda retains its worker. The separate live-CDP control exposes that lifecycle difference rather than hiding it.
• Payload fields are checked, not just exit codes. Only correct successes enter latency quantiles; a failed attempt would still be counted. Quantiles use the nearest rank. No builds or browser QA ran during measurement.
• The script needs Bun (Bun.spawn, Bun.serve) and a locally built Hycli; it takes its flags as --name value pairs and ignores a flag it does not know.
• A CLI read is not necessarily one HTTP request. For 20 warm browser-fetch reads, the fixtures observed 60 total requests from Hycli and 40 from itda; warm render observed 40 and 20. Bootstrap/favicon requests are included.
• Results are local synthetic measurements, not a real-site success-rate study. Windows/Linux behavior and arbitrary website challenges were not exercised.

The full raw samples, cold results, counts and binary SHA-256 hashes are in the primary data and the paired data. Only local binary paths were replaced with labels; measurements are unchanged.

Reproduce

Build the pinned Hycli checkout using its build instructions, including its dashboard assets (npm --prefix dashboard ci, npm --prefix dashboard run check, npm --prefix dashboard run build) before cargo build --release --locked --bin hycli. Set HYCLI_BIN to that executable and CHROME to the installed browser.

From this worktree:

cargo build --release --locked -p itda-cli
ITDA_BIN="${CARGO_TARGET_DIR:-target}/release/itda"
bun scripts/bench-transports.mjs \
  --itda "$ITDA_BIN" --hycli "$HYCLI_BIN" --browser "$CHROME" \
  --out /tmp/itda-transports.json --samples 20 --think-ms 1500 --live yes
bun scripts/bench-transports.mjs \
  --itda "$ITDA_BIN" --hycli "$HYCLI_BIN" --browser "$CHROME" \
  --out /tmp/itda-direct-paired.json --samples 30 --think-ms 1500 \
  --only direct-paired

Verification

With ITDA_TEST_BROWSER set to the installed Chrome, workspace tests, cargo fmt --all --check, strict workspace/all-target clippy, layer and changelog checks, and the locked release build passed. Actual CLI tests cover cross-process session reuse, concurrent origins, worker death after execution and worker death before DevTools registration. Browser tests cover credential changes, raw A-B-A redirect cookies, foreign resources/frames/workers, read-only GraphQL, optional-resource cooldowns and a shutdown that leaves nothing running.

Threat model

itda runs on the user’s machine and acts on websites for an AI agent. itda treats the agent, the SiteSpec and every website response as untrusted. Only the user can approve a change or resume a paused site.

“Today” lists controls that exist in the code now. “Planned” lists controls from the roadmap that are not built yet.

Assets

• Website credentials and session cookies
• The user’s accounts on those websites (what a change can do to them)
• The user’s local network (what a request can reach)
• The record of what was done (audit trail)
• Files on disk: attachments itda saved, and files the user sends

The knowledge base in itda.db adds no asset: it holds the shape of pages and answers (selectors, counts, field names, keys and types), verdicts, status codes and times, never an answer, input, cookie, header value, record or form value, and nothing that sends a request reads it.

Threats and controls

Out of scope

• A compromised user account or operating system. itda cannot protect secrets from software already running as the user.
• An agent with unrestricted shell access as the user. It could edit the data directory or drive a terminal itself. The terminal prompt keeps honest agents from approving their own changes; it is not a sandbox.
• Websites’ own vulnerabilities.

See HONEST_CLIENT.md for the rules on how itda treats websites, and SECURITY.md to report a problem.

Changelog

All notable changes to itda are listed here. The format follows Keep a Changelog and versions follow Semantic Versioning. Until 1.0, a minor version may change the definition format or the CLI.

Unreleased

0.7.0 - 2026-10-24

Reads that get past a challenge, a knowledge base per site, and an agent that prepares a site itself. A read a site answers with a challenge page now recovers in the browser installed on the computer, and every request in that mode carries that browser’s user agent; a change is still sent once, over direct HTTP, after a single-use approval. itda writes down what it found and tried for each site, itda fsck lists what was never tried or keeps failing, and itda_shape shows the shape of a page or an answer without its values. When setup keeps one read or none, itda_prepare lets the agent draft the site from its docs, seeing shapes and evidence, never what the site holds.

Added

• itda_prepare, one MCP tool for an agent to prepare a site that itda_setup drafted thinly, as a loop the agent runs: start, recon (the entry page, the API description it links, its GraphQL schema, the routes its docs name and a draft itda made, each with an evidence id), read, search, propose, verify, review and install. itda calls no model and the agent never sees a value the site holds: only titles, paths, methods, field names, selectors, keys, types, pointers and counts. Each proposed operation is kept only when the evidence carries it (a documented or answering server, the route in the docs or a page at that path, something to check in an HTML answer), a declared read whose request asks for a change becomes a change, a route that needs a sign-in itda cannot use is dropped, and a draft that only reads the home page is refused. verify tries the kept reads through the same path every call takes, fills inputs from earlier answers with $result:<read>:<pointer> (scalars only), adds required_pointers from the field names at the top of the answer, says in counts where a page read’s selectors miss, and never sends a change. Reads go only to the site’s registrable domain and the hosts it links as documentation. A session has 120 calls, 48 page requests and 24 check requests (browser recovery counted), 6 reads per verify and two coverage and two repair rounds. install takes the same path as itda_setup. When itda_setup keeps one read or none, its result carries a remedy that names itda_prepare. recon with bundles: true also reads the scripts the entry page loads and keeps a route string only when one GET answers with data. skills/itda-prepare/SKILL.md is the loop for skill loaders.
• Reads that a site answers with a challenge page can recover through the browser installed on the computer. itda fetches the page inside a hidden browser window kept for that one site and account and, for a GET, lets the page render. Every request in this mode, a change or a sign-in form included, carries the browser’s user agent, and the hidden window keeps the browser’s own client hints, so the site sees one client whichever way a request goes and a clearance the browser earned holds for the direct requests too. itda remembers which way worked for an hour, per site, account and action, so the next call does not pay for the failed try again, and forgets a way that failed after a few minutes. The browser session stays warm in a worker process across CLI calls and closes after five idle minutes; changing an input does not restart it. Everything the page loads passes the same address and read checks as a direct request: other sites get neither the account’s credentials nor a referrer, private addresses stay refused, and a page may send a GraphQL query, never a mutation. A challenge the browser did not get past fails that one read (blocked_by_site, paused: false) without pausing the site. A browser answer may be up to 16 MiB. The worker keeps its files under browser-runtime/ in the data directory, one directory per itda build; a build’s directory is removed a day after it stopped being used. ITDA_TRANSPORT=http keeps direct HTTP only, with the pauses it always had. docs/HONEST_CLIENT.md has the rules, docs/TRANSPORT_BENCHMARKS.md the measurements.
• A local knowledge base per site, in itda.db. Setup, check, refresh and every call write down what was found and tried: the pages and actions, which list read can supply which detail read’s input, every try with its stage, verdict, HTTP status and time, and the hashes of the definition and the last verdict. It keeps shapes only (selectors with match counts, field names, keys and types), never an answer, input, cookie, header value or record. Nothing that sends a request reads it, and itda remove deletes a site’s rows. A call itda refused before sending (waiting for an approval, a bad input) is not counted as a try.
• itda fsck [site] runs fixed rules over the knowledge base and lists, worst first, the reads never tried, the reads that need an input (with the list read and pointer that can supply it), the reads that fail every recent try or now and then, and a definition or verdict file changed under itda, each with the command to run. It sends nothing; exit 0, or 1 when a gap is at priority 1. Over MCP, itda_manage takes fsck, and each gap carries the next tool to call with its arguments. itda setup ends with the top three.
• itda_shape, a read-only MCP tool: the shape of a page (selectors with counts, named fields, the keys and types of embedded data) or of an action’s last answer (keys, types and pointers), from the knowledge base or, with fresh, read now the way setup reads a page. At most 24 KB and no values.
• itda ls --json and itda_sites say per site how many actions answered on their last try (verified), the recent pass_rate and the reads that fail now and then (unstable). itda ls --json and itda_sites with a site add a user_guide (what can be read, what can be changed, how one read feeds another) and two to four natural_prompts, made by rule in the person’s language; itda describe <site> prints both.

Changed

• The knowledge base records a preparation loop’s tries under a stage of their own, prepare, and its notes under the prepare scope; the pass rate, the last success and the itda fsck rules leave both out.

• The honest-client rule changes: itda no longer stops at a challenge. Every request carries the installed browser’s user agent, a read may run inside that browser after a challenge, and a challenged read no longer pauses the site. What stays: a change is sent once, over direct HTTP, after a single-use approval; credentials go only to their own site and account; one request at a time per site, with Retry-After respected, whichever way the request goes; captchas are not solved.

Fixed

• Opening itda.db could fail with internal (“Local file operation failed”) when another itda process, the browser worker or the MCP server, closed its connection at that moment: SQLite removed itda.db-wal while itda was making it private. A file that is gone is now left alone.

0.6.0 - 2026-10-23

Files in and out, a check after a lost answer, sessions kept in browser storage, a gate that reads the request it is about to send, and twelve languages. A change can name the read that shows it landed, so after a lost answer itda checks once before anyone is asked to approve again. Reads can save an attachment, and a change can send a file whose hash you approved. A single-page app that keeps its session in localStorage now signs in. Setup, the landing page and the READMEs speak twelve languages, and the mark is a cursor striking a site.

Added

• Twelve languages. What itda setup, itda login, itda refresh and the first bare itda print now comes in English, Korean, Japanese, Simplified and Traditional Chinese, Spanish, French, German, Brazilian Portuguese, Vietnamese, Indonesian and Russian, chosen from ITDA_LANG or the system LANG (ja_JP.UTF-8, zh-TW, pt all resolve). The landing page picks the browser’s language, has a picker in the header and remembers the choice; the README has one translation per language, linked from a language line at the top of each. What agents act on (tool descriptions, error codes and remedies) stays English. The strings live in apps/cli/text/<tag>.json, site/i18n/<tag>.js and README.<tag>.md; docs/i18n.md has the glossary and the rules.

• Outcome check after a lost answer: a change may name the read that shows it landed (confirm: {read, match: {pointer, from}} in the definition). When the change is sent and its answer is lost (action_outcome_unknown, exit 22), itda runs that read once, as a read, and reports landed, not_found or unknown next to the error, as outcome_check in the CLI output, --json, the MCP result and the audit record (outcome_check, confirm_read). The change is never resent. After landed, a new approval request for the same inputs carries a note in the review and previous_outcome: landed in the answer, so the person can decline. itda audit lists lost answers with what the read said; itda_manage audit returns them under unknown_outcome with check. itda ls and itda doctor report a confirm that names a missing operation, a change or a read that needs inputs as a definition problem. itda setup and itda draft fill confirm when a POST’s list read is on the same path prefix and a string input of the change appears in the read’s records; the evidence says so. The lab gets lossy (8089), the scripted portal whose post is saved and then the line drops, and every reviewed lab definition names its confirming read.

• Files out: a read may declare response: {format: file, media_types: [...], max_bytes: N, allow_empty: false}. itda streams the answer to a file under files/<site>/ in the data directory (or itda call ... --out <dir>), seals it at the end, and returns a manifest {path, bytes, media_type, sha256}, never the bytes; over MCP the result adds a resource_link to the file and the tool’s description says what comes back. The content type must be one of media_types (an HTML answer only as an attachment), and a 206 or Content-Range, a body shorter than its Content-Length, an empty body or one over the cap fail by name (wrong_media_type, partial_answer, empty_answer, too_large) and leave nothing on disk. File names come from the site’s Content-Disposition or the address, reduced to plain characters, and never replace a file already there. itda check skips file reads. A transfer longer than the gate’s turn renews it (Lease::renew) every 30 seconds; a lost turn stops the transfer (request_lease_lost).

• Files in: a change may declare body: {multipart: {fields: {...}, file: {name, from}}}. The agent gives the path of a file on this computer in the from input; the approval shows the file’s name, size and SHA-256 and is bound to that hash, so other bytes under the same path withdraw it (approval_expired, reason: file_changed). The file is streamed from one open handle in 64 KiB chunks with Content-Length set, its size and modification time checked before every chunk and its hash at the end; a file that changes mid-send aborts the send (action_outcome_unknown, reason: file_changed). The audit log records the hash. A body with a file is always a change and goes only to the site’s own origin.

• Drafts: a page form with enctype=multipart/form-data and a file control becomes such a change (Upload a file to <page>), and links the page labels as attachments (a download attribute, download or attachment words in English or Korean, or an icon named for one) become file reads grouped by shape (download-file with a file_id input), with media_types from the kinds the links name or the usual document types. itda draft har and itda record draft a recorded multipart post from its part names and a recorded Content-Disposition: attachment answer as a file read. itda describe says what a file read returns and where it lands, and which input a change sends as a file.

• Storage sessions: a site that keeps no session cookie and instead holds a token in the browser’s localStorage (or sessionStorage) and sends it as Authorization: Bearer or a custom header now signs in and works. When you set the site up or record it, itda reads that one origin’s storage once, over the DevTools protocol, from the window you signed in to, and recognises the token as the session when the recorded calls actually sent it as a header: a JWT shape, or a long opaque value under a key named like token, access_token, id_token, auth, session or jwt. A stored value no request sent is reported and never kept. It is drafted as a kind: header auth entry with value_from: storage:<key>; the token lives in the keyring, never in the definition, and itda login <site> --browser reads it again at the next sign-in. If the token is a JWT with exp, itda check reports signed_out (not site_changed) once it has passed, and itda_sites shows when the sign-in expires; itda never signs in again on its own. The token is redacted from results, errors and the audit log like a cookie. value_from on a header entry now accepts storage:<key> beside store:<site>/<key>, and on a browser entry query:<key> beside cookie:<name>, with a validation error for anything else. itda reads only the signed-in origin’s storage, never another site’s, never a profile on disk, and never writes anything into a page; see docs/THREAT_MODEL.md. The definition format is unchanged: spec_version stays 1.

• The API description a page points at is also found in the first page’s HTTP Link header (RFC 8288) and under two more relations: api-catalog (RFC 9727) and describedby, in the header or on <link>/<a>. Learning where costs no request. service-desc wins, then api-catalog, then describedby. An API catalog is a linkset (RFC 9264): itda follows its service-desc links, up to three, and takes the first OpenAPI document. A describedby document counts only when it is one; otherwise /openapi.json is still tried. rel is matched as a list of relation types, case-insensitively, so rel="not-service-desc" no longer counts. Pagination’s header:link reads the header with the same parser, so a target with a comma in it or rel="Next" is read right.

• itda spec validate <file> [--json] checks a definition the way itda add would (Spec::validate and the policy checks), without installing it. A valid file exits 0; otherwise every problem is printed as problem: <field>: <detail>, the way a draft prints its own, and it exits 2, the definition-problem code. --json gives {status, file, site, actions, issues}.

Changed

• The mark is a cursor striking a site; the hero shows it. The tile is a white cursor at the bottom left, a browser window at the top right and a blue bolt inside the window where the cursor’s tip touches it. The favicon is a heavier cut of the same tile that reads at 16 px. The landing’s hero adds the cursor from the mark: it flies in, strikes the terminal’s prompt, the transcript appears, it strikes the About window, and it holds; with prefers-reduced-motion it rests at the prompt. assets/logo.svg is the one master; assets/src/mark.py stamps it into the wordmarks and the hero, assets/src/flow.py reads it, and assets/social.html renders the link preview from it. The README banners (assets/hero.png, assets/hero.ko.png) are rendered again and carry it in the wordmark.
• The gate reads the request it is about to send, not only the declared inputs. After the template is rendered, every query key and body field, the value of an intent field such as action or mode, and any GraphQL document in query (or q/document on a GraphQL path) are read again. A declared read whose rendered request asks for a change (a json_template whose literal body is a mutation, {"op": "delete"} deep inside it) is treated as a change: approval_required carries reclassified with the reason, the review shows it, and the audit record says effect: write with the same reclassified reason. A read whose effect cannot be told (a GraphQL endpoint sent no document, a document itda cannot read) stops with effect_unknown (exit 2) and a remedy; nothing is sent. A declared write is unchanged, and so are the 101 reads in the bundled definitions.
• itda describe shows the read a change names in confirm, one line under the change in the person’s language (after a lost answer: checks list-notices for the new title); --json adds confirm: {read, match}. The change’s MCP tool description says the same in English, and itda_describe in catalog mode now returns the same description as the tool, the approval note included.
• Action descriptions are drafted in the person’s language, any of the twelve, not only in Korean or English: a Japanese setup now writes Hacker News の一覧を読む, not List what Hacker News shows. The language is ITDA_LANG or LANG, else the page’s <html lang>, else English. The phrases are one table in crates/prep/src/label.rs with the same placeholders in every language (a test checks it); the site’s own words (titles, field and operation names) stay as the site wrote them, and outside Korean so does the kind of record (news articles). Agents read all twelve; tool names, error codes and remedies stay English.

Fixed

• A site whose only reads save files ended itda setup as if nothing worked: setup skipped every file read (“saves a file”), so no read had answered and the definition was thrown away. Setup now tries a file read once, through the gate, by the answer’s headers and first bytes: the status, media type and size the definition allows count it as working, the rest of the answer is dropped and nothing is saved. A read answered with a page instead of the file is left out (wrong_media_type). itda check still skips file reads.
• A same-origin redirect or a next-page address of the form /graphql?query=mutation{...} passed the read check, because only the path and the query keys were read. The check now parses a GraphQL document in query (and q/document on a GraphQL path) for its operation type; a mutation or subscription is not followed or turned to.
• X-Original-URL and X-Rewrite-URL, which ask a server to treat the request as one to another address, are refused like the method override headers.
• The SQLite database was created with the umask; only its directory was private. The file and its -wal/-shm companions are now 0600 on Unix (files left by an earlier run are tightened when the store opens); on Windows the directory’s ACL covers them.

0.5.0 - 2026-10-23

Uglier sites, fewer steps, and a bundle for Claude Desktop. itda setup now reads pages whose content sits in frames, signs in with a password without a browser, follows a session carried in the address, turns pages, recognises known software, and refreshes a definition when the site changed. The landing page says plainly what works and what does not. Every release now carries an MCP Bundle per platform, so Claude Desktop installs itda by opening a file.

Added

• Frames: when itda draft page or itda setup fetches a page that is a shell whose content lives in one or more <iframe src> (or an older frameset) on the same origin, and the page has nothing of its own to read, itda fetches each frame page as itself, on the same pacing and with the same session, and drafts from the frame pages as pages of the site, each under the frame’s own address. At most four frames are followed, at most two deep; a cross-origin frame, and a same-origin frame that answered with nothing, are listed in the notes and never fetched. The setup lines and the draft say what was followed (“Followed 1 frame: /frame/board.”). itda refresh follows them again.

• Query sessions: a site that carries its session in the URL as a query key (?sid=...) rather than a cookie now gets a kind: browser auth entry with value_from: query:<key>. itda draft har, itda record and itda setup recognise it when a sign-in’s answer hands the key out (in the redirect Location or on the first signed-in page) and every signed-in call carries it: every operation that sent it gets auth: session, the key is dropped from the operations’ inputs, and the value goes to the keyring, never into the definition. itda login <site> captures it from the sign-in the same way it captures a cookie. At run time the value is appended to the query of each request; it is redacted in results, error text, the audit log and the recording kept for a refresh (addresses, Location headers and the links in recorded pages). value_from on a browser entry now accepts query:<key> beside cookie:<name>, with a validation error for anything else. Because the value rides in URLs, docs/THREAT_MODEL.md notes it can reach server and proxy logs. The definition format is unchanged: spec_version stays 1.

• cargo xtask check-changelog, run by CI: the changelog has one of each section per release, the newest release matches the workspace version, and the landing page and quickstart print the same version. CONTRIBUTING.md says what a minor and a patch version mean before 1.0.

• Sign in with a password, without a browser: a login block on a browser credential names the site’s sign-in page and its user and password fields, and itda login <site> --user me reads the page as itda, fills the form in with the password you type (or pipe on stdin), sends it once with the hidden fields and cookies the page gave, and keeps the session the way a browser sign-in is kept. A redirect means the site accepted it; the form coming back is reported, never retried. itda setup <page> --user me does the same when the page needs a sign-in (a redirect to a sign-in page, 401 or 403, or a “log in to see this” page that links to one), drafts from the page as you see it signed in, gives every action auth: session and writes the login block from the form it found. Over MCP, itda_setup never takes this path. --secret on itda login now names the API key path explicitly (api-key stays the name when the site has no sign-in form).

• examples/lab: Gitea, Redmine, WordPress, MediaWiki and a small legacy intranet (intranet/server.py, standard library only) in Docker Compose, pinned by digest, on fixed local ports, with one seeded account and a little content each, plus reviewed definitions in specs/. With ITDA_LAB=1, apps/cli/tests/lab.rs walks each one from itda setup --user through itda login, a read, a change approved in a terminal and the audit log. CI never runs it.

• examples/lab: three uglier intranets alongside the five, to measure what itda does on pages built the harder ways (intranet/framed.py, scripted.py, urltoken.py, standard library only). framed (8086) keeps the notices table two iframes deep, so setup from the home page finds only the shell; pointed at the frame it signs in and reads and writes the board, and specs/framed.yaml runs to an approved change. scripted (8087) draws the table from GET /api/notices in a script, so itda setup --watch-only watches the browser load it and drafts the read, and specs/scripted.yaml posts with the X-CSRF-Token from <meta name="csrf-token">. urltoken (8088) carries its session in ?sid= with no cookie; with frame following and query sessions in this release, setup signs in, reads the sid from the sign-in redirect and keeps it as a value_from: query:sid session, and specs/urltoken.yaml runs to an approved change. README.md records the measured outcome per case; the one itda cannot do yet - signing in from a shell whose frame redirects to a login, so framed from the home page still finds only the shell - is a test marked #[ignore] with the reason.

• Sites that run known software are recognised. itda setup reads the page’s HTML for GitLab, Jira, Confluence, Redmine, Discourse, MediaWiki, WordPress and Gitea or Forgejo (a generator meta, well-known asset paths, the Atlassian context-path metas, body classes), confirms the guess with exactly one GET to that software’s own version or info endpoint, and then drafts from a template under sites/software/ instead of reading the page like any other: the reads an agent needs most, up to three changes marked as such, models and the software’s own way of signing in, every operation with its documentation in evidence. The template’s base_url is filled with the instance’s API base, context path included (/jira, /w, a GitLab relative URL root, a Gitea appSubUrl, the WordPress API root the page links to); the site is named after the host; one line says so (“This looks like GitLab. Using its API at .”). The page draft still runs and its lists, forms and feeds join the template, the same method and path drafted once, and a page that needs a sign-in or scripts still gets the template when the software is confirmed. A fingerprint the API does not confirm is dropped quietly. itda setup --as <software> forces a template, --no-template skips them, itda check works on the result as on any site, and itda_setup over MCP takes template and names the template it used in its result. The site’s sources.json names the template and its API base, so itda refresh fills the same template again, with the page read again when it still opens.

• itda refresh <site>: when itda check says site_changed, draft the site again from the sources it was set up from and merge the result with the installed definition. The site’s name, title and address, defaults, auth and every action edited by hand are kept; actions the draft changed take the new version, ones it no longer drafts are dropped only when their read also failed, and new ones are tried once and added when they answer. The diff is printed in plain words (added, removed, changed, kept as edited) and written after a yes, or at once with -y; the site is checked right after and the verdict printed. Approvals for the site are withdrawn, as for any replaced definition: what the user reviewed is no longer what would be sent. To make that possible, itda setup, itda draft ... --install and itda record --install now write specs/<site>/sources.json next to the definition: the pages, the API description, the GraphQL endpoints asked, the recording when one was kept (copied under the site as recording.har with its cookie, token and session values, private fields and sign-in answers blanked), the draft’s options and a hash of every operation as drafted. itda check now points at itda refresh <site> when a site changed, and itda check --all prints one verdict line per site.

• itda_manage over MCP gains refresh: the person confirms the diff in a form (a form nobody answers counts as no), and the site’s tools are reloaded and checked. itda_check without a site already checks every site; the docs now say so.

• itda draft page and itda setup read a page that is one thing (an article, a package, a product, a bug) as its own content: the headline, the body text, what sits beside the headline, a date, an author and the values the page labels in definition lists and label-value rows, as html.page fields that each match once. Such a page used to be one read that checked the title. A page that is one thing with a named list of records on it (a package with its releases) gets both reads, and itda setup says “the page’s own content” when it finds one.

• Repeated siblings of one shape become records when they share a title at one place: a link as before, or a heading, a text named as a title, or the record itself when it is a link with something inside. The fields come from what the records share: a summary, a byline, a date, and whatever sits under a class the site named (score, author, release__version becomes version), with build names left out and a text that reads as a date as published_at. Bare paragraphs, bare links and menus never qualify. A list read is described by what its records are (List the projects on Projects) when the page names them.

• A list whose links share one shape (/item/{id}, view.php?id=) gets a read of one record by its id, with the query keys every link sends as inputs with defaults and no response check yet.

• The page input follows the link marked rel="next" and starts at 0 for offset and start.

• itda setup watches what a page drawn by scripts loads by itself before asking anyone to record. When the page shows itda nothing but a title, carries scripts that could fetch something (a script file or a preloaded module, or an inline script that imports a module or mentions fetch, XMLHttpRequest, graphql or api) and a browser is installed, it opens the browser on the page in the same fresh profile recording uses, waits until the network has been quiet for two seconds (ten at most), scrolls once to the bottom, waits again, closes the window and drafts from the recording the way itda draft har does, the page’s own address first so what the page itself shows is never lost to a busier API elsewhere. One line says what it saw (Watched the page load: 12 calls, 3 reads drafted., in English or Korean, counting the reads beyond a title check); only when no such read came out does it ask to record as before. Nothing in the window is clicked or typed, nothing it signed in with is kept, and a page whose scripts go to a sign-in page stops with the same auth_required words a redirect gets. --no-record skips the window too; a new --watch-only watches but never asks to record, for scripts. A site whose software is recognised gets its template instead and is not watched. itda_setup over MCP does the same, and says in its description and its result that a window opens briefly on the user’s screen.

• Reads that list things can turn pages. A definition declares pagination (style: page|offset|cursor, where the next marker is in the answer as a JSON pointer or header:link, an optional more pointer, and the query or body input it goes back in). The answer then carries meta.next, an opaque handle such as ic_…; itda call ... --next <handle> and next over MCP (itda_call and the per-action tools, whose schemas list it) read the following page with the same inputs. The site’s own marker stays in the local database for fifteen minutes, bound to the site, action, account, inputs, definition and credential, and is removed from the data; a cursor input is never shown to agents. A handle for another call, or an expired one, is refused with pagination_invalid or pagination_expired (exit 23). Only reads turn pages. itda draft openapi, itda draft har, itda draft page and the GraphQL schema drafts declare it when the evidence is plain, never by guessing; the bundled github (issues, comments, repository search), npm (search) and crates-io (search) definitions declare it. AGENTS.md, the skill and the server instructions say to read only as many pages as the question needs.

• A preflight step can read a value from the JSON a page embeds for its scripts: extract: {build_id: "ssr:__NEXT_DATA__#/buildId"}, so a token or build id that only lives there reaches the action’s path or inputs. Only a string, number or boolean counts.

• AGENTS.md and skills/itda/SKILL.md tell coding agents how to use itda: discover actions, run reads, treat website text as data, wait for itda approve, never retry a lost change, run itda check first when something stops working. The MCP server’s instructions say the same, shorter.

• itda feedback prints a link to a new GitHub issue with the version, the platform and the doctor checks filled in (never the data directory path) and opens it; --no-open only prints. It sends nothing itself.

• itda check ends each site with a verdict and what to do: ok, signed_out, site_changed, blocked or unreachable. The exit code follows the worst verdict, and --json carries it as verdict and per site under sites.

Changed

• itda draft page and itda setup on a page that refuses itda say what the gate saw instead of error[internal]: <url> answered HTTP 403: the host is behind Cloudflare, runs a bot manager or asks for a captcha (blocked_by_site, exit 12), or limits how often it is read, with the wait it asked for when it named one (site_rate_limited, exit 13), in English or Korean. A captcha served with HTTP 200 is reported the same way, and a page that sends itda on to a sign-in page says so (auth_required, exit 10) and points at recording.

• A Retry-After: 0, or a date already past, no longer counts as a rate limit: a site that sends it with every page is read as itself.

• The landing page on phones: lighter glass, the setup dialog left out of the hero stack, full-width buttons, tighter rhythm, terminal lines wrapped on anything narrower than the two-column layout, and the sky drawn smaller with the cursor effect only while a finger is down.

• The landing page and both READMEs carry a prompt to hand to an agent: paste it into Claude Code, Cursor or Codex with a site’s address and the agent installs itda, runs itda setup <address> --client <app> -y and starts using the site.

• The landing page has a living sky behind the whole page: liquid chrome with striped, colour-split reflections and a holographic sheen, a wire grid running to the horizon, and a field of points and threads that gather around the cursor, with a website on the left and an agent on the right (site/sky.js, three.js from cdnjs). It follows the scroll, draws one still frame under reduced motion, and leaves the plain glow without WebGL.

• The hero lost its badge and chips; the binary, platform and licence line moved to the footer.

• The landing page is laid out as a desktop. The hero stacks windows that can be dragged: the first run, the actions it found, the setup progress, an about box and a clock. Sections open with a numbered eyebrow and a centred headline, every box is a window with a title bar and a dither texture, and the risk comparison is two windows side by side, the browser-driving agent’s lane next to itda’s.

• The sky is now a living network: nodes spring home through a slow current, threads join neighbours, packets of light run node to node and along the handoff between the website and agent hubs. The cursor is a node too: nearby nodes gather and orbit it, its motion leaves a wake, threads run from it, and a click sends a ring through the field. Node count follows the viewport, with a lower cap on touch screens.

• The landing page’s components now speak the same language as the sky: smoked-glass panels with a chrome hairline and faint scanlines, chrome headlines with a holographic accent, glossy pill buttons, Aqua-style window lights on the terminal, and chrome coins for the step numbers.

• itda <address> sets that site up, and itda github (or npm, crates-io, pypi) adds the ready-made site and connects the agent apps found on this computer; the README’s one line is the one line you type. The tagline and the landing page say so.

• action_outcome_unknown now says that itda never resends a change on its own, and the runtime tests prove it against a server that drops the connection after taking the request.

• A bare itda in a terminal says what it is and asks for one address, then runs itda setup on it, so the first run is: type itda, paste, Enter.

• itda setup finds the agent apps on this computer (Claude Desktop, Claude Code, Cursor, Codex, or a project with a .vscode folder) and connects them all after one Enter; the numbered list only appears when none is found.

• itda setup asks whether the site needs a sign-in only when the page it fetched has a password form; a page without one is used as it is.

• The installer ends with “Open a new terminal window and type: itda”.

• At the first prompt, a ready-made site’s name (github, npm, crates-io, pypi) installs that site and connects the agent apps found on this computer.

• After adding itda to Claude Desktop on macOS, itda offers to restart the app when it is open, or says that opening it is enough; for Claude Code it runs claude mcp add itself when claude is on the PATH.

• itda doctor lists the agent apps whose settings already start itda.

• itda setup on a page of pypi.org, github.com, npmjs.com (with or without www.) or crates.io uses the ready-made definition itda add installs for it, says “This is PyPI. Using its JSON API.” (or the site’s name and API), does not fetch the page and tries the definition’s reads; --no-template reads the page instead. itda_setup over MCP does the same and puts the line in its notes.

Removed

• The browser-fetch and browser transports and the derived credential kind, left over from the port: no code ran them, and a definition that named them was accepted and then refused at run time. itda add now refuses them with the field named.

Fixed

• Signing in from a shell whose frame redirects to a login. When a page is a shell and its same-origin frame answers with a redirect to a sign-in page, itda setup now treats it as if the top-level page had: with --user it signs in through that form and reads the frame again with the session, then drafts from it, instead of drafting only the shell’s title. Following the frame’s redirect to read the login form is a read; nothing is posted without the person’s credentials and the usual consent. Without --user, setup names the sign-in the frame leads to, and itda draft page notes that the frame leads to a sign-in rather than only that it was not read.
• Approving in the client works on MCP protocol 2026-07-28, which Claude Code 2.1.289 negotiates: that revision took server-to-client requests away, so the elicitation/create request itda sent was dropped unseen and the call hung until itda gave up. itda now hands the form back as the call’s result (resultType: input_required), the client shows it, and calls again with the answer and the approval id as requestState; the id only ever names an approval itda stored for this very call, and anything else is asked again. The confirmations itda_manage and itda_login put to the person go the same way. Clients on the earlier handshake keep the request they had. The review the form shows no longer starts with a blank line, and leaves “as account” out when the site has no accounts: Claude Code cut a five-line review to its first three and hid the request and the inputs behind “(+2 more lines)”, and shows the four-line one whole.
• A change answered with a redirect (post, then redirect, then get, as Gitea, Redmine and most server-rendered sites do) is reported as landed, with the address the site pointed at, instead of request_failed. A redirect to a sign-in page is reported as auth_required, since the site is asking for a session it no longer accepts.
• The cookies a preflight step’s answer sets go along with the change, so a Rails site (Redmine) that rewrites its session cookie on every answer accepts the token it just handed out.
• A read redirected to an address itda will not follow, such as a sign-in page with a reauth parameter (WordPress), is answered as the redirect it is instead of failing with bad_url, so itda setup can name the sign-in page.
• Two itda processes starting on a fresh data directory at once (the MCP server and itda approve, say) no longer race in the database setup: Store::migrate reads the schema version and applies the steps in one immediate transaction.
• A GraphQL document nested deeper than 32 levels is refused before it is parsed, with a clear message in a definition’s default and bad_request for an agent’s input, instead of running the parser out of stack.
• api_denied (exit 14): a 403 that is not a sign-in problem says the site refused that one request as not allowed, with upstream_status and, when the site’s JSON answer names one of a short list of reasons, provider_reason; nothing else from the answer is passed on. A 403 whose reason says the session was rejected stays auth_required. Every refusal now carries upstream_status, and itda check counts an address answered with 404, 405 or 410 and a query answered with errors (query_failed, exit 11) as site_changed.
• approval_pending (exit 20): a call with an approval the user has not answered yet is told to wait and call again with the same id, with the command to run in command; the approval stays. A call with other inputs withdraws the approval (approval_expired, reason: inputs_changed). itda reject also withdraws a granted approval, and itda logout, itda remove, a new itda login and replacing a definition withdraw every approval for the site or account. The review itda approve prints, and the form an MCP client shows, name the action, say what it does in the definition’s words, and cut a value longer than 500 characters with its length.
• A read is classified again after its preflight steps with the found values filled in; one that would now be a change stops with effect_changed (exit 2) and is not sent. Headers and inputs that override the method (X-HTTP-Method-Override and the like) are refused at install and before sending. A GraphQL answer that carries errors behind a 2xx is action_outcome_unknown for a change and query_failed for a read, never a success.
• itda audit and itda doctor show a change_started record with no outcome after it as a change with an unknown outcome (the process stopped after it was sent), and itda_manage audit returns them under unknown_outcome. A change that failed before anything left the machine (no turn at the gate, a name that did not resolve, a refused connection) keeps its network code and is reported as not sent instead of unknown.
• Long secrets are sealed into vault.sealed under the data directory (AES-256-GCM, a fresh nonce per write) with one 32-byte master key per data directory kept in the system keyring; every browser session goes there, and so does anything over 1024 bytes or that the keyring refuses as too long (Windows Credential Manager caps a credential at CRED_MAX_CREDENTIAL_BLOB_SIZE, 2560 bytes). API keys stay in the keyring. Existing entries keep working and move on their next write, in both directions; itda doctor says where secrets are. The cipher comes from aws-lc-rs, already built through rustls.
• itda describe <site>[.<action>] prints each action’s inputs and a command to copy, with a placeholder for every input it cannot run without; itda ls --json carries the same command as example. An unknown site, action or input names the nearest one (“Did you mean”), in the CLI and over MCP.
• itda mcp --site <name> serves one site only: its actions are the only tools, itda_setup is refused, and the other management tools stay inside it.
• Two more ways to install, from the next release on. Every release carries one MCP Bundle per platform (itda-<target>.mcpb): open it and Claude Desktop installs itda with its tools, no terminal needed; approving a change still happens in a terminal with itda approve. The bundle is packed by cargo xtask mcpb from the release archives, with a manifest that follows the MCPB spec (manifest_version 0.3, server.type binary, itda mcp as the command). A winget manifest for 0.4.0 (manifests/b/brnyxx/itda/) is ready to submit to winget-pkgs and is not submitted yet.
• Five MCP tools so an agent never needs a terminal to set a site up or look after it: itda_setup (look at a page as itda, draft, try every read once, keep what works; the site’s actions become tools in the same session, announced with notifications/tools/list_changed, which the server now declares with tools.listChanged), itda_login (the person signs in in their own browser, after a form in clients that show one; the definition must name the sign-in cookie), itda_check (the verdict per site, as itda check --json), itda_sites (what is set up, with the last check’s time and verdict, now kept in specs/<site>/check.json) and itda_manage (remove and resume after the person confirms in a form, approvals, audit). itda_setup never asks anyone to record and never keeps a credential; pages that need a sign-in, or still show nothing after the watched load above, are refused with the command to run instead. The server instructions, AGENTS.md and the skill say when to call them.
• A new itda-setup crate holds the steps behind itda setup, itda login --browser, itda check and the installed sites, with the questions answered through a trait and progress reported through a callback, so the command line and the MCP server run the same code. The CLI’s words and questions are unchanged.
• itda draft page and itda setup draft a typed read for each list they find in a page’s embedded data, instead of one read that returns the whole payload: an ItemList or a list of one typed thing (NewsArticle, Product…) in ld+json, and in __NEXT_DATA__, __NEXT_F__, __APOLLO_STATE__, __PRELOADED_STATE__ and the like the list of objects with the most to read. Each read is named after what it holds (list-news-articles), points extract_pointer at the list and keeps up to eight plain fields of every record through a model, ids and titles first and credentials left out. itda check counts its records. The whole payload is drafted only when no list is in it.
• An Apollo cache (__APOLLO_STATE__) is also grouped by typename, so a definition can point at /Question or /Product.
• defaults.interval in a site definition asks for more time between requests to that site (2s, 500ms, up to 30 s). itda’s own pace, one request at a time per site about 1.2 seconds apart, is the floor; a definition can only slow it down. A value that is not a time is refused by itda add.
• A site that answers a read with 429 or 503 and a Retry-After of ten seconds or less gets that wait, once, and the read is tried again. A longer wait stops the read with site_rate_limited, itda check reports the site as blocked, and the error, the check result (retry_after_s) and the MCP server instructions say how long the site asked for. A change is never sent twice.
• Requests queued in one process now take turns in order instead of polling the shared gate against each other.
• A draft that sees a GraphQL endpoint (a recorded call to it, or a page naming a same-origin /graphql path) asks it once, with the standard introspection query, what it offers, and drafts one read per root Query field whose arguments are scalars, enums or ids: the field name is the action, the arguments are typed inputs, and the selection is the field’s scalars two levels deep, 24 at most. An optional argument that holds an object or a list is left out and listed; a field that requires one is listed instead. Mutation fields are listed in the notes and never drafted. A site with introspection off is drafted from its pages and calls alone. The query is sent as itda, read-only, with a size cap, by itda draft page, itda draft har, itda record and itda setup.
• An optional input the agent leaves out now leaves the json_template body too, instead of standing in as an empty string where a number or null belongs; GraphQL variables typed Int or Boolean need that.
• itda draft page and itda setup read the API description a site publishes: the one the page links to, else /openapi.json on the same origin when it answers with one (one GET, as itda, at most 4 MB). Its reads join the draft the way itda draft openapi makes them, drafted once when the page already had the same path; its changes become notes, and a read keyed by a credential input is left out and listed. A description on another address is noted, not merged, and one that does not parse leaves the page draft as it is. The header comment and each merged action’s evidence name where it came from, and itda setup says what it read in one line.
• Requests send Accept-Language: * (no preference) instead of ko-KR,ko;q=0.9,en;q=0.8, a value left over from the browser header block itda was derived from. pypi.org answered a project page asked for with any Korean Accept-Language (ko, ko-KR or that list) with a 3 KB “Client Challenge” page and kept challenging every request from the same address for a few minutes after, so itda draft page https://pypi.org/project/requests/ drafted the challenge instead of the 322 KB page. Leaving the header out is not enough: amazon.com then sends a gzip body itda does not decode. A definition that needs a language can still set one in defaults.headers.
• A challenge page served with HTTP 200 (small, titled as a challenge, only a script and no link to follow, as bugzilla.mozilla.org’s bug list and pypi.org answer when they challenge) now counts as a block: the site is paused, itda draft page and itda setup say the site’s bot protection refused itda (blocked_by_site, exit 12), and itda check says blocked. Before, it was drafted as a read named after the challenge and checked as ok.
• Drafts leave ad slots out of a page’s records (an element whose class, id or label marks it as an ad: AdHolder, ad-*, sponsored, aria-label="Sponsored"): when ads share their classes with the records beside them, the records’ selector excludes the ad class. On amazon.com the draft had picked the sponsored results, which are not there when the first page is asked for by number.
• The page input a draft adds when a page links to its next page (page, offset, start and the like) has no default any more, so the read and itda check ask for the address the draft saw until an agent or a page handle asks for another page; the next page is still counted from 1, or from 0 for an offset. Sending page=1 made some sites answer with different markup and the check fail.
• A read the site blocks or challenges while itda setup tries it is left out with “: the site does not give itda this page”, nothing more is sent to the site in that run (the reads after it are kept and shown as not tried, for the next itda check), and the site is not left paused, so a challenge on pypi.org’s search page no longer takes the three feeds after it down too. itda check and calls on an installed site still pause it.

0.4.0 - 2026-10-22

One address is enough: itda setup looks at a page, or watches you use the site in your own browser, names what agents will be able to do in plain words, tries every read, and connects an agent. Any website, not only the ones with an API description.

Added

• itda setup <url> sets a site up in one go: it looks at the page, or opens your browser and records when the page refuses, needs a sign-in or is drawn by scripts; shows what agents will be able to do in plain words; tries every read once and keeps the ones that work; saves the site; and connects an agent. It asks before each step; --record/--no-record, --client and --yes answer for scripts. ITDA_LANG=ko (or a Korean LANG) makes it, and the drafted descriptions, speak Korean.
• Drafted actions carry a description a person would say (List what Notices shows, 공지사항 목록 읽기), taken from the page’s title or the call’s name, in English or Korean.
• itda record <url> opens your own browser in a fresh window and records what the pages ask the server for while you use the site, then drafts a definition the same way itda draft har does. The recording stays in memory; --save keeps it as a HAR file. itda never clicks, types or navigates in the window. ITDA_DEBUG_CDP=1 prints the browser messages.
• itda record --install offers to keep the token and the browser session the recording signed in with, each after a yes in the terminal, so a site that sends a bearer token from its scripts works without pasting it.
• A recorded GraphQL call becomes one action per operation (exploreProjects is explore-projects): queries are reads, mutations are changes, and the variables are the typed inputs, rendered through a json_template.
• itda record and itda draft har also draft the pages the recording holds, as itda draft page does, so a site that renders its lists and forms on the server gets actions even when its pages call no API.
• itda draft page <url>... drafts a site definition from the pages you use, fetched with the honest client: a table or a list of records becomes html fields, data a page embeds for its scripts becomes ssr_json, a search form becomes a read, a post form becomes a change with its token read through a preflight step, page links become a page input, and RSS or Atom feeds come along. Every read gets a response check, so itda check notices when a page changes. Lists are found by their shape, not only by known class names: any run of three or more siblings outside navigation that each hold a link at the same place, with the title and link read from that link’s own path. When a page embeds its data for its scripts, the draft points extract_pointer at the list inside the payload and checks the keys every record shares.
• itda draft har also handles a token sent as a header, such as X-CSRF-Token: a preflight step reads it from the page’s <meta name="csrf-token"> tag before each call.
• itda add also takes an https URL, or the name of a ready-made site (itda add github); the four definitions in sites/ are built in.

Changed

• itda setup names the agent app it connects (“Adding itda to Claude Desktop…”), shows the settings file it wrote with ~ for your home folder, says so in Korean too, lines the action names up only as wide as they need, and writes its example request mid-sentence.
• The README and the landing page open with a recording of itda setup as it ran on Hacker News (assets/setup.gif, Korean in assets/setup.ko.gif, rebuilt from assets/src/setup.*.tape with vhs).
• A new key visual, a hand passing a website card to an agent (assets/handoff.png), on the README banners and the link preview (assets/hero.png, assets/hero.ko.png, assets/social.png, rendered from assets/src/banner.html), and the docs introduction says the same thing the README does.

0.3.0 - 2026-10-20

Install ready-made sites with one command, and work with old intranet forms that need a fresh security token on every change.

Added

• Preflight steps: an action can read a page just before it runs and pass a fresh value, such as a CSRF token, into its headers, query or form as {{step.<step>.<name>}}. Agents never see or set those values.
• The sandbox has a write form with a one-time CSRF token (sandbox.write-notice) to try preflight steps on.
• itda draft har turns a form token such as _csrf into a preflight step that reads it from the form page recorded before the post.
• itda add <file> installs a site definition (or - for stdin) and shows where it sends requests, which actions change the site and how it signs in; itda remove <site> takes it away.
• Ready-made site definitions in sites/: GitHub (public reads without an account, issues and comments with a token), npm, crates.io and PyPI.

Changed

• A model now applies to each record when the answer is a JSON list, instead of returning an empty object.

0.2.0 - 2026-10-20

Sign in through your own browser, approve changes inside the agent app, and check that sites still answer the way their definitions say.

Added

• itda accounts lists signed-in accounts and the names of their secrets; itda logout <site> removes an account and its saved secrets.
• itda check [<site>] runs every read that needs no input and reports which ones no longer match the site, with exit code 11 when a site changed.
• Browser sign-in for sites without API keys: itda login <site> --browser opens your own browser in a fresh profile, keeps only that site’s session cookies in the system keyring, and kind: browser actions send them only to the same site.
• Approve changes inside the MCP client: with itda mcp --approve-in-client (or itda mcp install <client> --approve-in-client), clients that show elicitation forms ask you to approve the exact request, and declining returns approval_rejected.

0.1.0 - 2026-10-19

The first release: reads and approved changes on plain HTTP sites with API keys, from the command line or over MCP, and definitions drafted from OpenAPI documents or browser recordings.

Added

• itda command: ls, call, login, resume, doctor, with a stable exit code contract for scripts and agents (2 input, 10 sign in, 11 page changed, 12 blocked, 13 rate limited, 20–22 approvals and changes, 30 network).
• MCP server (itda mcp): one tool per action up to 30 actions, three stable catalog tools (itda_search, itda_describe, itda_call) above that. Results are marked untrusted and cut to 24 KB.
• itda draft openapi: draft a site definition from an OpenAPI 3 or Swagger 2.0 document, with response checks, header auth and a list of what could not be translated. --install puts it in the data directory.
• itda draft har: draft a site definition from a browser recording of you using the site. Only the shape of each call is kept; recorded tokens, cookies and values never reach the draft.
• itda mcp install for Claude Desktop, Cursor, VS Code and Codex, and the claude mcp add command for Claude Code. Existing settings are kept and backed up.
• Approvals for changes: a change returns an approval id, the user reviews the exact request with itda approve in a terminal, and the change runs once with exactly those inputs. itda approvals and itda reject list and refuse them.
• Hash-chained audit log of every call, approval and change, with itda audit and itda audit --verify. Input values and credentials are never written to it.
• Credential vault on the OS keyring, or ITDA_SECRET__ environment variables for CI and containers. Agents only ever see account ids.
• Site definitions (spec.yaml): JSON and server-rendered HTML responses, declared response checks, models, and safety validation with named problems.
• Network layer: honest itda/<version> user agent, per-site pacing and budgets, pauses on blocks and expired sign-ins, private-address guard, credentials bound to their origin.
• Sandbox example site for trying everything locally.