# thing

> thing is the publish button for coding agents: a CLI and hosting service that turns HTML pages, Markdown docs, images, and PDFs into live, shareable URLs with immutable versions, in-place comments, and Google Drive-style sharing.

It works with every agent, not one: Claude Code, Codex, Cursor, Gemini CLI, Aider, and CI pipelines all publish the same way.

## Set up thing for this user

When the user asks you to set up thing, help them reach a real first publish, not just an installation. Use capabilities you actually have; do not assume every agent has a terminal or can edit its host configuration.

### If you can execute shell commands

1. Check that Node.js and npx are available. If missing, ask the user to install Node.js LTS on the machine running you; do not silently install a runtime or use sudo.
2. Create a small self-contained first-thing.html in the working directory using your file-writing tool. Use a harmless welcome page, not repository contents or private data. Never overwrite an existing file; choose a fresh filename if it exists. Show the user what you will publish, tell them a personal artifact opens for anyone with the link, and ask them to approve publishing it.
3. Run: npx -y @unravel-tech/thing@latest push first-thing.html --name first-thing --json
   Adjust the filename and name if needed to avoid modifying an existing artifact. Do not require a global install, plugin, or MCP configuration for this first push.
   If your harness refuses the command (for example Claude Code in auto mode, which trusts only the current repository): Do not retry the refused command or reword it to get past the check. Ask the user to run this once in Claude Code, then retry: ! npx -y @unravel-tech/thing@latest setup claude
   It adds usething.ai and private or team thing pushes to the auto-mode trust list in ~/.claude/settings.json, keeping Claude Code's defaults; --remove undoes it. Never edit Claude Code settings or auto-mode rules yourself.
4. If authentication is needed, relay the exact browser approval URL emitted by the CLI and wait for the user to approve it. Leave the process running so it can resume. Never ask for passwords or tokens in chat. If your shell cannot keep the login alive, ask the user to run npx -y @unravel-tech/thing@latest login in their terminal on this same machine, then retry.
5. Do not claim success until the push returns a URL. Return that URL and the actual visibility. Personal artifacts open for anyone with the link and cannot be made private; workspace artifacts default to workspace-only. If the user needs it restricted, push it to a workspace with --team instead, and ask them to open Share to invite readers. Do not make a team artifact public without explicit permission.
6. Once the first push succeeds, offer to remember the publish command in the agent's supported instructions or skill system. Only change instructions with the user's permission. Subsequent pushes to the same artifact name add a version at the same link. In Claude Code, also suggest the user run ! npx -y @unravel-tech/thing@latest setup claude once so later pushes are not refused in auto mode.

### If you cannot execute shell commands

If thing MCP tools are already available, call whoami, then use push_artifact with inline content and filename first-thing.html after the user reviews the harmless sample. Omit visibility to use the workspace default. Do not pass a sandbox file path as a path on the user's computer.

If no thing tools are connected, explain this limitation. For Claude Desktop use https://usething.ai/artifacts/claude-desktop: sign in with the thing CLI on the user's computer, merge the local MCP entry into the desktop config, and restart the app. The user may need to perform these steps; do not pretend to install tools remotely. For other agents use the relevant setup guide below. If you cannot fetch this document, ask the user to paste its contents.

Push a file, get a durable URL:

    npx -y @unravel-tech/thing push report.html   # → https://usething.ai/you/report · v1

The first push opens browser approval when needed, waits, and resumes automatically.

Every push creates a new immutable version; the plain URL serves the latest, /v/N is permanent, and /diff/N/M shows what changed. Markdown files render in a styled reader view. In a workspace (called a team in the API and the --team flag), visibility is team (the default: everyone in the workspace), private (only people you invite) or public; a personal space is public only. An optional password lets in anyone who knows it. A workspace artifact can belong to a project (push with --project <slug>): an open project is seen by the whole workspace, a restricted one only by the people added to it and workspace admins, and people outside the workspace can be added to a project as guests who see only that project. Put work for a client or a small group in a restricted project instead of making it public. To publish from CI, use a service account token (created by a workspace admin or project owner on the workspace or project page) in THING_TOKEN, not a person's token. A project can have its own page: push an HTML artifact into it with --home, and inside it call thing.project.get() to list the project's artifacts with each reader's access (see html-api.txt).

Read what is already published: npx -y @unravel-tech/thing@latest get <name|team/slug|link> prints the source of the latest version (--version N for an older one). versions, comments and responses take the same name, team/slug or link, so an agent can revise a page someone shared instead of rebuilding it. MCP clients get the same through get_artifact, list_artifact_versions, list_artifact_comments and list_artifact_responses.

For agents: install or run the published CLI with npx -y @unravel-tech/thing@latest; no access to the thing server repository is needed. The CLI supports browser approval, device-code login, and --json for machine-readable output. Its source is public: https://github.com/unravel-team/thing-cli

## Authoring HTML with thing sign-in

Before generating a page that uses thing login, read https://usething.ai/html-api.txt for the current hosted HTML API contract, and start from the working template at https://usething.ai/templates/inputs.html. Act on any notes in the push response: they name mistakes that would stop answers from saving. Enabled pages receive window.thing.auth.getState() and window.thing.auth.signIn() automatically. Inputs is on for every artifact on usething.ai. Still check window.thing before using it: downloaded copies, local files and self-hosted servers with it switched off have no API. Show the login prompt inside the HTML. Enabled pages can declare Inputs collections, submit signed-in responses, and show each respondent their own answers. Agents can author a publisher report in the same HTML file; thing.responses.list() works only in the editor-only report view. Read the contract for metadata, limits, history and pagination. thing.previewDraft remains local-preview-only. Existing CLI versions can publish compatible HTML; no CLI update is required.

