### Development Setup and Build Commands

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

This section provides the necessary commands for setting up the development environment, including cloning the repository, installing dependencies, building the project, and running type checks. It ensures the project is ready for development.

```bash
# Clone your fork
git clone git@github.com:YOUR-USERNAME/opencode-sessions.git
cd opencode-sessions

# Install dependencies
npm install

# Build the project
npm run build

# Run type checking
npm run typecheck
```

--------------------------------

### Real-World Workflow Examples with Session Tool (TypeScript)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Illustrates practical, end-to-end workflows using the 'session' tool. Examples cover a code review cycle, a research-plan-implement pipeline, managing long conversations with compression, and parallel architectural exploration using 'fork' mode.

```typescript
// Example 1: Code Review Workflow
// Build implements → Review analyzes → Build fixes → Review approves

// Step 1: Build implements feature
// [Build agent writes authentication code]

// Step 2: Build hands to review
session({
  mode: "message",
  agent: "review",
  text: "Review this authentication implementation for security issues and best practices"
})

// Step 3: Review agent responds with findings in same conversation
// [Review: "Found 3 issues: 1) No rate limiting on login endpoint..."]

// Step 4: Build fixes issues based on feedback
// [Build agent makes fixes]

// Step 5: Build hands back to review
session({
  mode: "message",
  agent: "review",
  text: "Please verify the security fixes are correct"
})

// Example 2: Research → Plan → Implement Pipeline with Clean Phases

// Phase 1: Research (fresh start)
session({
  mode: "new",
  agent: "researcher",
  text: "Research best practices for real-time notifications in web apps (WebSockets, SSE, polling)"
})
// [Researcher investigates and documents findings]

// Phase 2: Planning (clean slate, no research clutter)
session({
  mode: "new",
  agent: "plan",
  text: "Design a real-time notification system for 10k concurrent users with message persistence"
})
// [Plan agent designs architecture]

// Phase 3: Implementation (clean slate, focused on building)
session({
  mode: "new",
  agent: "build",
  text: "Implement the notification system using WebSockets with Redis pub/sub"
})
// [Build agent implements the design]

// Example 3: Long Conversation with Compression and Handoff

// After 50+ messages of implementation back-and-forth...
// Token count approaching limit, need to compress

session({
  mode: "compact",
  agent: "plan",
  text: "Review the overall architecture and suggest improvements"
})
// [History compresses, plan agent sees summary + recent context]
// [Plan reviews and suggests architectural improvements]

// Continue implementing with compressed context
session({
  mode: "compact",
  text: "Implement the caching layer we discussed"
})

// Example 4: Parallel Architectural Exploration

// Exploring three different database architectures before committing

session({
  mode: "fork",
  agent: "plan",
  text: "Design the data layer using PostgreSQL with normalized tables and foreign keys"
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design the data layer using MongoDB with denormalized documents"
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design the data layer using DynamoDB with single-table design"
})

// Switch between sessions in UI to compare:
// - Read each design document
// - Ask questions about trade-offs
// - Iterate on each approach
// - Make final decision based on requirements

// Choose the best approach and continue in that session
// Other sessions can be archived or deleted
```

--------------------------------

### Install Latest Version of Package

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

Command to install the latest published version of the 'opencode-sessions' package from npm. This is used to verify the release on the npm registry.

```bash
npm install opencode-sessions@latest
```

--------------------------------

### Research -> Plan -> Implement Pipeline Example (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Illustrates a sequential workflow using the 'new' mode for clean handoffs between research, planning, and implementation agents.

```typescript
// Phase 1: Research (clean start)
session({
  mode: "new",
  agent: "researcher",
  text: "Research best practices for API rate limiting in 2025",
})

// Phase 2: Planning (clean handoff)
session({
  mode: "new",
  agent: "plan",
  text: "Design a rate limiting system based on the research",
})

// Phase 3: Implementation (clean handoff)
session({
  mode: "new",
  agent: "build",
  text: "Implement the rate limiting system per the plan",
})
```

--------------------------------

