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.