opencode-session-todo 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandru Nedelcu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# OpenCode TODO
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A task list that stays with your session.**
+
+Session-local [todo.txt](https://github.com/todotxt/todo.txt) for OpenCode V2.
+Tools for the agent. A sidebar for you. Plain text you can edit.
+
+## Get started
+
+Add to `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-session-todo",
+      "options": {
+        "sidebarLimit": 5,
+      },
+    },
+  ],
+}
+```
+
+Reload OpenCode and reopen the TUI.
+
+- **Read and write** with `todoread` and `todowrite`, with conflict detection and change diffs.
+- **Keep tasks in view** in the sidebar; open `/todos` for the full list.
+- **Own the file** at `.agents/sessions/<session-id>/todo.txt`.
+
+[Usage & permissions](USAGE.md) · [Development & publishing](docs/development.md) · [MIT](LICENSE)

package/USAGE.md

@@ -0,0 +1,83 @@
+# Session TODOs
+
+## Setup
+
+Configure the plugin in `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [{ "package": "opencode-session-todo", "options": { "sidebarLimit": 5 } }]
+}
+```
+
+Then reload OpenCode:
+
+```sh
+opencode reload
+```
+
+Reopen the TUI after configuration changes. `sidebarLimit` is a positive integer, default **5**.
+
+## Tools
+
+Only root sessions expose these tools and receive the TODO lifecycle instructions. Subagents see neither tool.
+
+- `todoread({})` reads the current session's tasks and file path. Missing files return an empty list.
+- `todowrite({ previous, todos })` replaces the ordered list only when the stored list still equals `previous`; take `previous` from the latest `todoread` or `todowrite` result. A mismatch fails with an instruction to `todoread` and retry. The result reports a before/after diff. An empty `todos` array clears the list.
+
+```json
+{
+  "previous": [],
+  "todos": [
+    { "content": "Run the tests", "status": "in_progress", "priority": "high" }
+  ]
+}
+```
+
+Statuses: `pending`, `in_progress`, `completed`, `cancelled`. Priorities: `high`, `medium`, `low`.
+At most one task may be `in_progress`. Content must be one nonempty trimmed line,
+cannot begin with a priority/date, and cannot contain `status:` or `pri:` tokens.
+
+## TUI
+
+- Click **TODO** or its `▼` / `▶` arrow to expand or collapse the sidebar list.
+- Above `sidebarLimit` total tasks, the sidebar shows only unfinished tasks, capped at the limit,
+  with the active task first.
+- **Show all …**, `/todos`, or **Ctrl+P → Toggle session todos** opens the full scrollable panel.
+- Close with **Close ×**, **Esc** while focused, or the same command-palette action.
+- Each `todowrite` pops a toast with the before/after diff of the change.
+- Manual file edits appear within two seconds. Collapsing does not change the tasks.
+
+## Storage
+
+```text
+<project/worktree>/.agents/sessions/<session-id>/todo.txt
+```
+
+```text
+(A) Run the tests status:in_progress
+(B) Review the changes
+x Read the docs pri:C
+x Superseded approach pri:B status:cancelled
+```
+
+`A` / `B` / `C` map to high / medium / low; other priority letters are unsupported.
+Add `.agents/sessions/` to your project's ignore rules to keep these files out of version control.
+
+## Permissions
+
+Both tools use `todowrite`. Writes require agent/session rules resolving to `allow`; `ask` and
+`deny` are rejected. Approval prompts, saved approvals, and experimental policies are unsupported.
+Read-only agents should deny `todowrite`.
+
+## Commands
+
+From the repository root:
+
+```sh
+bun run check
+bun test
+bun run format       # dprint fmt
+bun run format:check # dprint check
+```

package/docs/development.md

@@ -0,0 +1,28 @@
+# Development
+
+Requires Bun >= 1.4.2.
+
+```sh
+bun ci
+make test
+```
+
+`make test` runs typecheck, tests, and formatting checks.
+`make upgrade-dependencies` updates pinned dependencies and the lockfile.
+
+## Package entry points
+
+The package ships TypeScript sources for OpenCode's Bun runtime; no build step is required.
+
+- `opencode-session-todo`: tools and RPC handlers.
+- `opencode-session-todo/tui`: sidebar and full panel.
+- `opencode-session-todo/rpc`: shared RPC definitions.
+
+## Publishing
+
+```sh
+npm login
+make publish
+```
+
+`make publish` runs the checks and a package dry-run before `npm publish --access public`.

package/index.ts

@@ -0,0 +1,211 @@
+import { Plugin } from "@opencode/plugin/effect"
+import type { Registration } from "@opencode/plugin/effect/registration"
+import type { RpcHandlers } from "@opencode/plugin/effect/rpc"
+import type { SessionContext } from "@opencode/plugin/effect/session"
+import { Agent } from "@opencode/schema/agent"
+import { Permission } from "@opencode/schema/permission"
+import { Session } from "@opencode/schema/session"
+import { Tool } from "@opencode/schema/tool"
+import { Effect, Schema, type Scope } from "effect"
+import { resolve } from "node:path"
+import { TodoRpc } from "./rpc.ts"
+import { diffTodos } from "./src/diff.ts"
+import { TodoInstructions } from "./src/instructions.ts"
+import { Snapshot, TodoError, Todos } from "./src/model.ts"
+import { makeTodoStore, SessionDirectory, type TodoStore, type WriteResult } from "./src/store.ts"
+
+const WriteInput = Schema.Struct({ previous: Todos, todos: Todos })
+const ReadInput = Schema.Struct({})
+
+const toolError = (error: TodoError): Tool.Error => new Tool.Error({ message: error.message })
+
+export interface TodoPluginContext {
+  readonly location: Pick<Plugin.Context["location"], "directory">
+  readonly tool: Pick<Plugin.Context["tool"], "transform">
+  readonly rpc: Pick<Plugin.Context["rpc"], "register">
+  readonly session: Pick<Plugin.Context["session"], "get"> & {
+    readonly hook: (
+      name: "context",
+      callback: (event: SessionContext) => Effect.Effect<void>,
+    ) => Effect.Effect<Registration, never, Scope.Scope>
+  }
+  readonly agent: Pick<Plugin.Context["agent"], "get">
+}
+
+const matches = (value: string, pattern: string): boolean => {
+  const normalized: string = value.replaceAll("\\", "/")
+  let expression: string = pattern
+    .replaceAll("\\", "/")
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".")
+  if (expression.endsWith(" .*")) expression = `${expression.slice(0, -3)}( .*)?`
+  return new RegExp(`^${expression}$`, process.platform === "win32" ? "si" : "s").test(normalized)
+}
+
+const allowed = (action: string, resource: string, rules: readonly Permission.Rule[]): boolean =>
+  rules.findLast(
+    (rule): boolean => matches(action, rule.action) && matches(resource, rule.resource),
+  )?.effect === "allow"
+
+export const register = (ctx: TodoPluginContext): Effect.Effect<void, never, Scope.Scope> =>
+  Effect.gen(function*(): Effect.fn.Return<void, unknown, Scope.Scope> {
+    const store: TodoStore = yield* makeTodoStore
+    yield* ctx.session.hook(
+      "context",
+      (event): Effect.Effect<void> =>
+        Effect.gen(function*(): Effect.fn.Return<void> {
+          if (!Object.hasOwn(event.tools, "todowrite") && !Object.hasOwn(event.tools, "todoread")) {
+            return
+          }
+          const root: boolean = yield* ctx.session.get({ sessionID: event.sessionID }).pipe(
+            Effect.match({
+              onSuccess: (session): boolean => session.parentID === undefined,
+              onFailure: (): boolean => false,
+            }),
+          )
+          if (!root) {
+            delete event.tools.todowrite
+            delete event.tools.todoread
+            return
+          }
+          if (!Object.hasOwn(event.tools, "todowrite") || !Object.hasOwn(event.tools, "todoread")) {
+            return
+          }
+          if (
+            event.system.some(
+              (part): boolean => part.type === "text" && part.text === TodoInstructions,
+            )
+          ) {
+            return
+          }
+          event.system.push({ type: "text", text: TodoInstructions })
+        }),
+    )
+    const getSession = Effect.fnUntraced(function*(
+      sessionID: Session.ID,
+    ): Effect.fn.Return<Session.Info, TodoError> {
+      const session: Session.Info = yield* ctx.session
+        .get({ sessionID })
+        .pipe(
+          Effect.mapError(
+            (error): TodoError =>
+              new TodoError({ message: `Cannot find session: ${String(error)}` }),
+          ),
+        )
+      if (resolve(session.location.directory) !== resolve(ctx.location.directory)) {
+        return yield* new TodoError({
+          message: "The todo session belongs to another project location",
+        })
+      }
+      return session
+    })
+
+    const directoryFor = (session: Session.Info): Effect.Effect<SessionDirectory, TodoError> =>
+      Schema.decodeUnknownEffect(SessionDirectory)({
+        directory: session.location.directory,
+        name: session.id,
+      }).pipe(Effect.mapError((error): TodoError => new TodoError({ message: error.message })))
+
+    const read = Effect.fnUntraced(function*(
+      sessionID: Session.ID,
+    ): Effect.fn.Return<Snapshot, TodoError> {
+      return yield* store.read(yield* directoryFor(yield* getSession(sessionID)))
+    })
+
+    const rpcHandlers: RpcHandlers<typeof TodoRpc> = {
+      read: (input, context): ReturnType<RpcHandlers<typeof TodoRpc>["read"]> =>
+        read(input.sessionID).pipe(
+          Effect.mapError(
+            (error): ReturnType<typeof context.error<"storage">> =>
+              context.error("storage", error.message, { message: error.message }),
+          ),
+        ),
+    }
+    const rpc = yield* ctx.rpc.register(TodoRpc, rpcHandlers)
+
+    const executeWrite: Tool.Info<typeof WriteInput, typeof Snapshot>["execute"] = Effect.fn(
+      "todo.write",
+    )(function*(input, context): Effect.fn.Return<Tool.Result<typeof Snapshot>, Tool.Error> {
+      const session: Session.Info = yield* getSession(context.sessionID).pipe(
+        Effect.mapError(toolError),
+      )
+      const agent: Agent.Info = (yield* ctx.agent
+        .get({ agentID: context.agent })
+        .pipe(
+          Effect.mapError(
+            (error): Tool.Error =>
+              new Tool.Error({ message: `Cannot resolve todo permissions: ${String(error)}` }),
+          ),
+        )).data
+      const rules: readonly Permission.Rule[] = [
+        ...agent.permissions,
+        ...(session.permissions ?? []),
+      ]
+      const resource: string = `.agents/sessions/${session.id}/todo.txt`
+      if (!allowed("todowrite", resource, rules)) {
+        return yield* new Tool.Error({
+          message:
+            "todowrite requires an allow permission. OpenCode V2 does not expose custom-tool approval prompts; deny and ask are rejected.",
+        })
+      }
+      const target: SessionDirectory = yield* directoryFor(session).pipe(
+        Effect.mapError(toolError),
+      )
+      const saved: WriteResult = yield* store.write(target, input.todos, input.previous).pipe(
+        Effect.mapError(toolError),
+      )
+      const diff: string = diffTodos(saved.previous, saved.todos)
+      yield* rpc.events
+        .emit("updated", { sessionID: context.sessionID, diff })
+        .pipe(
+          Effect.catch(
+            (error): Effect.Effect<void> =>
+              Effect.logWarning("Todo saved, but notification failed", error),
+          ),
+        )
+      return {
+        output: { path: saved.path, todos: saved.todos },
+        content: diff === "" ? "Todo list unchanged." : `Todo list updated:\n${diff}`,
+        metadata: { todos: saved.todos, path: saved.path },
+      }
+    })
+
+    const executeRead: Tool.Info<typeof ReadInput, typeof Snapshot>["execute"] = (
+      _input,
+      context,
+    ): Effect.Effect<Tool.Result<typeof Snapshot>, Tool.Error> => {
+      return read(context.sessionID).pipe(
+        Effect.map(
+          (snapshot): Tool.Result<typeof Snapshot> => ({
+            output: snapshot,
+            content: JSON.stringify(snapshot),
+          }),
+        ),
+        Effect.mapError(toolError),
+      )
+    }
+
+    yield* ctx.tool.transform((editor): void => {
+      editor.add({
+        name: "todowrite",
+        description:
+          `Replace this session's ordered todo list when it still equals the \`previous\` list you send; take \`previous\` from the latest todoread or todowrite result in this conversation. A mismatch fails the write: use todoread, then retry. Status: pending, in_progress, completed, cancelled; at most one in_progress. Priority: high, medium, low. Text is one trimmed line; status:/pri: are reserved. An empty todos array clears the list. Persists as project-local todo.txt and updates the TUI.\n\n${TodoInstructions}`,
+        input: WriteInput,
+        output: Snapshot,
+        options: { codemode: false, permission: "todowrite" },
+        execute: executeWrite,
+      })
+      editor.add({
+        name: "todoread",
+        description:
+          `Read this session's todo.txt list and storage path. Use it to obtain the \`previous\` list todowrite expects, or to retry after a failed write; missing files mean an empty list.\n\n${TodoInstructions}`,
+        input: ReadInput,
+        output: Snapshot,
+        options: { codemode: false, permission: "todowrite" },
+        execute: executeRead,
+      })
+    })
+  }).pipe(Effect.orDie)
+
+export default Plugin.define({ id: "session-todo", effect: register })

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "opencode-session-todo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Session-local todo.txt tools and TUI for OpenCode V2",
+  "homepage": "https://github.com/alexandru/opencode-todo#readme",
+  "bugs": {
+    "url": "https://github.com/alexandru/opencode-todo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexandru/opencode-todo.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui.tsx",
+    "./rpc": "./rpc.ts"
+  },
+  "files": [
+    "index.ts",
+    "tui.tsx",
+    "rpc.ts",
+    "src",
+    "USAGE.md",
+    "LICENSE",
+    "README.md",
+    "docs/development.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "bun test",
+    "format": "dprint fmt",
+    "format:check": "dprint check",
+    "prepublishOnly": "bun run check && bun run test && bun run format:check"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.27",
+    "@opencode/schema": "2.0.27",
+    "effect": "4.0.1"
+  },
+  "devDependencies": {
+    "@opencode/theme": "2.0.27",
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
+    "@types/bun": "1.3.11",
+    "dprint": "0.63.0",
+    "solid-js": "1.9.12",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.17",
+    "@opentui/solid": ">=0.5.17",
+    "solid-js": ">=1.9.0"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rpc.ts

@@ -0,0 +1,22 @@
+import { Rpc } from "@opencode/schema/rpc"
+import { Session } from "@opencode/schema/session"
+import { Schema } from "effect"
+import { Snapshot } from "./src/model.ts"
+
+export const TodoRpc = Rpc.define({
+  id: "session-todo",
+  methods: {
+    read: {
+      input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Session.ID })),
+      output: Schema.toStandardSchemaV1(Snapshot),
+      errors: { storage: Schema.toStandardSchemaV1(Schema.Struct({ message: Schema.String })) },
+    },
+  },
+  events: {
+    updated: {
+      schema: Schema.toStandardSchemaV1(
+        Schema.Struct({ sessionID: Session.ID, diff: Schema.String }),
+      ),
+    },
+  },
+})