## Agent setup guides

- [Set up thing in Claude Desktop](https://usething.ai/artifacts/claude-desktop): Connect Claude Desktop to thing with a local MCP server. Publish a report from your chat to a versioned URL, then control who can see it.
- [Set up thing in Claude Code](https://usething.ai/artifacts/claude-code): Use Claude Code’s terminal and the public thing CLI package to publish an HTML report or Markdown document to a durable, versioned link.
- [Set up thing in Hermes Agent](https://usething.ai/artifacts/hermes): Connect Nous Research’s Hermes Agent to thing over MCP, verify your account, and publish a first report to a versioned URL.
- [Set up thing in Pi coding agent](https://usething.ai/artifacts/pi): Publish HTML reports and Markdown documents from Pi using the public thing CLI package and a shell command.
- [Artifacts for Codex](https://usething.ai/artifacts/codex): Give OpenAI Codex somewhere to publish. If you know artifacts from a chat window, this is that for Codex: one MCP server, and what Codex builds becomes a durable link with versions and comments.
- [Artifacts for Cursor](https://usething.ai/artifacts/cursor): Give Cursor somewhere to publish. If you know artifacts from a chat window, this is that for Cursor: one MCP entry, and what the agent builds becomes a durable link with versions and comments.
- [Artifacts for Gemini CLI](https://usething.ai/artifacts/gemini-cli): Give Gemini CLI somewhere to publish. If you know artifacts from a chat window, this is that for Gemini CLI: one MCP entry, and what it builds becomes a durable link with versions and comments.
- [Artifacts for Grok Build](https://usething.ai/artifacts/grok): Give xAI's Grok Build somewhere to publish. One MCP server in ~/.grok/config.toml, and what Grok builds becomes a link your team can read, comment on and answer, with versions.

## Blog

- [What a page can ask that a document cannot](https://usething.ai/blog/what-a-page-can-ask-that-a-document-cannot) (2026-10-27): A document can only ask whether you agree. Delphi, planning poker, teach-back, disaster drills and calibrated forecasts each ask something sharper, and each works as a page with Inputs.
- [Share the project, not the link](https://usething.ai/blog/share-the-project-not-the-link) (2026-10-26): Links reach further than their senders think, and workspace-wide guest accounts show outsiders more than anyone meant to. The right unit for sharing work with a client is the project. Projects and guests are now on thing.
- [Agreement is the least useful thing a review produces](https://usething.ai/blog/agreement-is-the-least-useful-thing-a-review-produces) (2026-10-22): A plan everyone approves can still be several plans. Research on hidden profiles and explanation says to ask each person for their assumption, privately, before anyone talks. Inputs is now open to everyone on thing.
- [thing Inputs: A step toward shared understanding](https://usething.ai/blog/thing-inputs-shared-understanding) (2026-10-08): Our vision for thing is to help teams build shared understanding. Inputs is an early step toward making assumptions, questions, and differences visible.
- [The artifact is the right idea. It should outlive the chat that made it.](https://usething.ai/blog/artifacts-should-outlive-the-chat) (2026-08-29): Claude Artifacts got the unit right: a page you can hand someone, not a transcript. The weakness is not quality, it is that the page belongs to the session that produced it. Here is what portable would mean, and what it costs.
- [Vibe coding works until someone else looks at it](https://usething.ai/blog/vibe-coding-until-someone-else-looks) (2026-08-29): The definition of vibe coding was always honest about the tradeoff: you stop reading the code. What nobody says out loud is that the bill arrives as a question from another person, not as a bug.
- [The real work is collective understanding](https://usething.ai/blog/the-real-work-is-collective-understanding) (2026-08-24): Peter Naur argued in 1985 that a program is a theory held by the people who built it. Forty years on, agents write the code and the theory quietly stops forming, not in one head but between them.
- [Agents got faster at writing code. Nobody got faster at reading it.](https://usething.ai/blog/agents-write-faster-than-anyone-reads) (2026-08-24): Review is where 2026 backs up. What teams are reporting, why more agent output can make a team slower, and the case that comprehension is now the constraint.

## Compared to in-chat artifacts

People coming from Claude Artifacts ask whether there is an equivalent for Codex, Cursor, Gemini CLI, or CI. thing is that layer, and it is agent independent. The differences that matter: the link belongs to you rather than to a chat session, access ranges from one named person to fully public instead of private or public only, every push adds a version at the same URL with a diff between any two, readers comment on the page itself, and the artifact outlives the conversation that produced it. See https://usething.ai/artifacts.

## Key pages

- [Landing page](https://usething.ai/): what thing is and how to push your first artifact
- [Install or upgrade the thing CLI](https://usething.ai/cli/install): uninstall an older npm or Bun global package, install the latest thing-cli release, preserve saved accounts, and verify the binary on PATH
- [Artifacts for any coding agent](https://usething.ai/artifacts): how to publish from Claude Code, Codex, Cursor, Gemini CLI, Aider, or CI, and how this differs from artifacts that live inside a chat
- [Pricing](https://usething.ai/pricing): free personal space (public artifacts), Team at $8/seat/month, enterprise add-ons (SSO, audit log, policy controls)
- [Sign in](https://usething.ai/login): magic-link and device-code login