git-artifact

git-artifact

Artifacts on a separate Git branch

AI-assisted development creates many working materials—notes, plans, prompt logs, analysis reports, and more. Saving them on the same branch as source code risks maintenance issues, such as docs drifting from the implementation. git-artifact stores these materials as Artifacts on an orphan branch. Load only what you need, edit ordinary files, and save snapshots through Git history.

Get startedRead the docs

How it fits

git-artifact is a Git subcommand that stores Artifacts on a dedicated orphan branch.

  1. 01

    Create the artifacts branch

    The artifacts branch is a separate orphan branch for development materials. It is meant for temporary working products that do not belong permanently alongside source code. Keep them clearly separated on the artifacts branch.

  2. 02

    Ordinary directories and files

    An Artifact is simply a directory under .artifacts/ and the files inside it. Create, save, and load them without leaving your working branch—no checkout of the storage branch required.

  3. 03

    Keep the workspace clean

    After saving, remove Artifacts from the working tree and keep only what you still need locally. Your source workspace stays uncluttered while history lives on the artifacts branch.

  4. 04

    Find and restore later

    Search saved Artifacts and load them again when past materials become useful. Bring back only the ones you need, when you need them.

Example workflow

Local filesystem & commands

artifacts branch

  1. $git artifact init
    Create the orphan artifacts branch
    tree
    • artifacts/
    • README.md
  2. AI agent designs, implements, and reviews
    tree
    • app/
    • design.md
    • review.md
    AI agent generates files
  3. $git artifact new auth-redesign
    Create Artifact
    tree
    • app/
    • .artifacts/
    • auth-redesign/
    • (empty)
    tree
    • artifacts/
    • README.md
    • auth-redesign/
    • .artifact.json
  4. Move design.md and review.md into .artifacts/auth-redesign/
    tree
    • app/
    • .artifacts/
    • auth-redesign/
    • design.md
    • review.md
  5. $git artifact save -d "#42 Auth redesign"
    Save files in the Artifact
    tree
    • artifacts/
    • auth-redesign/
    • .artifact.json
    • design.md
    • review.md
  6. Remove the local Artifact directory
    tree
    • app/
    • .artifacts/
    • (empty)
  7. Later, when looking up past work
  8. $git artifact list
    Search past Artifacts
  9. $git artifact load auth-redesign
    Restore files into .artifacts/
    tree
    • app/
    • .artifacts/
    • auth-redesign/
    • design.md
    • review.md
    tree
    • artifacts/
    • auth-redesign/
    • .artifact.json
    • design.md
    • review.md

Install

Homebrew installs git-artifact in one step. Manual install is a single Python executable on your PATH.

brew install kohkimakimoto/tap/git-artifact
Installation details →