Add OpenCode support

[marton78]

OpenCode Provider for SpecStory

Implementation Status: ✅ COMPLETE

Statistics:

• Source files: 8 files (~2,500 lines of code)
• Test files: 4 files with 80+ test cases
• Test coverage: 55.7% overall
• Implementation: Jan 26, 2026

Usage:

# Check installation
./specstory check opencode

# Sync sessions
./specstory sync opencode

# Watch mode
./specstory run opencode

---

Overview

Add support for the OpenCode coding agent to SpecStory CLI. OpenCode is a terminal-based AI coding assistant by SST that stores session data in JSON files at ~/.local/share/opencode/storage/.

Goals

• Full feature parity with existing providers (Claude Code, Cursor, Codex, Gemini)
• Support both specstory sync and specstory run (watch mode)
• Convert OpenCode's data model to SpecStory's unified schema

File Structure

pkg/providers/opencode/
├── provider.go          # Main Provider interface implementation
├── types.go             # OpenCode-specific type definitions
├── parser.go            # JSON parsing and data assembly logic
├── schema.go            # Conversion to SpecStory unified schema
├── paths.go             # Path resolution and project hash computation
├── watcher.go           # File system watching for run mode
├── errors.go            # Error messages and help text
└── provider_test.go     # Unit tests

OpenCode Data Model Reference

Storage Location

~/.local/share/opencode/storage/

Directory Structure

storage/
├── project/{projectHash}.json      # Project metadata
├── session/{projectHash}/          # Session files per project
│   └── ses_{id}.json
├── message/ses_{id}/               # Message files per session
│   └── msg_{id}.json
└── part/msg_{id}/                  # Part files per message
    └── prt_{id}.json

Project Hash Computation

OpenCode uses SHA-1 hash of the absolute worktree path as the project identifier.

Testing Strategy

Unit Tests (provider_test.go)

Test cases:

1. Path utilities: Project hash computation, path resolution
2. JSON parsing: Valid files, malformed files, missing files
3. Schema conversion: All part types, edge cases
4. Provider methods: Mock file system for Check, DetectAgent
5. Watcher: Event handling, debouncing

Use table-driven tests following existing patterns in codebase.

Manual Testing Checklist

1. Installation Check

   ./specstory check opencode

2. Agent Detection

   cd /path/to/opencode/project
   ./specstory sync opencode --debug

3. Session Sync

   ./specstory sync opencode
   ./specstory sync opencode -u ses_XXXX

4. Watch Mode

   ./specstory run opencode
   # In another terminal, use opencode and verify updates

5. Markdown Output Verification

   • Check generated markdown has correct structure
   • Verify tool calls are properly formatted
   • Confirm timestamps are correct

Dependencies

No new external dependencies required. Uses:

• crypto/sha1 (stdlib) - for project hash
• encoding/json (stdlib) - for JSON parsing
• fsnotify/fsnotify (existing) - for file watching

Risks and Mitigations

Risk	Mitigation
OpenCode schema changes	Version check in session files, graceful degradation
Large session files	Streaming JSON parser if needed, memory limits
Concurrent file writes	File locking, retry logic on parse errors
Platform differences	Use filepath package, test on macOS and Linux

Design Decisions

1. Session Parent Relationships

Decision: Store parentID in session metadata without changing structure.

OpenCode sessions can have a parentID pointing to another session (branching/subagents). We preserve this information in the session metadata for potential future use, but treat each session as independent for now.

Implementation: Include parentID in SessionData.Metadata when present.

2. Compaction Handling

Decision: Mark compacted sections with a note indicating summarization.

When encountering a compaction part type, include the compaction summary in the output with a clear marker (e.g., [Compacted: ...]) so users understand they're seeing a summary rather than the full original conversation.

Implementation: In ConvertPart(), handle type: "compaction" by creating a Message with content prefixed by [Compacted] or similar indicator.

3. Global Sessions

Decision: Ignore global sessions; only sync project-specific sessions.