### Conventional Commits Specification Examples

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Examples demonstrating the format and usage of Conventional Commits for various types of changes, including features, bug fixes, and breaking changes. Adhering to this format facilitates automated versioning and changelog generation.

```bash
# Simple feature
feat: add support for nested skill directories

# Bug fix with scope
fix(parser): handle empty frontmatter correctly

# Breaking change
feat!: require Node.js 20+

BREAKING CHANGE: Drops support for Node.js 18 and below
```

--------------------------------

### Clean Phase Transitions with New Session (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

This example shows how to achieve clean phase transitions by starting a new session with `mode: "new"`. This ensures that each work phase begins with a fresh context, free from the baggage of previous work. It's useful for sequential workflows like Research → Planning → Implementation → Validation, preventing context bleed and allowing for unrelated tasks.

```typescript
session({
  mode: "new",
  agent: "researcher",
  text: "Research API design best practices for 2025",
})
// Fresh session, clean context
// Previous implementation details don't influence research
```

--------------------------------

### Check Installed Plugin Version (Bash)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Command to display the currently installed version of the opencode-sessions plugin.

```bash
cat ~/.cache/opencode/node_modules/opencode-sessions/package.json | grep version
```

--------------------------------

### Messaging Agent Handoff Example (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Demonstrates using the 'message' mode for agent handoffs, such as a build agent handing off to a review agent for feedback.

```typescript
// Build agent implements, then hands to review
session({
  mode: "message",
  agent: "review",
  text: "Review this authentication implementation for security issues",
})

// Review agent provides feedback, build can address
// Or research → plan handoff
session({
  mode: "message",
  agent: "plan",
  text: "Design our rate limiting system based on this research",
})
```

--------------------------------

### Conventional Commits Examples - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Examples of crafting commit messages using the Conventional Commits specification. This standardizes commit history and helps with automated changelog generation.

```bash
git commit -m "feat: add new skill discovery feature"
git commit -m "fix: correct path resolution bug"
git commit -m "docs: update installation instructions"
```

--------------------------------

### OpenCode Plugin Configuration (JSON)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Configuration snippet for adding the 'opencode-sessions' plugin to your OpenCode setup, either globally or for a specific version.

```json
{
  "plugin": ["opencode-sessions"]
}
```

```json
{
  "plugin": ["opencode-sessions@x.y.z"]
}
```

--------------------------------

### Breaking Change Commit Example - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

An example demonstrating how to signify a breaking change within a commit message using Conventional Commits. Prefixed with '!' after the type and scope.

```bash
git commit -m "feat!: change skill loading API

BREAKING CHANGE: Skills now require a version field in frontmatter"
```

--------------------------------

### Long Conversation Compression Example (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Shows how to use the 'compact' mode after a lengthy discussion to compress history and hand off to another agent for review, preserving essential context.

```typescript
// After extensive back-and-forth implementation discussion...

// Compress and hand off to plan for architectural review
session({
  mode: "compact",
  agent: "plan",
  text: "Review the overall architecture we've built so far",
})

// Plan sees:
// [Compacted history of implementation]
// User: [Compacting session - plan agent will respond after completion]
// User: Review the overall architecture we've built so far
```

--------------------------------

### Configure OpenCode Sessions Plugin in opencode.json

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

To enable the session management capabilities of the OpenCode Sessions plugin, it must be added to the 'plugin' array in the opencode.json configuration file. The plugin supports installation by name or by a specific version (e.g., 'opencode-sessions@1.0.0'). It can be enabled globally or on a per-agent basis using the 'tool.session' or 'agent.<agent_name>.tool.session' settings, with per-agent configuration recommended to prevent unintended use by sub-agents.

```json
// ~/.config/opencode/opencode.json or .opencode/opencode.json
{
  "plugin": ["opencode-sessions"]
}

// Pin to specific version
{
  "plugin": ["opencode-sessions@1.0.0"]
}

// Enable per-agent (recommended to prevent sub-agents from using it)
{
  "agent": {
    "build": {
      "tool": {
        "session": true  // Enable for build agent
      }
    },
    "plan": {
      "tool": {
        "session": true  // Enable for plan agent
      }
    },
    "code-reviewer": {
      "tool": {
        "session": false  // Disable for sub-agents
      }
    }
  },
  "tool": {
    "session": false  // Disable globally, enable per-agent only
  }
}

```

