Claude Code sessions forget everything the moment they end. The fix I use is not a clever context trick, it is plain markdown kept in the repo: a progress log, a decision log, and tickets, updated with every commit. Last week I wrote about that method in three separate posts. Enough people tried it that I packaged the whole thing into devlog, a Claude Code plugin. It is open source, MIT licensed, and you can install it right now.
How do I install devlog?
Two commands inside Claude Code:
/plugin marketplace add razamit/claude-devlog
/plugin install devlog@devlog-marketplaceThen, in any project, run /devlog:init. It scaffolds the three artifacts (adapting to files you already have instead of replacing them) and maintains a clearly marked block in the project's CLAUDE.md, so the discipline is available as standing instructions in every future session.
What does the plugin actually give you?
Four things, extracted from a real production project where they kept dozens of Claude Code sessions coherent across months:
- A progress log (
docs/PROGRESS.md): newest-first, one dated entry per completed unit of work, each with a status marker (DONE / PARTIAL / NOT STARTED), a scope note, and real proof: test output, before/after. Reading the head of the file tells you exactly where things stand. No archaeology. - A decision log (
docs/DECISIONS.md): append-only rows that record not just what was decided but why, and which alternatives were rejected. Changing a decision requires going back to its recorded reasons, not quietly reversing it. - Tickets (
docs/tickets/): one markdown file per issue, filed the moment a defect is discovered instead of leaving a TODO in the code. Each ticket captures symptom, evidence, why it matters, and the scope to decide. Tickets close by a status flip; they are never deleted. - Session wrap: the discipline that ties it together. Before any commit, an evidence summary enumerates every touched file and is verified against the actual diff, then all three logs are updated in the same commit as the work.
Each piece also has an explicit entry point when you want to drive it yourself: /devlog:session-wrap for the full pre-commit close-out, /devlog:tickets <issue> to investigate and file a ticket, /devlog:progress-log to write the session's progress entry, and /devlog:decision-log <decision> to record a decision with its reasons.
Why does this work?
Every part of the system exists because of a specific failure mode of long-running AI-assisted projects:
- Newest-first progress means "where are we?" is answered by reading the top of one file.
- Decisions carry their reasons, so future sessions either respect them or consciously supersede them. Silent reversals, the classic multi-session failure, stop happening.
- Tickets beat TODO comments because the evidence is attached while it is fresh, in a file the next session will actually find, not buried in code comments or chat scrollback.
- The session-wrap evidence summary closes the gap that lets unrelated working-tree changes ride into commits unnoticed: if the diff shows a path, the summary must mention it.
No hooks, no scripts, no dependencies
Devlog is plain markdown skills. There is nothing to configure and nothing that can break in your toolchain. If you do not want the plugin mechanism at all, you can copy the skills/* folders straight into a project's .claude/skills/ directory and get the same behavior.
Two honest limits. First, proactivity is model-directed, not hard enforcement: the CLAUDE.md block and the skill descriptions make Claude notice when a ticket or a log entry is due, but nothing guarantees it. Review generated log updates like any other project documentation. Second, file-based tickets complement a shared issue tracker rather than replace it; when work needs assignment and notifications across a team, keep the tracker.
The posts behind the plugin
Devlog is the packaged version of a method I documented piece by piece:
- progress.md: How to Know What Your AI Coding Agent Actually Built
- Why Your AI Coding Agent Needs a decisions.md File
- Markdown Tickets in the Repo: Issue Tracking for AI-Agent Projects
- And the payoff story: A CI Dead Man's Switch for Tech Debt, which grew directly out of one of those tickets.
This discipline is also how I keep client work sane: several agents, months of sessions, one coherent record. It is a core part of how I run AI consulting engagements.
If you run something similar or have an idea for improvement, I would love to hear it: reply on the original thread or open an issue on the repo.
FAQ
Do I need hooks or scripts to run devlog?
No. Devlog is plain markdown skills with zero dependencies. If you prefer not to install it as a plugin, you can copy the skills folders straight into your project's .claude/skills/ directory and get the same behavior.
Does devlog replace GitHub Issues or Jira?
No. Its file-based tickets complement a shared tracker rather than replace it. They shine for solo and agent-heavy work; when tasks need assignment, notifications, or cross-team reporting, keep the shared tracker.
Will every session be logged automatically?
Not guaranteed. Proactivity comes from a CLAUDE.md block and the skill descriptions, so it is model-directed rather than hard enforcement. Review generated log updates the way you review any other project documentation.