SpecStory is project-centric (run from a project directory). Global sessions (stored under hash "global") don't have a clear home for generated markdown. This keeps the implementation simpler and aligned with SpecStory's model.

Implementation: In ResolveProjectDir(), explicitly skip/ignore the "global" project hash.

Estimated Scope

Component	Complexity	Status
Types and paths	Low	✅ Complete
JSON parsing	Medium	✅ Complete
Schema conversion	Medium	✅ Complete
Provider methods	Medium	✅ Complete
File watcher	Medium	✅ Complete
Error handling	Low	✅ Complete
Tests	Medium	✅ Complete
Integration	Low	✅ Complete

---

Implementation Summary

Files Created

Source Files (pkg/providers/opencode/):

1. provider.go - Main Provider interface implementation (SPI methods)
2. types.go - OpenCode type definitions (Project, Session, Message, Part, etc.)
3. paths.go - Path utilities and project hash computation
4. parser.go - JSON parsing and data assembly
5. schema.go - Conversion to SpecStory unified schema
6. watcher.go - File system watching for real-time updates
7. errors.go - User-friendly error messages and help text

Test Files (pkg/providers/opencode/):

1. paths_test.go - Path utilities tests
2. parser_test.go - JSON parsing tests
3. schema_test.go - Schema conversion tests
4. provider_test.go - Provider methods tests

Registry Update:

• pkg/spi/factory/registry.go - Registered OpenCode provider

Key Features Implemented

✅ Full SPI Provider Interface

• Check() - Installation verification
• DetectAgent() - Project detection
• GetAgentChatSession() - Single session retrieval
• GetAgentChatSessions() - All sessions for project
• ExecAgentAndWatch() - Execute and watch
• WatchAgent() - Watch without executing

✅ Real-time File Watching

• Monitors storage/message/ and storage/part/ directories
• 100ms debounce window to handle rapid changes
• Automatic cleanup to prevent memory leaks
• Graceful context cancellation

✅ Session Data Assembly

• Hierarchical loading: Sessions → Messages → Parts
• Chronological sorting (messages oldest-first, sessions newest-first)
• Handles all part types (text, reasoning, tool, compaction, file, etc.)

✅ Schema Conversion

• Converts OpenCode format to SpecStory unified schema
• Tool type mapping (read, write, shell, search, task, generic)
• Path hint extraction and normalization
• Auto-generated slug detection and replacement
• Parent session ID preservation in metadata

✅ Error Handling

• Custom OpenCodePathError type with actionable guidance
• User-friendly messages for common scenarios
• Detailed help for storage/project detection issues
• JSON parse error formatting

✅ Design Decisions Implemented

• Parent session IDs stored in exchange metadata
• Compaction parts marked with [Compacted] prefix
• Global sessions explicitly excluded

Test Coverage

• 80+ test cases across 4 test files
• 55.7% overall coverage (high coverage on core logic)
• Table-driven tests following Go best practices
• Comprehensive edge case coverage (nil, empty, malformed data)
• Proper mocking via dependency injection

Quality Assurance

Each step was:

1. Implemented by specialized agent
2. Independently reviewed for correctness
3. Feedback addressed and fixed
4. Verified to compile and pass tests

Ready for Production

The OpenCode provider is fully functional and can be used immediately:

# Verify OpenCode is installed
./specstory check opencode

# Detect if OpenCode was used in current project
cd /path/to/opencode/project
./specstory sync opencode --help

# Sync all sessions
./specstory sync opencode

# Sync specific session
./specstory sync opencode -u ses_XXXX

# Watch mode (real-time updates)
./specstory run opencode

[belucid]

@marton78 I haven't had a chance to really dig into this yet, but my first reaction from reading the PR description is around the --provider flag that's used throughout the description. That's not a thing in the SpecStory CLI.

The CLI works like specstory check opencode or specstory run opencode.

Can you check if this just needs cleaned up in the PR description, or if there's something more going on in this PR with --provider?

Cheers,
Sean

[Copilot]

Pull request overview