--------------------------------

### Clean Phase Transitions with New Mode

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Facilitates clean phase transitions in workflows by initiating a new session with a specified agent, ensuring a fresh context without prior conversation baggage. The `session` tool with `mode: 'new'` is ideal for starting distinct stages of a workflow, such as research, planning, and implementation, ensuring each phase begins with a clean slate. The output indicates the creation of a new session and its agent.

```typescript
// Phase 1: Research with clean context
session({
  mode: "new",
  agent: "researcher",
  text: "Research best practices for API rate limiting in 2025"
})

// Phase 2: Planning in fresh session (research details don't clutter)
session({
  mode: "new",
  agent: "plan",
  text: "Design a rate limiting system for REST API with 1000 req/min limit"
})

// Phase 3: Implementation in fresh session
session({
  mode: "new",
  agent: "build",
  text: "Implement the rate limiting middleware using Redis for distributed systems"
})

// Returns: "New session created with build agent (ID: abc-123)"
```

--------------------------------

### Release Process Steps (Quick)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

These commands outline the quick steps for initiating a release by creating a promotion pull request from the 'dev' branch to the 'main' branch. Subsequent steps involving automated PRs from Release Please are managed automatically after merging.

```bash
# Create promotion PR
gh pr create \
  --base main \
  --head dev \
  --title "chore: release v0.x.x - description"
```

--------------------------------

### Build Project

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

Command to initiate the build process for the project using npm. This is a crucial step in the release checklist to ensure the project compiles correctly.

```bash
npm run build
```

--------------------------------

### Verify Build and Types

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

These commands are used to verify the project's build process and TypeScript types. They are typically run after developing on the 'dev' branch and before promoting changes to 'main'.

```bash
npm run build
npm run typecheck
```

--------------------------------

### Sequence Diagram for Session Compression

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Visualizes the process of session compression and agent handoff, showing the interaction between the build agent, session manager, and plan agent.

```mermaid
sequenceDiagram
    participant Build as Build Agent
    participant Session as Session
    participant Plan as Plan Agent

    Note over Build: Long conversation...
    Build->>Session: Tool: session(mode: "compact", agent: "plan")
    Session->>Session: Inject: "[Compacting - plan will respond]"
    Session->>Session: Compress history
    Session->>Session: Wait for idle
    Session->>Plan: "Continue architecture review"
    Plan->>Session: Reviews compacted context and responds
```

--------------------------------

### Promote dev Branch to main for Release using GitHub CLI

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

This command creates a pull request from the 'dev' branch to the 'main' branch, signaling readiness for a release. It includes a structured title and body for clarity, and is a crucial step before Release Please automation takes over.

```bash
gh pr create \
  --base main \
  --head dev \
  --title "chore: release v0.x.x - brief description" \
  --body "Promotes integrated changes from dev to main:

- feat: feature description (#PR)
- fix: bug fix description (#PR)
- docs: documentation updates

[Include BREAKING CHANGE note if applicable]

After merge, Release Please will handle versioning and publishing."
```

--------------------------------

### Testing Changes with Build and Typecheck

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Commands for building the project and performing type checking, crucial steps after making code changes to ensure code quality and correctness. It also mentions testing within a local OpenCode project.

```bash
# Build the project
npm run build

# Verify types
npm run typecheck
```

--------------------------------

### Session Tool - New Mode (Clean Phase Transitions)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Creates a fresh session with a new agent, providing a clean slate without context baggage from previous work. Ideal for phase transitions in workflows where previous implementation details should not influence the next phase.