package/src/diff.ts

@@ -0,0 +1,64 @@
+import type { Todo, Todos } from "./model.ts"
+
+const lineFor = (todo: Todo): string => `[${todo.status}|${todo.priority}] ${todo.content}`
+
+const MAX_CELLS: number = 1 << 20
+
+const replaced = (previous: readonly string[], next: readonly string[]): readonly string[] => [
+  ...previous.map((line: string): string => `- ${line}`),
+  ...next.map((line: string): string => `+ ${line}`),
+]
+
+const advance = (cursor: Iterator<string>): string | undefined => {
+  const step: IteratorResult<string> = cursor.next()
+  return step.done ? undefined : step.value
+}
+
+const diffLines = (previous: readonly string[], next: readonly string[]): readonly string[] => {
+  if (
+    previous.length === 0 || next.length === 0
+    || previous.length * next.length > MAX_CELLS
+  ) return replaced(previous, next)
+  const width: number = next.length + 1
+  const lengths: Int32Array = new Int32Array((previous.length + 1) * width)
+  const cell = (index: number): number => lengths[index] ?? 0
+  previous.reduceRight<void>((_, prevLine: string, i: number): void => {
+    next.reduceRight<void>((_, nextLine: string, j: number): void => {
+      lengths[i * width + j] = prevLine === nextLine
+        ? cell((i + 1) * width + j + 1) + 1
+        : Math.max(cell((i + 1) * width + j), cell(i * width + j + 1))
+    }, undefined)
+  }, undefined)
+  const lines: string[] = []
+  const previousCursor: Iterator<string> = previous[Symbol.iterator]()
+  const nextCursor: Iterator<string> = next[Symbol.iterator]()
+  let i: number = 0
+  let j: number = 0
+  let previousLine: string | undefined = advance(previousCursor)
+  let nextLine: string | undefined = advance(nextCursor)
+  while (previousLine !== undefined || nextLine !== undefined) {
+    if (previousLine === nextLine) {
+      i += 1
+      j += 1
+      previousLine = advance(previousCursor)
+      nextLine = advance(nextCursor)
+      continue
+    }
+    if (
+      previousLine !== undefined
+      && (nextLine === undefined || cell((i + 1) * width + j) >= cell(i * width + j + 1))
+    ) {
+      lines.push(`- ${previousLine}`)
+      i += 1
+      previousLine = advance(previousCursor)
+    } else if (nextLine !== undefined) {
+      lines.push(`+ ${nextLine}`)
+      j += 1
+      nextLine = advance(nextCursor)
+    }
+  }
+  return lines
+}
+
+export const diffTodos = (previous: Todos, next: Todos): string =>
+  diffLines(previous.map(lineFor), next.map(lineFor)).join("\n")

