Summarize Work

Generate meaningful summaries of work completed in one or more sessions. Use for commit messages, PR descriptions, or documenting what happened across a time period.

OpenCode Server API

OpenCode exposes session data through its HTTP server. The server runs automatically when OpenCode is active.

Server URL

Discover the server URL with:

OPENCODE_URL=$(curl -sf http://localhost:4096/global/health | jq -r '.version' > /dev/null && echo "http://localhost:4096")

Default is http://localhost:4096. All endpoints below are relative to this base URL.

API Reference

See references/api.md for the full endpoint reference. The key endpoints for summarization:

Discover sessions across all projects:

curl -sf "$OPENCODE_URL/global/session?roots=true&limit=20" | jq '.[] | {id, title, project: .project.worktree}'

Query parameters: directory, roots, start, search, limit, archived.

Discover sessions for the current project:

curl -sf "$OPENCODE_URL/session?roots=true&limit=20" | jq '.[] | {id, title}'

Query parameters: directory, roots, start, search, limit.

Read a session's messages:

curl -sf "$OPENCODE_URL/session/<SESSION_ID>/message" | jq '[.[] | {role: .info.role, parts: [.parts[] | select(.type == "text") | .text[:1000]]}]'

Get a session's todos:

curl -sf "$OPENCODE_URL/session/<SESSION_ID>/todo" | jq '.[] | {content, status, priority}'

Fallback: SQLite

If the server is unreachable (e.g. OpenCode not running), first mention the API is unavailable. Then query the database directly at ~/.local/share/opencode/opencode.db when local access is acceptable. Tables: session, message, todo. Columns mirror the API response shapes. Use json_extract() for JSON fields.

Key conventions

• Timestamps are Unix epoch milliseconds. Use ?start=<ms> to filter by time.
• Root sessions exclude subagent sessions. Use ?roots=true for session discovery.
• Archived sessions are excluded by default. Use ?archived=true to include them.
• Global vs project-scoped: /global/session returns sessions across all projects with project metadata. /session returns sessions for the current project only.
• Empty sessions (1-2 messages) are noise. Filter in post-processing.

Determining Scope

Read the user's request to decide which endpoint to use. Default to the current project unless the request asks for more.

Request	Endpoint
"summarize this session"	Use conversation history already in context. Do not query the API.
"summarize my last session"	GET /session -- current project.
"summarize today's sessions"	GET /session?start=<today_ms> -- current project.
"summarize this morning"	GET /session?start=<today_ms> -- current project, filter by time.
"summarize all my work this morning"	GET /global/session?start=<today_ms> -- all projects.
"what did I do today across repos"	GET /global/session?start=<today_ms> -- all projects.
"summarize the bonk sessions"	GET /global/session?search=bonk -- all projects.
"summarize sessions in this repo"	GET /session -- current project.

If the user says the summary is incomplete or asks "what about X?", widen scope and re-query.

Workflow

- [ ] Gather context (session history + git state)
- [ ] Categorize changes
- [ ] Generate summary

Gather Context

Current session: Use the conversation history already in context.

Other sessions: Determine scope (above), then query the appropriate endpoint. For each substantive session (more than 2 messages), read messages via /session/:id/message. Supplement with todo data via /session/:id/todo if the text alone is unclear.

For repo-scoped requests, also check git state so summaries reflect actual changes rather than transcript intent:

git diff --stat
git diff --cached --stat
git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline origin/master..HEAD

Categorize Changes

Group into these categories (skip empty ones):

Category	Examples
Features	New endpoints, UI components, CLI commands
Fixes	Edge case handling, validation, error corrections
Refactors	Extractions, simplifications, performance
Challenges	Issues requiring 3+ attempts, debugging sessions
Review fixes	Changes made from code review feedback

Generate Summary

Write like a colleague giving a verbal recap. Mix prose and bullets naturally.

• Open with 1-2 sentences of context -- what happened and why
• Follow with bullets only where they add specifics. A list of 3 changes is useful; a list of 15 is not.
• If a session was focused on one thing, a paragraph with no bullets is fine.

Commit messages: One subject line, a sentence of context in the body, a few bullets if there were multiple meaningful changes. Most commits don't need bullets.

PR summaries: Open with the goal and outcome in prose. Bullet the major functional changes. Skip what the diff already makes obvious.

Cross-project summaries: Group by project or theme. A short prose paragraph per group reads better than a flat list of bullets across unrelated repos.

Calibration

Context	Shape
Single commit	1-3 sentences, maybe a couple bullets. No headers.
Multi-commit session	Paragraph of context + grouped bullets.
Feature branch	Prose intro + bullets per component. Include challenges if significant.
Cross-session / cross-project	Paragraph per project or theme, bullets within each.

Guidelines

• Focus on meaningful changes -- skip trivial edits, typo fixes, formatting
• Do not include secrets, tokens, private URLs, or sensitive environment values from transcripts or diffs.
• Capture the "why," not just the "what"
• Highlight multi-iteration challenges -- valuable context for future maintainers
• Be specific -- "fix auth token expiry handling" not "fix auth bug"
• Use imperative mood -- "add", "fix", "refactor"
• Match structure to content -- not every summary needs headers, tables, or bullets

Anti-patterns

• Listing every file changed (the diff shows that)
• Mixing trivial changes with meaningful ones
• Vague descriptions ("various improvements", "code cleanup")
• Omitting context for complex changes
• Querying the API for the current session when conversation history is already in context
• Summarizing intended work that is not supported by git state, file changes, or session evidence
• Forcing a rigid template when the content doesn't fit