```APIDOC
## Session Tool - New Mode (Clean Phase Transitions)

### Description
Creates a fresh session with a new agent, providing a clean slate without context baggage from previous work. Ideal for phase transitions in workflows where previous implementation details should not influence the next phase.

### Method
POST

### Endpoint
/session

### Parameters
#### Request Body
- **mode** (string) - Required - The mode of operation, must be 'new'.
- **agent** (string) - Required - The agent to start the new session with.
- **text** (string) - Required - The initial prompt or task for the new session.

### Request Example
```json
{
  "mode": "new",
  "agent": "researcher",
  "text": "Research best practices for API rate limiting in 2025"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the new session creation.

#### Response Example
```json
{
  "message": "New session created with researcher agent (ID: def-456)"
}
```
```

--------------------------------

### Session Tool Modes and Parameters (TypeScript)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Defines the TypeScript interface for session tool arguments and demonstrates usage for 'message', 'new', 'compact', and 'fork' modes. Includes error handling for non-existent agents and expected return values or side effects for each mode.

```typescript
interface SessionArgs {
  text: string      // Required: Message to send
  mode: "message" | "new" | "compact" | "fork"  // Required: Operation mode
  agent?: string    // Optional: Target agent name (defaults to current agent)
}

// Message mode - returns immediately, message sent after agent finishes
session({
  mode: "message",
  agent: "review",
  text: "Review the security of this implementation"
})
// Returns: "Message sent to review agent. They will respond in this conversation."

// New mode - creates session and sends first message
session({
  mode: "new",
  agent: "researcher",
  text: "Research GraphQL vs REST for our API"
})
// Returns: "New session created with researcher agent (ID: session-abc-123)"

// Compact mode - returns immediately, compaction happens after agent finishes
session({
  mode: "compact",
  agent: "plan",
  text: "Continue reviewing the architecture"
})
// Returns: "I'll compact the session after completing this response, then hand off to plan."

// Fork mode - creates child session with copied history
session({
  mode: "fork",
  agent: "build",
  text: "Implement using approach A"
})
// Returns: "Forked session with build agent - history preserved (ID: fork-xyz-456)"

// Error handling
try {
  session({ mode: "message", agent: "nonexistent", text: "Hello" })
} catch (error) {
  // Returns: "Error: Agent 'nonexistent' not found"
  // Also shows toast notification in OpenCode UI
}
```

--------------------------------

### Perform Manual Version Bump and Push

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

This command allows for a manual version bump on the 'main' branch if necessary, overriding automated processes. The changes, including the new tag, are then pushed to the remote repository. Release Please is designed to detect and adjust to these manual bumps.

```bash
# On main branch
npm version patch  # or minor, major
git push --follow-tags
```

--------------------------------

### Typecheck Project

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

Command to run type checking for the project using npm. This is part of the release checklist to ensure code quality and type safety.

```bash
npm run typecheck
```

--------------------------------

### Basic Session Syntax (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Defines the basic syntax for the `session` function, outlining the required `text` and `mode` parameters, and the optional `agent` parameter.

```typescript
session({
  text: string,      // Required - message to send
  mode: string,      // Required - "message" | "new" | "compact" | "fork"
  agent?: string     // Optional - target agent name
})
```

--------------------------------

### Parallel Architectural Exploration with Session Fork

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Demonstrates how to use the 'session' tool with 'mode: "fork"' to explore different architectural approaches concurrently. This is ideal for design exploration before committing to a specific implementation. It highlights initiating parallel design tasks for microservices, modular monolith, and serverless architectures.

```typescript
// Exploring architectural approaches before committing

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a microservices architecture",
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a modular monolith",
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a serverless architecture",
})

// Switch between sessions (<leader>l) to discuss trade-offs with each approach
// Iterate on designs, then commit to one architecture
// Note: Fork works best for design exploration, not parallel implementations