package/src/instructions.ts

@@ -0,0 +1,10 @@
+export const TodoInstructions: string = `TODO lifecycle
+
+- You MUST keep this session's TODO list synchronized with the requested work and its actual progress.
+- You MUST pass the list you expect to be stored as \`previous\` to every todowrite; when the write reports the stored list changed, you MUST use todoread and retry with the refreshed list. You MUST preserve existing tasks, order, statuses, and priorities unless actual progress or the user's instructions require a change.
+- You MUST mark a task in_progress before starting it. You MUST keep at most one task in_progress.
+- You MUST mark a task completed immediately after finishing its work and required verification.
+- You MUST NOT mark blocked, failed, skipped, unfinished, or unverified work completed. Unstarted or deferred work MUST remain pending; cancelled work MUST be represented as cancelled.
+- You MUST update the list after each meaningful status transition. You MUST NOT batch status updates until the end of the conversation or leave finished work in_progress.
+- Before your final response, you MUST reconcile the list with what was actually done and accurately retain unfinished work.
+- You SHOULD keep task descriptions concise and actionable.`

package/src/model.ts

@@ -0,0 +1,51 @@
+import { Schema } from "effect"
+
+export const Content = Schema.String.check(
+  Schema.isMinLength(1),
+  Schema.isTrimmed(),
+  Schema.isPattern(/^[^\r\n\x00]+$/),
+  Schema.makeFilter(
+    (value: string): boolean =>
+      !/^(?:\([A-Z]\) |\d{4}-\d{2}-\d{2}(?: |$))/.test(value)
+      && !/(?:^|\s)(?:status|pri):/.test(value),
+    {
+      message:
+        "Task text must not start with a priority/date or contain reserved status:/pri: tokens",
+    },
+  ),
+).pipe(Schema.brand("TodoContent"))
+
+export const Status = Schema.Literals(["pending", "in_progress", "completed", "cancelled"])
+export const Priority = Schema.Literals(["high", "medium", "low"])
+export const Todo = Schema.Struct({ content: Content, status: Status, priority: Priority })
+export type Todo = typeof Todo.Type
+
+export const Todos = Schema.Array(Todo)
+  .check(
+    Schema.makeFilter(
+      (todos: readonly Todo[]): boolean => {
+        let active: boolean = false
+        for (const todo of todos) {
+          if (todo.status !== "in_progress") continue
+          if (active) return false
+          active = true
+        }
+        return true
+      },
+      { message: "At most one todo may be in_progress" },
+    ),
+  )
+  .pipe(Schema.brand("TodoList"))
+export type Todos = typeof Todos.Type
+
+export const SessionName = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9][A-Za-z0-9_-]*$/),
+).pipe(Schema.brand("TodoSessionName"))
+export type SessionName = typeof SessionName.Type
+
+export const Snapshot = Schema.Struct({ path: Schema.String, todos: Todos })
+export type Snapshot = typeof Snapshot.Type
+
+export class TodoError extends Schema.TaggedError<TodoError>()("TodoError", {
+  message: Schema.String,
+}) {}

