Dogcat - lightweight, file-based issue tracking and memory upgrade for AI agents (and humans!)

dogcat is a memory upgrade for AI agents. No more tracking issues and progress in Markdown files and burning your context window on them. With a simple command line utility (and some TUI niceties!) you can create, edit, manage and display issues.

• Installation
• Usage
  • Telling your agent to use dogcat
  • Command cheat sheet
• Screenshots
• Tips & tricks
• FAQ

Installation

Homebrew (macOS)

brew install oroddlokken/tap/dogcat

This installs dcat/dogcat and handles Python and dependencies automatically via uv.

pip / pipx / uv (all platforms)

# With uv (recommended for CLI tools)
uv tool install dogcat

# With pipx
pipx install dogcat

# With pip
pip install dogcat

From source

Install uv, then run ./dcat.py.

Usage

Run dcat init to initialize the program. Then you can run dcat prime to see the information an AI agent should use.
For a guide more suited for humans, run dcat guide.

If you don't want to store issues in git, use dcat init --no-git.

Sharing a dogcat database between multiple repos

Three setups, in order of scope:

1. Per-repo: dcat init creates a local .dogcats/. The default.

2. A few repos sharing one store: dcat init --use-existing-folder /path/to/.dogcats writes a .dogcatrc in the repo pointing at the shared directory. Each repo can set its own namespace with dcat config set --local namespace <name>.

3. Machine-wide default: Set a global default store that any new repo without its own .dogcats/ or .dogcatrc will fall back to:

   dcat config set --global default_storage ~/dev/issues/.dogcats
   

See docs/sharing-a-database.md for the namespace rules, the resolution order, and the config precedence chain.

Telling your agent to use dogcat

Run dcat example-md to print a starting block for your AGENTS.md/CLAUDE.md. It covers the session-start command, when to mark an issue in_progress, when to ask before creating an issue, and the approval gate before closing one:

dcat example-md >> AGENTS.md

This is only a starting point - it's up to you to decide how dogcat fits best in your workflow!

dcat prime mainly concerns itself on how to use the dcat CLI, not how your workflow should be.
dcat prime --opinionated is a more opinionated version of the guide for agents, with stricter guidelines.

You can run diff <(dcat prime) <(dcat prime --opinionated) to see the differences.

Command cheat sheet

Git Workflows: Merges and Field-Level Conflicts

Dogcat uses a custom merge driver (dcat git setup installs it) to automatically resolve JSONL conflicts. The driver implements a state-based merge algebra:

• Issues: LWW by status finality first, then updated_at. Status rank is draft < the active statuses (open, in_progress, in_review, blocked, deferred) < closed < tombstone; a more final status wins regardless of timestamp, so a branch that closes or deletes an issue is never silently reverted by a later edit that left it open elsewhere. Within one rank the later updated_at wins entirely — concurrent edits to different fields on the same issue may result in data loss. For example, if branch A edits the title and branch B edits the priority (with a later timestamp) and both leave the issue open, B's entire record wins and A's title edit is lost.

• Proposals: LWW by status finality (open < closed < tombstone), then by updated_at. Once a proposal is closed or tombstoned, it cannot be reverted.

• Dependencies & Links: Three-way merge with add/remove semantics. Deletes on one side win over silent no-ops on the other.

• Events: Append-only, deduplicated by identity.

Detecting field-level conflicts: After a merge, run dcat doctor --post-merge to detect concurrent edits. The output shows which fields were affected and their values on each branch. If you detect unexpected conflicts, coordinate edits across branches or use dcat update to manually restore lost changes.

See docs/merge-coverage.md for the claim-to-test matrix and the known limitations.

Screenshots

Table view (dcat list --table):

Tree view (dcat list --tree):

List view (dcat list):

Ready issues (dcat ready):

Issue details (dcat show $id):

TUI for creating new issues (dcat new):

TUI for editing issues, select the one you want to edit (dcat edit):

TUI for editing issues (dcat edit $id):

List issues in progress:

List issues in review:

Tips & tricks

Personally, I use these aliases:

alias dcl="dcat list --tree"
alias dct="dcat list --table"

alias dcn="dcat new"
alias dce="dcat edit"

FAQ

What's a dogcat?
¯_(ツ)_/¯ Some cats are dog-like, and some dogs are cat-like.

Why Python?
I wanted to use Textual, which is awesome for making TUIs with. It's also the language I am the most familiar with.

Development

dogcat is now in a state where it can be dogfooded. Included is the issues.jsonl file containing the current issues.