```

--------------------------------

### Sync dev Branch with main

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

After a release and the merge of the Release Please PR, this sequence of commands synchronizes the 'dev' branch with the updated 'main' branch, ensuring 'dev' includes the latest version bumps and changes.

```bash
git checkout dev
git pull origin dev
git merge main
git push origin dev
```

--------------------------------

### Develop Feature on dev Branch using GitHub CLI

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

This snippet demonstrates how to create a new feature branch from 'dev', make changes, and then create a pull request targeting the 'dev' branch using the GitHub CLI. It's the initial step in the maintainer workflow.

```bash
git checkout dev
git checkout -b feature/your-feature-name
# ... make changes ...
gh pr create --base dev --head feature/your-feature-name
```

--------------------------------

### Backport Commit to Development Branch

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

Steps to cherry-pick a specific commit from a hotfix branch to the 'dev' branch and push the changes. This ensures that critical fixes are propagated to the development line.

```bash
git checkout dev
git cherry-pick <hotfix-commit-sha>
git push origin dev
```

--------------------------------

### Clone Repository - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Cloning the OpenCode Session Plugin repository to your local machine using either SSH or HTTPS protocols. This is the first step to making changes.

```bash
# Clone using SSH
git clone git@github.com:YOUR-USERNAME/opencode-sessions.git

# OR Clone using HTTPS
git clone https://github.com/YOUR-USERNAME/opencode-sessions.git
cd opencode-sessions
```

--------------------------------

### Git Branching and Pull Request Workflow

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

This snippet illustrates the standard workflow for creating a feature branch from 'dev', developing code, committing with conventional commits, and creating a pull request back to 'dev'. It's essential for collaborative development and integration.

```bash
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
gh pr create --base dev --head feature/your-feature-name
```

--------------------------------

### Manual Session Compression with Agent Handoff (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Initiates a compressed session, allowing for agent handoffs and continuation of long conversations without immediate token limit concerns. It injects a handoff message and compresses the history.

```typescript
session({
  mode: "compact",
  agent: "plan",
  text: "Continue architecture review",
})
// Compacts history, injects handoff context, plan agent responds
```

--------------------------------

### Session Tool - Fork Mode (Parallel Exploration)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Creates a child session that copies the full conversation history, allowing exploration of different approaches without affecting the parent session. Best for architectural exploration and "what if" scenarios.

```APIDOC
## Session Tool - Fork Mode (Parallel Exploration)

### Description
Creates a child session that copies the full conversation history, allowing exploration of different approaches without affecting the parent session. Best for architectural exploration and "what if" scenarios.

### Method
POST

### Endpoint
/session

### Parameters
#### Request Body
- **mode** (string) - Required - The mode of operation, must be 'fork'.
- **agent** (string) - Required - The agent to use in the forked session.
- **text** (string) - Required - The prompt or task for the forked session.

### Request Example
```json
{
  "mode": "fork",
  "agent": "plan",
  "text": "Design this e-commerce system as a microservices architecture with API gateway"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the forked session creation.

#### Response Example
```json
{
  "message": "Forked session with plan agent - history preserved (ID: xyz-456)"
}
```
```

--------------------------------

### Create Feature Branch - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Creating a new branch for your feature or fix. Follows a convention like 'feature/description', 'fix/description', etc. Ensures changes are isolated.

```bash
git checkout main
git checkout -b feature/your-feature-name
```

--------------------------------

### Force Update OpenCode and Plugins (Bash)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Command to forcefully update OpenCode and all its plugins to their latest versions by removing the cache.

```bash
rm -rf ~/.cache/opencode && opencode
```

--------------------------------

### Create Hotfix Branch on main

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

This procedure is for emergency hotfixes that need to be applied directly to the 'main' branch, bypassing the usual 'dev' branch workflow. It involves checking out 'main', creating a new branch for the hotfix, and then proceeding with the fix.

```bash
git checkout main
git checkout -b hotfix/critical-fix
```

--------------------------------

### Session Management Modes

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Defines the different modes for managing agent sessions, including creating new sessions, sending messages within existing sessions, compacting history, and forking sessions.

