opencode-session-archiver

OpenCode plugin for archiving sessions to S3 and other pluggable storage backends.

Features

• Automatic archiving: Archives sessions when they become idle
• Manual archiving: Tools to manually archive, list, retrieve, and delete sessions
• Multiple backends: Define multiple storage backends and route archives based on project paths
• AWS profile support: Use credentials from ~/.aws/config profiles
• S3-compatible: Works with AWS S3, MinIO, Cloudflare R2, and other S3-compatible services

Architecture

This project is structured as a Bun workspace monorepo with three modular packages:

• @session-archiver/core - Agent-agnostic archiving logic and transformation engine

  • Pure data transformation layer
  • No external dependencies (except minimatch)
  • Reusable across different AI agent platforms

• @session-archiver/backend-s3 - S3 storage backend implementation

  • Pluggable storage interface
  • AWS SDK integration for S3, MinIO, Cloudflare R2, etc.
  • Depends on core for types and logic

• @session-archiver/opencode - OpenCode plugin adapter

  • Bridges OpenCode API with core archiver
  • Handles YAML configuration
  • Exports tools for manual archiving control
  • Depends on core and backend-s3

This modular design enables the core archiving logic to be reused with other AI agent platforms in the future (Claude Code, Codex, GitHub Copilot, etc.) by creating new adapter packages.

Installation

npm install opencode-session-archiver

Quick Start

1. Register the Plugin

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-session-archiver"]
}

2. Configure Storage

Create ~/.config/opencode/opencode-session-archiver.yaml:

backends:
  default:
    type: s3
    bucket: my-opencode-archives

That's it! The plugin will use AWS SDK default credentials and region.

Configuration Examples

Using AWS Profile

backends:
  default:
    type: s3
    bucket: my-opencode-archives
    profile: my-aws-profile  # Uses credentials and region from ~/.aws/config

Using Explicit Credentials

backends:
  default:
    type: s3
    bucket: my-opencode-archives
    region: us-east-1
    credentials:
      accessKeyId: AKIA...
      secretAccessKey: secret...

Using MinIO or S3-Compatible Services

backends:
  minio:
    type: s3
    bucket: opencode
    endpoint: http://localhost:9000
    forcePathStyle: true
    credentials:
      accessKeyId: minioadmin
      secretAccessKey: minioadmin

Available Tools

The plugin provides these tools in OpenCode:

• archive_session - Archive a specific session
• list_archives - List archived sessions with filtering
• retrieve_archive - Get details about an archived session
• delete_archive - Delete an archived session

Example Usage

archive_session sessionId="ses_abc123"
list_archives projectPath="/home/user/project" limit=10
retrieve_archive key="project/2024-01-15/ses_abc123.json"
delete_archive key="project/2024-01-15/ses_abc123.json"

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | bucket | string | Yes | S3 bucket name | | region | string | No | AWS region (defaults to SDK default) | | profile | string | No | AWS profile from ~/.aws/config | | credentials | object | No | Explicit AWS credentials | | prefix | string | No | Key prefix (default: stores at bucket root) | | endpoint | string | No | Custom S3 endpoint (for MinIO, R2, etc.) | | forcePathStyle | boolean | No | Use path-style URLs (required for MinIO) |

Advanced Configuration

For advanced features like:

• Multiple backends with routing rules
• AWS credential chain details
• S3-compatible service configurations
• Troubleshooting

See Advanced Configuration Guide

Storage Structure

Archives are stored as:

{project-path}/{date}/{session-id}.json

Example:

home_user_my-project/2024-01-15/ses_abc123.json

License

MIT