package/src/sidebar.ts

@@ -0,0 +1,44 @@
+import { Effect, Schema } from "effect"
+import type { Todo, Todos } from "./model.ts"
+
+export const SidebarLimit = Schema.Int.check(Schema.isGreaterThan(0)).pipe(
+  Schema.brand("TodoSidebarLimit"),
+)
+export type SidebarLimit = typeof SidebarLimit.Type
+
+export const SidebarOptions = Schema.Struct({
+  sidebarLimit: SidebarLimit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(5))),
+})
+
+export type TodoProjection =
+  | { readonly kind: "all"; readonly items: readonly Todo[]; readonly remaining: number }
+  | {
+    readonly kind: "limited"
+    readonly items: readonly Todo[]
+    readonly remaining: number
+    readonly total: number
+  }
+
+const incomplete = (todo: Todo): boolean =>
+  todo.status === "pending" || todo.status === "in_progress"
+
+export const projectTodos = (todos: Todos, mode: "full" | SidebarLimit): TodoProjection => {
+  if (mode === "full" || todos.length <= mode) {
+    return {
+      kind: "all",
+      items: todos,
+      remaining: todos.reduce((count, todo): number => count + Number(incomplete(todo)), 0),
+    }
+  }
+  const items: Todo[] = []
+  let remaining: number = 0
+  for (const todo of todos) {
+    if (!incomplete(todo)) continue
+    remaining += 1
+    if (todo.status === "in_progress") {
+      if (items.length === mode) items.pop()
+      items.unshift(todo)
+    } else if (items.length < mode) items.push(todo)
+  }
+  return { kind: "limited", items, remaining, total: todos.length }
+}