```APIDOC
## POST /session (Session Modes)

### Description
Manages agent sessions using different modes to control conversation flow, history, and agent interaction.

### Method
POST

### Endpoint
`/session`

### Parameters
#### Request Body
- **text** (string) - Required - The primary message or instruction for the agent.
- **mode** (string) - Required - The session management mode. Accepts `"message"`, `"new"`, `"compact"`, or `"fork"`.
  - `"message"`: Sends a message within the current session context.
  - `"new"`: Starts a new, clean session, discarding previous context.
  - `"compact"`: Compresses the existing history before processing the message.
  - `"fork"`: Creates a new branch of the session, preserving the current state.
- **agent** (string) - Optional - The target agent for the session interaction.

### Request Example
```json
{
  "mode": "new",
  "agent": "researcher",
  "text": "Research best practices for API rate limiting in 2025"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the session operation.
- **message** (string) - A descriptive message about the outcome.

#### Response Example
```json
{
  "status": "success",
  "message": "New session initiated with researcher agent."
}
```
```

--------------------------------

### Manual Token Compression with Compact Mode

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Manages token limits by compressing conversation history while preserving essential context, optionally handing off to another agent. The `session` tool with `mode: 'compact'` allows for the reduction of lengthy conversation logs, enabling long interactions to continue without exceeding token constraints. It can be used to stay with the current agent or switch to a different one after compaction.

```typescript
// After extensive implementation discussion, compress and hand to plan
session({
  mode: "compact",
  agent: "plan",
  text: "Review the overall architecture we've built so far"
})

// What plan agent sees after compaction:
// [Compacted summary of previous implementation work]
// User: [Session will compact after this response - plan agent will continue]
// User: Review the overall architecture we've built so far

// Compact without agent switch (stay with current agent)
session({
  mode: "compact",
  text: "Continue implementing the remaining endpoints"
})

// Returns: "I'll compact the session after completing this response, then hand off to plan."
```

--------------------------------

### Manual Compression with Messaging

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Trigger manual compression of the session history, inject a handoff message, and optionally direct the response to a specific agent. This is useful for managing long conversations and token limits.

```APIDOC
## POST /session (Manual Compression)

### Description
Triggers session compaction with an optional message and agent handoff. This preserves essential context while reducing token usage for long conversations.

### Method
POST

### Endpoint
`/session`

### Parameters
#### Request Body
- **text** (string) - Required - The message to be included in the session after compression.
- **mode** (string) - Required - Must be `"compact"` to trigger manual compression.
- **agent** (string) - Optional - The name of the agent to receive the compacted session and the message.

### Request Example
```json
{
  "mode": "compact",
  "agent": "plan",
  "text": "Continue architecture review"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Session compacted and handed off to plan agent."
}
```
```

--------------------------------

### Push Changes to Fork - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Pushing your committed changes from your local feature branch to your forked repository on GitHub. This makes your changes available for a pull request.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Parallel Exploration with Fork Mode

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Supports parallel exploration of different approaches by creating child sessions that duplicate the parent's conversation history. The `session` tool with `mode: 'fork'` is ideal for 'what if' scenarios and architectural divergence, allowing multiple independent lines of inquiry without impacting the original session. Users can switch between these forked sessions to compare distinct solutions.

```typescript
// Explore three different architectural approaches in parallel
session({
  mode: "fork",
  agent: "plan",
  text: "Design this e-commerce system as a microservices architecture with API gateway"
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this e-commerce system as a modular monolith with domain-driven design"
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this e-commerce system as serverless with AWS Lambda and DynamoDB"
})

// Switch between sessions in UI (<leader>l) to compare approaches
// Each fork has full conversation history and can be iterated on independently
// Returns: "Forked session with plan agent - history preserved (ID: xyz-456)"
```

--------------------------------

### Parallel Exploration with Session Forking (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

This snippet demonstrates how to explore different architectural approaches by forking into independent sessions. Each fork maintains full primary agent capabilities and conversational context, allowing for risk-free experimentation and comparison before committing to a direction. It's best suited for design and architectural exploration.

```typescript
// Exploring architectural approaches (not parallel implementations)
session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a microservices architecture",
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a modular monolith",
})

session({
  mode: "fork",
  agent: "plan",
  text: "Design this as a serverless architecture",
})

// Switch between sessions to discuss trade-offs, iterate on each approach
// before committing to one architecture
```

--------------------------------

### Session Tool - Compact Mode (Manual Compression)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Triggers session compaction to compress conversation history while preserving context, optionally handing off to a different agent. Allows long conversations to continue without hitting token limits.

```APIDOC
## Session Tool - Compact Mode (Manual Compression)

