feat: add parallel session workflow with branch-synced session naming#6
Conversation
- Add parallel session safety guidance to git-workflow.md - Add /sync-branch and /rename commands for session title management - Add session-rename custom tool to update session titles via API - Add branch merge workflow to release.md for merging work branches - Support multiple OpenCode sessions working on same repo safely
|
Caution Review failedThe pull request is closed. Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Note
|
| Cohort / File(s) | Summary |
|---|---|
Workflow documentation .agent/workflows/git-workflow.md, .agent/workflows/release.md |
Added branch-state verification, pre-action fetch/diff step, parallel session safety section with decision tables and decision-tree guidance, session-branch tracking commands and examples, expanded workflow tracking table, and a "Merging Work Branch to Main" pre-release section (direct merge vs PR/MR). |
Command documentation .opencode/command/rename.md, .opencode/command/sync-branch.md |
New docs describing the rename and sync-branch commands and their usage to update session titles and sync them with the current Git branch. |
Session rename tool .opencode/tool/session-rename.ts |
New TypeScript tool exporting a default rename tool (PATCH /session/{sessionID} with a title) and a named sync_branch tool that reads the current Git branch, validates it, and PATCHes the session title; includes basic error handling for git and network failures. |
Sequence Diagram(s)
sequenceDiagram
participant User
participant Tool as session-rename (local)
participant Git as Local Git
participant API as OpenCode API
User->>Tool: invoke sync_branch (no args) or rename(title)
Tool->>Git: run `git branch --show-current` (sync_branch only)
Git-->>Tool: branch name or empty
alt branch found
Tool->>API: PATCH /session/{sessionID} { title: branch/title }
API-->>Tool: 200 OK (updated session)
Tool-->>User: success message
else branch missing or invalid
Tool-->>User: error about missing/invalid branch
end
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~20 minutes
- Review focus:
.opencode/tool/session-rename.ts— network error handling, input validation, and correct API endpoint/port resolution.- Command docs — consistency with CLI/tool naming and examples (
/sync-branch,/rename). - Workflow docs — ensure decision tables and pre-release merge steps align with existing policies and don't conflict with other workflow guidance.
Poem
🐰
I hopped through branches, bright and spry,
I named each session as I spied,
Sync’d titles with the Git's clear song,
Safe parallel work — hop along! 🥕✨
Pre-merge checks and finishing touches
✅ Passed checks (3 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Title check | ✅ Passed | The title clearly and accurately describes the main change: adding parallel session workflow capabilities with branch-synced session naming. It is specific, concise, and directly summarizes the primary objective without vague language. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
📜 Recent review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.agent/workflows/branch.md
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the OpenCode workflow by introducing robust mechanisms for managing parallel sessions and improving session traceability. It provides new tools and updated documentation to ensure users can safely run multiple sessions on a single repository, synchronize session names with Git branches for clarity, and follow structured procedures for merging work into the main branch before releases, thereby streamlining development and reducing potential conflicts. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Mon Dec 22 01:48:45 UTC 2025 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a valuable workflow for managing parallel sessions by syncing session names with git branches. It adds new commands (/sync-branch, /rename), a corresponding tool, and updates the documentation with safety guidelines and merge procedures. The changes are well-structured. I've provided a couple of suggestions: one to improve the clarity of the documentation in git-workflow.md, and a more significant one for session-rename.ts to address an unhandled exception and reduce code duplication. Overall, this is a great feature addition.
| import { tool } from "@opencode-ai/plugin" | ||
|
|
||
| export default tool({ | ||
| description: "Rename the current session to a new title. Use this after creating a git branch to sync the session name with the branch name.", | ||
| args: { | ||
| title: tool.schema.string().describe("New title for the session (e.g., branch name like 'feature/my-feature')"), | ||
| }, | ||
| async execute(args, context) { | ||
| const { sessionID } = context | ||
| const { title } = args | ||
|
|
||
| // Call the OpenCode API to update the session | ||
| // The server runs on localhost:4096 by default | ||
| const port = process.env.OPENCODE_PORT || "4096" | ||
| const baseUrl = `http://localhost:${port}` | ||
|
|
||
| try { | ||
| const response = await fetch(`${baseUrl}/session/${sessionID}`, { | ||
| method: "PATCH", | ||
| headers: { | ||
| "Content-Type": "application/json", | ||
| }, | ||
| body: JSON.stringify({ title }), | ||
| }) | ||
|
|
||
| if (!response.ok) { | ||
| const error = await response.text() | ||
| return `Failed to rename session: ${error}` | ||
| } | ||
|
|
||
| const session = await response.json() | ||
| return `Session renamed to: ${session.title || title}` | ||
| } catch (error) { | ||
| return `Error renaming session: ${error instanceof Error ? error.message : String(error)}` | ||
| } | ||
| }, | ||
| }) | ||
|
|
||
| // Also export a tool that syncs with the current git branch | ||
| export const sync_branch = tool({ | ||
| description: "Rename the current session to match the current git branch name. Call this after creating or switching branches.", | ||
| args: {}, | ||
| async execute(_args, context) { | ||
| const { sessionID } = context | ||
|
|
||
| // Get current branch name | ||
| const branchResult = await Bun.$`git branch --show-current`.text() | ||
| const branch = branchResult.trim() | ||
|
|
||
| if (!branch) { | ||
| return "Not in a git repository or no branch checked out" | ||
| } | ||
|
|
||
| // Call the OpenCode API to update the session | ||
| const port = process.env.OPENCODE_PORT || "4096" | ||
| const baseUrl = `http://localhost:${port}` | ||
|
|
||
| try { | ||
| const response = await fetch(`${baseUrl}/session/${sessionID}`, { | ||
| method: "PATCH", | ||
| headers: { | ||
| "Content-Type": "application/json", | ||
| }, | ||
| body: JSON.stringify({ title: branch }), | ||
| }) | ||
|
|
||
| if (!response.ok) { | ||
| const error = await response.text() | ||
| return `Failed to sync session with branch: ${error}` | ||
| } | ||
|
|
||
| const session = await response.json() | ||
| return `Session synced with branch: ${session.title || branch}` | ||
| } catch (error) { | ||
| return `Error syncing session: ${error instanceof Error ? error.message : String(error)}` | ||
| } | ||
| }, | ||
| }) |
There was a problem hiding this comment.
This file has two main areas for improvement:
-
Unhandled Exception: The
Bun.$command at line 47 can throw an exception if thegitcommand fails (e.g., not in a git repository). This exception is not currently caught, which would crash the tool. Thetry...catchblock should be extended to cover this call. -
Code Duplication: The logic for making the API call to rename the session is duplicated in both the default tool and the
sync_branchtool. This can be extracted into a shared helper function to improve maintainability and reduce redundancy.
The suggested change below addresses both points by creating a renameSession helper and ensuring all fallible operations are within try...catch blocks.
import { tool } from "@opencode-ai/plugin"
async function renameSession(sessionID: string, title: string): Promise<string> {
// Call the OpenCode API to update the session
// The server runs on localhost:4096 by default
const port = process.env.OPENCODE_PORT || "4096"
const baseUrl = `http://localhost:${port}`
const response = await fetch(`${baseUrl}/session/${sessionID}`, {
method: "PATCH",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({ title }),
})
if (!response.ok) {
const error = await response.text()
// Throwing an error to be caught by the caller
throw new Error(error)
}
const session = await response.json()
return session.title || title
}
export default tool({
description: "Rename the current session to a new title. Use this after creating a git branch to sync the session name with the branch name.",
args: {
title: tool.schema.string().describe("New title for the session (e.g., branch name like 'feature/my-feature')"),
},
async execute(args, context) {
const { sessionID } = context
const { title } = args
try {
const newTitle = await renameSession(sessionID, title)
return `Session renamed to: ${newTitle}`
} catch (error) {
return `Failed to rename session: ${error instanceof Error ? error.message : String(error)}`
}
},
})
// Also export a tool that syncs with the current git branch
export const sync_branch = tool({
description: "Rename the current session to match the current git branch name. Call this after creating or switching branches.",
args: {},
async execute(_args, context) {
const { sessionID } = context
try {
// Get current branch name
const branchResult = await Bun.$`git branch --show-current`.text()
const branch = branchResult.trim()
if (!branch) {
return "Not in a git repository or no branch checked out"
}
const newTitle = await renameSession(sessionID, branch)
return `Session synced with branch: ${newTitle}`
} catch (error) {
return `Error syncing session: ${error instanceof Error ? error.message : String(error)}`
}
},
})| | Command | Purpose | | ||
| |---------|---------| | ||
| | `/sync-branch` | Rename session to match current git branch | | ||
| | `/rename feature/xyz` | Rename session to any title | |
There was a problem hiding this comment.
For clarity, the command in the documentation should be represented generically using a placeholder, rather than a specific example. This helps users understand that feature/xyz is a placeholder for a value they need to provide.
| | `/rename feature/xyz` | Rename session to any title | | |
| | `/rename <new-title>` | Rename session to any title | |
🤖 Augment PR SummarySummary: This PR improves multi-session OpenCode workflows by making branch state and session identity easier to track. Changes:
Technical Notes: The session renaming tool uses a local HTTP 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| const { sessionID } = context | ||
|
|
||
| // Get current branch name | ||
| const branchResult = await Bun.$`git branch --show-current`.text() |
There was a problem hiding this comment.
Bun.$\git branch --show-current`can throw (e.g., not a git repo / detached HEAD), which would bypass the laterif (!branch)message; consider catching the command failure (similar to howgithub-release.tsuses.catch(...)) so /sync-branch` degrades gracefully.
🤖 Was this useful? React with 👍 or 👎
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
.opencode/tool/session-rename.ts (2)
3-37: Consider adding input validation for the title parameter.The default export tool implementation is clear and handles errors appropriately. However, consider adding validation for the
titleparameter to catch common issues early:
- Empty or whitespace-only titles
- Extremely long titles (e.g., >200 characters)
- Invalid characters if the API has restrictions
This would provide better user feedback before making the API call.
🔎 Optional validation enhancement
async execute(args, context) { const { sessionID } = context const { title } = args + + // Validate title + const trimmedTitle = title.trim() + if (!trimmedTitle) { + return "Error: Title cannot be empty" + } + if (trimmedTitle.length > 200) { + return "Error: Title must be 200 characters or less" + } // Call the OpenCode API to update the session // The server runs on localhost:4096 by default const port = process.env.OPENCODE_PORT || "4096" const baseUrl = `http://localhost:${port}` try { const response = await fetch(`${baseUrl}/session/${sessionID}`, { method: "PATCH", headers: { "Content-Type": "application/json", }, - body: JSON.stringify({ title }), + body: JSON.stringify({ title: trimmedTitle }), })
14-15: Consider extracting shared API call logic to reduce duplication.The port configuration (lines 14-15, 55-56) and the API call pattern (lines 18-35, 59-76) are duplicated between the two tools. Extracting this into a shared helper function would improve maintainability and reduce the risk of inconsistencies.
🔎 Refactoring suggestion
// Helper function to call the session API async function updateSessionTitle(sessionID: string, title: string): Promise<string> { const port = process.env.OPENCODE_PORT || "4096" const baseUrl = `http://localhost:${port}` try { const response = await fetch(`${baseUrl}/session/${sessionID}`, { method: "PATCH", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ title }), }) if (!response.ok) { const error = await response.text() throw new Error(`API error: ${error}`) } const session = await response.json() return session.title || title } catch (error) { throw error } } export default tool({ description: "Rename the current session to a new title. Use this after creating a git branch to sync the session name with the branch name.", args: { title: tool.schema.string().describe("New title for the session (e.g., branch name like 'feature/my-feature')"), }, async execute(args, context) { const { sessionID } = context const { title } = args try { const newTitle = await updateSessionTitle(sessionID, title) return `Session renamed to: ${newTitle}` } catch (error) { return `Error renaming session: ${error instanceof Error ? error.message : String(error)}` } }, }) export const sync_branch = tool({ description: "Rename the current session to match the current git branch name. Call this after creating or switching branches.", args: {}, async execute(_args, context) { const { sessionID } = context // Get current branch name const branchResult = await Bun.$`git branch --show-current`.text() const branch = branchResult.trim() if (!branch) { return "Not in a git repository or no branch checked out" } try { const newTitle = await updateSessionTitle(sessionID, branch) return `Session synced with branch: ${newTitle}` } catch (error) { return `Error syncing session: ${error instanceof Error ? error.message : String(error)}` } }, })Also applies to: 55-56, 18-35, 59-76
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
.agent/workflows/git-workflow.md.agent/workflows/release.md.opencode/command/rename.md.opencode/command/sync-branch.md.opencode/tool/session-rename.ts
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-12-22T01:24:46.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:46.937Z
Learning: Use `.agent/scripts/version-manager.sh release [major|minor|patch]` for releasing new versions
Applied to files:
.agent/workflows/release.md
📚 Learning: 2025-12-22T01:25:03.128Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/git/AGENTS.md:0-0
Timestamp: 2025-12-22T01:25:03.128Z
Learning: Follow security protocols for all git and DevOps operations
Applied to files:
.agent/workflows/git-workflow.md
📚 Learning: 2025-12-22T01:24:53.929Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.929Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/workflows/git-workflow.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (6)
.agent/workflows/release.md (1)
57-108: LGTM! Clear and comprehensive merge workflow guidance.The new "Merging Work Branch to Main" section provides well-structured guidance for both solo and collaborative workflows. The decision tree table effectively covers common scenarios, and the bash examples are correct and easy to follow.
.agent/workflows/git-workflow.md (2)
24-24: Good emphasis on parallel session safety.The updated CRITICAL note appropriately highlights the importance of verifying branch state before file operations when working with parallel sessions.
38-72: Excellent parallel session and session-branch tracking guidance.The additions provide clear, actionable guidance for managing parallel OpenCode sessions:
- The remote update check commands (lines 38-41) are essential for preventing conflicts
- The parallel session safety table (lines 43-53) covers key scenarios
- The session-branch tracking tables (lines 54-72) provide a clear mental model for keeping sessions aligned with branches
The workflow guidance is practical and well-organized.
.opencode/command/rename.md (1)
1-7: LGTM! Clear and concise rename command documentation.The command documentation correctly uses
$ARGUMENTSas a placeholder for the new session title and references thesession-renametool (default export fromsession-rename.ts)..opencode/tool/session-rename.ts (1)
47-47: No action required — Bun.$ usage is standard for OpenCode tools.The code correctly uses
Bun.$to execute shell commands. This is the idiomatic pattern for OpenCode custom tools and aligns with documented examples in the OpenCode tool development guide.Likely an incorrect or invalid review comment.
.opencode/command/sync-branch.md (1)
5-5: Tool name reference is correct.The tool name
session-rename_sync_branchin line 5 follows OpenCode's naming convention for named exports: filename (session-rename) + underscore + export name (sync_branch). Confirmed in.opencode/tool/session-rename.ts, which exports a namedsync_branchtool alongside the default export.
Explicit guidance to start branch descriptions with action verbs: - add- for new functionality - improve- for enhancements - fix- for bug fixes - remove- for deprecations This helps identify branch purpose at a glance, especially useful when tracking multiple OpenCode sessions by branch name.
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Mon Dec 22 01:58:48 UTC 2025 Generated by AI DevOps Framework Code Review Monitoring |
- Wrap Bun.$ git command in try/catch to handle non-git directories - Extract renameSession() helper to eliminate code duplication - Improve error messages for detached HEAD state - Add JSDoc comment for helper function Addresses feedback from PR #6 (Gemini Code Assist, Augment)
1 participant
Summary
/sync-branchand/renamecommands to sync session titles with git branchessession-renamecustom tool that uses OpenCode API to update session titlesrelease.mdfor merging work branches before releaseNew Commands
/sync-branch/rename <title>Changes
.agent/workflows/git-workflow.md- Parallel session safety, session-branch tracking.agent/workflows/release.md- Branch merge workflow (solo + collaborative).opencode/tool/session-rename.ts- Custom tool for session renaming via API.opencode/command/sync-branch.md- Slash command for branch sync.opencode/command/rename.md- Slash command for manual renameSummary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.