Artifacts

Overview#

An artifact is something an agent made for you to look at: a report, a plan, a code review, an architecture diagram, a dashboard of measured numbers, a clickable prototype, or a small form that asks for your decision. The agent writes it as an ordinary file in its worktree and publishes it with dev artifact publish. Agentastic keeps every version, opens it in an Artifacts tab beside the agent, and lets you comment on parts of it, share it, and send your comments back to the agent.

Artifacts work the same for agents on this Mac, on Remote SSH hosts, and on cloud nodes. On a remote host the agent's dev reads the files there and sends them to the app, so nothing on the host needs to be reachable from your Mac.

Every agent learns about artifacts from the built-in Artifacts plugin (Settings → Plugins), which delivers the artifacts skill to each run. Turn the plugin off there to stop it.

What an artifact can be#

HTML artifacts load Agentastic's design system, the same one Manager Agents use, so a page written with its classes follows your theme in light and dark mode. Pages run sandboxed: scripts may load from a few CDNs (jsDelivr, unpkg, cdnjs, Tailwind, Google Fonts), and a page can't fetch from or post to anything else. A folder may hold up to 500 files and 50 MB (20 MB when published from a remote host).

Viewing and versions#

Publishing opens the artifact in an Artifacts tab in the agent's worktree. If you're looking at another worktree, Agentastic notifies you instead of switching. View → Artifacts opens the gallery: every artifact with a thumbnail, filtered by All, Shared, and Archived, with search. Artifacts your teams shared with you appear there too.

Each publish of the same path adds a version. The version menu in the tab's toolbar shows them all with what changed, and you can open any of them. Publishing identical files adds nothing. The toolbar also reloads the page, exports a PNG, and renames, archives, or deletes the artifact.

Click a codeedit://artifact/… link anywhere in the app (an agent prints one after publishing) to open the artifact.

Comments and feedback#

Turn on comments in the toolbar, then click any part of the page to pin a comment to it, or comment on the page as a whole. Click Send New Comments to Agent to deliver unread comments to the agent that published the artifact: its chat, its terminal (when an agent is running there), or, for a Manager Agent, its mail. The agent edits the source, publishes a new version, replies in the thread, and resolves what it fixed.

Comments people leave on a shared copy come back the same way. Agentastic checks for them while the app runs and delivers them to the agent automatically, at most 60 times an hour for each artifact.

Readers' comments reach the agent marked as untrusted text: information about the page, never instructions that override you.

Interactive pages#

A page can collect answers and keep shared data through window.agentastic, the same API Agentastic Sites uses, so it behaves the same in the app and once shared:

• A <form data-agentastic> sends its fields to the agent as one response; agentastic.submit() and agentastic.ask() do the same from script.
• agentastic.data stores records in collections declared in an agentastic.json beside index.html (votes, a shared checklist, a triage board). Records survive republishing, conflicting writes fail cleanly, and open pages update live. Agents read and write the same records with dev artifact data, and edits people make on a shared copy are copied back to the app while it runs.

When people change the shared data of a page a Manager Agent owns, in the app or on a shared copy, the manager wakes up to look.

The artifacts skill ships three starting points agents can copy: a findings report, a decision page with a form, and a shared board people add to and vote on.

Sharing#

Click Share in the tab's toolbar. Sharing uploads a copy to Agentastic Sites, so you need to be signed in to your Agentastic account (Settings → Accounts).

Permissions: Can view opens the page and reads its data, Can comment and respond also sends comments and form responses, Can edit data also writes shared records.

By default the shared copy follows new versions. Turn off Update the shared copy when a new version is published to keep readers on the version they have, and use Update Now when you're ready. Stop Sharing deletes the shared copy; every link stops working and the artifact stays on your Mac.

Before uploading, Agentastic scans the files for credentials and warns you about anything that looks like one. An agent can ask to share with dev artifact share, but every share it asks for waits for you to approve it.

Teams#

Create a team in Settings → Accounts → Agentastic → Teams, then invite people by email. Owners and admins manage members and invitations; members see what the team shares in the Artifacts gallery and can open it signed in. Sharing with a team is a choice in the Share popover, alongside links for individual people.

Manager Agents#

A Manager Agent's pages (dev manager page) are artifacts it owns. The page header has Open as artifact and Share, so a manager's dashboard page can be versioned, commented on, and shared like any other. Comments and responses arrive in its mail. dev memory publish <page> publishes a wiki page, and an artifact one of its workers publishes appears in its feed as an output.

For agents#

Agents write artifacts under .agentastic/artifacts/ in the worktree; Agentastic adds that folder to the repository's .git/info/exclude so the sources stay out of your git status. The full command list is in the dev CLI reference.

Where it's stored#

Artifacts live in ~/Library/Application Support/Agentastic.dev/Artifacts/: a database of artifacts, versions, comments, and shared data, beside the files of every version, stored once by content. Deleting an artifact removes its versions and comments, and takes its shared copy down.