### Description
Triggers session compaction to compress conversation history while preserving context, optionally handing off to a different agent. Allows long conversations to continue without hitting token limits.

### Method
POST

### Endpoint
/session

### Parameters
#### Request Body
- **mode** (string) - Required - The mode of operation, must be 'compact'.
- **agent** (string) - Optional - The agent to hand off to after compaction. If not provided, the current agent continues.
- **text** (string) - Required - The prompt or task to be processed before compaction.

### Request Example
```json
{
  "mode": "compact",
  "agent": "plan",
  "text": "Review the overall architecture we've built so far"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the compaction and potential handoff.

#### Response Example
```json
{
  "message": "I'll compact the session after completing this response, then hand off to plan."
}
```
```

--------------------------------

### Create Hotfix Pull Request

Source: https://github.com/malhashemi/opencode-sessions/blob/main/RELEASE.md

Command to create a pull request for a hotfix branch targeting the 'main' branch. This is a common Git operation for managing urgent fixes.

```bash
gh pr create --base main --head hotfix/critical-fix
```

--------------------------------

### Available Agents

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

Lists the types of agents that can be targeted within the OpenCode Sessions plugin. This includes built-in agents and custom agents configured by the user.

```APIDOC
## Available Agents

### Description
The OpenCode Sessions plugin automatically detects and allows interaction with various agents. These include built-in agents provided by OpenCode and any custom agents defined in your configuration.

### Built-in Agents
- **build**: Handles full development tasks, including access to all tools.
- **plan**: Focuses on analysis and planning, typically with read-only tool access.
- **researcher**: Dedicated to investigation and information gathering.
- **implement**: Primarily focused on code implementation tasks.

### Custom Agents
Any agents defined in your `opencode.json` configuration file are also available. Use Tab completion in OpenCode to see a dynamic list of all discoverable agents.
```

--------------------------------

### Handle Session Compacted Events for Immediate Message Sending

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

The session.compacted event handler ensures messages are sent immediately after the history compaction process is complete. This is vital for maintaining smooth agent handoffs following context compression. After the compaction event fires and a brief lock release period, the stored message is sent to the target agent, which then responds with the updated, compacted context.

```typescript
// Internal implementation (automatic)
// When compaction completes:
// 1. session.compacted event fires
// 2. Wait 100ms for lock release
// 3. Send stored message to target agent
// 4. Target agent responds with compacted context

// Example compact mode flow:
session({
  mode: "compact",
  agent: "plan",
  text: "Continue architecture review"
})
// [Build agent finishes response]
// [session.idle: compaction starts]
// [History compressed by OpenCode]
// [session.compacted fires]
// [Plugin sends "Continue architecture review" to plan agent]
// [Plan agent responds with access to compacted history]

```

--------------------------------

### Session Tool - Message Mode (Agent Collaboration)

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Enables turn-based collaboration between agents in the same conversation thread. The current agent sends a message to a target agent, who receives it as user input and responds within the same conversation.

