@andre-barbosa/opencode-commit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-commit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# opencode-commit
+
+OpenCode plugin that generates **Conventional Commits** messages from staged git changes using a dedicated sub-agent on a model you choose.
+
+Run `/commit` in the OpenCode TUI to get a suggested message like `feat(auth): add oauth login flow` — copy it and commit manually.
+
+## Features
+
+- `/commit` slash command (display only, no auto-commit)
+- Dedicated hidden `commit-writer` sub-agent with its own model
+- Conventional Commits format enforced (`feat(scope): ...`, `fix(scope): ...`, etc.)
+- Optional hint: `/commit emphasize breaking API change`
+- Uses staged diff, branch name, and recent commit subjects for context
+
+## Requirements
+
+- [OpenCode](https://opencode.ai/) with plugin support
+- A git repository with staged changes
+
+## Installation
+
+### 1. Copy agent and command templates
+
+```bash
+mkdir -p .opencode/agents .opencode/commands
+cp agents/commit-writer.md .opencode/agents/commit-writer.md
+cp commands/commit.md .opencode/commands/commit.md
+```
+
+### 2. Configure the plugin
+
+**Local development** (this repo):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "file:///C:/absolute/path/to/opencode-commit/src/index.ts",
+      {
+        "agent": "commit-writer",
+        "maxDiffChars": 12000
+      }
+    ]
+  ],
+  "agent": {
+    "commit-writer": {
+      "model": "anthropic/claude-haiku-4-20250514"
+    }
+  }
+}
+```
+
+**From npm** (when published):
+
+```json
+{
+  "plugin": [
+    ["opencode-commit", { "agent": "commit-writer" }]
+  ]
+}
+```
+
+See [opencode.example.json](opencode.example.json) for a full example.
+
+### 3. Set your model
+
+Edit the model on the `commit-writer` agent in `opencode.json` or in `.opencode/agents/commit-writer.md`:
+
+```yaml
+model: anthropic/claude-haiku-4-20250514
+```
+
+Run `opencode models` to list available models.
+
+## Usage
+
+1. Stage your changes: `git add ...`
+2. Open OpenCode in the project
+3. Run `/commit`
+4. Copy the suggested message and commit: `git commit -m "feat(scope): ..."`
+
+Optional extra instruction:
+
+```text
+/commit focus on test coverage improvements
+```
+
+## Plugin options
+
+When loading the plugin as a tuple `[name, options]`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `agent` | `commit-writer` | Sub-agent name to invoke |
+| `maxDiffChars` | `12000` | Max staged diff characters sent to the sub-agent |
+
+## Commit message format
+
+Generated messages follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): short imperative description
+
+- optional bullet body
+```
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`.
+
+## Project layout
+
+```
+opencode-commit/
+├── src/                  # plugin source
+├── agents/               # commit-writer sub-agent template
+├── commands/             # /commit command stub
+└── opencode.example.json
+```
+
+## License
+
+MIT

package/agents/commit-writer.md

@@ -0,0 +1,27 @@
+---
+description: Generates conventional commit messages from git diffs
+mode: subagent
+hidden: true
+model: anthropic/claude-haiku-4-20250514
+temperature: 0.1
+permission:
+  edit: deny
+  bash: deny
+  webfetch: deny
+---
+
+You are a commit message writer. Given a git diff and context, produce a single commit message.
+
+You MUST follow Conventional Commits:
+
+- Subject: `type(scope): description` or `type: description`
+- Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
+- Scope: optional but preferred for localized changes (e.g. auth, api, ui)
+- Description: imperative, lowercase, no trailing period, max 72 chars for the subject line
+- Body: optional blank line then bullet points for non-obvious context
+- Breaking changes: `feat!:` / `fix!:` or a `BREAKING CHANGE:` footer
+
+Never output free-form subjects like "Update files", "WIP", or "Misc changes".
+Never wrap the message in code fences.
+Never add commentary before or after the commit message.
+Output only the commit message text.

package/commands/commit.md

@@ -0,0 +1,5 @@
+---
+description: Generate a commit message from staged changes
+---
+
+Handled by the opencode-commit plugin.

package/opencode.example.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-commit",
+      {
+        "agent": "commit-writer",
+        "maxDiffChars": 12000
+      }
+    ]
+  ],
+  "agent": {
+    "commit-writer": {
+      "model": "your-provider/your-model"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@andre-barbosa/opencode-commit",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that generates Conventional Commit messages via a dedicated sub-agent",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "agents",
+    "commands",
+    "opencode.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "git",
+    "commit",
+    "conventional-commits"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndreB10/opencode-commit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AndreB10/opencode-commit/issues"
+  },
+  "homepage": "https://github.com/AndreB10/opencode-commit#readme",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.3.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/sdk": "^1.3.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/generate.ts

@@ -0,0 +1,112 @@
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+import type { AgentInfo, ModelRef } from "./types.js";
+import { buildCommitPrompt, stripCodeFences } from "./prompt.js";
+import type { GitContext } from "./types.js";
+
+type Client = ReturnType<typeof createOpencodeClient>;
+
+function extractText(parts: Array<{ type?: string; text?: string }>): string {
+  return parts
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text as string)
+    .join("")
+    .trim();
+}
+
+export function formatModelRef(model?: ModelRef): string {
+  if (!model) return "default";
+  return `${model.providerID}/${model.modelID}`;
+}
+
+export async function fetchAgent(
+  client: Client,
+  agentName: string,
+): Promise<AgentInfo | undefined> {
+  const { data, error } = await client.app.agents();
+  if (error || !Array.isArray(data)) return undefined;
+
+  const agent = data.find((entry) => entry.name === agentName);
+  if (!agent) return undefined;
+
+  return {
+    name: agent.name,
+    model: agent.model
+      ? {
+          providerID: agent.model.providerID,
+          modelID: agent.model.modelID,
+        }
+      : undefined,
+  };
+}
+
+async function createChildSession(
+  client: Client,
+  parentSessionID: string,
+): Promise<string> {
+  const { data: session, error } = await client.session.create({
+    body: {
+      title: "Commit message",
+      parentID: parentSessionID,
+    },
+  });
+
+  if (error || !session?.id) {
+    throw new Error(`Failed to create child session: ${String(error)}`);
+  }
+
+  return session.id;
+}
+
+export async function generateCommitMessage(input: {
+  client: Client;
+  parentSessionID: string;
+  agentName: string;
+  agent: AgentInfo;
+  context: GitContext;
+  userHint?: string;
+}): Promise<{ message: string; childSessionID: string; modelLabel: string }> {
+  const childSessionID = await createChildSession(
+    input.client,
+    input.parentSessionID,
+  );
+
+  const prompt = buildCommitPrompt(input.context, input.userHint);
+  const body: {
+    agent: string;
+    parts: Array<{ type: "text"; text: string }>;
+    model?: ModelRef;
+  } = {
+    agent: input.agentName,
+    parts: [{ type: "text", text: prompt }],
+  };
+
+  if (input.agent.model) {
+    body.model = input.agent.model;
+  }
+
+  const { data: result, error } = await input.client.session.prompt({
+    path: { id: childSessionID },
+    body,
+  });
+
+  if (error) {
+    throw new Error(`Sub-agent prompt failed: ${String(error)}`);
+  }
+
+  const parts =
+    (result as { parts?: Array<{ type?: string; text?: string }> } | undefined)
+      ?.parts ?? [];
+  const rawText = extractText(parts);
+
+  if (!rawText) {
+    throw new Error(
+      `Sub-agent returned no text. Child session: ${childSessionID}`,
+    );
+  }
+
+  return {
+    message: stripCodeFences(rawText),
+    childSessionID,
+    modelLabel: formatModelRef(input.agent.model),
+  };
+}

package/src/git.ts

@@ -0,0 +1,64 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { GitContext } from "./types.js";
+
+type Shell = PluginInput["$"];
+
+async function readGitOutput(
+  $: Shell,
+  worktree: string,
+  run: ($: Shell) => Promise<{ exitCode: number; stdout?: { toString(): string } }>,
+): Promise<string> {
+  const result = await run($);
+  if (result.exitCode !== 0) {
+    return "";
+  }
+  return result.stdout?.toString().trim() ?? "";
+}
+
+export async function isGitRepo($: Shell, worktree: string): Promise<boolean> {
+  const result = await $`git rev-parse --git-dir`.cwd(worktree).quiet().nothrow();
+  return result.exitCode === 0;
+}
+
+export async function gatherGitContext(
+  $: Shell,
+  worktree: string,
+  maxDiffChars: number,
+): Promise<GitContext> {
+  const branch =
+    (await readGitOutput($, worktree, ($) =>
+      $`git symbolic-ref --quiet --short HEAD`.cwd(worktree).quiet().nothrow(),
+    )) ||
+    (await readGitOutput($, worktree, ($) =>
+      $`git rev-parse --short HEAD`.cwd(worktree).quiet().nothrow(),
+    )) ||
+    "unknown";
+
+  const stat = await readGitOutput($, worktree, ($) =>
+    $`git diff --staged --stat`.cwd(worktree).quiet().nothrow(),
+  );
+  const rawDiff = await readGitOutput($, worktree, ($) =>
+    $`git diff --staged`.cwd(worktree).quiet().nothrow(),
+  );
+  const diff =
+    rawDiff.length > maxDiffChars
+      ? `${rawDiff.slice(0, maxDiffChars)}\n\n[diff truncated at ${maxDiffChars} characters]`
+      : rawDiff;
+
+  const logOutput = await readGitOutput($, worktree, ($) =>
+    $`git log -5 --pretty=format:%s`.cwd(worktree).quiet().nothrow(),
+  );
+  const recentCommits = logOutput
+    ? logOutput.split("\n").map((line) => line.trim()).filter(Boolean)
+    : [];
+
+  const hasStagedChanges = stat.length > 0 || rawDiff.length > 0;
+
+  return {
+    branch,
+    stat,
+    diff,
+    recentCommits,
+    hasStagedChanges,
+  };
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { Part } from "@opencode-ai/sdk";
+import { gatherGitContext, isGitRepo } from "./git.js";
+import { fetchAgent, generateCommitMessage } from "./generate.js";
+import { resolveConfig, type PluginOptions } from "./types.js";
+
+const COMMAND_NAME = "commit";
+const SKIP_ERROR = "skip";
+
+function textPart(text: string): Part {
+  return { type: "text", text } as Part;
+}
+
+function formatOutput(input: {
+  message: string;
+  modelLabel: string;
+  childSessionID: string;
+}): string {
+  return [
+    "## Suggested commit message",
+    "",
+    "```",
+    input.message,
+    "```",
+    "",
+    `Model: \`${input.modelLabel}\` · Child session: \`${input.childSessionID}\``,
+    "",
+    "Copy the message above and run `git commit` when ready.",
+  ].join("\n");
+}
+
+const skipCommand = (): never => {
+  throw new Error(SKIP_ERROR);
+};
+
+export const OpenCodeCommitPlugin: Plugin = async (
+  { client, $, worktree },
+  options?: PluginOptions,
+) => {
+  const config = resolveConfig(options);
+
+  const log = async (
+    level: "info" | "warn" | "error",
+    message: string,
+    extra?: Record<string, unknown>,
+  ) => {
+    await client.app
+      .log({
+        body: {
+          service: "opencode-commit",
+          level,
+          message,
+          extra,
+        },
+      })
+      .catch(() => {});
+  };
+
+  return {
+    "command.execute.before": async (input, output) => {
+      if (input.command !== COMMAND_NAME) return;
+
+      try {
+        if (!(await isGitRepo($, worktree))) {
+          output.parts = [
+            textPart(
+              "Not a git repository. Run `/commit` from inside a git worktree.",
+            ),
+          ];
+          return skipCommand();
+        }
+
+        const context = await gatherGitContext($, worktree, config.maxDiffChars);
+
+        if (!context.hasStagedChanges) {
+          output.parts = [
+            textPart(
+              "No staged changes found. Stage files with `git add` and run `/commit` again.",
+            ),
+          ];
+          return skipCommand();
+        }
+
+        const resolvedAgent = await fetchAgent(client, config.agent);
+        if (!resolvedAgent) {
+          output.parts = [
+            textPart(
+              [
+                `Sub-agent \`${config.agent}\` is not configured.`,
+                "",
+                "Copy `agents/commit-writer.md` from this plugin into `.opencode/agents/commit-writer.md`,",
+                "or add the agent to your `opencode.json`.",
+              ].join("\n"),
+            ),
+          ];
+          return skipCommand();
+        }
+
+        await log("info", "Generating commit message", {
+          agent: config.agent,
+          branch: context.branch,
+          sessionID: input.sessionID,
+        });
+
+        const userHint = input.arguments?.trim() || undefined;
+        const result = await generateCommitMessage({
+          client,
+          parentSessionID: input.sessionID,
+          agentName: config.agent,
+          agent: resolvedAgent,
+          context,
+          userHint,
+        });
+
+        output.parts = [textPart(formatOutput(result))];
+        return skipCommand();
+      } catch (error) {
+        if (error instanceof Error && error.message === SKIP_ERROR) {
+          throw error;
+        }
+
+        await log("error", "Commit message generation failed", {
+          error: String(error),
+          sessionID: input.sessionID,
+        });
+
+        output.parts = [
+          textPart(`Failed to generate commit message: ${String(error)}`),
+        ];
+        return skipCommand();
+      }
+    },
+  };
+};
+
+export default OpenCodeCommitPlugin;

