artikeep

Never lose what your AI agents make.

English · Русский

Agents publish pages, canvases and documents to places you don't control: a hosted artifact link, a chat you can lose access to, a temp folder that gets cleaned. artikeep keeps a copy of each one on your disk the moment it is made. Every change becomes a version, a gallery lets you browse and compare versions, and an MCP server lets any agent search what you already have.

• Automatic where it can be. Hooks in Claude Code and Codex capture without the model having to remember anything.
• Every change is a version. Compare any two side by side, with the changed text lines.
• Plain files, in git. The archive is a folder of HTML, Markdown and JSON. It opens without artikeep, and syncs between machines through a private git remote.
• Agents can look it up. Before rebuilding a report from scratch, an agent searches the archive through MCP.
• No dependencies. Python 3.9+ standard library. Nothing to pip install for capture.

Quick start

uv tool install git+https://github.com/aquahitt/artikeep   # or: pipx install git+https://github.com/aquahitt/artikeep
artikeep init ~/artikeep        # the archive folder (a git repo)
artikeep install                # hooks + MCP for the agents found
artikeep doctor                 # check

From now on, whatever Claude Code or Codex makes lands in ~/artikeep. Open the gallery with artikeep open, or artikeep serve --open for the local app.

No package manager? A clone works as is, with no install step: git clone https://github.com/aquahitt/artikeep ~/artikeep-src, then python3 ~/artikeep-src/bin/artikeep init ~/artikeep and so on.

Claude Code only? Use the plugin instead of install: /plugin marketplace add aquahitt/artikeep, then /plugin install artikeep@artikeep (details below).

What gets captured

Files git already tracks are skipped: they are safe where they are.

The gallery

index.html at the archive root: a static page that works from disk. Grid or list, filters (project, source, type, how the copy was made), groups, full-text search, a panel per item with its version history, side-by-side comparison of any two versions with the changed text lines. Light and dark, English and Russian, usable on a phone.

Every save that changes something is a version, with its time, label and size of change.	Compare any two versions: both pages live, plus what changed in the text.
Full-text search across every item and source, in any language.	Works on a phone too.

Keyboard: / search, G / L grid or list, ← → previous and next item, C compare first and current versions, Esc close, ? all shortcuts.

As a local app

artikeep serve runs the gallery on http://127.0.0.1:8765 (archived files on the next port; --port changes both). On top of the file version it searches the full text of every item and highlights the match, updates by itself when an agent saves something, lets you rename and describe an item, make an old version current (as a new version: nothing is overwritten), delete an item (it stays in the archive's git history), show it in Finder, and add files or chat exports by dropping them on the page. Pages that load their own files with fetch() or ES modules, which browsers refuse over file://, work here. In Chrome, "Install as app" gives it its own window and dock icon.

When capturing fails, artikeep also says so on the desktop (macOS notification, or notify-send on Linux), at most once an hour per kind of failure; "notify": false turns it off.

Install, in detail

install finds Claude Code (~/.claude), Codex (~/.codex) and Claude Desktop, adds its hooks next to yours (nothing else is touched; every edited file is backed up first), registers the MCP server with each agent's own mcp add (for Desktop, in claude_desktop_config.json; reopen Desktop after), and puts a short rules block into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md. If ~/.local/bin is on your PATH, it also links the artikeep command there. --agents claude-code,codex,claude-desktop limits it, --dry-run shows the changes, --uninstall removes them.

To sync across machines, give the archive a private remote: artikeep init ~/artikeep --remote git@github.com:you/my-artifacts.git. The background pass commits after each capture and pushes.

Claude Code deletes session transcripts after 30 days by default. install raises cleanupPeriodDays to ten years: transcripts are the last place a lost artifact can be recovered from.

Claude Code plugin

Instead of install, Claude Code users can add the plugin: /plugin marketplace add aquahitt/artikeep, then /plugin install artikeep@artikeep. It brings the same hooks and MCP server; Codex still needs artikeep install --agents codex. Use one or the other for Claude Code, not both (artikeep doctor flags it). The plugin keeps copies in ~/artikeep from the first artifact on; run artikeep init (with --remote if you want sync) to give that folder git history, and set "cleanupPeriodDays": 3650 in ~/.claude/settings.json yourself — a plugin cannot change it, and doctor reminds you.

Use

artikeep open                      # the gallery as a file: filters, versions, compare
artikeep serve --open              # the same gallery as a local app
artikeep search kitchen layout     # full-text, any language; --agent, --type, --project, --json
artikeep add ~/Downloads/report.pdf --title "Q3 report"
artikeep import chatgpt ~/Downloads/chatgpt-export.zip
artikeep scan codex --all          # archive deliverables from past Codex sessions
artikeep scan claude-code          # recover publishes missed in the last 30 days (--days N, --all)
artikeep rebuild                   # rebuild gallery and search index, commit and push

(artikeep here is the command uv tool or pipx installed, the one install linked into ~/.local/bin for a clone, or python3 <clone>/bin/artikeep.)

From any agent, through MCP:

By default an agent sees only items made in the repository it works in. See SECURITY.md for why, and how to widen it.

Settings

The archive is ~/artikeep unless artikeep init <path> chose another folder (remembered in ~/.config/artikeep/config.json) or $ARTIKEEP_HOME is set. Behaviour lives in artikeep.json at the archive root, so it travels with the archive:

How it works

Hooks only copy files and start a detached background pass, so an agent never waits on disk or network. The background pass renders viewers (Design canvases, Markdown documents, React components with the libraries claude.ai artifacts may import: React, Tailwind, recharts, lucide-react, lodash, d3, mathjs, PapaParse, SheetJS, three, Tone, Chart.js, and stand-ins for shadcn/ui), makes offline copies with CDN scripts and fonts vendored, updates the search index (SQLite FTS5) and the gallery, then commits and pushes. The on-disk layout is specified in FORMAT.md; any tool can write into it.

Limits, honestly

• macOS and Linux. Windows is not supported (file locking uses fcntl).
• Host formats are undocumented. The hook inputs of Claude Code's Artifact tool, Codex rollouts and the Claude Docs export can change with any release. artikeep logs every raw hook input to .hooklog/payloads.jsonl, and on session start checks recent transcripts for publishes it missed and archives them late. artikeep doctor shows when each source last saved something.
• Importers are checked against documented shapes and synthetic exports, not yet against many real ones. Anything they do not recognise is counted and reported, not guessed. Please open an issue with an anonymised sample if an import comes out wrong.
• Codex has no artifact tool. artikeep recognises deliverables by extension, by being outside git, and by being named in the final answer. A file a script wrote and the answer never mentioned is missed.
• Web chats are not captured live. ChatGPT and claude.ai come in through their data exports, which you request by hand.

Development

python3 -m unittest discover -s tests -t .     # the test suite, no dependencies
scripts/e2e-codex.sh                           # live check of the Codex adapter: one real Codex request
scripts/readme-media/make.sh                   # rebuild the README screenshots and GIF

The screenshots come from a synthetic archive (scripts/readme-media/seed.py), not from anyone's real one; rebuilding them needs Playwright with Chromium and Pillow.

License

MIT. Changes are listed in CHANGELOG.md.