dkod

title: Session Storage description: How sessions are stored as git refs, the blob layout, commit linking, and the refs/dkod/ namespace.

Session Storage

dkod stores agent sessions as git objects inside your repository. No external database, no cloud storage — just git.

Ref layout

refs/dkod/sessions/<session-id>     blob (compressed JSON) — one per session
refs/dkod/commits/<commit-sha>      blob (JSON list of session IDs) — fan-out

A session ref points at one blob. A commit ref points at a list of session IDs, so multiple sessions can be linked to the same commit and the same session can be linked from multiple commit refs.

Repo config

.dkod/config.toml lives in the working tree (not a git ref) and is committed to the repo. Created by dkod init. See Configuration for the full reference.

Session blob format

Each session is a compressed JSON blob containing:

  • metadata — session ID, agent name, author, timestamp, duration
  • transcript — the full conversation (after redaction)
  • diff — the code changes produced by the session
  • files — list of files touched
  • commits — commit SHAs produced during the session

Why blobs, not commits

Sessions are git blobs under custom refs, not commits. This means:

  • They don't appear in git log
  • They don't bloat the working tree
  • They don't affect branch history
  • They push and fetch with standard git

Commit linking

Each refs/dkod/commits/<sha> ref stores a JSON list of session IDs. This is a many-to-many mapping: a session can produce multiple commits (each gets its own commit ref containing that session ID), and a commit can be linked from multiple sessions (the commit ref's list grows).

Push and fetch

dkod init adds a push refspec to .git/config so session refs are included in normal pushes:

# Push sessions with your branch (refspec configured by dkod init)
git push origin main

# Fetch sessions from remote
git fetch origin 'refs/dkod/*:refs/dkod/*'

No special protocol, no additional tooling.