package/src/prompt.ts

@@ -0,0 +1,51 @@
+import type { GitContext } from "./types.js";
+
+export function buildCommitPrompt(context: GitContext, userHint?: string): string {
+  const recentCommitsBlock =
+    context.recentCommits.length > 0
+      ? context.recentCommits.map((subject) => `- ${subject}`).join("\n")
+      : "(none)";
+
+  const hintBlock =
+    userHint && userHint.trim().length > 0
+      ? `\nAdditional instruction from the user:\n${userHint.trim()}\n`
+      : "";
+
+  return `Write a git commit message for the staged changes below.
+
+Format rules (Conventional Commits — required):
+- Subject line MUST use type(scope): description or type: description
+- Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
+- Scope is optional but preferred when changes are localized (e.g. feat(auth):, fix(api):)
+- Description: imperative mood, lowercase, no trailing period, max 72 chars for the full subject
+- Optional body: blank line after subject, then bullet points; keep lines <= 72 chars
+- Breaking changes: use feat!: or fix!: prefix, or add a BREAKING CHANGE: footer
+- Do NOT use free-form subjects like "Update files", "WIP", or "Misc changes"
+- Output ONLY the commit message text — no code fences, no commentary, no tool calls
+
+Examples:
+feat(auth): add oauth login flow
+
+- add google and github providers
+- store refresh tokens in secure storage
+
+fix(api): handle null response from user endpoint
+${hintBlock}
+Branch: ${context.branch}
+
+Recent commit subjects (align scope naming when sensible):
+${recentCommitsBlock}
+
+Staged changes (stat):
+${context.stat || "(empty)"}
+
+Staged diff:
+${context.diff || "(empty)"}
+`;
+}
+
+export function stripCodeFences(text: string): string {
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/^```(?:\w*\n)?([\s\S]*?)```$/);
+  return (fenced?.[1] ?? trimmed).trim();
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+export type ModelRef = {
+  providerID: string;
+  modelID: string;
+};
+
+export type PluginOptions = {
+  agent?: string;
+  maxDiffChars?: number;
+};
+
+export type ResolvedPluginConfig = {
+  agent: string;
+  maxDiffChars: number;
+};
+
+export const DEFAULT_AGENT = "commit-writer";
+export const DEFAULT_MAX_DIFF_CHARS = 12_000;
+
+export function resolveConfig(options?: PluginOptions): ResolvedPluginConfig {
+  return {
+    agent: options?.agent?.trim() || DEFAULT_AGENT,
+    maxDiffChars:
+      typeof options?.maxDiffChars === "number" && options.maxDiffChars > 0
+        ? Math.floor(options.maxDiffChars)
+        : DEFAULT_MAX_DIFF_CHARS,
+  };
+}
+
+export type GitContext = {
+  branch: string;
+  stat: string;
+  diff: string;
+  recentCommits: string[];
+  hasStagedChanges: boolean;
+};
+
+export type AgentInfo = {
+  name: string;
+  model?: ModelRef;
+};