```APIDOC
## Session Tool - Message Mode (Agent Collaboration)

### Description
Enables turn-based collaboration between agents in the same conversation thread. The current agent stores a message, completes its turn, and hands off to the target agent who receives the message as user input and responds in the same conversation.

### Method
POST

### Endpoint
/session

### Parameters
#### Request Body
- **mode** (string) - Required - The mode of operation, must be 'message'.
- **agent** (string) - Required - The target agent to send the message to.
- **text** (string) - Required - The message content to send to the agent.

### Request Example
```json
{
  "mode": "message",
  "agent": "review",
  "text": "Review this authentication implementation for security issues"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the action taken.

#### Response Example
```json
{
  "message": "Message sent to review agent."
}
```
```

--------------------------------

### Discover Agents with Primary Mode in YAML Frontmatter

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

This process automatically finds primary agents by examining markdown files in configuration directories. It looks for YAML frontmatter with 'mode: primary' or 'mode: all' and also checks opencode.json to ensure agents are not explicitly disabled. The system scans standard locations like ~/.config/opencode/agent/ and .opencode/agent/ for agent definitions.

```typescript
// Agent discovery process (internal function)
// Scans these directories:
// - ~/.config/opencode/agent/ (or $XDG_CONFIG_HOME/opencode/agent/)
// - .opencode/agent/ (project-local)

// Example agent file: ~/.config/opencode/agent/researcher.md
// ---
// mode: primary
// description: Research and investigation agent
// ---
// Your researcher agent prompt here...

// Example opencode.json to disable an agent:
{
  "plugin": ["opencode-sessions"],
  "agent": {
    "build": {
      "disable": false  // Enable built-in build agent
    },
    "researcher": {
      "disable": true   // Disable custom researcher agent
    }
  }
}

// Built-in agents (always available unless disabled):
// - build: General-purpose implementation agent
// - plan: Strategic planning and architecture agent

```

--------------------------------

### Add Upstream Remote - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Adding the upstream remote repository to your cloned fork. This allows you to fetch changes from the original project repository.

```bash
git remote add upstream https://github.com/malhashemi/opencode-sessions.git
```

--------------------------------

### Turn-Based Agent Collaboration (TypeScript)

Source: https://github.com/malhashemi/opencode-sessions/blob/main/README.md

This code illustrates turn-based agent collaboration where agents work together in the same conversation, passing control sequentially. It's ideal for complex problems requiring multiple perspectives, such as code reviews or research handoffs. Note that it's not recommended for agents using different providers and is primarily tested with Sonnet 4.5.

```typescript
// Agent implements, then hands to review agent
session({
  mode: "message",
  agent: "review",
  text: "Review this authentication implementation",
})

// Or research hands to plan
session({
  mode: "message",
  agent: "plan",
  text: "Design our rate limiting based on this research",
})
```

--------------------------------

### Agent Collaboration with Message Mode

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

Enables turn-based communication between agents in the same conversation thread. The `session` tool with `mode: 'message'` allows an agent to send a message to a target agent, which receives it as user input and responds within the same conversation. This is useful for passing tasks and feedback between agents, such as a build agent handing off code for review.

```typescript
session({
  mode: "message",
  agent: "review",
  text: "Review this authentication implementation for security issues"
})

// Review agent receives the message and responds in same conversation
// Can pass back to build agent if changes needed
session({
  mode: "message",
  agent: "build",
  text: "Fix the password hashing - use bcrypt with 12 rounds minimum"
})

// Example: Research hands findings to plan agent
session({
  mode: "message",
  agent: "plan",
  text: "Based on the research above, design our rate limiting system using token bucket algorithm"
})
```

--------------------------------

### Update Branch with Upstream - Git Bash

Source: https://github.com/malhashemi/opencode-sessions/blob/main/CONTRIBUTING.md

Fetching the latest changes from the upstream repository and rebasing your current branch onto it. This keeps your feature branch up-to-date with the main development line.

```bash
git fetch upstream
git rebase upstream/main
```

--------------------------------

### Handle Session Idle Events to Send Pending Messages

Source: https://context7.com/malhashemi/opencode-sessions/llms.txt

The session.idle event handler is triggered after the current agent finishes its turn, allowing pending messages to be sent. This is crucial for the relay pattern, ensuring messages are delivered whether in 'message' mode or 'compact' mode. For message mode, messages are stored and then sent; for compact mode, compaction requests are stored, a context marker is injected, and the idle event initiates the compaction process.

```typescript
// Internal implementation (automatic)
// When session tool is called with mode: "message":
// 1. Message stored in pendingMessages Map
// 2. Current agent completes its turn
// 3. session.idle event fires
// 4. Event handler sends message to target agent

// Example flow:
// Build agent: session({ mode: "message", agent: "review", text: "Review this" })
// [Build agent continues and finishes its response]
// [session.idle event fires]
// [Plugin sends "Review this" to review agent]
// [Review agent responds in same conversation]

// For compact mode:
// 1. Compaction request stored in pendingCompactions Map
// 2. Context marker injected: "[Session will compact - plan agent will continue]"
// 3. Current agent completes its turn
// 4. session.idle event fires
// 5. Plugin starts compaction process
// 6. session.compacted event fires (see next section)

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.