package/src/store.ts

@@ -0,0 +1,162 @@
+import { DateTime, Effect, Schema, Semaphore } from "effect"
+import { randomUUID } from "node:crypto"
+import type { Stats } from "node:fs"
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises"
+import { isAbsolute, join } from "node:path"
+import { SessionName, Snapshot, Todo, TodoError, Todos } from "./model.ts"
+import { type Document, parse, render } from "./todotxt.ts"
+
+export const SessionDirectory = Schema.Struct({
+  directory: Schema.String.check(
+    Schema.makeFilter((directory: string): boolean => isAbsolute(directory), {
+      message: "The todo project directory must be absolute",
+    }),
+  ).pipe(Schema.brand("TodoProjectDirectory")),
+  name: SessionName,
+})
+export type SessionDirectory = typeof SessionDirectory.Type
+
+export interface WriteResult extends Snapshot {
+  readonly previous: Todos
+}
+
+export interface TodoStore {
+  readonly read: (session: SessionDirectory) => Effect.Effect<Snapshot, TodoError>
+  readonly write: (
+    session: SessionDirectory,
+    todos: Todos,
+    expected?: Todos,
+  ) => Effect.Effect<WriteResult, TodoError>
+}
+
+const sameTodos = (left: readonly Todo[], right: readonly Todo[]): boolean => {
+  if (left.length !== right.length) return false
+  const cursor: Iterator<Todo> = right[Symbol.iterator]()
+  for (const todo of left) {
+    const step: IteratorResult<Todo> = cursor.next()
+    if (
+      step.done
+      || step.value.content !== todo.content
+      || step.value.status !== todo.status
+      || step.value.priority !== todo.priority
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+const io = <A>(message: string, run: () => Promise<A>): Effect.Effect<A, TodoError> =>
+  Effect.tryPromise({
+    try: run,
+    catch: (error): TodoError => new TodoError({ message: `${message}: ${String(error)}` }),
+  })
+
+const missing = (error: unknown): boolean =>
+  Schema.is(Schema.Struct({ code: Schema.Literal("ENOENT") }))(error)
+
+const pathFor = (session: SessionDirectory): string =>
+  join(session.directory, ".agents", "sessions", session.name, "todo.txt")
+
+const requireDirectory = async (directory: string): Promise<void> => {
+  const info: Stats = await lstat(directory)
+  if (!info.isDirectory()) {
+    throw new Error(`${directory} must be a real directory`)
+  }
+}
+
+const load = Effect.fnUntraced(function*(path: string): Effect.fn.Return<Document, TodoError> {
+  const text: string = yield* io(`Cannot read ${path}`, async (): Promise<string> => {
+    try {
+      const info: Stats = await lstat(path)
+      if (!info.isFile()) {
+        throw new Error("todo.txt must be a regular file")
+      }
+      return await readFile(path, "utf8")
+    } catch (error) {
+      if (missing(error)) return ""
+      throw error
+    }
+  })
+  return yield* parse(text)
+})
+
+const checkDirectory = Effect.fnUntraced(function*(
+  session: SessionDirectory,
+): Effect.fn.Return<void, TodoError> {
+  yield* io("Cannot access session directory", async (): Promise<void> => {
+    let directory: string = await realpath(session.directory)
+    for (const segment of [".agents", "sessions", session.name]) {
+      directory = join(directory, segment)
+      try {
+        await requireDirectory(directory)
+      } catch (error) {
+        if (missing(error)) return
+        throw error
+      }
+    }
+  })
+})
+
+const ensureDirectory = Effect.fnUntraced(function*(
+  session: SessionDirectory,
+): Effect.fn.Return<void, TodoError> {
+  yield* io("Cannot prepare session directory", async (): Promise<void> => {
+    let directory: string = await realpath(session.directory)
+    for (const segment of [".agents", "sessions", session.name]) {
+      directory = join(directory, segment)
+      await mkdir(directory, { recursive: true, mode: 0o700 })
+      await requireDirectory(directory)
+    }
+  })
+})
+
+export const makeTodoStore: Effect.Effect<TodoStore> = Effect.gen(
+  function*(): Effect.fn.Return<TodoStore> {
+    const lock: Semaphore.Semaphore = yield* Semaphore.make(1)
+    const read: TodoStore["read"] = Effect.fnUntraced(function*(
+      session: SessionDirectory,
+    ): Effect.fn.Return<Snapshot, TodoError> {
+      const path: string = pathFor(session)
+      yield* checkDirectory(session)
+      const document: Document = yield* load(path)
+      return { path, todos: document.todos }
+    })
+    const write: TodoStore["write"] = (
+      session,
+      todos,
+      expected,
+    ): Effect.Effect<WriteResult, TodoError> =>
+      lock.withPermit(
+        Effect.uninterruptible(
+          Effect.gen(function*(): Effect.fn.Return<WriteResult, TodoError> {
+            const path: string = pathFor(session)
+            yield* ensureDirectory(session)
+            const previous: Document = yield* load(path)
+            if (expected !== undefined && !sameTodos(expected, previous.todos)) {
+              return yield* new TodoError({
+                message:
+                  "The stored todo list does not match the `previous` list you sent. Use todoread, then retry todowrite with the refreshed `previous` list.",
+              })
+            }
+            const temporary: string = `${path}.${randomUUID()}.tmp`
+            const today: string = DateTime.formatIsoDateUtc(yield* DateTime.now)
+            yield* io(`Cannot write ${path}`, async (): Promise<void> => {
+              try {
+                await writeFile(temporary, render(todos, previous.records, today), {
+                  encoding: "utf8",
+                  mode: 0o600,
+                  flag: "wx",
+                })
+                await rename(temporary, path)
+              } finally {
+                await rm(temporary, { force: true })
+              }
+            })
+            return { path, todos, previous: previous.todos }
+          }),
+        ),
+      )
+    return { read, write }
+  },
+)

package/src/todotxt.ts

@@ -0,0 +1,150 @@
+import { Effect, Schema } from "effect"
+import { Todo, TodoError, Todos } from "./model.ts"
+
+export type Record =
+  & Pick<Todo, "content" | "priority">
+  & { readonly created: string | undefined }
+  & (
+    | { readonly status: "pending" | "in_progress" }
+    | {
+      readonly status: "completed" | "cancelled"
+      readonly completed: string | undefined
+    }
+  )
+
+const Letters = Schema.Literals(["A", "B", "C"])
+type Letter = typeof Letters.Type
+const priorities: Readonly<{ A: "high"; B: "medium"; C: "low" }> = {
+  A: "high",
+  B: "medium",
+  C: "low",
+}
+const letters: Readonly<{ high: "A"; medium: "B"; low: "C" }> = {
+  high: "A",
+  medium: "B",
+  low: "C",
+}
+const STATUS_PREFIX: string = "status:"
+const PRIORITY_PREFIX: string = "pri:"
+
+export interface Document {
+  readonly records: readonly Record[]
+  readonly todos: Todos
+}
+
+const decodeLetter = (value: unknown): Effect.Effect<Letter, TodoError> =>
+  Schema.decodeUnknownEffect(Letters)(value).pipe(
+    Effect.mapError(
+      (): TodoError => new TodoError({ message: "Supported todo.txt priorities are A, B, and C" }),
+    ),
+  )
+
+const parseLine = Effect.fnUntraced(function*(line: string): Effect.fn.Return<Record, TodoError> {
+  const closed: boolean = line.startsWith("x ")
+  let body: string = closed ? line.slice(2) : line
+  let letter: Letter | undefined
+  const priority: RegExpMatchArray | null = body.match(/^\(([A-Z])\) /)
+  if (priority) {
+    letter = yield* decodeLetter(priority[1])
+    body = body.slice(priority[0].length)
+  }
+  const datePrefix: RegExpMatchArray | null = body.match(
+    closed ? /^\d{4}-\d{2}-\d{2} (?:\d{4}-\d{2}-\d{2} )?/ : /^\d{4}-\d{2}-\d{2} /,
+  )
+  const dates: string = datePrefix?.[0] ?? ""
+  body = body.slice(dates.length)
+  let statusToken: string | undefined
+  const words: string[] = []
+  for (const word of body.split(" ")) {
+    if (word.startsWith(STATUS_PREFIX)) {
+      if (statusToken !== undefined) {
+        return yield* new TodoError({ message: "Duplicate status: token" })
+      }
+      statusToken = word.slice(STATUS_PREFIX.length)
+    } else if (word.startsWith(PRIORITY_PREFIX)) {
+      if (letter !== undefined) return yield* new TodoError({ message: "Duplicate priority" })
+      letter = yield* decodeLetter(word.slice(PRIORITY_PREFIX.length))
+    } else {
+      words.push(word)
+    }
+  }
+  const status: string = statusToken ?? (closed ? "completed" : "pending")
+  if (closed !== (status === "completed" || status === "cancelled")) {
+    return yield* new TodoError({ message: "The x marker and status: token disagree" })
+  }
+  const todo: Todo = yield* Schema.decodeUnknownEffect(Todo)({
+    content: words.join(" ").trim(),
+    status,
+    priority: priorities[letter ?? "B"],
+  }).pipe(Effect.mapError((error): TodoError => new TodoError({ message: error.message })))
+  const [first, second] = dates.trim().split(" ")
+  switch (todo.status) {
+    case "pending":
+    case "in_progress":
+      return { ...todo, status: todo.status, created: dates ? first : undefined }
+    case "completed":
+    case "cancelled":
+      return { ...todo, status: todo.status, completed: dates ? first : undefined, created: second }
+  }
+})
+
+export const parse = Effect.fnUntraced(function*(
+  text: string,
+): Effect.fn.Return<Document, TodoError> {
+  const records: Record[] = []
+  let lineNumber: number = 0
+  for (const line of text.replace(/^\uFEFF/, "").split(/\r?\n/)) {
+    lineNumber += 1
+    if (!line.trim()) continue
+    const record: Record = yield* parseLine(line).pipe(
+      Effect.mapError(
+        (error): TodoError =>
+          new TodoError({ message: `todo.txt line ${lineNumber}: ${error.message}` }),
+      ),
+    )
+    records.push(record)
+  }
+  const todos: Todos = yield* Schema.decodeUnknownEffect(Todos)(records).pipe(
+    Effect.mapError((error): TodoError => new TodoError({ message: error.message })),
+  )
+  return { records, todos }
+})
+
+const renderLine = (todo: Todo, old: Record | undefined, today: string): string => {
+  const created: string | undefined = old?.created
+  const openBody: string = created ? `${created} ${todo.content}` : todo.content
+  const letter: Letter = letters[todo.priority]
+  switch (todo.status) {
+    case "pending":
+      return `(${letter}) ${openBody}\n`
+    case "in_progress":
+      return `(${letter}) ${openBody} status:in_progress\n`
+    case "completed":
+    case "cancelled": {
+      const completed: string | undefined =
+        old?.status === "completed" || old?.status === "cancelled"
+          ? old.completed
+          : created
+          ? today
+          : undefined
+      const closedBody: string = completed ? `${completed} ${openBody}` : todo.content
+      const status: string = todo.status === "cancelled" ? " status:cancelled" : ""
+      return `x ${closedBody} pri:${letter}${status}\n`
+    }
+  }
+}
+
+export const render = (todos: Todos, previous: readonly Record[], today: string): string => {
+  const records: Map<Todo["content"], Record[]> = previous.reduceRight(
+    (grouped: Map<Todo["content"], Record[]>, record: Record): Map<Todo["content"], Record[]> => {
+      const existing: Record[] | undefined = grouped.get(record.content)
+      if (existing) existing.push(record)
+      else grouped.set(record.content, [record])
+      return grouped
+    },
+    new Map<Todo["content"], Record[]>(),
+  )
+  return todos.map(
+    (todo: Todo): string => renderLine(todo, records.get(todo.content)?.pop(), today),
+  ).join("")
+}

package/tui.tsx

@@ -0,0 +1,299 @@
+import { Plugin } from "@opencode/plugin/tui"
+import type { KeymapLayer, PanelInput } from "@opencode/plugin/tui/context"
+import { Session } from "@opencode/schema/session"
+import type { ResolvedTheme } from "@opencode/theme/tui"
+import type { MouseEvent } from "@opentui/core"
+import type { JSX } from "@opentui/solid"
+import { Effect, Result, Schema } from "effect"
+import {
+  type Accessor,
+  createEffect,
+  createMemo,
+  createSignal,
+  For,
+  onCleanup,
+  Show,
+} from "solid-js"
+import { TodoRpc } from "./rpc.ts"
+import { type Snapshot, type Todo } from "./src/model.ts"
+import { projectTodos, SidebarOptions, type TodoProjection } from "./src/sidebar.ts"
+
+type View =
+  | { readonly status: "loading" }
+  | { readonly status: "ready"; readonly snapshot: Snapshot }
+  | { readonly status: "error"; readonly message: string }
+
+interface Props {
+  readonly sessionID: string
+  readonly full?: boolean
+}
+
+const symbols: Readonly<Record<Todo["status"], string>> = {
+  pending: "[ ]",
+  in_progress: "[•]",
+  completed: "[✓]",
+  cancelled: "[–]",
+}
+
+const colorFor = (
+  status: Todo["status"],
+  theme: ResolvedTheme,
+): ResolvedTheme["text"]["base"] => {
+  switch (status) {
+    case "pending":
+      return theme.text.base
+    case "in_progress":
+      return theme.text.feedback.warning.base
+    case "completed":
+      return theme.text.muted
+    case "cancelled":
+      return theme.text.feedback.error.base
+  }
+}
+
+const Message = Schema.Struct({ message: Schema.String })
+const messageFor = (error: unknown): string =>
+  Schema.is(Message)(error) ? error.message : String(error)
+
+export default Plugin.define({
+  id: "session-todo",
+  setup(ctx): () => void {
+    const options = Schema.decodeUnknownResult(SidebarOptions)(ctx.options)
+    if (Result.isFailure(options)) {
+      ctx.ui.toast.show({
+        title: "Invalid TODO sidebar options",
+        message: options.failure.message,
+        variant: "error",
+      })
+      return (): void => {}
+    }
+    const api = ctx.client.rpc(TodoRpc)
+    const [sidebarView, updateSidebarView] = ctx.storage.store("sidebar", {
+      initial: { open: true },
+    })
+    const notify: () => void = api.events.on("updated", (event): void => {
+      if (event.data.diff === "") return
+      ctx.ui.toast.show({
+        title: "TODO updated",
+        message: event.data.diff,
+        variant: "info",
+        sessionID: event.data.sessionID,
+      })
+    })
+    const List = (props: Props): JSX.Element => {
+      const [view, setView] = createSignal<View>({ status: "loading" })
+      createEffect((): void => {
+        const sessionID: string = props.sessionID
+        setView({ status: "loading" })
+        const controller: AbortController = new AbortController()
+        let running: boolean = false
+        const refresh = (): void => {
+          if (running || controller.signal.aborted) return
+          running = true
+          const request: Effect.Effect<Snapshot, unknown> = Schema.decodeUnknownEffect(Session.ID)(
+            sessionID,
+          ).pipe(
+            Effect.flatMap(
+              (id): Effect.Effect<Snapshot, unknown> =>
+                Effect.tryPromise({
+                  try: (): Promise<Snapshot> =>
+                    api.read(
+                      { sessionID: id },
+                      {
+                        signal: controller.signal,
+                        location: ctx.data.session.get(sessionID)?.location
+                          ?? ctx.location
+                          ?? ctx.data.location.default(),
+                      },
+                    ),
+                  catch: (error): unknown => error,
+                }),
+            ),
+          )
+          void Effect.runPromise(
+            request.pipe(
+              Effect.match({
+                onSuccess: (snapshot): View => ({ status: "ready", snapshot }),
+                onFailure: (error): View => ({ status: "error", message: messageFor(error) }),
+              }),
+            ),
+          )
+            .then((next): void => {
+              if (!controller.signal.aborted) setView(next)
+            })
+            .catch((error: unknown): void => {
+              if (!controller.signal.aborted) {
+                setView({ status: "error", message: messageFor(error) })
+              }
+            })
+            .finally((): void => {
+              running = false
+            })
+        }
+        refresh()
+        const timer: ReturnType<typeof setInterval> = setInterval(refresh, 2000)
+        const unsubscribe: () => void = api.events.on("updated", (event): void => {
+          if (event.data.sessionID === sessionID) refresh()
+        })
+        onCleanup((): void => {
+          controller.abort()
+          clearInterval(timer)
+          unsubscribe()
+        })
+      })
+
+      const snapshot: Accessor<Snapshot | undefined> = (): Snapshot | undefined => {
+        const current: View = view()
+        return current.status === "ready" ? current.snapshot : undefined
+      }
+      const projection: Accessor<TodoProjection | undefined> = createMemo(
+        (): TodoProjection | undefined => {
+          const current: Snapshot | undefined = snapshot()
+          return current === undefined
+            ? undefined
+            : projectTodos(current.todos, props.full ? "full" : options.success.sidebarLimit)
+        },
+      )
+      const todos: Accessor<readonly Todo[]> = (): readonly Todo[] => projection()?.items ?? []
+      const active: Accessor<number> = (): number => projection()?.remaining ?? 0
+      const more: Accessor<number | undefined> = (): number | undefined => {
+        const current: TodoProjection | undefined = projection()
+        return current?.kind === "limited" ? current.total : undefined
+      }
+      const error: Accessor<string | undefined> = (): string | undefined => {
+        const current: View = view()
+        return current.status === "error" ? current.message : undefined
+      }
+      const visible: Accessor<boolean> = (): boolean =>
+        Boolean(props.full || snapshot()?.todos.length || error())
+      return (
+        <Show when={visible()}>
+          <box flexDirection="column" gap={0} paddingTop={1}>
+            <box
+              flexDirection="row"
+              gap={1}
+              onMouseDown={(event: MouseEvent): void => {
+                if (props.full) return
+                event.stopPropagation()
+                void updateSidebarView((draft): void => {
+                  draft.open = !draft.open
+                }).catch((error: unknown): void => {
+                  ctx.ui.toast.show({
+                    title: "Todo sidebar",
+                    message: `Cannot save expanded state: ${messageFor(error)}`,
+                    variant: "error",
+                  })
+                })
+              }}
+            >
+              <Show when={!props.full}>
+                <text fg={ctx.theme.text.base}>{sidebarView.open ? "▼" : "▶"}</text>
+              </Show>
+              <text fg={ctx.theme.text.base}>
+                <b>TODO</b>
+                <span style={{ fg: ctx.theme.text.muted }}>{" "}({active()} remaining)</span>
+              </text>
+            </box>
+            <Show when={props.full || sidebarView.open}>
+              <Show when={props.full}>
+                <text fg={ctx.theme.text.muted}>{snapshot()?.path ?? "Loading todo.txt…"}</text>
+              </Show>
+              <Show when={error()}>
+                <text fg={ctx.theme.text.feedback.error.base}>Cannot read todos: {error()}</text>
+              </Show>
+              <Show when={props.full && view().status === "ready" && todos().length === 0}>
+                <text fg={ctx.theme.text.muted}>No todos for this session.</text>
+              </Show>
+              <For each={todos()}>
+                {(todo): JSX.Element => (
+                  <text fg={colorFor(todo.status, ctx.theme)}>
+                    {symbols[todo.status]} {todo.content} · {todo.priority}
+                  </text>
+                )}
+              </For>
+              <Show when={more()}>
+                <text
+                  fg={ctx.theme.text.feedback.info.base}
+                  onMouseDown={(event: MouseEvent): void => {
+                    event.stopPropagation()
+                    ctx.ui.panel.open("session-todo.list")
+                  }}
+                >
+                  Show all {more()} todos →
+                </text>
+              </Show>
+            </Show>
+          </box>
+        </Show>
+      )
+    }
+
+    const sidebar: () => void = ctx.ui.slot({
+      append: "sidebar.content",
+      render: (props): JSX.Element => <List sessionID={props.sessionID} />,
+    })
+    const Panel = (props: PanelInput): JSX.Element => {
+      ctx.keymap.layer(
+        (): KeymapLayer => ({
+          mode: "global",
+          enabled: props.focused,
+          commands: [
+            {
+              bind: "escape",
+              title: "Close session todos",
+              run: props.close,
+            },
+          ],
+        }),
+      )
+      return (
+        <box flexDirection="column" flexGrow={1} padding={1}>
+          <text
+            fg={ctx.theme.text.base}
+            onMouseDown={(event: MouseEvent): void => {
+              event.stopPropagation()
+              props.close()
+            }}
+          >
+            Close × · Esc when focused · Ctrl+P to toggle
+          </text>
+          <scrollbox flexGrow={1}>
+            <List sessionID={props.sessionID} full />
+          </scrollbox>
+        </box>
+      )
+    }
+    const panel: () => void = ctx.ui.slot({
+      append: "session.panel",
+      render: (props): JSX.Element => (
+        <Show when={props.name === "session-todo.list"}>
+          <Panel {...props} />
+        </Show>
+      ),
+    })
+    ctx.keymap.layer(
+      (): KeymapLayer => ({
+        mode: "global",
+        commands: [
+          {
+            id: "session-todo.list",
+            title: "Toggle session todos",
+            group: "Session",
+            palette: true,
+            slash: { name: "todos" },
+            enabled: ctx.ui.router.current().type === "session",
+            run: (): void => {
+              if (ctx.ui.panel.current()?.name === "session-todo.list") ctx.ui.panel.close()
+              else ctx.ui.panel.open("session-todo.list")
+            },
+          },
+        ],
+      }),
+    )
+    return (): void => {
+      sidebar()
+      panel()
+      notify()
+    }
+  },
+})