Worklog

 ██╗    ██╗ ██████╗ ██████╗ ██╗  ██╗██╗      ██████╗  ██████╗ 
 ██║    ██║██╔═══██╗██╔══██╗██║ ██╔╝██║     ██╔═══██╗██╔════╝ 
 ██║ █╗ ██║██║   ██║██████╔╝█████╔╝ ██║     ██║   ██║██║  ███╗
 ██║███╗██║██║   ██║██╔══██╗██╔═██╗ ██║     ██║   ██║██║   ██║
 ╚███╔███╔╝╚██████╔╝██║  ██║██║  ██╗███████╗╚██████╔╝╚██████╔╝
  ╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝ 

---

The problem

OpenCode sessions are stateless. Every context compaction or restart wipes the agent's working memory — todos vanish, blockers disappear, half-finished decisions evaporate. You're left re-explaining context that was perfectly documented ten minutes ago.

opencode-worklog fixes this. It persists todos, blockers, and decisions to disk, then automatically injects them back into context at compaction time. Work in progress survives session resets.

---

What it does

An OpenCode plugin (index.ts) that hooks into two lifecycle events:

1. On session start — bootstraps the .worklog/ directory structure in the project root (idempotent; safe to run repeatedly)
2. On session start — auto-installs 6 skills to .opencode/skills/ (skips any already present)
3. On context compaction — reads open todos and active blockers from disk, injects them into the compaction payload so they land in the next session's context

---

How it works

Session Start
     │
     ├──► Bootstrap .worklog/ directory structure
     │
     └──► Auto-install skills to .opencode/skills/
                │
                ▼
         Inject system prompt:
         "use /worklog, /worklog-todo, /worklog-decide…"
                │
                ▼
          [ work happens ]
                │
                ▼
     Context Compaction
                │
                └──► Read todos.json + blockers.md
                          │
                          ▼
                   Inject into compaction payload
                          │
                          ▼
                  Open work survives reset ✓

---

Install

Add to opencode.json in your project root:

{
  "plugins": ["opencode-worklog"]
}

That's it. On the next session start the plugin bootstraps .worklog/ and installs the skills automatically. No further configuration needed.

Local / development

{
  "plugins": ["file:../opencode-worklog"]
}

Peer dependency: @opencode-ai/plugin
Runtime: Bun (OpenCode's native runtime)

---

Skills reference

Six skills are installed to .opencode/skills/ automatically. Invoke them by slash command or by describing what you want to the agent.

Skill	Triggers	Purpose
worklog	/worklog · /worklog checkpoint · /worklog end	Session dashboard, mid-session checkpoint, close-out summary
worklog-todo	/worklog-todo add <title> · list · done <id> · drop <id>	Cross-session todo list backed by .worklog/todos.json
worklog-archive	/worklog-archive	Move done/dropped todos to todos.done.json
worklog-blocker	/worklog-blocker add <title> · resolve <id>	Record and resolve blockers and open questions
worklog-decide	/worklog-decide	Lightweight ADR appended to .worklog/decisions.md
worklog-docs	/worklog-docs · new adr · new report · new research	Full ADR, formal report, and research note management

---

.worklog/ layout

.worklog/
├── todos.json          ← active todos (JSON array)
├── todos.done.json     ← archived done/dropped todos
├── blockers.md         ← open questions and blockers
├── decisions.md        ← lightweight ADRs (ADR-001…)
├── sessions/           ← daily session files (YYYY-MM-DD.md)
├── adrs/               ← pre-decision technical research
├── reports/            ← formal investigation reports
└── research/           ← quick audit notes

docs/
└── adr-NNN-*.md        ← full formal ADRs (committed, permanent)

---

Gitignore recommendations

# Session files are noisy — safe to ignore
.worklog/sessions/

# Auto-installed skills — reinstalled each session start
.opencode/skills/worklog
.opencode/skills/worklog-todo
.opencode/skills/worklog-archive
.opencode/skills/worklog-blocker
.opencode/skills/worklog-decide
.opencode/skills/worklog-docs

Worth committing: .worklog/todos.json, .worklog/decisions.md, .worklog/blockers.md, and everything under docs/. These are your persistent project memory.

---

Contributing

PRs and issues welcome on GitHub. Keep it small — this plugin is intentionally minimal.

---

License

MIT