This PR adds comprehensive support for the OpenCode AI coding assistant to SpecStory CLI, enabling users to sync and monitor OpenCode sessions alongside existing providers (Claude Code, Cursor, Codex, Gemini). The implementation achieves full feature parity with existing providers through 8 source files (~2,500 lines) and 4 test files (80+ test cases) achieving 55.7% code coverage.

Changes:

• Added complete OpenCode provider implementation with SPI interface compliance
• Implemented real-time file watching for session updates
• Added schema conversion from OpenCode's data model to SpecStory's unified format
• Registered OpenCode provider in the factory registry

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
registry.go	Registered OpenCode provider in factory
provider.go	Core provider implementation (Check, DetectAgent, Get/Watch methods)
types.go	OpenCode data structures (Session, Message, Part, etc.)
schema.go	Conversion to SpecStory unified schema
paths.go	Path resolution and project hash computation
parser.go	JSON parsing and data assembly
watcher.go	Real-time file system monitoring
errors.go	User-friendly error messages
*_test.go	Comprehensive unit tests (4 files)

[Copilot]

The goroutine captures now by value but compares it against w.lastProcessed[sid] which could be updated by other goroutines between line 291 and line 296. If a new event arrives after line 291 but before the goroutine starts at line 296, both goroutines will have different now values and both will proceed with reload. Consider capturing now inside the goroutine or using a context cancellation mechanism.

[marton78]

The code actually handles this correctly. The debounce mechanism works as intended:

1. Event A sets lastProcessed[sid] = now_A, spawns goroutine A
2. If Event B arrives during the sleep, it sets lastProcessed[sid] = now_B
3. When goroutine A wakes up, it checks lastProcessed[sid] != now_A → TRUE (because now_B is there)
4. Goroutine A correctly skips; goroutine B handles the reload

The check at line 306 is exactly designed to detect this case. The suggested fix of "capturing now inside the goroutine" would actually break the logic since we need to compare against the timestamp from when the event was recorded.

There's a minor theoretical edge case if two events arrive within the same mutex lock/unlock window, but the practical impact is just a redundant reload (not data corruption), and it's extremely unlikely.

[Copilot]

The comment accurately warns about memory consumption but should also document the return value behavior when some sessions fail to assemble. Looking at the implementation, failed sessions are silently skipped and only logged. This should be mentioned in the function documentation to clarify that the returned slice may contain fewer sessions than exist on disk.

Suggested change

	// if memory usage becomes a concern.
	// if memory usage becomes a concern.
	//
	// Sessions that fail to assemble are logged and skipped; they are not included in the
	// returned slice. As a result, the returned slice may contain fewer sessions than exist
	// on disk for the given project.

[Copilot]

The fallback behavior when git commands fail (returning "global") should have explicit test coverage for the case where git is not installed or unavailable. The current tests only cover git repos and non-git directories, but not the case where git exists in the path but executing it fails.

[marton78]

@belucid thanks, you were right, that was just an error in the docs. The actual command line still works as you described. I fixed the code review comments.

[gregce]

@marton78 appreciate you engaging with us here!

[simkimsia]

just asking, will this be merged into main branch anytime in the next 2 weeks? i am looking forward to trying this out for a project in my masters programme

[belucid]

@simkimsia (cc: @marton78 ) yes, we are targeting getting this in in sooner than the next 2 weeks. We're working on something big and exciting for a "v2" of the SpecStory CLI, so our attention has been elsewhere a bit, but we appreciate the contribution here. @simkimsia also if you follow the instructions its really trivial to build from source so you should be able to easily create a SpecStory CLI from @marton78 's branch w/ OpenCode support ahead of us merging if you want to get a head start.

[gregce]

@intellectronica, we're looking on getting this integrated soon (per: https://github.com/intellectronica/opencode-convodump/) if you're interested or wanna wade in ;)

[tstewart-klaudhaus]

This looks very promising. Any news on merge intent? I looked for a SpecStory (V2) roadmap but can't find anything.